Actions API - @lifi/perps-sdk

All mutating operations follow the create -> authorize -> execute pattern through two unified endpoints. The action field determines the operation.

These endpoints are intended to be used via @lifi/perps-sdk. The SDK is the supported integration path: it satisfies setup steps, exposes the recommended option of each choice without applying it, runs the steps in sequence, and makes the client-side venue calls. If you cannot use the SDK, see Integrating without the SDK.

Each provider action declares a relay in GET /providers. Submit a signed step to POST /executeAction only when its action declares relay: API. A step with relay: CLIENT goes from the client to the venue, and nothing reaches LI.FI. See Integrating without the SDK for each CLIENT step.

POST /createAction

Build provider-specific authorization steps. Signed EIP-712, WASM, EVM, and HMAC steps continue to POST /executeAction; a SiweActionStep or a client-only session step is completed directly by the provider plugin and never submitted to /executeAction. Every provider action requires the address to have accepted the current terms. Until it has, createAction and executeAction fail with 401 / 2012 (TermsNotAccepted). Accept them first with metaAcceptTerms or metaOnboard, sent with provider: "meta".

POST /v1/perps/createAction

Request Body

{
  "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": { "type": "MARKET", "triggerPrice": "100000.00" },
    "stopLoss": { "type": "LIMIT", "triggerPrice": "90000.00", "limitPrice": "89800.00" }
  }
}

Request Fields

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier (e.g. `hyperliquid`), or the literal `"meta"` for `metaAcceptTerms`, `metaOnboard`, and `metaCreateReferralCode`
`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

provider: "meta" routes metaAcceptTerms, metaOnboard, and metaCreateReferralCode to a provider-independent handler instead of a venue plugin. No other action accepts the "meta" provider.

Action Types

Action	Description	Params
`revokeAgent`	Deregister an existing agent to free an agent slot (Hyperliquid). The backend picks the agent.	`{}` (empty)
`revokeSessionAgent`	Remove the session agent the SDK signs with (Hyperliquid). The `revoke` action of `approveAgent`.	`{ agentAddress }`
`revokeBuilderFee`	Revoke the builder fee approval (Hyperliquid). The `revoke` action of `approveBuilderFee`.	`{}` (empty)
`revokeIntegrator`	Revoke the integrator approval (Lighter). The `revoke` action of `approveIntegrator`.	`{}` (empty)
`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`
`updateAssetCollateral`	Opt a spot asset in or out of the cross-margin collateral pool (Lighter unified account)	`UpdateAssetCollateralParams`
`withdrawal`	Withdraw funds	`WithdrawalParams`
`transfer`	Internal L2 transfer used by Lighter’s fastwithdraw flow. Internal-only — no public flow sends this action directly.	`{}` (internal)
`deposit`	Fund the account via an L1 bridge transaction	`DepositParams`
`approveAgent`	Authorize an agent wallet	`ApproveAgentParams`
`approveBuilderFee`	Approve builder fee	`{}` (empty)
`approveIntegrator`	Sign a one-time on-chain approval authorizing LI.FI’s integrator account to collect its fee on the account’s trades, up to a maximum rate (Lighter setup action)	`{}` (empty)
`setReferrer`	Set the account’s referrer code (Hyperliquid, Lighter, and Ondo setup action)	`{}` (empty)
`approveReadOnlyToken`	Create a long-lived Lighter read-only token authorizing authenticated read endpoints (orders, fills, activity history). Client-only: performed by the SDK and never sent to this endpoint.	`ApproveReadOnlyTokenParams` (`{ accountIndex, expirySeconds, scope: 'single' \| 'all' }`); not sent to `POST /createAction`
`accountMode`	Switch the account’s operating mode. A choice step: each option on the setup step binds its `mode` value.	`AccountModeParams`
`accountType`	Switch the Lighter account tier (`plus` or `premium`). A choice step: each option on the setup step binds its `tier` value. 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)
`addWithdrawalAddress`	Add the login address to the venue’s withdrawal address book (Ondo). Client-only session step	`{}` (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`
`metaAcceptTerms`	Provider-independent: record signed acceptance of the current Terms of Service (sent with `provider: "meta"`)	`{}` (empty — the accepted terms version is backend-owned, not client-supplied)
`metaOnboard`	Provider-independent: accept the current Terms of Service and, optionally, attach an internal referral code, in one signature (sent with `provider: "meta"`)	`OnboardParams`
`metaCreateReferralCode`	Provider-independent: reserve the shareable internal referral code an address owns (sent with `provider: "meta"`)	`CreateReferralCodeParams`

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`	Varies	`OrderType` — one of `MARKET`, `LIMIT`, `STOP_MARKET`, `STOP_LIMIT`, `TAKE_PROFIT_MARKET`, `TAKE_PROFIT_LIMIT`. Required on Hyperliquid. Optional on Lighter and Ondo, where an omitted value defaults to `LIMIT`. Lighter accepts the trigger types only through `placeTriggerOrder` or `takeProfit`/`stopLoss`, and spot allows only `MARKET` and `LIMIT`. Ondo supports `MARKET` and `LIMIT` only.
`size`	`string`	Yes	Order size
`price`	`string`	Varies	Limit price (LIMIT) or slippage limit (MARKET). Required on Hyperliquid and Lighter; optional on Ondo.
`leverage`	`number`	No	Leverage to set, at least 1. Hyperliquid and Ondo accept integers. Lighter accepts up to `Provider.leveragePrecision` decimal places. When provided, an `updateLeverage` action is always generated ahead of the order; it is never compared with the current setting.
`marginMode`	`'ISOLATED' \| 'CROSS'`	No	Margin mode for the position. Not defaulted. Hyperliquid requires `leverage` alongside it and rejects `marginMode` without `leverage`. 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
`type`	`string`	Yes	`MARKET` or `LIMIT`. The execution kind of the leg. The `takeProfit` or `stopLoss` key gives the TP or SL kind. A leg without `type` returns a `400`.
`triggerPrice`	`string`	Yes	Price at which the order triggers
`limitPrice`	`string`	Varies	The price limit of the execution. For `LIMIT`, it is the resting limit price. For `MARKET`, it is the slippage-adjusted limit price, on providers that take one. See the table below.
`size`	`string`	No	Fixed base-asset close size. Omit to cover the whole position and track later size changes.

Each provider reads type and limitPrice as follows:

Provider	`MARKET` leg	`LIMIT` leg
Hyperliquid	Takes no `limitPrice`. A `limitPrice` returns a `400`.	Requires `limitPrice`: the resting limit price. Without it, the request returns a `400`.
Lighter	Requires `limitPrice`: the slippage-adjusted limit price. It needs a value strictly below `triggerPrice` on a `SELL` leg and strictly above `triggerPrice` on a `BUY` leg.	Requires `limitPrice`: the resting limit price.
Ondo	Takes no `limitPrice`. A `limitPrice` returns a `400`.	Not supported. Returns a `400`.

The backend does no slippage calculation. To calculate the limitPrice of a Lighter MARKET leg, see Trigger Orders.

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. Bounds vary by provider: Hyperliquid `300`–`604800` (5 minutes–7 days), in multiples of `60`; Lighter `300`–`2592000` (5 minutes–30 days); Ondo `300`–`86400` (5 minutes–24 hours)
`reduceOnly`	`boolean`	No	Only reduce position (default `false`)
`randomize`	`boolean`	No	Hyperliquid extra — randomize each sub-order’s size by up to ±20%
`frequencySeconds`	`integer`	No	Ondo extra — interval between child orders in seconds. Range `1`–`86400`
`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 `<market_id>:<order_id>`. Lighter caps this array at `100` ids per call; Hyperliquid and Ondo impose no cap
`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). On Lighter this must be digits only, up to 20 characters

ModifyOrderParams

Lighter requires id and size on every modification. It also requires a price: price for a regular order, or limitPrice for a trigger order. A Lighter modify transaction replaces the resting order wholesale. Lighter accepts 1 to 100 modifications per call. Lighter rejects type and rejects a modification that has both price and limitPrice.

Field	Type	Required	Description
`modifications`	`ModifyOrderInput[]`	Yes	Array of modifications. Lighter accepts `1` to `100` items
`assetId`	`string`	No	Lighter only. Market context for a bare order id in `modifications[].id`; the market’s `id`

Each ModifyOrderInput:

Field	Type	Required	Description
`id`	`string`	Yes	Order ID to modify
`type`	`string`	No	`MARKET` or `LIMIT`. The new execution kind of a trigger order. Hyperliquid applies it. Without `type`, the modify keeps the kind of the existing order. Lighter rejects `type` with a `400`, because a Lighter modify cannot change the order type.
`price`	`string`	Varies	New limit price of a regular order. Lighter requires `price` or `limitPrice`, not both
`size`	`string`	Varies	New order size. Required on Lighter
`triggerPrice`	`string`	No	New trigger price
`limitPrice`	`string`	No	The new price limit of the execution of a trigger order. For `LIMIT`, it is the resting limit price. For `MARKET`, it is the slippage-adjusted limit price, on providers that take one. Hyperliquid rejects it when the result is a `MARKET` trigger order. Hyperliquid also requires it on a change from `MARKET` to `LIMIT`. Lighter signs it as the price of a trigger order.

UpdateLeverageParams

Field	Type	Required	Description
`market`	`MarketRef`	Yes	Target market
`leverage`	`number`	Yes	New leverage value, at least 1. Hyperliquid and Ondo accept integers. Lighter accepts up to `Provider.leveragePrecision` decimal places
`marginMode`	`'ISOLATED' \| 'CROSS'`	No	Margin mode to apply alongside the leverage change. Not defaulted: when omitted on Hyperliquid, the venue receives isolated.

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
`accountId`	`string`	Ondo: Yes	Ondo only. Digits string, 1–20 characters. The SDK populates it
`source`	`{ categoryId, asset: { id } }`	No	The holding to withdraw from. Omitted withdraws from the venue’s default holding. Hyperliquid accepts `categoryId` `hyperliquid` or `spot`, Lighter accepts `perps` or `spot`, and Ondo accepts only `ondo` with `asset.id` `USDC`
`withdrawalOptions`	`object`	No	Provider options, taken unchanged from `getWithdrawalTypes`. Lighter accepts `{ mode: 'standard' }` or `{ mode: 'fast', toAccountIndex, fee }`

Lighter also accepts the legacy assetId and route fields, and rejects them together with source.

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 (Hyperliquid: disabled, unifiedAccount, portfolioMargin; Lighter: simpleTradingAccount, unifiedTradingAccount). The accepted mode values are provider-specific — read them from the params.mode of each entry in the options array of the corresponding setup step on GET /providers. @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 `params.mode` of the chosen option instead of hard-coding values

AccountTypeParams

Generic account-level fee tier switch (Lighter plus or premium). Providers without tiering omit the action entirely.

Field	Type	Required	Description
`tier`	`string`	Yes	Provider-specific tier identifier

RevokeAgentParams

{}. The backend selects the target agent: LI.FI’s own leftover agent first, otherwise the earliest-expiring named agent. It returns no step when an agent slot is already free.

UpdateAssetCollateralParams

Field	Type	Required	Description
`assetId`	`string`	Yes	Provider-native spot asset id
`enabled`	`boolean`	Yes	Whether the asset counts toward the cross-margin collateral pool

OnboardParams

Field	Type	Required	Description
`termsVersion`	`string`	No	Terms version being accepted
`referralCode`	`string`	No	Internal referral code to attach

CreateReferralCodeParams

Field	Type	Required	Description
`code`	`string`	Yes	Code to reserve: 4–20 characters from `A-Z`, `0-9` or `-`. The backend does not generate one

CancelAllOrdersParams

Field	Type	Required	Description
`timeInForce`	`number`	Yes	`0` = immediate (cancel GTC), `1` = scheduled, `2` = abort scheduled. Ondo only accepts `0`
`timestampMs`	`number`	No	Unix milliseconds (required for scheduled cancels)

RegisterApiKeyParams

Field	Type	Required	Description
`knownPublicKey`	`string`	No	The SDK’s currently-stored Lighter public key, if any. The backend returns no ChangePubKey step (already satisfied) only when this matches the on-chain pubkey at the slot it selects; otherwise it stages a ChangePubKey blob. Omit when the SDK has no local key. Hex string, with or without a `0x` prefix.

DepositParams

Field	Type	Required	Description
`amount`	`string`	Yes	Amount in the token’s smallest unit as an integer string, e.g. `"100500000"` for 100.5 USDC. Convert with `parseUnits(humanAmount, decimals).toString()`; use `flow.collateral.decimals` from `getDepositFlow`
`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`	Varies	Collateral asset id (the token index string from `Asset.id`). Required on Hyperliquid; ignored on Lighter, where the transferred asset is fixed to USDC by protocol
`sourceDex`	`string`	Yes	Source category. Hyperliquid: a category id (`hyperliquid`, `xyz`, `spot`, …). Lighter: `perps` or `spot`
`destinationDex`	`string`	Yes	Destination category. Hyperliquid: a category id (`hyperliquid`, `xyz`, `spot`, …). Lighter: `perps` or `spot`
`amount`	`string`	Yes	Amount to transfer

Response `201`

In this example, each typedData value is a string placeholder. The real value is an EIP-712 object with the keys domain, types, primaryType, and message.

{
  "actions": [
    {
      "action": "updateLeverage",
      "typedData": "<EIP-712 typed data object>"
    },
    {
      "action": "placeOrder",
      "typedData": "<EIP-712 typed data object>"
    }
  ]
}

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 }`. HMAC-signed client-side and submitted via `executeAction` for Ondo trading actions; Ondo’s `setReferrer` reuses this shape but is `session`-signed instead — see below.
`SiweActionStep`	`siwe`	ERC-4361 login challenge `{ challengeId, message }` the wallet must `personal_sign` (Ondo `siweLogin`). The signed challenge is exchanged for a venue session client-side and is never submitted to `/executeAction`.
`SessionActionStep`	`session`	Client-only marker, `{ action, session }`. Ondo `createDepositAddress` carries a fixed network/asset/destination policy in `session`; `acceptProviderTerms`, `registerApiKey`, and `addWithdrawalAddress` carry an empty `session: {}`.

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 is signed and submitted via executeAction. SiweActionStep and SessionActionStep carry no material submitted to executeAction: a signed SiweActionStep is exchanged for a venue session client-side, and a SessionActionStep carries no signable material at all — the SDK performs the venue call directly with its session token in both cases and skips executeAction. Ondo’s setReferrer is session-signed like a SessionActionStep, but is wire-shaped as a request-bearing HmacActionStep — the SDK submits its request directly with the session credential instead of HMAC-signing it, and also skips executeAction.

Responses

Status	Meaning
`400`	Validation error
`401`	Authentication error — invalid signature, invalid API key, or terms not accepted (`2012`)
`404`	Market not found
`409`	Setup required, or the nonce was already used
`422`	Insufficient margin
`424`	An upstream provider or dependency failed
`429`	Rate limit exceeded — see rate limit headers

POST /executeAction

Submit signed payloads from /createAction.

POST /v1/perps/executeAction

Request Body

In this example, each typedData value is a string placeholder for the typedData object that /createAction returned for the same step. Each signature value is a placeholder for the hex signature of that object.

{
  "provider": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "action": "placeOrder",
  "actions": [
    {
      "action": "updateLeverage",
      "typedData": "<typedData from createAction>",
      "signature": "<hex signature of typedData>"
    },
    {
      "action": "placeOrder",
      "typedData": "<typedData from createAction>",
      "signature": "<hex signature of typedData>"
    }
  ]
}

Field	Type	Required	Description
`provider`	`string`	Yes	Provider identifier, or the literal `"meta"` for `metaAcceptTerms`, `metaOnboard`, and `metaCreateReferralCode`
`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 }`, `clientOrderIndex` (optional, present only when the step places an order)
`EvmTxSignedActionStep`	`action`, `txParams`, `txHash` (on-chain)
`HmacSignedActionStep`	`action`, `request`, `hmac: { keyId, timestampMs, signature }`

The example above shows the EIP-712 variant. Submit signed steps in the same shape and order they were returned by /createAction. SiweSignedActionStep (action, siwe, signature hex personal_sign) and SessionActionSteps are not submitted here — the SDK exchanges a signed SiweSignedActionStep for a venue session client-side, and a SessionActionStep carries no signable material at all; both skip /executeAction. Submitting action: 'siweLogin' to /executeAction is rejected with 400/2002 (ValidationError).

Response `202`

The backend returns 202 Accepted with one ActionResult for every step that it attempted. Three separate axes describe the outcome:

Axis	Where	What it tells you
HTTP status	Response status line	The backend processed the request. `202` does not mean that the venue accepted a step.
Action status	`results[i].status`	How far that step went. See Statuses.
Error cause	`results[i].errorCode` and `results[i].error`	Why a step failed or is uncertain, for example `TimeoutError` (`2003`).

{
  "results": [
    {
      "action": "updateLeverage",
      "status": "submitted"
    },
    {
      "action": "placeOrder",
      "status": "submitted",
      "orderId": "12345678"
    }
  ]
}

Each ActionResult:

Field	Type	Description
`action`	`string`	Action type
`status`	`string`	`submitted`, `accepted`, `indeterminate` or `failed`. See Statuses
`orderId`	`string?`	Order ID when the step placed an order
`twapId`	`string?`	Provider-native identifier for a placed TWAP parent order
`txHash`	`string?`	Venue transaction hash, present only where the venue’s hash is known at submission time
`explorerLink`	`string?`	Fully resolved explorer URL for `txHash`, when configured
`error`	`string?`	Set unless `status` is `submitted` or `accepted`
`errorCode`	`number?`	The cause of the failure or uncertainty, as a numeric `PerpsErrorCode`, when classified. See Error Codes

There is no boolean success field. Read status.

Statuses

The lifecycle has five values. created is a stored state that never appears in a result.

Status	Meaning	What to do
`created`	An unsigned intent. Nothing went to the venue.	Not returned. A step that was not attempted has no result.
`submitted`	The venue acknowledged the send. The acknowledgement is not proof, and the backend verifies the step later. Lighter and Hyperliquid return this status.	Treat the step as sent. Track the outcome with the account reads, for example Order Status.
`accepted`	The venue provably took and applied the step. Ondo can return this status in the response.	Treat the step as applied.
`indeterminate`	The send started and the venue gave no clear answer: a timeout, a transport failure, a 5xx answer, or an answer that the backend cannot read. The step can have taken effect. `error` ends with `Check your account history and positions before you retry.`	Read the account state first. Do not submit the action again until you know the result.
`failed`	The venue refused the step, or a check or claim failed before the backend sent a later step. Nothing was applied.	Read `error` and `errorCode`. You can correct the request and submit again.

A failed result with a classified cause is a confirmed rejection. After the backend verifies a step, the stored status of a submitted or indeterminate step can change to accepted or failed. The 202 response does not change after the backend sends it, and the API does not push this change to the caller.

Which steps have a result

The list holds only the steps that the backend attempted, in execution order. A step that was not attempted stays created and has no result.
Execution stops at the first step that is failed or indeterminate. Later steps stay created, so you can execute the remaining steps again. The backend refuses to execute an indeterminate step again, because the first send can have reached the venue.
Every member of an attempted atomic batch has its own result. Lighter sends an order and its trigger orders as one batch, so all of them share one status.
Two steps with the same action keep two results. Do not key the results by action.
Results of earlier acknowledged steps stay in the list after a later step fails.
If the first step fails before the backend sends it, the request returns an error response, for example 400 or 409, and not a list of results.

Examples

Acknowledged, then failed. The leverage step was sent. The order was refused because the margin was too low. The result for the leverage step stays in the report:

{
  "results": [
    {
      "action": "updateLeverage",
      "status": "submitted"
    },
    {
      "action": "placeOrder",
      "status": "failed",
      "error": "Insufficient margin to place order. Required 650.00 USDC, available 120.50 USDC.",
      "errorCode": 2021
    }
  ]
}

Acknowledged, then indeterminate. A Lighter order with leverage, a take-profit and a stop-loss. The leverage step was acknowledged. The venue did not answer the batch that holds the order and both trigger orders, so each member has its own indeterminate result:

{
  "results": [
    {
      "action": "updateLeverage",
      "status": "submitted"
    },
    {
      "action": "placeOrder",
      "status": "indeterminate",
      "error": "placeOrder was submitted to lighter but we could not confirm it was accepted. Check your account history and positions before you retry.",
      "errorCode": 2003
    },
    {
      "action": "placeTriggerOrder",
      "status": "indeterminate",
      "error": "placeTriggerOrder was submitted to lighter but we could not confirm it was accepted. Check your account history and positions before you retry.",
      "errorCode": 2003
    },
    {
      "action": "placeTriggerOrder",
      "status": "indeterminate",
      "error": "placeTriggerOrder was submitted to lighter but we could not confirm it was accepted. Check your account history and positions before you retry.",
      "errorCode": 2003
    }
  ]
}

Handle every result. Do not read only the first result, do not combine the results into one success flag, and do not resubmit the action when a result is indeterminate:

for (const result of results) {
  switch (result.status) {
    case 'submitted':
    case 'accepted':
      // The venue acknowledged this step.
      break
    case 'indeterminate':
      // The step may have taken effect. Read the account state first.
      break
    case 'failed':
      // The venue refused the step. result.error and result.errorCode say why.
      break
  }
}

Responses

Status	Meaning
`400`	Validation error
`401`	Authentication error — invalid signature, invalid API key, or terms not accepted (`2012`)
`409`	Setup required, or the nonce was already used
`410`	The signed payload’s nonce/deadline expired — rebuild and re-sign the action
`422`	Insufficient margin for the order
`424`	An upstream provider or dependency failed
`429`	Rate limit exceeded — see rate limit headers

Order details (SDK)

Single-order lookup is served by the SDK directly from each provider via getOrder — there is no LI.FI HTTP endpoint. It returns an Order, the same union getOrders returns:

{
  "type": "MARKET",
  "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": "0", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }
  },
  "side": "BUY",
  "status": "FILLED",
  "price": "95500.00",
  "originalSize": "0.1",
  "remainingSize": "0.0",
  "filledSize": "0.1",
  "averagePrice": "95050.00",
  "timeInForce": "GTC",
  "reduceOnly": false,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:01Z"
}

Order is RegularOrder | TriggerOrder | TwapOrder, discriminated on type. Trigger orders add triggerPrice, triggerCondition, and limitPrice?; regular orders carry price?, timeInForce, and expiresAt?; TWAP orders carry durationSeconds and startedAt. See Order fields, OrderType, and OrderStatus for the full field and status tables. SDK: getOrder()

​POST /createAction

​Request Body

​Request Fields

​Action Types

​MarketRef

​PlaceOrderParams

​PlaceTriggerOrderParams

​PlaceTwapOrderParams

​CancelOrderParams

​CancelTwapOrderParams

​ModifyOrderParams

​UpdateLeverageParams

​UpdatePositionMarginParams

​WithdrawalParams

​ApproveAgentParams

​AccountModeParams

​AccountTypeParams

​RevokeAgentParams

​UpdateAssetCollateralParams

​OnboardParams

​CreateReferralCodeParams

​CancelAllOrdersParams

​RegisterApiKeyParams

​DepositParams

​SendAssetParams

​Response 201

​Responses

​POST /executeAction

​Request Body

​Response 202

​Statuses

​Which steps have a result

​Examples

​Responses

​Order details (SDK)

POST /createAction

Request Body

Request Fields

Action Types

MarketRef

PlaceOrderParams

PlaceTriggerOrderParams

PlaceTwapOrderParams

CancelOrderParams

CancelTwapOrderParams

ModifyOrderParams

UpdateLeverageParams

UpdatePositionMarginParams

WithdrawalParams

ApproveAgentParams

AccountModeParams

AccountTypeParams

RevokeAgentParams

UpdateAssetCollateralParams

OnboardParams

CreateReferralCodeParams

CancelAllOrdersParams

RegisterApiKeyParams

DepositParams

SendAssetParams

Response `201`

Responses

POST /executeAction

Request Body

Response `202`

Statuses

Which steps have a result

Examples

Responses

Order details (SDK)