Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

API overview

The gateway serves an HTTP/JSON API and a WebSocket under /v1. Examples on these pages write the gateway's address as $GATEWAY: on the testnet, the web client's address (these pages are on docs. and that name).

Three kinds of route

KindAuthenticationRoutes
SignedThe request carries its own EIP-712 signature. No session.POST /v1/orders, /v1/batch, /v1/cancel, /v1/quote-request, /v1/withdraw
PrivateA session token for the address in the path, as Authorization: Bearer <token>.GET /v1/account/{addr} and its /orders, /fills and /settlements, /v1/orders/{maker}/{nonce}, /v1/withdrawals/{user}
PublicNone.Config, events, instruments, underlyings, books, prints, candles, reference prices, settlements, stats, status
Signed routes need no session because the signature is the authority: the gateway checks it, the engine journals it, and the settlement contract checks it again before any money moves. See Signing and Sessions.

Order entry is asynchronous

POST /v1/orders answers 202 once the order is sequenced, and its outcome arrives on the WebSocket and at GET /v1/orders/{maker}/{nonce}. Add ?wait=ms to hold the request for the engine's answer instead. See Orders.

Snapshots and the stream

Several routes take ?envelope=1 and then wrap their array as {"position": …, "<name>": [...]}, where position is the stream position the answer is complete to. Use it to join a snapshot to the WebSocket without a gap.

Numbers

Every quantity is a JSON integer. Strings are refused where a number is expected.
QuantityUnit
Option price, strike, reference valuemicros of probability, 0 to 1000000
Money (cash, fees, amounts)micro-USDC
expiresAt, expiryMs, ts, sinceengine milliseconds: ms since 2020-01-01T00:00:00Z
Session expires, signing-key expiryunix seconds
Engine time is unix time shifted by a fixed epoch: engineMs = unixMs − 1577836800000.
An instrument's specifier is a 64-bit integer, often above 253. In JavaScript, parse and serialize these with a BigInt-safe JSON library, or they silently lose precision and name a different contract.

History pages

The history routes answer in pages, newest first, each naming where the next starts: fills, settlements, prints, reference prices and settled contracts.
  • A page holds at most 100 rows, which is also the default limit.
  • A premium account's session may ask for up to 1,000 rows a page, on its private reads and on a public read that carries the session.
  • A limit above what is allowed is cut to it, not refused.
  • Ask for the next page with ?before= the cursor the route names. How fast you turn pages is your rate limit's to say; there is no limit on how many.

Errors

Every error body is {"error": "<text>"}.
StatusMeaning
401No session, or an invalid one
403The session is another address's
404No such order or contract
413The body is over 1 MiB
422The gateway refused the request; error says why. See Refusals
429Rate limited; Retry-After says how many seconds until the limit has room. See Rate limits
503Not now: try again after Retry-After. The causes are below
An order the engine refuses is not an HTTP error: with ?wait, it is a 200 with "status": "refused" and the engine's code.

503: try again

CauseRetry-AfterApplies toWhat is open
On-chain settlement is behind. The chain has fallen more than half the forced-withdrawal window behind the exchange, and new orders wait while it catches up.60New ordersCancels and withdrawals
The chain reader is behind. The exchange must apply a key or nonce floor set on chain before it binds on chain, so new orders wait until it has caught up.10New ordersCancels
A projection is behind. One of the exchange's own views of the engine is catching up.1New ordersCancels
The engine's queue did not take it, or the gateway cannot tell whether it did.1Any signed request
History is unavailable. The history store is away or slow.1History routesLive routes: the account, resting orders, books
The settler is unavailable.1GET /v1/withdrawals/{user}
Every 503 on a signed request is safe to retry with the same signed body. If the first attempt did reach the engine, the second is refused as NONCE_USED and tells you where the first one stands.
A 503 without Retry-After is a gateway that does not serve that route at all (no history, no settler, no configuration); asking again will not help.

Rate limits

Each gateway limits on its own. The per-address limits depend on the account's class, and each class's rates and bursts are published in classes on GET /v1/config.
Applies toKeyed byOrdinary (testnet)Premium (testnet)
Signed requests: an order costs 1, a cancel ⅛, a batch the sum of its membersthe signing address20/s, burst 40200/s, burst 400
Fills as the taker: an order's size, given back for what it did not fillthe signing address5/s, burst 100200/s, burst 4,000
Quote requests, after the signed limitthe signing address1/s, burst 510/s, burst 50
Private readsthe session's address200/s, burst 2001,000/s, burst 1,000
Every request: public, private and signed, and WebSocket connectsclient IP (an IPv6 /56)50/s, burst 100signed and private requests are not charged
Requests refused before admission: a bad signature, an unknown account, refused terms, a failed sign-inclient IP5/s, burst 205/s, burst 20
  • A 429 carries Retry-After, the whole seconds until the bucket that refused it has room again.
  • A request that could never fit, a batch costing more than the class's whole signed burst or orders larger in all than its whole fill burst, is a 422 by name, not a 429.
  • Once an IP has spent its refusal budget, every signed request and sign-in from it is answered 429 until the budget refills. A cancel still passes.
  • The WebSocket has caps of its own: see Streaming.