Trading API

Endpoints for order placement, cancellation, and status queries

Endpoints for order placement, cancellation, and status queries. All mutating operations follow the create → sign → submit pattern.

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 /createOrder

Build order payloads for signing. Returns an array of typedData payloads that must be signed before submitting to POST /order.

POST /v1/perps/createOrder

Flow

1. Call this endpoint with order parameters
2. Sign each typedData in the response array
3. Submit all signatures to POST /order
4. Query GET /order/{id} to check status

Request Body

Market order with TP/SL:

{
  "dex": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "symbol": "BTC",
  "side": "BUY",
  "type": "MARKET",
  "size": "0.1",
  "price": "95500.00",
  "leverage": 10,
  "reduceOnly": false,
  "takeProfit": {
    "triggerPrice": "100000.00"
  },
  "stopLoss": {
    "triggerPrice": "90000.00",
    "limitPrice": "89800.00"
  }
}

Simple limit order:

{
  "dex": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "symbol": "ETH",
  "side": "BUY",
  "type": "LIMIT",
  "size": "1.0",
  "price": "3150.00",
  "reduceOnly": false,
  "timeInForce": "GTC"
}

Request Fields

Field	Type	Required	Description
dex	string	Yes	DEX identifier
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.
symbol	string	Yes	Trading symbol
side	string	Yes	BUY or SELL
type	string	Yes	MARKET or LIMIT
size	string	Yes	Order size
price	string	Yes	Limit price (LIMIT) or slippage limit (MARKET)
leverage	integer	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	ISO 8601 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)

Response 201

{
  "actions": [
    {
      "action": "updateLeverage",
      "description": "Set BTC leverage to 10x",
      "typedData": { "..." }
    },
    {
      "action": "placeOrder",
      "description": "Place BUY 0.1 BTC @ 95500.00",
      "typedData": {
        "domain": {
          "name": "HyperliquidSignTransaction",
          "version": "1",
          "chainId": 42161,
          "verifyingContract": "0x0000000000000000000000000000000000000000"
        },
        "types": {
          "EIP712Domain": [
            { "name": "name", "type": "string" },
            { "name": "version", "type": "string" },
            { "name": "chainId", "type": "uint256" },
            { "name": "verifyingContract", "type": "address" }
          ]
        },
        "primaryType": "Agent",
        "message": {
          "source": "a",
          "connectionId": "0x..."
        }
      }
    },
    {
      "action": "placeTriggerOrder",
      "description": "Take profit at 100000.00",
      "typedData": { "..." }
    },
    {
      "action": "placeTriggerOrder",
      "description": "Stop loss at 90000.00 (limit 89800.00)",
      "typedData": { "..." }
    }
  ]
}

Action Types

Action	When Generated
updateLeverage	If leverage differs from current position leverage
placeOrder	Always (the main order)
placeTriggerOrder	Once per TP/SL specified

Response 400

Validation error.

SDK: createOrder(), perps.placeOrder()

---

POST /cancelOrder

Build cancel payloads for signing.

POST /v1/perps/cancelOrder

Flow

1. Call this endpoint with order ID(s) to cancel
2. Sign each typedData in the response array
3. Submit all signatures to POST /order

Request Body

{
  "dex": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "ids": ["0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d", "12345678"]
}

Field	Type	Required	Description
dex	string	Yes	DEX identifier
address	string	Yes	User’s wallet address (account owner)
signerAddress	string	No	Address that will sign the payloads. Required for USER_AGENT mode. Defaults to address.
ids	string[]	Yes	Order IDs to cancel (orderId from the submit response)

Response 201

{
  "actions": [
    {
      "action": "cancelOrder",
      "description": "Cancel order 0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "typedData": { "..." }
    },
    {
      "action": "cancelOrder",
      "description": "Cancel order 12345678",
      "typedData": { "..." }
    }
  ]
}

Response 400

Validation error.

Response 404

Order not found.

SDK: cancelOrder(), perps.cancelOrders()

---

POST /order

Submit signed order or cancel payloads from /createOrder or /cancelOrder.

POST /v1/perps/order

Request Body

{
  "dex": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "actions": [
    {
      "action": "updateLeverage",
      "typedData": { "...typedData from createOrder action 1..." },
      "signature": "0xabcd1234..."
    },
    {
      "action": "placeOrder",
      "typedData": { "...typedData from createOrder action 2..." },
      "signature": "0xefgh5678..."
    }
  ]
}

Field	Type	Required	Description
dex	string	Yes	DEX 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.
actions	SignedOrderAction[]	Yes	Signed actions from /createOrder or /cancelOrder

Each SignedOrderAction:

Field	Type	Required	Description
action	string	Yes	Action type from the create response
typedData	object	Yes	Original typedData from /createOrder or /cancelOrder
signature	string	Yes	User’s or agent’s signature of the typedData

Response 202

{
  "results": [
    {
      "action": "updateLeverage",
      "success": true
    },
    {
      "action": "placeOrder",
      "success": true,
      "orderId": "12345678"
    },
    {
      "action": "placeTriggerOrder",
      "success": true,
      "orderId": "87654321"
    }
  ]
}

Each OrderActionResult:

Field	Type	Description
action	string	updateLeverage, placeOrder, placeTriggerOrder, or cancelOrder
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.

SDK: submitOrder(), perps.submitSignedOrder()

---

GET /order/

Get the status and details of a specific order.

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

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Order ID (orderId from the submit response)
dex	query	string	Yes	DEX 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",
  "symbol": "BTC",
  "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
symbol	string	Trading symbol
side	string	BUY or SELL
type	string	MARKET or LIMIT
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 DEX
EXPIRED	GTT order expired
TRIGGERED	Trigger order activated (TP/SL)

Response 404

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

SDK: getOrder()