/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).| Kind | Authentication | Routes |
| Signed | The request carries its own EIP-712 signature. No session. | POST /v1/orders, /v1/batch, /v1/cancel, /v1/quote-request, /v1/withdraw |
| Private | A 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} |
| Public | None. | Config, events, instruments, underlyings, books, prints, candles, reference prices, settlements, stats, status |
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.?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.| Quantity | Unit |
| Option price, strike, reference value | micros of probability, 0 to 1000000 |
| Money (cash, fees, amounts) | micro-USDC |
expiresAt, expiryMs, ts, since | engine milliseconds: ms since 2020-01-01T00:00:00Z |
Session expires, signing-key expiry | unix seconds |
engineMs = unixMs − 1577836800000.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.limit.limit above what is allowed is cut to it, not refused.?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.{"error": "<text>"}.| Status | Meaning |
401 | No session, or an invalid one |
403 | The session is another address's |
404 | No such order or contract |
413 | The body is over 1 MiB |
422 | The gateway refused the request; error says why. See Refusals |
429 | Rate limited; Retry-After says how many seconds until the limit has room. See Rate limits |
503 | Not now: try again after Retry-After. The causes are below |
?wait, it is a 200 with
"status": "refused" and the engine's code.| Cause | Retry-After | Applies to | What 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. | 60 | New orders | Cancels 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. | 10 | New orders | Cancels |
| A projection is behind. One of the exchange's own views of the engine is catching up. | 1 | New orders | Cancels |
| The engine's queue did not take it, or the gateway cannot tell whether it did. | 1 | Any signed request | |
| History is unavailable. The history store is away or slow. | 1 | History routes | Live routes: the account, resting orders, books |
| The settler is unavailable. | 1 | GET /v1/withdrawals/{user} |
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.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.classes on GET /v1/config.| Applies to | Keyed by | Ordinary (testnet) | Premium (testnet) |
| Signed requests: an order costs 1, a cancel ⅛, a batch the sum of its members | the signing address | 20/s, burst 40 | 200/s, burst 400 |
| Fills as the taker: an order's size, given back for what it did not fill | the signing address | 5/s, burst 100 | 200/s, burst 4,000 |
| Quote requests, after the signed limit | the signing address | 1/s, burst 5 | 10/s, burst 50 |
| Private reads | the session's address | 200/s, burst 200 | 1,000/s, burst 1,000 |
| Every request: public, private and signed, and WebSocket connects | client IP (an IPv6 /56) | 50/s, burst 100 | signed and private requests are not charged |
| Requests refused before admission: a bad signature, an unknown account, refused terms, a failed sign-in | client IP | 5/s, burst 20 | 5/s, burst 20 |
429 carries Retry-After, the whole seconds until the bucket that refused
it has room again.422 by
name, not a 429.429 until the budget refills. A cancel still passes.