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.Three kinds of route
| Kind | Authentication | Routes |
| Signed | The request carries its own EIP-712 signature. No session. | POST /v1/orders, /v1/batch, /v1/cancel, /v1/withdraw |
| Private | A session token for the address in the path. | GET /v1/account/{addr}, /v1/orders/{maker}/{nonce}, /v1/withdrawals/{user} |
| Public | None. | Instruments, underlyings, books, prints, candles, reference prices, settlements, status |
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.
| 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 and withdrawal expires, deadline, signing-key expiry | unix 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.Errors
Every error body is
{"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: 1 |
503 | Try again after Retry-After. Order entry is paused, the engine's queue is full, or history is unavailable |
A
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.An order the engine refuses is not an HTTP error: with
?wait, it is a 200 with
"status": "refused" and the engine's code.Rate limits
Each gateway limits on its own:
| Applies to | Keyed by | Rate | Burst |
| Signed requests (a batch counts once) | the signing address | 20/s | 40 |
| Private reads | the session's address | 200/s | 200 |
| Public reads, session routes, WebSocket connects | client IP | 50/s | 100 |
| Requests refused for a bad signature | client IP | 5/s | 20 |
Once an IP has spent its bad-signature budget, every signed request from it is
answered
429 until the budget refills. The WebSocket also allows at most 16
connections per IP.