Skip to content

Commit 9a533a4

Browse files
spacesailor24spacesailor24
authored
Merge pull request #407 from LIT-Protocol/docs/hl-ability
Init Hyperliquid Docs
2 parents bac33dc + 7b711f5 commit 9a533a4

File tree

14 files changed

+4865
-0
lines changed

14 files changed

+4865
-0
lines changed

‎docs/ability/official-abilities/hyperliquid/cancel-all-orders-for-symbol.mdx‎

Lines changed: 370 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,370 @@
1+
---
2+
title: Cancel All Orders
3+
---
4+
5+
The `cancelAllOrdersForSymbol` action enables Vincent Apps to cancel all open orders for a specific symbol on Hyperliquid's spot or perpetuals market.
6+
7+
## Prerequisites
8+
9+
Before executing the `cancelAllOrdersForSymbol` action, the following conditions must be met:
10+
11+
- **Symbol**: You must provide the symbol (trading pair for spot or asset for perp) for which to cancel all orders.
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 cancel all orders, without actually performing the operation.
21+
22+
For the `cancelAllOrdersForSymbol` action, the `precheck` function will validate the following:
23+
24+
- Open orders for the specified symbol must exist.
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.CANCEL_ALL_ORDERS_FOR_SYMBOL)
36+
*/
37+
action: HyperliquidAction.CANCEL_ALL_ORDERS_FOR_SYMBOL;
38+
/**
39+
* Whether to use Hyperliquid testnet (optional, defaults to false)
40+
*/
41+
useTestnet?: boolean;
42+
/**
43+
* Cancel all orders parameters
44+
*/
45+
cancelAllOrdersForSymbol: {
46+
/**
47+
* The symbol for which to cancel all orders.
48+
* For spot: trading pair (e.g., "PURR/USDC")
49+
* For perp: base asset (e.g., "SOL", "ETH")
50+
*/
51+
symbol: string;
52+
};
53+
}
54+
```
55+
56+
</Tab>
57+
58+
<Tab title="Implementation">
59+
To execute `precheck`, you'll need to:
60+
61+
- Create an instance of the `VincentAbilityClient` using the `getVincentAbilityClient` function (imported from `@lit-protocol/vincent-app-sdk/abilityClient`)
62+
- Pass in the Ability's `bundledVincentAbility` object (imported from `@lit-protocol/vincent-ability-hyperliquid`)
63+
- Pass in the `ethersSigner` you'll be using to sign the request to Lit with your Delegatee private key
64+
- Use the `VincentAbilityClient` instance to call the `precheck` function
65+
66+
```typescript
67+
import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
68+
import { bundledVincentAbility, HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';
69+
import { ethers } from 'ethers';
70+
71+
// Your delegatee signer (one of the delegatee signers for the Vincent App)
72+
const delegateeSigner = new ethers.Wallet('YOUR_DELEGATEE_PRIVATE_KEY', provider);
73+
74+
// Create ability client
75+
const hyperliquidAbilityClient = getVincentAbilityClient({
76+
bundledVincentAbility,
77+
ethersSigner: delegateeSigner,
78+
});
79+
80+
// Run precheck
81+
const precheckResult = await hyperliquidAbilityClient.precheck(
82+
{
83+
action: HyperliquidAction.CANCEL_ALL_ORDERS_FOR_SYMBOL,
84+
useTestnet: false, // Set to true for testnet
85+
cancelAllOrdersForSymbol: {
86+
symbol: 'PURR/USDC', // For spot orders, or 'PURR' for perp orders
87+
},
88+
},
89+
{
90+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
91+
},
92+
);
93+
94+
if (precheckResult.success) {
95+
console.log('Cancel all orders 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('Cancel all orders 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: 'cancelAllOrdersForSymbol';
123+
}
124+
```
125+
126+
### Failure
127+
128+
A failure `precheck` response will contain:
129+
130+
```typescript
131+
{
132+
/**
133+
* The action that was prechecked
134+
*/
135+
action: 'cancelAllOrdersForSymbol';
136+
/**
137+
* The reason the precheck failed
138+
*/
139+
reason: string;
140+
}
141+
```
142+
143+
</Tab>
144+
</Tabs>
145+
146+
## Executing the `execute` Function
147+
148+
The `execute` function performs the actual cancel operation, removing all open orders for the specified symbol from Hyperliquid.
149+
150+
For the `cancelAllOrdersForSymbol` action, the `execute` function will:
151+
152+
- Cancel all open orders for the specified symbol on Hyperliquid.
153+
- Return the cancellation result from Hyperliquid.
154+
155+
<Tabs>
156+
<Tab title="Parameters">
157+
The `execute` function requires the following parameters:
158+
159+
```typescript
160+
import { HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';
161+
162+
{
163+
/**
164+
* The action to perform (must be HyperliquidAction.CANCEL_ALL_ORDERS_FOR_SYMBOL)
165+
*/
166+
action: HyperliquidAction.CANCEL_ALL_ORDERS_FOR_SYMBOL;
167+
/**
168+
* Whether to use Hyperliquid testnet (optional, defaults to false)
169+
*/
170+
useTestnet?: boolean;
171+
/**
172+
* Cancel all orders parameters
173+
*/
174+
cancelAllOrdersForSymbol: {
175+
/**
176+
* The symbol for which to cancel all orders.
177+
* For spot: trading pair (e.g., "PURR/USDC")
178+
* For perp: base asset (e.g., "SOL", "ETH")
179+
*/
180+
symbol: string;
181+
};
182+
}
183+
```
184+
185+
</Tab>
186+
187+
<Tab title="Implementation">
188+
The `execute` function can be executed using the same `VincentAbilityClient` instance as used for the `precheck` function:
189+
190+
```typescript
191+
const executeResult = await hyperliquidAbilityClient.execute(
192+
{
193+
action: HyperliquidAction.CANCEL_ALL_ORDERS_FOR_SYMBOL,
194+
useTestnet: false, // Set to true for testnet
195+
cancelAllOrdersForSymbol: {
196+
symbol: 'PURR/USDC', // For spot orders, or 'PURR' for perp orders
197+
},
198+
},
199+
{
200+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
201+
},
202+
);
203+
204+
if (executeResult.success) {
205+
const { cancelResult } = executeResult.result;
206+
console.log('All orders cancelled successfully:', cancelResult);
207+
} else {
208+
// Handle different types of failures
209+
if (executeResult.runtimeError) {
210+
console.error('Runtime error:', executeResult.runtimeError);
211+
}
212+
if (executeResult.schemaValidationError) {
213+
console.error('Schema validation error:', executeResult.schemaValidationError);
214+
}
215+
if (executeResult.result) {
216+
console.error('Cancel all orders execution failed:', executeResult.result.reason);
217+
}
218+
}
219+
```
220+
221+
</Tab>
222+
223+
<Tab title="Response">
224+
**Success Response**
225+
226+
A successful `execute` response will contain:
227+
228+
```typescript
229+
{
230+
/**
231+
* The action that was executed
232+
*/
233+
action: 'cancelAllOrdersForSymbol';
234+
/**
235+
* The order response from Hyperliquid request as defined by the Hyperliquid SDK: @nktkas/hyperliquid
236+
* https://github.com/nktkas/hyperliquid/blob/2233ce942eb50ef8850073b387b9918d3a54a10b/src/api/exchange/cancel.ts#L74-L120
237+
*/
238+
cancelResult: CancelResponse;
239+
}
240+
```
241+
242+
**Failure Response**
243+
244+
A failure `execute` response will contain:
245+
246+
```typescript
247+
{
248+
/**
249+
* The action that was executed
250+
*/
251+
action: 'cancelAllOrdersForSymbol';
252+
/**
253+
* The reason the execution failed
254+
*/
255+
reason: string;
256+
}
257+
```
258+
259+
</Tab>
260+
</Tabs>
261+
262+
## Important Considerations
263+
264+
<AccordionGroup>
265+
<Accordion title="Symbol-Specific Cancellation" icon="filter">
266+
This action cancels **all open orders for a specific symbol only**. Orders for other symbols will remain open.
267+
268+
For example:
269+
270+
- If you cancel all orders for "PURR/USDC", orders for "ETH/USDC" will not be affected
271+
- If you cancel all orders for "SOL" (perp), orders for "ETH" (perp) will not be affected
272+
273+
</Accordion>
274+
275+
<Accordion title="Symbol Format" icon="tag">
276+
The symbol format differs between spot and perpetual orders:
277+
278+
- **Spot orders**: Use trading pair format (e.g., "PURR/USDC", "ETH/USDC")
279+
- **Perp orders**: Use base asset only (e.g., "SOL", "ETH", "BTC")
280+
281+
Make sure to use the correct format for the type of orders you're cancelling.
282+
283+
</Accordion>
284+
285+
<Accordion title="No Orders to Cancel" icon="info-circle">
286+
If there are no open orders for the specified symbol, the action will still succeed. The result
287+
will indicate that the operation completed successfully, even though no orders were cancelled.
288+
</Accordion>
289+
290+
<Accordion title="Both Sides Cancelled" icon="exchange-alt">
291+
This action cancels **all orders for the symbol**, including:
292+
293+
- Buy orders (bids)
294+
- Sell orders (asks)
295+
- Limit orders
296+
- Any other order types for the symbol
297+
298+
All open orders for the symbol will be removed.
299+
300+
</Accordion>
301+
302+
<Accordion title="Verifying Cancellation Success" icon="check">
303+
After the cancellation is executed, you can verify it was successful by:
304+
- Checking the open orders list using the [Hyperliquid API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-a-users-open-orders)
305+
- Confirming the order ID no longer appears in the list
306+
- Reviewing the cancellation result response
307+
</Accordion>
308+
</AccordionGroup>
309+
310+
## Reference Implementation
311+
312+
For a complete working example showing the full cancel all orders workflow including verification, see the [cancel-all-orders.spec.ts](https://github.com/LIT-Protocol/Vincent/blob/main/packages/apps/ability-hyperliquid/test/e2e/spot/cancel-all-orders.spec.ts) end-to-end test in the `ability-hyperliquid` package.
313+
314+
## Next Steps
315+
316+
Explore the rest of the supported Hyperliquid actions:
317+
318+
<CardGroup cols={3}>
319+
320+
<Card title="Deposit" href="/ability/official-abilities/hyperliquid/deposit" icon="arrow-down" />
321+
322+
<Card title="Withdraw" href="/ability/official-abilities/hyperliquid/withdraw" icon="arrow-up" />
323+
324+
<Card
325+
title="Send Spot Asset"
326+
href="/ability/official-abilities/hyperliquid/send-spot-asset"
327+
icon="coins"
328+
/>
329+
330+
<Card
331+
title="Send Perp USDC"
332+
href="/ability/official-abilities/hyperliquid/send-perp-usdc"
333+
icon="dollar-sign"
334+
/>
335+
336+
<Card
337+
title="Transfer to Spot"
338+
href="/ability/official-abilities/hyperliquid/transfer-to-spot"
339+
icon="arrow-right"
340+
/>
341+
342+
<Card
343+
title="Transfer to Perp"
344+
href="/ability/official-abilities/hyperliquid/transfer-to-perp"
345+
icon="arrow-left"
346+
/>
347+
348+
<Card
349+
title="Spot Buy"
350+
href="/ability/official-abilities/hyperliquid/spot-buy"
351+
icon="shopping-cart"
352+
/>
353+
354+
<Card title="Spot Sell" href="/ability/official-abilities/hyperliquid/spot-sell" icon="tag" />
355+
356+
<Card
357+
title="Perp Long"
358+
href="/ability/official-abilities/hyperliquid/perp-long"
359+
icon="arrow-up-right"
360+
/>
361+
362+
<Card
363+
title="Perp Short"
364+
href="/ability/official-abilities/hyperliquid/perp-short"
365+
icon="arrow-down-right"
366+
/>
367+
368+
<Card title="Cancel Order" href="/ability/official-abilities/hyperliquid/cancel-order" icon="ban" />
369+
370+
</CardGroup>

0 commit comments

Comments
 (0)