Actions API - @lifi/perps-sdk

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 action payloads for signing. Returns an array of typedData payloads that must be signed before executing via POST /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`)
`address`	`string`	Yes	User’s wallet address (account owner)
`signerAddress`	`string`	No	Address that will sign the payloads. For agent-signed actions (Hyperliquid trading) this must be the agent address. Defaults 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`
`cancelOrder`	Cancel one or more orders	`CancelOrderParams`
`cancelAllOrders`	Cancel every open order on the account	`CancelAllOrdersParams`
`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)
`accountMode`	Switch the account’s operating mode (e.g. Hyperliquid abstraction variant, Lighter UTA/Simple). Accepts either signer; the backend dispatches to the right typed-data builder based on which key signs the request.	`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 a Lighter API-key slot	`RegisterApiKeyParams`
`sendAsset`	Transfer assets between sub-exchanges	`SendAssetParams`

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)

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

CancelOrderParams

Field	Type	Required	Description
`ids`	`string[]`	Yes	Order IDs to cancel

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	Amount to withdraw

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 (e.g. `unifiedAccount`, `dexAbstraction`, `disabled` on Hyperliquid)

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.

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	Chain ID of the source chain (e.g. `1` for Ethereum, `42161` for Arbitrum)

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

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.

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 the payloads. For agent-signed actions (Hyperliquid trading) this must be the agent address. Defaults 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)

The example above shows the EIP-712 variant. Submit signed steps in the same shape and order they were returned by /createAction.

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 (for `placeOrder` and `placeTriggerOrder`)
`error`	`string`	Error message if failed

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

​POST /createAction

​Request Body

​Request Fields

​Action Types

​MarketRef

​PlaceOrderParams

​PlaceTriggerOrderParams

​CancelOrderParams

​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

CancelOrderParams

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