Skip to content

Commit ab40e78

Browse files
spacesailor24spacesailor24
committed
docs: send perp usdc
1 parent 8f038b8 commit ab40e78

File tree

1 file changed

+374
-0
lines changed
  • docs/ability/official-abilities/hyperliquid/perp-trading

1 file changed

+374
-0
lines changed

‎docs/ability/official-abilities/hyperliquid/perp-trading/send-usdc.mdx‎

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

0 commit comments

Comments
 (0)