Skip to content

Commit ebaf785

Browse files
spacesailor24spacesailor24
committed
docs: cancel order
1 parent 4576b72 commit ebaf785

File tree

1 file changed

+382
-0
lines changed

1 file changed

+382
-0
lines changed

‎docs/ability/official-abilities/hyperliquid/cancel-order.mdx‎

Lines changed: 382 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,382 @@
1+
---
2+
title: Cancel Order
3+
---
4+
5+
The `cancelOrder` action enables Vincent Apps to cancel a specific open order on Hyperliquid's spot or perpetuals market.
6+
7+
## Prerequisites
8+
9+
Before executing the `cancelOrder` action, the following conditions must be met:
10+
11+
- **Open Order**: There must be an open order with the specified order ID that belongs to the Vincent User Agent Wallet.
12+
- **Order Details**: You must provide the symbol (trading pair for spot or asset for perp) and the order ID to cancel.
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 cancel order, without actually performing the operation.
22+
23+
For the `cancelOrder` action, the `precheck` function will validate the following:
24+
25+
- Order with provided order ID must exist and be open.
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.CANCEL_ORDER)
37+
*/
38+
action: HyperliquidAction.CANCEL_ORDER;
39+
/**
40+
* Whether to use Hyperliquid testnet (optional, defaults to false)
41+
*/
42+
useTestnet?: boolean;
43+
/**
44+
* Cancel order parameters
45+
*/
46+
cancelOrder: {
47+
/**
48+
* The symbol for the order to cancel.
49+
* For spot: trading pair (e.g., "PURR/USDC")
50+
* For perp: base asset (e.g., "SOL", "ETH")
51+
*/
52+
symbol: string;
53+
/**
54+
* The order ID to cancel (oid from the order)
55+
*/
56+
orderId: number;
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.CANCEL_ORDER,
89+
useTestnet: false, // Set to true for testnet
90+
cancelOrder: {
91+
symbol: 'PURR/USDC', // For spot orders, or 'PURR' for perp orders
92+
orderId: 123456, // The order ID to cancel
93+
},
94+
},
95+
{
96+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
97+
},
98+
);
99+
100+
if (precheckResult.success) {
101+
console.log('Cancel order 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('Cancel order 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: 'cancelOrder';
129+
}
130+
```
131+
132+
### Failure
133+
134+
A failure `precheck` response will contain:
135+
136+
```typescript
137+
{
138+
/**
139+
* The action that was prechecked
140+
*/
141+
action: 'cancelOrder';
142+
/**
143+
* The reason the precheck failed
144+
*/
145+
reason: string;
146+
}
147+
```
148+
149+
</Tab>
150+
</Tabs>
151+
152+
## Executing the `execute` Function
153+
154+
The `execute` function performs the actual cancel operation, removing the specified order from Hyperliquid.
155+
156+
For the `cancelOrder` action, the `execute` function will:
157+
158+
- Cancel the specified order on Hyperliquid.
159+
- Return the cancellation result from Hyperliquid.
160+
161+
<Tabs>
162+
<Tab title="Parameters">
163+
The `execute` function requires the following parameters:
164+
165+
```typescript
166+
import { HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';
167+
168+
{
169+
/**
170+
* The action to perform (must be HyperliquidAction.CANCEL_ORDER)
171+
*/
172+
action: HyperliquidAction.CANCEL_ORDER;
173+
/**
174+
* Whether to use Hyperliquid testnet (optional, defaults to false)
175+
*/
176+
useTestnet?: boolean;
177+
/**
178+
* Cancel order parameters
179+
*/
180+
cancelOrder: {
181+
/**
182+
* The symbol for the order to cancel.
183+
* For spot: trading pair (e.g., "PURR/USDC")
184+
* For perp: base asset (e.g., "SOL", "ETH")
185+
*/
186+
symbol: string;
187+
/**
188+
* The order ID to cancel (oid from the order)
189+
*/
190+
orderId: number;
191+
};
192+
}
193+
```
194+
195+
<Note>
196+
The `arbitrumRpcUrl` parameter is **not required** for the `execute` function, only for `precheck`.
197+
</Note>
198+
199+
</Tab>
200+
201+
<Tab title="Implementation">
202+
The `execute` function can be executed using the same `VincentAbilityClient` instance as used for the `precheck` function:
203+
204+
```typescript
205+
const executeResult = await hyperliquidAbilityClient.execute(
206+
{
207+
action: HyperliquidAction.CANCEL_ORDER,
208+
useTestnet: false, // Set to true for testnet
209+
cancelOrder: {
210+
symbol: 'PURR/USDC', // For spot orders, or 'PURR' for perp orders
211+
orderId: 123456, // The order ID to cancel
212+
},
213+
},
214+
{
215+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
216+
},
217+
);
218+
219+
if (executeResult.success) {
220+
const { cancelResult } = executeResult.result;
221+
console.log('Order cancelled successfully:', cancelResult);
222+
} else {
223+
// Handle different types of failures
224+
if (executeResult.runtimeError) {
225+
console.error('Runtime error:', executeResult.runtimeError);
226+
}
227+
if (executeResult.schemaValidationError) {
228+
console.error('Schema validation error:', executeResult.schemaValidationError);
229+
}
230+
if (executeResult.result) {
231+
console.error('Cancel order execution failed:', executeResult.result.reason);
232+
}
233+
}
234+
```
235+
236+
</Tab>
237+
238+
<Tab title="Response">
239+
**Success Response**
240+
241+
A successful `execute` response will contain:
242+
243+
```typescript
244+
{
245+
/**
246+
* The action that was executed
247+
*/
248+
action: 'cancelOrder';
249+
/**
250+
* The order response from Hyperliquid request as defined by the Hyperliquid SDK: @nktkas/hyperliquid
251+
* https://github.com/nktkas/hyperliquid/blob/2233ce942eb50ef8850073b387b9918d3a54a10b/src/api/exchange/cancel.ts#L74-L120
252+
*/
253+
cancelResult: CancelResponse;
254+
}
255+
```
256+
257+
**Failure Response**
258+
259+
A failure `execute` response will contain:
260+
261+
```typescript
262+
{
263+
/**
264+
* The action that was executed
265+
*/
266+
action: 'cancelOrder';
267+
/**
268+
* The reason the execution failed, such as order not found
269+
*/
270+
reason: string;
271+
}
272+
```
273+
274+
</Tab>
275+
</Tabs>
276+
277+
## Important Considerations
278+
279+
<AccordionGroup>
280+
<Accordion title="Finding Order IDs" icon="search">
281+
To cancel an order, you need its order ID (`oid`). You can find order IDs by:
282+
283+
- Querying open orders using the [Hyperliquid API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-a-users-open-orders)
284+
- Checking the order result when placing orders (the `oid` is returned in the response)
285+
- Using a [Hyperliquid SDK](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api to fetch open orders
286+
287+
</Accordion>
288+
289+
<Accordion title="Symbol Format" icon="tag">
290+
The symbol format differs between spot and perpetual orders:
291+
292+
- **Spot orders**: Use trading pair format (e.g., "PURR/USDC", "ETH/USDC")
293+
- **Perp orders**: Use base asset only (e.g., "SOL", "ETH", "BTC")
294+
295+
Make sure to use the correct format for the type of order you're cancelling.
296+
297+
</Accordion>
298+
299+
<Accordion title="Order Must Exist" icon="exclamation-triangle">
300+
The order must be an open order that:
301+
302+
- Belongs to the Vincent User's Agent Wallet
303+
- Has not already been filled, cancelled, or expired
304+
- Is for the specified symbol
305+
306+
If the order doesn't exist or has already been cancelled/filled, the cancellation will fail.
307+
308+
</Accordion>
309+
310+
<Accordion title="Verifying Cancellation Success" icon="check">
311+
After the cancellation is executed, you can verify it was successful by:
312+
- 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)
313+
- Confirming the order ID no longer appears in the list
314+
- Reviewing the cancellation result response
315+
</Accordion>
316+
</AccordionGroup>
317+
318+
## Reference Implementation
319+
320+
For a complete working example showing the full cancel order workflow including verification, see the [cancel-order.spec.ts](https://github.com/LIT-Protocol/Vincent/blob/main/packages/apps/ability-hyperliquid/test/e2e/spot/cancel-order.spec.ts) end-to-end test in the `ability-hyperliquid` package.
321+
322+
## Next Steps
323+
324+
Explore the rest of the supported Hyperliquid actions:
325+
326+
<CardGroup cols={3}>
327+
328+
<Card title="Deposit" href="/ability/official-abilities/hyperliquid/deposit" icon="arrow-down" />
329+
330+
<Card title="Withdraw" href="/ability/official-abilities/hyperliquid/withdraw" icon="arrow-up" />
331+
332+
<Card
333+
title="Send Spot Asset"
334+
href="/ability/official-abilities/hyperliquid/send-spot-asset"
335+
icon="coins"
336+
/>
337+
338+
<Card
339+
title="Send Perp USDC"
340+
href="/ability/official-abilities/hyperliquid/send-perp-usdc"
341+
icon="dollar-sign"
342+
/>
343+
344+
<Card
345+
title="Transfer to Spot"
346+
href="/ability/official-abilities/hyperliquid/transfer-to-spot"
347+
icon="arrow-right"
348+
/>
349+
350+
<Card
351+
title="Transfer to Perp"
352+
href="/ability/official-abilities/hyperliquid/transfer-to-perp"
353+
icon="arrow-left"
354+
/>
355+
356+
<Card
357+
title="Spot Buy"
358+
href="/ability/official-abilities/hyperliquid/spot-buy"
359+
icon="shopping-cart"
360+
/>
361+
362+
<Card title="Spot Sell" href="/ability/official-abilities/hyperliquid/spot-sell" icon="tag" />
363+
364+
<Card
365+
title="Perp Long"
366+
href="/ability/official-abilities/hyperliquid/perp-long"
367+
icon="arrow-up-right"
368+
/>
369+
370+
<Card
371+
title="Perp Short"
372+
href="/ability/official-abilities/hyperliquid/perp-short"
373+
icon="arrow-down-right"
374+
/>
375+
376+
<Card
377+
title="Cancel All Orders"
378+
href="/ability/official-abilities/hyperliquid/cancel-all-orders-for-symbol"
379+
icon="trash"
380+
/>
381+
382+
</CardGroup>

0 commit comments

Comments
 (0)