> ## Documentation Index
> Fetch the complete documentation index at: https://public-perps-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Actions API
> Unified action construction and execution endpoints for trading, setup, and withdrawals
All mutating operations follow the **create -> sign -> execute** pattern through two unified endpoints. The `action` field determines the operation.
These endpoints are intended to be used via [`@lifi/perps-sdk`](https://www.npmjs.com/package/@lifi/perps-sdk). The typed data signing and submission flow is complex and best handled by the SDK.
***
## POST /createAction
Build provider-specific authorization steps. Signed EIP-712, WASM, EVM, HMAC, and SIWE steps continue to `POST /executeAction`; a client-only session step is completed directly by the provider plugin.
```
POST /v1/perps/createAction
```
### Request Body
```json theme={null}
{
"provider": "hyperliquid",
"address": "0x1234567890abcdef1234567890abcdef12345678",
"signerAddress": "0x5678901234abcdef5678901234abcdef56789012",
"action": "placeOrder",
"params": {
"market": { "marketId": "BTC", "categoryId": "hyperliquid" },
"side": "BUY",
"type": "MARKET",
"size": "0.1",
"price": "95500.00",
"leverage": 10,
"takeProfit": { "triggerPrice": "100000.00" },
"stopLoss": { "triggerPrice": "90000.00", "limitPrice": "89800.00" }
}
}
```
### Request Fields
| Field | Type | Required | Description |
| --------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | `string` | Yes | Provider identifier (e.g. `hyperliquid`) |
| `address` | `string` | Yes | User's wallet address (account owner) |
| `signerAddress` | `string` | No | Address contributing an address-based signature. Provider plugins populate SDK-managed signer addresses; user-signed actions default to `address`. |
| `action` | `string` | Yes | Action type (see table below) |
| `params` | `object` | Yes | Action-specific parameters |
### Action Types
| Action | Description | Params |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `placeOrder` | Place a new order | `PlaceOrderParams` |
| `placeTriggerOrder` | Place standalone TP/SL | `PlaceTriggerOrderParams` |
| `placeTwapOrder` | Place a TWAP parent order that executes over a fixed duration | `PlaceTwapOrderParams` |
| `cancelOrder` | Cancel one or more orders | `CancelOrderParams` |
| `cancelAllOrders` | Cancel every open order on the account | `CancelAllOrdersParams` |
| `cancelTwapOrder` | Cancel a running TWAP parent order | `CancelTwapOrderParams` |
| `modifyOrder` | Modify existing orders | `ModifyOrderParams` |
| `updateLeverage` | Change leverage (and optionally margin mode) for a market | `UpdateLeverageParams` |
| `updatePositionMargin` | Add/remove position margin | `UpdatePositionMarginParams` |
| `withdrawal` | Withdraw funds | `WithdrawalParams` |
| `deposit` | Fund the account via an L1 bridge transaction | `DepositParams` |
| `approveAgent` | Authorize an agent wallet | `ApproveAgentParams` |
| `approveBuilderFee` | Approve builder fee | `{}` (empty) |
| `setReferrer` | Set the account's referrer code (Hyperliquid, Lighter, and Ondo setup action) | `{}` (empty) |
| `accountMode` | Switch the account's operating mode. Read the provider descriptor for its allowed signer and values. | `AccountModeParams` |
| `accountType` | Switch the account's fee/latency tier (e.g. Lighter standard/premium). Omitted by providers with no tiering. | `AccountTypeParams` |
| `registerApiKey` | Register or rotate an API-key slot. Lighter: registers an on-chain key at a numbered slot (`RegisterApiKeyParams`). Ondo: a client-only session step that creates a venue trading key | Lighter: `RegisterApiKeyParams`; Ondo: `{}` (empty) |
| `siweLogin` | Exchange a wallet signature over a backend-issued ERC-4361 challenge for a client-held venue session | `{}` (empty) |
| `createDepositAddress` | Provision the provider-managed deposit address through a client-only session step | `{}` (fixed policy marker in the response) |
| `acceptProviderTerms` | Record acceptance of venue terms through the client-held session | `{}` (empty) |
| `sendAsset` | Transfer assets between sub-exchanges | `SendAssetParams` |
| `metaVote` | Provider-independent: cast a signed vote for a registered but inactive provider (sent with the `META_PROVIDER` sentinel) | `VoteParams` |
| `metaAcceptTerms` | Provider-independent: record signed acceptance of the current Terms of Service (sent with the `META_PROVIDER` sentinel) | `AcceptTermsParams` |
### MarketRef
Many action params use a `market` field with the `MarketRef` type:
| Field | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `marketId` | `string` | Yes | Provider's canonical, stringified market id that uniquely identifies the trading instrument (e.g., `"BTC"`, `"xyz:PURR"`, `"@142"`; numeric on Lighter) |
| `categoryId` | `string` | Yes | Provider category id (e.g., `"hyperliquid"`, `"xyz"`, `"spot"`) |
### PlaceOrderParams
| Field | Type | Required | Description |
| ------------- | ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `market` | `MarketRef` | Yes | Target market |
| `side` | `string` | Yes | `BUY` or `SELL` |
| `type` | `string` | Yes | `OrderType` — one of `MARKET`, `LIMIT`, `STOP_MARKET`, `STOP_LIMIT`, `TAKE_PROFIT_MARKET`, `TAKE_PROFIT_LIMIT`, `TRIGGER_ONLY`. Required — there is no default order type. |
| `size` | `string` | Yes | Order size |
| `price` | `string` | Yes | Limit price (LIMIT) or slippage limit (MARKET). Required. |
| `leverage` | `integer` | No | Leverage to set — integer ≥ 1 (generates `updateLeverage` action if different). Some providers require it when `marginMode` is set. |
| `marginMode` | `'ISOLATED' \| 'CROSS'` | No | Margin mode for the position. Optional — the default when omitted **differs per provider** (see the provider's section). Set explicitly to be unambiguous across providers. |
| `reduceOnly` | `boolean` | No | Only reduce position (default `false`) |
| `timeInForce` | `string` | No | `GTC` (default), `IOC`, `POST_ONLY`, `GTT` |
| `expiresAt` | `string` | No | Unix ms timestamp expiry for GTT orders |
| `takeProfit` | `TriggerOrderInput` | No | Take profit trigger |
| `stopLoss` | `TriggerOrderInput` | No | Stop loss trigger |
`TriggerOrderInput`:
| Field | Type | Required | Description |
| -------------- | -------- | -------- | ------------------------------------------------------------------------------------------- |
| `triggerPrice` | `string` | Yes | Price at which the order triggers |
| `limitPrice` | `string` | No | Execution limit price (market order if omitted) |
| `size` | `string` | No | Fixed base-asset close size. Omit to cover the whole position and track later size changes. |
### PlaceTriggerOrderParams
Place standalone TP/SL on an existing position.
| Field | Type | Required | Description |
| ------------ | ------------------- | -------- | ------------------- |
| `market` | `MarketRef` | Yes | Target market |
| `side` | `string` | Yes | `BUY` or `SELL` |
| `takeProfit` | `TriggerOrderInput` | No | Take profit trigger |
| `stopLoss` | `TriggerOrderInput` | No | Stop loss trigger |
### PlaceTwapOrderParams
Place a TWAP parent order that executes over a fixed duration. `market`, `side`, `size`, `durationSeconds`, and `reduceOnly` are provider-independent; the remaining fields are extras honoured only by the provider that advertises them on its `placeTwapOrder` action's `params` descriptors (`GET /providers`) — a provider that does not advertise an extra ignores it.
| Field | Type | Required | Description |
| ------------------ | ----------- | -------- | -------------------------------------------------------------------------- |
| `market` | `MarketRef` | Yes | Target market |
| `side` | `string` | Yes | `BUY` or `SELL` |
| `size` | `string` | Yes | Total base-asset size executed across the TWAP's lifetime |
| `durationSeconds` | `integer` | Yes | Total execution window in seconds |
| `reduceOnly` | `boolean` | No | Only reduce position (default `false`) |
| `randomize` | `boolean` | No | Hyperliquid extra — randomize sub-order timing within the execution window |
| `frequencySeconds` | `integer` | No | Ondo extra — interval between child orders in seconds |
| `minPrice` | `string` | No | Ondo extra — lowest acceptable child-order price |
| `maxPrice` | `string` | No | Ondo extra — highest acceptable child-order price |
### CancelOrderParams
| Field | Type | Required | Description |
| --------- | ---------- | -------- | ------------------------------------------------------------------------------ |
| `ids` | `string[]` | Yes | Order IDs to cancel; market-scoped venues also accept `:` |
| `assetId` | `string` | No | Market id context for venues whose order ids are scoped per market |
### CancelTwapOrderParams
| Field | Type | Required | Description |
| -------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `market` | `MarketRef` | Yes | Target market — required by every provider's cancel wire even where the TWAP id is globally unique |
| `twapId` | `string` | Yes | Provider-native TWAP identifier: Hyperliquid's numeric id, Ondo's `twap_`-prefixed id, or Lighter's order index (scoped per market) |
### ModifyOrderParams
| Field | Type | Required | Description |
| --------------- | -------------------- | -------- | ---------------------- |
| `modifications` | `ModifyOrderInput[]` | Yes | Array of modifications |
Each `ModifyOrderInput`:
| Field | Type | Required | Description |
| -------------- | -------- | -------- | ----------------------- |
| `id` | `string` | Yes | Order ID to modify |
| `price` | `string` | No | New limit price |
| `size` | `string` | No | New order size |
| `triggerPrice` | `string` | No | New trigger price |
| `limitPrice` | `string` | No | New trigger limit price |
### UpdateLeverageParams
| Field | Type | Required | Description |
| ------------ | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `market` | `MarketRef` | Yes | Target market |
| `leverage` | `integer` | Yes | New leverage value (integer ≥ 1) |
| `marginMode` | `'ISOLATED' \| 'CROSS'` | No | Margin mode to apply alongside the leverage change. Optional — the default when omitted **differs per provider** (see the provider's section). |
### UpdatePositionMarginParams
| Field | Type | Required | Description |
| -------- | ----------- | -------- | ----------------- |
| `market` | `MarketRef` | Yes | Target market |
| `action` | `string` | Yes | `add` or `remove` |
| `amount` | `string` | Yes | Margin amount |
### WithdrawalParams
| Field | Type | Required | Description |
| ------------- | ------------------- | -------- | ------------------------------------------------------------------------ |
| `destination` | `string` | Yes | Destination address (e.g. Arbitrum L1 for Hyperliquid) |
| `amount` | `string` | Yes | Human-readable amount in the selected asset's units |
| `assetId` | `string` | No | Provider-native asset id for row-based withdrawals (for example Lighter) |
| `route` | `'perps' \| 'spot'` | No | Balance route paired with `assetId`; provider-specific |
### ApproveAgentParams
| Field | Type | Required | Description |
| -------------- | -------- | -------- | ---------------------------------- |
| `agentAddress` | `string` | Yes | Agent wallet address to authorize |
| `agentTtlMs` | `number` | No | Agent approval TTL in milliseconds |
### AccountModeParams
Generic account-level operating-mode switch (e.g. Hyperliquid abstraction variants, Lighter UTA / Simple). The accepted `mode` values are provider-specific — read them from the corresponding `setup` / `options` descriptor on `GET /providers` (the descriptor's `params[].values` array enumerates them). `@lifi/perps-types` intentionally does not encode the per-provider value list, so providers can add new modes without a types release.
| Field | Type | Required | Description |
| ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `mode` | `string` | Yes | Provider-specific mode identifier; use the descriptor's `params[].values` instead of hard-coding values |
### AccountTypeParams
Generic account-level fee/latency tier switch (e.g. Lighter standard / premium). Providers without tiering omit the action entirely.
| Field | Type | Required | Description |
| ------ | -------- | -------- | --------------------------------- |
| `tier` | `string` | Yes | Provider-specific tier identifier |
### CancelAllOrdersParams
| Field | Type | Required | Description |
| ------------- | -------- | -------- | -------------------------------------------------------------------- |
| `timeInForce` | `number` | Yes | `0` = immediate (cancel GTC), `1` = scheduled, `2` = abort scheduled |
| `timestampMs` | `number` | No | Unix milliseconds (required for scheduled cancels) |
### RegisterApiKeyParams
| Field | Type | Required | Description |
| ---------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKeyIndex` | `number` | Yes | API-key slot index to register (0-255). Reusing a fixed slot overwrites the old key. |
| `knownPublicKey` | `string` | No | The SDK's currently-stored Lighter public key for this slot, if any. The backend reports the slot already satisfied only when this matches the on-chain pubkey; otherwise it stages a ChangePubKey blob. Omit when the SDK has no local key. |
### DepositParams
| Field | Type | Required | Description |
| -------------- | -------- | -------- | ------------------------------------------------------- |
| `amount` | `string` | Yes | Human-readable token amount (e.g. `"100.5"`) |
| `tokenAddress` | `string` | Yes | ERC-20 token address on the source chain |
| `chainId` | `number` | Yes | Source chain ID declared by the provider's deposit flow |
### SendAssetParams
| Field | Type | Required | Description |
| ---------------- | -------- | -------- | ------------------------ |
| `collateral` | `string` | Yes | Collateral type |
| `sourceDex` | `string` | Yes | Source sub-exchange |
| `destinationDex` | `string` | Yes | Destination sub-exchange |
| `amount` | `string` | Yes | Amount to transfer |
### Response `201`
```json theme={null}
{
"actions": [
{
"action": "updateLeverage",
"typedData": {
"domain": { "..." },
"types": { "..." },
"primaryType": "...",
"message": { "..." }
}
},
{
"action": "placeOrder",
"typedData": { "..." }
}
]
}
```
`ActionStep` is a **discriminated union** by structural shape — the variant depends on the action's `signingMethod` on the provider descriptor:
| Variant | Discriminating key | Description |
| -------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Eip712ActionStep` | `typedData` | EIP-712 typed data to sign (Hyperliquid and other EVM dexes) |
| `WasmBlobActionStep` | `wasmSignParams` | Parameters for the provider's WASM signer (Lighter and zk-rollup dexes) |
| `EvmTxActionStep` | `txParams` | On-chain EVM transaction the SDK submits (e.g. Lighter `deposit`) |
| `HmacActionStep` | `request` | Unsigned venue request `{ method, path, body }` the SDK HMAC-signs client-side (Ondo trading actions) |
| `SiweActionStep` | `siwe` | ERC-4361 login challenge `{ challengeId, message }` the wallet must `personal_sign` (Ondo `siweLogin`) |
| `SessionActionStep` | `session` | Client-only marker. `createDepositAddress` carries fixed network/asset/destination policy; other session steps use an empty object. |
All variants carry the same `action` field (the `ActionType` from the request). The example above shows the EIP-712 variant; the `wasmBlob` variant carries `wasmSignParams` and the `evmTx` variant (e.g. `deposit`) carries `txParams` in place of `typedData`. `HmacActionStep` and `SiweActionStep` are signed and submitted via `executeAction`; a `SessionActionStep` carries no signable material — the SDK performs the venue call directly with its session token and skips `executeAction`.
### Response `400`
Validation error.
***
## POST /executeAction
Submit signed payloads from `/createAction`.
```
POST /v1/perps/executeAction
```
### Request Body
```json theme={null}
{
"provider": "hyperliquid",
"address": "0x1234567890abcdef1234567890abcdef12345678",
"action": "placeOrder",
"actions": [
{
"action": "updateLeverage",
"typedData": { "...typedData from createAction..." },
"signature": "0xabcd1234..."
},
{
"action": "placeOrder",
"typedData": { "...typedData from createAction..." },
"signature": "0xefgh5678..."
}
]
}
```
| Field | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | `string` | Yes | Provider identifier |
| `address` | `string` | Yes | User's wallet address (account owner) |
| `signerAddress` | `string` | No | Address that signed an address-based payload. Provider plugins populate SDK-managed signer addresses; user-signed actions default to `address`. |
| `action` | `string` | Yes | Action type from the create request |
| `actions` | `SignedActionStep[]` | Yes | Signed actions from `/createAction` |
`SignedActionStep` mirrors `ActionStep` as a discriminated union — each variant carries the original payload plus its signed artefact:
| Variant | Fields |
| -------------------------- | ------------------------------------------------------------------ |
| `Eip712SignedActionStep` | `action`, `typedData`, `signature` (hex) |
| `WasmBlobSignedActionStep` | `action`, `wasmSignParams`, `signedTx: { txType, txInfo, txHash }` |
| `EvmTxSignedActionStep` | `action`, `txParams`, `txHash` (on-chain) |
| `HmacSignedActionStep` | `action`, `request`, `hmac: { keyId, timestampMs, signature }` |
| `SiweSignedActionStep` | `action`, `siwe`, `signature` (hex `personal_sign`) |
The example above shows the EIP-712 variant. Submit signed steps in the same shape and order they were returned by `/createAction`. `SessionActionStep`s are not submitted here — they carry no signable material, so the SDK executes them client-side against the venue and skips `/executeAction`.
### Response `202`
```json theme={null}
{
"results": [
{
"action": "updateLeverage",
"success": true
},
{
"action": "placeOrder",
"success": true,
"orderId": "12345678"
}
]
}
```
Each `ActionResult`:
| Field | Type | Description |
| -------------- | --------- | ----------------------------------------------------------------------------------- |
| `action` | `string` | Action type |
| `success` | `boolean` | Whether the action was accepted |
| `orderId` | `string?` | Order ID on a successful order action |
| `twapId` | `string?` | Provider-native identifier for a placed TWAP parent order |
| `txHash` | `string?` | Venue transaction hash when known at submission time |
| `explorerLink` | `string?` | Fully resolved explorer URL for `txHash`, when configured |
| `error` | `string?` | Error message on a failed result |
| `errorCode` | `number?` | Structured numeric `PerpsErrorCode`, when provided. See [Error Codes](/error-codes) |
### Response `400`
Validation error.
### Response `401`
Authentication error (invalid signature).
### Response `422`
Insufficient margin for the order.
***
## Order details (SDK)
Single-order lookup is served by the SDK directly from each provider via `getOrder` — there is no LI.FI HTTP endpoint. The returned `Order` shape:
```json theme={null}
{
"orderId": "12345678",
"market": {
"providerId": "hyperliquid",
"id": "BTC",
"categoryId": "hyperliquid",
"baseAsset": { "providerId": "hyperliquid", "id": "BTC", "displaySymbol": "BTC", "logoURI": "https://assets.li.fi/tokens/btc.png" },
"quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }
},
"side": "BUY",
"type": "MARKET",
"price": "95500.00",
"originalSize": "0.1",
"remainingSize": "0.0",
"filledSize": "0.1",
"timeInForce": "GTC",
"reduceOnly": false,
"isTrigger": false,
"status": "FILLED",
"averagePrice": "95050.00",
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-15T10:30:01Z"
}
```
### Order Schema
| Field | Type | Description |
| ------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orderId` | `string` | Order ID |
| `market` | `MarketDisplay` | Market reference (`providerId`, `id`, `categoryId`, base/quote `Asset`) — see [MarketDisplay](/api-reference/account#marketdisplay) |
| `side` | `string` | `BUY` or `SELL` |
| `type` | `string` | `MARKET`, `LIMIT`, `STOP_MARKET`, `STOP_LIMIT`, `TAKE_PROFIT_MARKET`, `TAKE_PROFIT_LIMIT`, `TRIGGER_ONLY`, `TWAP` (read-side only — a running TWAP parent/child surfaced in the venue's order feed) |
| `price` | `string` | Limit price or execution price |
| `originalSize` | `string` | Original order size |
| `remainingSize` | `string` | Unfilled quantity |
| `filledSize` | `string` | Filled quantity |
| `timeInForce` | `string` | `GTC`, `IOC`, `POST_ONLY`, `GTT` |
| `expiresAt` | `string` | Expiration time (GTT orders) |
| `reduceOnly` | `boolean` | Whether reduce-only |
| `isTrigger` | `boolean` | Whether this is a trigger order (TP/SL) |
| `triggerPrice` | `string` | Trigger activation price |
| `triggerCondition` | `string` | `ABOVE` or `BELOW` |
| `status` | `string` | Order status (see below) |
| `statusReason` | `string` | Human-readable reason for a terminal non-`FILLED` status; absent when there is no actionable detail |
| `averagePrice` | `string` | Average fill price |
| `createdAt` | `string` | ISO 8601 creation timestamp |
| `updatedAt` | `string` | ISO 8601 last update timestamp |
### Order Status Values
| Status | Description |
| ------------------ | ------------------------------- |
| `PENDING` | Submitted, not yet on orderbook |
| `OPEN` | Resting on orderbook |
| `PARTIALLY_FILLED` | Some quantity filled |
| `FILLED` | Fully filled |
| `CANCELLED` | Cancelled by user |
| `REJECTED` | Rejected by provider |
| `EXPIRED` | GTT order expired |
| `TRIGGERED` | Trigger order activated (TP/SL) |
**SDK:** [`getOrder()`](/sdk/trading/order-status)