Skip to content

Commit dd5576a

Browse files
spacesailor24spacesailor24
committed
docs: transfer to perp
1 parent a9c7fcc commit dd5576a

File tree

2 files changed

+357
-3
lines changed

2 files changed

+357
-3
lines changed

‎docs/ability/official-abilities/hyperliquid/transfer-to-perp.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 Perp
3+
---
4+
5+
The `transferToPerp` action enables Vincent Apps to transfer USDC from a Vincent User's HyperCore spot balance to their perp balance.
6+
7+
## Prerequisites
8+
9+
Before executing the `transferToPerp` action, the following conditions must be met:
10+
11+
- **Spot Balance on HyperCore**: The Vincent User Agent Wallet must have sufficient USDC in their HyperCore spot 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 perp, without actually performing the operation.
21+
22+
For the `transferToPerp` action, the `precheck` function will validate the following:
23+
24+
- The Vincent User Agent Wallet has sufficient USDC in their HyperCore spot 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 'transferToPerp')
36+
*/
37+
action: 'transferToPerp';
38+
/**
39+
* Whether to use Hyperliquid testnet (optional, defaults to false)
40+
*/
41+
useTestnet?: boolean;
42+
/**
43+
* Transfer to perp parameters
44+
*/
45+
transfer: {
46+
/**
47+
* The amount of USDC to transfer in 6-decimal format.
48+
* Example: "9000000" = 9.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 } 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: 'transferToPerp',
83+
useTestnet: false, // Set to true for testnet
84+
transfer: {
85+
amount: '9000000', // 9.0 USDC (6 decimals)
86+
},
87+
arbitrumRpcUrl: 'https://arb1.arbitrum.io/rpc',
88+
},
89+
{
90+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
91+
},
92+
);
93+
94+
if (precheckResult.success) {
95+
console.log('Transfer to perp precheck passed, ready to execute');
96+
} else {
97+
// Handle different types of failures
98+
if (precheckResult.runtimeError) {
99+
console.error('Runtime error:', precheckResult.runtimeError);
100+
}
101+
if (precheckResult.schemaValidationError) {
102+
console.error('Schema validation error:', precheckResult.schemaValidationError);
103+
}
104+
if (precheckResult.result) {
105+
console.error('Transfer to perp precheck failed:', precheckResult.result.reason);
106+
}
107+
}
108+
```
109+
110+
</Tab>
111+
112+
<Tab title="Response">
113+
### Success
114+
115+
A successful `precheck` response will contain:
116+
117+
```typescript
118+
{
119+
/**
120+
* The action that was prechecked
121+
*/
122+
action: 'transferToPerp';
123+
/**
124+
* The available USDC balance in the Vincent User's HyperCore spot account (optional)
125+
*/
126+
availableBalance: string;
127+
}
128+
```
129+
130+
### Failure
131+
132+
A failure `precheck` response will contain:
133+
134+
```typescript
135+
{
136+
/**
137+
* The action that was prechecked
138+
*/
139+
action: 'transferToPerp';
140+
/**
141+
* The reason the precheck failed, such as insufficient spot balance
142+
*/
143+
reason: string;
144+
/**
145+
* The available balance of the asset in the Hyperliquid account (optional)
146+
*/
147+
availableBalance?: string;
148+
/**
149+
* The required balance for the action (optional)
150+
*/
151+
requiredBalance?: string;
152+
}
153+
```
154+
155+
</Tab>
156+
</Tabs>
157+
158+
## Executing the `execute` Function
159+
160+
The `execute` function performs the actual transfer operation, moving USDC from the Vincent User's HyperCore spot balance to their perp balance.
161+
162+
For the `transferToPerp` action, the `execute` function will:
163+
164+
- Transfer the specified amount of USDC from the Vincent User Agent Wallet's HyperCore spot balance to their perp balance.
165+
- Return the transfer result from Hyperliquid.
166+
167+
<Tabs>
168+
<Tab title="Parameters">
169+
The `execute` function requires the following parameters:
170+
171+
```typescript
172+
{
173+
/**
174+
* The action to perform (must be 'transferToPerp')
175+
*/
176+
action: 'transferToPerp';
177+
/**
178+
* Whether to use Hyperliquid testnet (optional, defaults to false)
179+
*/
180+
useTestnet?: boolean;
181+
/**
182+
* Transfer to perp parameters
183+
*/
184+
transfer: {
185+
/**
186+
* The amount of USDC to transfer in 6-decimal format.
187+
* Example: "9000000" = 9.0 USDC
188+
*/
189+
amount: string;
190+
};
191+
}
192+
```
193+
194+
</Tab>
195+
196+
<Tab title="Implementation">
197+
The `execute` function can be executed using the same `VincentAbilityClient` instance as used for the `precheck` function:
198+
199+
```typescript
200+
const executeResult = await hyperliquidAbilityClient.execute(
201+
{
202+
action: 'transferToPerp',
203+
useTestnet: false, // Set to true for testnet
204+
transfer: {
205+
amount: '9000000', // 9.0 USDC (6 decimals)
206+
},
207+
},
208+
{
209+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
210+
},
211+
);
212+
213+
if (executeResult.success) {
214+
const { transferResult } = executeResult.result;
215+
console.log('Transfer to perp executed successfully:', transferResult);
216+
} else {
217+
// Handle different types of failures
218+
if (executeResult.runtimeError) {
219+
console.error('Runtime error:', executeResult.runtimeError);
220+
}
221+
if (executeResult.schemaValidationError) {
222+
console.error('Schema validation error:', executeResult.schemaValidationError);
223+
}
224+
if (executeResult.result) {
225+
console.error('Transfer to perp execution failed:', executeResult.result.reason);
226+
}
227+
}
228+
```
229+
230+
</Tab>
231+
232+
<Tab title="Response">
233+
**Success Response**
234+
235+
A successful `execute` response will contain:
236+
237+
```typescript
238+
{
239+
/**
240+
* The action that was executed
241+
*/
242+
action: 'transferToPerp';
243+
/**
244+
* The transfer result from Hyperliquid request as defined by the Hyperliquid SDK: @nktkas/hyperliquid
245+
* https://github.com/nktkas/hyperliquid/blob/2233ce942eb50ef8850073b387b9918d3a54a10b/src/api/exchange/_base/_schemas.ts#L49-L73
246+
*/
247+
transferResult: SuccessResponse;
248+
}
249+
```
250+
251+
**Failure Response**
252+
253+
A failure `execute` response will contain:
254+
255+
```typescript
256+
{
257+
/**
258+
* The action that was executed
259+
*/
260+
action: 'transferToPerp';
261+
/**
262+
* The reason the execution failed, such as insufficient spot balance
263+
*/
264+
reason: string;
265+
}
266+
```
267+
268+
</Tab>
269+
</Tabs>
270+
271+
## Important Considerations
272+
273+
<AccordionGroup>
274+
<Accordion title="USDC Decimal Format" icon="hashtag">
275+
USDC uses **6 decimals** for the transfer amount parameter. When specifying the transfer amount:
276+
277+
- 9.0 USDC = `"9000000"`
278+
- 5.0 USDC = `"5000000"`
279+
- 100 USDC = `"100000000"`
280+
281+
</Accordion>
282+
283+
<Accordion title="Transfer Direction" icon="arrow-left">
284+
This action transfers USDC from the Vincent User's HyperCore **spot balance** to their **perp
285+
balance** on HyperCore. If you need to transfer in the opposite direction (perp to spot), use the
286+
[Transfer to Spot](/ability/official-abilities/hyperliquid/transfer-to-spot) 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 recipient and the spot clearinghouse state (spot balance) of the sender. 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 perp workflow including balance verification, see the [to-perp.spec.ts](https://github.com/LIT-Protocol/Vincent/blob/main/packages/apps/ability-hyperliquid/test/e2e/transfer/to-perp.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 Spot"
322+
href="/ability/official-abilities/hyperliquid/transfer-to-spot"
323+
icon="arrow-right"
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>

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -281,9 +281,9 @@ For the `transferToSpot` action, the `execute` function will:
281281
</Accordion>
282282

283283
<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.
284+
This action transfers USDC from the Vincent User's HyperCore **perp balance** to their **spot
285+
balance** on HyperCore. If you need to transfer in the opposite direction (spot to perp), use the
286+
[Transfer to Perp](/ability/official-abilities/hyperliquid/transfer-to-perp) action.
287287
</Accordion>
288288

289289
<Accordion title="Verifying Transfer Success" icon="check">

0 commit comments

Comments
 (0)