Trading API

Endpoints

All three routes are served from one API host. An asset's id is its index in the meta response: BTC 0, ETH 1, SOL 2, SUB 3. The SUB / USDC spot market is asset 10000. exchangeStatus returns, in its signing field, the chain id and custody address that trading actions and signed reads are bound to, with the network’s source and subliquidChain values. Owner actions are bound to the network by subliquidChain instead.

Signing

Trading actions

With agentType the Agent type string above, the digest is keccak256(0x19 0x01 ‖ domainSeparator ‖ keccak256(keccak256(agentType) ‖ keccak256(source) ‖ connectionId)). The server rebuilds each action in its schema order before hashing, so JSON keys may arrive in any order, while a client must hash in schema order to recover its own address. An unknown key, a missing required key, or an optional key sent as null is refused. A signed read hashes the request without nonce and signature, in the order type, user, its own fields, then an optional dex of "" last; any other dex is refused. The websocket sign-in hashes { type: "wsAuth", user, challenge }.

Owner actions

The request’s nonce must equal the struct’s time or nonce field. Owner actions carry no vaultAddress or expiresAfter. agentName may be left out when approving the unnamed agent; it is then signed as the empty string "". An agent’s expiry is optional. It rides in its name as "<name> valid_until <ms>", or "valid_until <ms>" for the unnamed agent, at most 180 days ahead. An agent approved without one stays until it is replaced. A withdrawal’s destination must be the owner’s own address.

Action schemas

Every action is a JSON object whose keys a client hashes in the order shown. A key marked ? is optional and is left out when unused, never sent as null. int is a JSON integer, bool a JSON boolean, and string a JSON string; prices, sizes, and token amounts are decimal strings. An agent may sign only the actions marked owner or agent; any other action an agent signs is refused with Action requires the account owner's signature.

A request is { action, nonce, signature, vaultAddress?, expiresAfter? }. vaultAddress names a sub-account of the signer’s owner; it is refused on owner typed data, createSubAccount, and subAccountTransfer. An order carrying builder is refused, as are sendAsset, approveBuilderFee, setReferrer, convertToMultiSigUser, multiSig, and tokenDelegate. subVest releases vested SUB from an in-engine grant to its beneficiary. reserveFund moves USDC from the signer’s own flat balance into the insurance fund.

Agents and API wallets

Each account has one unnamed agent and up to three named API wallets; approving a new agent in a slot replaces the old one immediately. Run bots on a named API wallet, since each terminal login replaces the unnamed agent. Never reuse an agent address. Order lifecycle lists what agents can and cannot sign.

Sub-accounts and transfers

createSubAccount, subAccountTransfer, and vaultTransfer use the trading-action scheme, signed by the owner’s own key, as do oiCommit, oiRelease, and cDeposit2. usdSend and spotSend use the owner’s typed data above.

Nonces and expiry

A nonce is a millisecond timestamp, unique per signer, from 2 days back to 1 day ahead. Signed reads use no nonce and stay valid for 5 s. Trading actions can carry an optional expiry. An exact retry returns the original receipt.

Place an order

A buy of 0.01 BTC at 84,750, good till canceled, signed by an API wallet:

POST /exchange
{
  "action": {
    "type": "order",
    "orders": [{ "a": 0, "b": true, "p": "84750", "s": "0.01", "r": false,
                 "t": { "limit": { "tif": "Gtc" } } }],
    "grouping": "na"
  },
  "nonce": 1793232000000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

Each order in the batch gets its own status: resting with its order id, filled with total size and average price, or error with a message. With grouping normalTpsl, the TP and SL children reply waitingForFill.

{ "status": "ok", "response": { "type": "order", "data": { "statuses": [
  { "filled": { "totalSz": "0.01", "avgPx": "84731", "oid": 77738308 } }
] } } }

The order fields are asset a, buy b, price p, size s, reduce-only r, type t (limit with Gtc, Ioc, or Alo for post-only, or trigger with isMarket, triggerPx, and tpsl), an optional client order id c, and, in hedge mode, the leg ps.

Cancel an order

POST /exchange
{
  "action": { "type": "cancel", "cancels": [{ "a": 0, "o": 77738308 }] },
  "nonce": 1793232000500,
  "signature": { "r": "0x...", "s": "0x...", "v": 28 }
}

{ "status": "ok", "response": { "type": "cancel", "data": { "statuses": ["success"] } } }

cancelByCloid takes { "asset", "cloid" } elements instead.

Read account state

A signed read carries the owner’s address and a nonce within 5 s of the engine clock; the signature comes from the owner or one of its agents.

POST /info
{
  "type": "clearinghouseState",
  "user": "0x...",
  "nonce": 1793232001000,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 }
}

{
  "assetPositions": [{ "type": "oneWay", "position": {
    "coin": "BTC", "szi": "0.01", "entryPx": "84731", "positionValue": "847.31",
    "unrealizedPnl": "0", "liquidationPx": "55462.40911", "marginUsed": "42.3655",
    "leverage": { "type": "cross", "value": 20 }, "maxLeverage": 40 } }],
  "marginSummary": { "accountValue": "299.61871", "totalNtlPos": "847.31",
    "totalRawUsd": "-547.69129", "totalMarginUsed": "42.3655" },
  "crossMaintenanceMarginUsed": "10.591375",
  "withdrawable": "214.88771",
  "positionMode": "oneWay",
  "time": 1793232001000
}

Abbreviated: replies also carry crossMarginSummary, funding since open, and return on equity. A read that fails authorization gets Unauthorized read., whether or not the account exists.

Info reads

Every read is POST /info with a JSON body carrying type. Public reads need no signature. Account reads add user, then their own fields, then an optional dex of "", then nonce and signature. They need a signature from the owner or one of its agents. Times are milliseconds and endTime defaults to now.

Public reads

Account reads

No read takes a page token. A time-range read returns at most its stated number of rows, oldest first from startTime; to page, send the next request with startTime just past the last row’s time. A read without a range returns the newest rows. These numbers bound one reply and never what is kept, so every row stays readable by time range.

Websocket

{ "method": "subscribe", "subscription": { "type": "l2Book", "coin": "BTC" } }

Every frame derived from engine state is sent only after that state is committed to disk. Frames leave in the order the engine computed them. On one connection, an account’s fills and order updates arrive in commit order. A client that reconnects rebuilds from a fresh snapshot. A post message carries an /info or /exchange request over the socket. Trades on the public tape carry no account or hash and do not mark liquidations; the liquidated account’s own fill carries a liquidation field. liquidationStats publishes liquidations in buckets of at least 5. Limits per IP address: 10 connections, 30 new connections a minute, 1,000 subscriptions, 10 authenticated users, 2,000 messages a minute and 100 posts in flight; an idle connection closes after 60 s, so send a ping.

Request weight

1,200 units per IP address over any 60 s. Every reply carries the weight used in the x-used-weight-1m header; above the limit the reply is HTTP 429 with Retry-After. Cancels, scheduled cancels, and reduce-only orders are charged weight but never refused for it. They still count against the account’s own request allowance, where cancels get extra room and reduce-only orders do not. An account can buy request allowance beyond its traded volume with reserveRequestWeight { weight } at 0.0005 USDC per request; that fee splits 50/20/10/10/10 like trading fees (Fees and payouts). Market making sets out the per-account limits.

Load shedding

The API gateway counts the exchange requests it has received and not yet answered. Once that count reaches its overload threshold, it refuses every new request outside the exit lane before any signature work. The refusal reads Server is overloaded; new orders are shed. Cancels, reduce-only and closing orders still run. with HTTP 200. Meanwhile exchangeStatus reports degraded: true until the count falls back.

The exit lane is also exempt from IP request weight refusals. Load shedding is the one case where traffic from other accounts can refuse an account’s request. A full matching cycle never does: requests past 8,192 wait for the next cycle. No order is refused or evicted because of the orders other accounts hold on the book.

Size, price, and amount precision

Sizes are whole size steps. Prices are whole ticks with at most 5 significant figures, or any whole dollar; a perp tick is 10^{−(6 − size decimals)} USDC and a spot tick 10^{−(8 − size decimals)} USDC (Markets and pricing). Numbers travel as decimal strings. A value finer than its unit is refused for that order alone. USDC amounts carry six decimals.

Errors

Each element of a batch fails on its own with its own message. Engine refusals, load shedding included, arrive with HTTP 200 and "status": "err". Other HTTP status codes: 400 for an invalid request, 404 for an unknown route, 413 above the 1 MiB body limit, 415 for a body that is not application/json, 429 above the weight limit, and 503 when the service is unavailable.

Response semantics

• An acknowledgement is sent after the request is committed, state-dependent refusals included.
• Malformed actions and bad signatures are refused immediately.
• A refused request changes nothing and does not count against the account’s request allowance; it still counts toward IP request weight.