Perps API

Account Data

All account reads are open, keyed by either the 20-byte wallet or the 32-byte account id (see the account model). Paginated endpoints take limit (max 200) and offset, return total, and sort newest first unless noted.

State

EndpointKeyed byReturns
GET /account/{account}/balanceaccountaccount, free_balance. Funds locked by in-flight withdrawals are excluded until the withdrawal completes or refunds
GET /account/{account}/positionsaccountdata.positions[] — every OPEN position: id, market, size (signed: positive = long, negative = short), entry_price, isolated_margin, closeable (reducible size), status, version

Open orders & triggers

EndpointParamsReturns
GET /account/open-orderswallet (required), market?, limit? (default 10), offset?, from?/to? (unix-ms bounds)Live resting orders, newest first
GET /account/position-triggerswallet (required)The complete set of armed reduce-only TP/SL triggers (not paginated)

Both return the same item shape (shown here for a TRIGGER order — trigger_price, trigger_direction, tpsl, and is_trigger_market are TRIGGER-only and omitted on other rows). Note that read rows render enums in lowercase (side, status, tpsl), unlike the uppercase write vocabulary:

1{
2  "order_id": "…",
3  "market": "BTC",
4  "side": "sell",
5  "size": "0.001",
6  "filled_size": "0",
7  "limit_price": "60000",
8  "order_type": "TRIGGER",
9  "time_in_force": "IOC",
10  "reduce_only": true,
11  "trigger_price": "60500",
12  "trigger_direction": "down",
13  "tpsl": "sl",
14  "is_trigger_market": true,
15  "status": "open",
16  "submitted_at": 1787067314951,
17  "status_at": 1787067314999,
18  "is_modifying": false
19}

History

EndpointParamsReturns
GET /account/order-historywallet, market?, limit?, offset?One entry per order status change (the same order_id appears once per transition), each with status ∈ open, triggered, filled, partially_filled_cancelled, cancelled, rejected
GET /account/trade-historywallet, market?, limit?, offset?Executed fills: tid (venue trade id), price, size, fee, closed_pnl (on reduce/close fills), dir (“Open Long”, “Close Short”, …), is_liquidation
GET /account/funding-historywallet, market?, limit?, offset?Hourly funding payments: direction (LONG/SHORT), size, signed payment (negative = paid), funding_rate (raw fraction — 0.000120 = 0.0120%), epoch_time, settled_at

Adjust isolated margin

POST /positions/margin

Adds or removes isolated margin on the open (account, market) position. Signed by the trading key as UpdateIsolatedMargin(bytes32 account,string market,string amount,uint256 nonce):

1{
2  "account_id": "0x<wallet 40 hex>000000000000000000000000",
3  "market": "BTC",
4  "amount": "25",
5  "nonce": 1787067314956,
6  "signature": "0x…"
7}
  • amount is a signed canonical decimal: positive adds margin from the free balance, negative removes it.
  • nonce here is a JSON integer (the order routes carry it as a string).
  • The adjustment applies asynchronously. The submit response is data: { request_id, status, reason? } with status ∈ SUBMITTED | REJECTED — a rejection is a 200 response, not an error.
  • Poll GET /positions/margin/{requestId} for the outcome: status ∈ APPLIED | REJECTED (404 while still pending).
  • reason values (submit or outcome): NO_OPEN_POSITION, UNKNOWN_MARKET, INVALID_REQUEST, INSUFFICIENT_BALANCE, EXCEEDS_MAX_REMOVABLE, TRANSFER_DECLINED, DECLINED.

Next: Deposits & Withdrawals