Skip to content

Commit a9c7fcc

Browse files
spacesailor24spacesailor24
committed
docs: transfer to spot
1 parent ab40e78 commit a9c7fcc

File tree

1 file changed

+354
-0
lines changed

1 file changed

+354
-0
lines changed

‎docs/ability/official-abilities/hyperliquid/transfer-to-spot.mdx‎

Lines changed: 354 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,354 @@
1+
---
2+
title: Transfer USDC to Spot
3+
---
4+
5+
The `transferToSpot` action enables Vincent Apps to transfer USDC from a Vincent User's HyperCore perp balance to their spot balance.
6+
7+
## Prerequisites
8+
9+
Before executing the `transferToSpot` action, the following conditions must be met:
10+
11+
- **Perp Balance on HyperCore**: The Vincent User Agent Wallet must have sufficient USDC in their HyperCore perp balance to cover the transfer amount.
12+
13+
<Info>
14+
To learn more about executing Vincent Abilities, see the [Executing
15+
Abilities](/ability/explaining-abilities) guide.
16+
</Info>
17+
18+
## Executing the `precheck` Function
19+
20+
The `precheck` function validates some prerequisites for executing a transfer to spot, without actually performing the operation.
21+
22+
For the `transferToSpot` action, the `precheck` function will validate the following:
23+
24+
- The Vincent User Agent Wallet has sufficient USDC in their HyperCore perp balance to cover the transfer amount.
25+
26+
<Tabs>
27+
<Tab title="Parameters">
28+
The `precheck` function requires the following parameters:
29+
30+
```typescript
31+
import { HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';
32+
33+
{
34+
/**
35+
* The action to perform (must be HyperliquidAction.TRANSFER_TO_SPOT)
36+
*/
37+
action: HyperliquidAction.TRANSFER_TO_SPOT;
38+
/**
39+
* Whether to use Hyperliquid testnet (optional, defaults to false)
40+
*/
41+
useTestnet?: boolean;
42+
/**
43+
* Transfer to spot parameters
44+
*/
45+
transferToSpot: {
46+
/**
47+
* The amount of USDC to transfer in 6-decimal format.
48+
* Example: "15000000" = 15.0 USDC
49+
*/
50+
amount: string;
51+
};
52+
}
53+
```
54+
55+
</Tab>
56+
57+
<Tab title="Implementation">
58+
To execute `precheck`, you'll need to:
59+
60+
- Create an instance of the `VincentAbilityClient` using the `getVincentAbilityClient` function (imported from `@lit-protocol/vincent-app-sdk/abilityClient`)
61+
- Pass in the Ability's `bundledVincentAbility` object (imported from `@lit-protocol/vincent-ability-hyperliquid`)
62+
- Pass in the `ethersSigner` you'll be using to sign the request to Lit with your Delegatee private key
63+
- Use the `VincentAbilityClient` instance to call the `precheck` function
64+
65+
```typescript
66+
import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
67+
import { bundledVincentAbility, HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';
68+
import { ethers } from 'ethers';
69+
70+
// Your delegatee signer (one of the delegatee signers for the Vincent App)
71+
const delegateeSigner = new ethers.Wallet('YOUR_DELEGATEE_PRIVATE_KEY', provider);
72+
73+
// Create ability client
74+
const hyperliquidAbilityClient = getVincentAbilityClient({
75+
bundledVincentAbility,
76+
ethersSigner: delegateeSigner,
77+
});
78+
79+
// Run precheck
80+
const precheckResult = await hyperliquidAbilityClient.precheck(
81+
{
82+
action: HyperliquidAction.TRANSFER_TO_SPOT,
83+
useTestnet: false, // Set to true for testnet
84+
transferToSpot: {
85+
amount: '15000000', // 15.0 USDC (6 decimals)
86+
},
87+
},
88+
{
89+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
90+
},
91+
);
92+
93+
if (precheckResult.success) {
94+
console.log('Transfer to spot precheck passed, ready to execute');
95+
} else {
96+
// Handle different types of failures
97+
if (precheckResult.runtimeError) {
98+
console.error('Runtime error:', precheckResult.runtimeError);
99+
}
100+
if (precheckResult.schemaValidationError) {
101+
console.error('Schema validation error:', precheckResult.schemaValidationError);
102+
}
103+
if (precheckResult.result) {
104+
console.error('Transfer to spot precheck failed:', precheckResult.result.reason);
105+
}
106+
}
107+
```
108+
109+
</Tab>
110+
111+
<Tab title="Response">
112+
### Success
113+
114+
A successful `precheck` response will contain:
115+
116+
```typescript
117+
{
118+
/**
119+
* The action that was prechecked
120+
*/
121+
action: 'transferToSpot';
122+
/**
123+
* The available USDC balance in the Vincent User's HyperCore perp account (optional)
124+
*/
125+
availableBalance: string;
126+
}
127+
```
128+
129+
### Failure
130+
131+
A failure `precheck` response will contain:
132+
133+
```typescript
134+
{
135+
/**
136+
* The action that was prechecked
137+
*/
138+
action: 'transferToSpot';
139+
/**
140+
* The reason the precheck failed, such as insufficient perp balance
141+
*/
142+
reason: string;
143+
/**
144+
* The available balance of the asset in the Hyperliquid account (optional)
145+
*/
146+
availableBalance?: string;
147+
/**
148+
* The required balance for the action (optional)
149+
*/
150+
requiredBalance?: string;
151+
}
152+
```
153+
154+
</Tab>
155+
</Tabs>
156+
157+
## Executing the `execute` Function
158+
159+
The `execute` function performs the actual transfer operation, moving USDC from the Vincent User's HyperCore perp balance to their spot balance.
160+
161+
For the `transferToSpot` action, the `execute` function will:
162+
163+
- Transfer the specified amount of USDC from the Vincent User Agent Wallet's HyperCore perp balance to their spot balance.
164+
- Return the transfer result from Hyperliquid.
165+
166+
<Tabs>
167+
<Tab title="Parameters">
168+
The `execute` function requires the following parameters:
169+
170+
```typescript
171+
import { HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';
172+
173+
{
174+
/**
175+
* The action to perform (must be HyperliquidAction.TRANSFER_TO_SPOT)
176+
*/
177+
action: HyperliquidAction.TRANSFER_TO_SPOT;
178+
/**
179+
* Whether to use Hyperliquid testnet (optional, defaults to false)
180+
*/
181+
useTestnet?: boolean;
182+
/**
183+
* Transfer to spot parameters
184+
*/
185+
transferToSpot: {
186+
/**
187+
* The amount of USDC to transfer in 6-decimal format.
188+
* Example: "15000000" = 15.0 USDC
189+
*/
190+
amount: string;
191+
};
192+
}
193+
```
194+
195+
</Tab>
196+
197+
<Tab title="Implementation">
198+
The `execute` function can be executed using the same `VincentAbilityClient` instance as used for the `precheck` function:
199+
200+
```typescript
201+
const executeResult = await hyperliquidAbilityClient.execute(
202+
{
203+
action: HyperliquidAction.TRANSFER_TO_SPOT,
204+
useTestnet: false, // Set to true for testnet
205+
transferToSpot: {
206+
amount: '15000000', // 15.0 USDC (6 decimals)
207+
},
208+
},
209+
{
210+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
211+
},
212+
);
213+
214+
if (executeResult.success) {
215+
const { transferResult } = executeResult.result;
216+
console.log('Transfer to spot executed successfully:', transferResult);
217+
} else {
218+
// Handle different types of failures
219+
if (executeResult.runtimeError) {
220+
console.error('Runtime error:', executeResult.runtimeError);
221+
}
222+
if (executeResult.schemaValidationError) {
223+
console.error('Schema validation error:', executeResult.schemaValidationError);
224+
}
225+
if (executeResult.result) {
226+
console.error('Transfer to spot execution failed:', executeResult.result.reason);
227+
}
228+
}
229+
```
230+
231+
</Tab>
232+
233+
<Tab title="Response">
234+
**Success Response**
235+
236+
A successful `execute` response will contain:
237+
238+
```typescript
239+
{
240+
/**
241+
* The action that was executed
242+
*/
243+
action: 'transferToSpot';
244+
/**
245+
* The transfer result from Hyperliquid request as defined by the Hyperliquid SDK: @nktkas/hyperliquid
246+
* https://github.com/nktkas/hyperliquid/blob/2233ce942eb50ef8850073b387b9918d3a54a10b/src/api/exchange/_base/_schemas.ts#L49-L73
247+
*/
248+
transferResult: SuccessResponse;
249+
}
250+
```
251+
252+
**Failure Response**
253+
254+
A failure `execute` response will contain:
255+
256+
```typescript
257+
{
258+
/**
259+
* The action that was executed
260+
*/
261+
action: 'transferToSpot';
262+
/**
263+
* The reason the execution failed, such as insufficient perp balance
264+
*/
265+
reason: string;
266+
}
267+
```
268+
269+
</Tab>
270+
</Tabs>
271+
272+
## Important Considerations
273+
274+
<AccordionGroup>
275+
<Accordion title="USDC Decimal Format" icon="hashtag">
276+
USDC uses **6 decimals** for the transfer amount parameter. When specifying the transfer amount:
277+
- 15.0 USDC = `"15000000"`
278+
- 5.0 USDC = `"5000000"`
279+
- 100 USDC = `"100000000"`
280+
281+
</Accordion>
282+
283+
<Accordion title="Transfer Direction" icon="arrow-right">
284+
This action transfers USDC from your **perp balance** to your **spot balance** on HyperCore. If
285+
you need to transfer in the opposite direction (spot to perp), use the [Transfer to
286+
Perp](/ability/official-abilities/hyperliquid/transfer-to-perp) action.
287+
</Accordion>
288+
289+
<Accordion title="Verifying Transfer Success" icon="check">
290+
After the transfer is executed, you can verify the balances changed by using a [Hyperliquid SDK](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api) to check the clearinghouse state (perp balance) of the sender and the spot clearinghouse state (spot balance) of the recipient. You can also use the Hyperliquid API retrieve the [perps balances](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-users-perpetuals-account-summary) and [spot balances](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-a-users-token-balances).
291+
</Accordion>
292+
</AccordionGroup>
293+
294+
## Reference Implementation
295+
296+
For a complete working example showing the full transfer to spot workflow including balance verification, see the [to-spot.spec.ts](https://github.com/LIT-Protocol/Vincent/blob/main/packages/apps/ability-hyperliquid/test/e2e/transfer/to-spot.spec.ts) end-to-end test in the `ability-hyperliquid` package.
297+
298+
## Next Steps
299+
300+
Explore the rest of the supported Hyperliquid actions:
301+
302+
<CardGroup cols={3}>
303+
304+
<Card title="Deposit" href="/ability/official-abilities/hyperliquid/deposit" icon="arrow-down" />
305+
306+
<Card title="Withdraw" href="/ability/official-abilities/hyperliquid/withdraw" icon="arrow-up" />
307+
308+
<Card
309+
title="Send Spot Asset"
310+
href="/ability/official-abilities/hyperliquid/send-spot-asset"
311+
icon="coins"
312+
/>
313+
314+
<Card
315+
title="Send Perp USDC"
316+
href="/ability/official-abilities/hyperliquid/send-perp-usdc"
317+
icon="dollar-sign"
318+
/>
319+
320+
<Card
321+
title="Transfer to Perp"
322+
href="/ability/official-abilities/hyperliquid/transfer-to-perp"
323+
icon="arrow-left"
324+
/>
325+
326+
<Card
327+
title="Spot Buy"
328+
href="/ability/official-abilities/hyperliquid/spot-buy"
329+
icon="shopping-cart"
330+
/>
331+
332+
<Card title="Spot Sell" href="/ability/official-abilities/hyperliquid/spot-sell" icon="tag" />
333+
334+
<Card
335+
title="Perp Long"
336+
href="/ability/official-abilities/hyperliquid/perp-long"
337+
icon="arrow-up-right"
338+
/>
339+
340+
<Card
341+
title="Perp Short"
342+
href="/ability/official-abilities/hyperliquid/perp-short"
343+
icon="arrow-down-right"
344+
/>
345+
346+
<Card title="Cancel Order" href="/ability/official-abilities/hyperliquid/cancel-order" icon="ban" />
347+
348+
<Card
349+
title="Cancel All Orders"
350+
href="/ability/official-abilities/hyperliquid/cancel-all-orders-for-symbol"
351+
icon="trash"
352+
/>
353+
354+
</CardGroup>

0 commit comments

Comments
 (0)