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

{
  "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 `<market_id>:<order_id>`
`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`

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

{
  "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. SessionActionSteps are not submitted here — they carry no signable material, so the SDK executes them client-side against the venue and skips /executeAction.

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

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:

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

Response `400`

POST /executeAction

Request Body

Response `202`

Response `400`

Response `401`

Response `422`

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

​Response 400

​POST /executeAction

​Request Body

​Response 202

​Response 400

​Response 401

​Response 422

​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`

Response `400`

POST /executeAction

Request Body

Response `202`

Response `400`

Response `401`

Response `422`

Order details (SDK)

Order Schema

Order Status Values