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 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": {
    "asset": { "assetId": "BTC", "market": "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. Required for `USER_AGENT` mode (set to 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`
`modifyOrder`	Modify existing orders	`ModifyOrderParams`
`updateLeverage`	Change leverage for an asset	`UpdateLeverageParams`
`updatePositionMargin`	Add/remove position margin	`UpdatePositionMarginParams`
`withdrawal`	Withdraw funds	`WithdrawalParams`
`approveAgent`	Authorize an agent wallet	`ApproveAgentParams`
`approveBuilderFee`	Approve builder fee	`{}` (empty)
`userSetAbstraction`	Set account abstraction (user-signed)	`SetAbstractionParams`
`agentSetAbstraction`	Set account abstraction (agent-signed)	`SetAbstractionParams`
`sendAsset`	Transfer assets between sub-exchanges	`SendAssetParams`

AssetIdentity

Many action params use an asset field with the AssetIdentity type:

Field	Type	Required	Description
`assetId`	`string`	Yes	Provider’s canonical asset ID (e.g., `"BTC"`, `"xyz:PURR"`, `"@142"`)
`market`	`string`	Yes	Market category (e.g., `"hyperliquid"`, `"xyz"`, `"spot"`)

PlaceOrderParams

Field	Type	Required	Description
`asset`	`AssetIdentity`	Yes	Target asset
`side`	`string`	Yes	`BUY` or `SELL`
`type`	`string`	No	`MARKET`, `LIMIT`, or `TRIGGER_ONLY` (default `MARKET`)
`size`	`string`	Yes	Order size
`price`	`string`	No	Limit price (LIMIT) or slippage limit (MARKET)
`leverage`	`number`	No	Leverage to set (generates `updateLeverage` action if different)
`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
`asset`	`AssetIdentity`	Yes	Target asset
`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
`asset`	`AssetIdentity`	Yes	Target asset
`leverage`	`number`	Yes	New leverage value

UpdatePositionMarginParams

Field	Type	Required	Description
`asset`	`AssetIdentity`	Yes	Target asset
`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

SetAbstractionParams

Field	Type	Required	Description
`abstraction`	`string`	No	Abstraction mode identifier

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": { "..." }
    }
  ]
}

Each ActionStep:

Field	Type	Description
`action`	`string`	Action type from the request
`typedData`	`object`	EIP-712 typed data to sign

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. Required for `USER_AGENT` mode. Defaults to `address`.
`action`	`string`	Yes	Action type from the create request
`actions`	`SignedActionStep[]`	Yes	Signed actions from `/createAction`

Each SignedActionStep:

Field	Type	Required	Description
`action`	`string`	Yes	Action type from the create response
`typedData`	`object`	Yes	Original `typedData` from `/createAction`
`signature`	`string`	Yes	Signer’s signature of the `typedData`

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.

GET /order/

Get the status and details of a specific order.

GET /v1/perps/order/12345678?provider=hyperliquid&address=0x1234...

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Order ID (`orderId` from the execute response)
`provider`	query	`string`	Yes	Provider identifier
`address`	query	`string`	Yes	User’s wallet address
`x-lifi-api-key`	header	`string`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

Response `200`

{
  "orderId": "12345678",
  "asset": {
    "assetId": "BTC",
    "market": "hyperliquid",
    "displaySymbol": "BTC",
    "displayQuote": "USDC"
  },
  "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
`asset`	`AssetDisplay`	Asset identity (`assetId`, `market`, `displaySymbol`, `displayQuote`)
`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)

Response `404`

{
  "code": 2024,
  "tool": "hyperliquid",
  "message": "Order not found"
}

SDK: getOrder()

Getting Started

Concepts

Providers

SDK

API Reference

Reference

POST /createAction

Request Body

Request Fields

Action Types

AssetIdentity

PlaceOrderParams

PlaceTriggerOrderParams

CancelOrderParams

ModifyOrderParams

UpdateLeverageParams

UpdatePositionMarginParams

WithdrawalParams

ApproveAgentParams

SetAbstractionParams

SendAssetParams

Response `201`

Response `400`

POST /executeAction

Request Body

Response `202`

Response `400`

Response `401`

Response `422`

GET /order/

Parameters

Response `200`

Order Schema

Order Status Values

Response `404`

Getting Started

Concepts

Providers

SDK

API Reference

Reference

​POST /createAction

​Request Body

​Request Fields

​Action Types

​AssetIdentity

​PlaceOrderParams

​PlaceTriggerOrderParams

​CancelOrderParams

​ModifyOrderParams

​UpdateLeverageParams

​UpdatePositionMarginParams

​WithdrawalParams

​ApproveAgentParams

​SetAbstractionParams

​SendAssetParams

​Response 201

​Response 400

​POST /executeAction

​Request Body

​Response 202

​Response 400

​Response 401

​Response 422

​GET /order/

​Parameters

​Response 200

​Order Schema

​Order Status Values

​Response 404

POST /createAction

Request Body

Request Fields

Action Types

AssetIdentity

PlaceOrderParams

PlaceTriggerOrderParams

CancelOrderParams

ModifyOrderParams

UpdateLeverageParams

UpdatePositionMarginParams

WithdrawalParams

ApproveAgentParams

SetAbstractionParams

SendAssetParams

Response `201`

Response `400`

POST /executeAction

Request Body

Response `202`

Response `400`

Response `401`

Response `422`

GET /order/

Parameters

Response `200`

Order Schema

Order Status Values

Response `404`