Actions API

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. 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, 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.

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": { "triggerPrice": "100000.00" },
    "stopLoss": { "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)	`RevokeAgentParams`
`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.	`TransferParams` (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.	Not sent to `POST /createAction`
`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`
`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`, `TRIGGER_ONLY`. Required on Hyperliquid. Optional on Lighter and Ondo, where an omitted value defaults to `LIMIT`.
`size`	`string`	Yes	Order size
`price`	`string`	Varies	Limit price (LIMIT) or slippage limit (MARKET). Required on Hyperliquid and Lighter; optional on Ondo.
`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. 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 sub-order timing within the execution window
`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, price, and size on every modification — a Lighter modify transaction replaces the resting order wholesale — and rejects triggerPrice/limitPrice, since Lighter orders carry no trigger legs.

Field	Type	Required	Description
`modifications`	`ModifyOrderInput[]`	Yes	Array of modifications
`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
`price`	`string`	Varies	New limit price. Required on Lighter
`size`	`string`	Varies	New order size. Required on Lighter
`triggerPrice`	`string`	No	New trigger price. Rejected on Lighter
`limitPrice`	`string`	No	New trigger limit price. Rejected on Lighter

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. 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	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`	No	Collateral type. Accepted but ignored on Lighter, where the transferred asset is fixed to USDC by protocol
`sourceDex`	`string`	Yes	Source sub-exchange. `perps` or `spot` on Lighter
`destinationDex`	`string`	Yes	Destination sub-exchange. `perps` or `spot` on Lighter
`amount`	`string`	Yes	Amount to transfer

Response `201`

{
  "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 }`. 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` and `registerApiKey` 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
`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

{
  "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 }`, `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`

{
  "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

Responses

Status	Meaning
`400`	Validation error
`401`	Authentication error (invalid signature)
`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. The returned Order shape:

{
  "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
`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()

Getting Started

Concepts

Providers

SDK

API Reference

Reference

POST /createAction

Request Body

Request Fields

Action Types

MarketRef

PlaceOrderParams

PlaceTriggerOrderParams

PlaceTwapOrderParams

CancelOrderParams

CancelTwapOrderParams

ModifyOrderParams

UpdateLeverageParams

UpdatePositionMarginParams

WithdrawalParams

ApproveAgentParams

AccountModeParams

AccountTypeParams

CancelAllOrdersParams

RegisterApiKeyParams

DepositParams

SendAssetParams

Response `201`

Responses

POST /executeAction

Request Body

Response `202`

Responses

Order details (SDK)

Order Schema

Order Status Values

​POST /createAction

​Request Body

​Request Fields

​Action Types

​MarketRef

​PlaceOrderParams

​PlaceTriggerOrderParams

​PlaceTwapOrderParams

​CancelOrderParams

​CancelTwapOrderParams

​ModifyOrderParams

​UpdateLeverageParams

​UpdatePositionMarginParams

​WithdrawalParams

​ApproveAgentParams

​AccountModeParams

​AccountTypeParams

​CancelAllOrdersParams

​RegisterApiKeyParams

​DepositParams

​SendAssetParams

​Response 201

​Responses

​POST /executeAction

​Request Body

​Response 202

​Responses

​Order details (SDK)

​Order Schema

​Order Status Values

POST /createAction

Request Body

Request Fields

Action Types

MarketRef

PlaceOrderParams

PlaceTriggerOrderParams

PlaceTwapOrderParams

CancelOrderParams

CancelTwapOrderParams

ModifyOrderParams

UpdateLeverageParams

UpdatePositionMarginParams

WithdrawalParams

ApproveAgentParams

AccountModeParams

AccountTypeParams

CancelAllOrdersParams

RegisterApiKeyParams

DepositParams

SendAssetParams

Response `201`

Responses

POST /executeAction

Request Body

Response `202`

Responses

Order details (SDK)

Order Schema

Order Status Values