Skip to content

Commit 8f038b8

Browse files
spacesailor24spacesailor24
committed
docs: send spot asset
1 parent 8cf85fe commit 8f038b8

File tree

1 file changed

+392
-0
lines changed
  • docs/ability/official-abilities/hyperliquid/spot-trading

1 file changed

+392
-0
lines changed

‎docs/ability/official-abilities/hyperliquid/spot-trading/send-asset.mdx‎

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

0 commit comments

Comments
 (0)