Endpoint
Each connection is scoped to exactly one subaccount. To watch orders across multiple subaccounts, open one connection per subaccount. The server pushes a snapshot of currently-open orders on connect, then a frame every time one of that subaccount’s orders changes user-visible status.
Query parameters
| Parameter | Required | Default | Description |
|---|
subaccount_id | yes | — | UUID of the subaccount whose orders you want to stream. Must belong to the authenticated user. |
extra_information | no | false | When true, every snapshot row and order frame additionally carries parent_iceberg_order_id, expiry_ts_utc, and complex_order_ids (TP/SL bucket). Useful for rendering full order rows without a REST round-trip. |
key_id / ts / sig | yes (programmatic) | — | Ed25519 signed-handshake params. See Authentication. |
access_token | yes (browser) | — | Supabase JWT for first-party web clients. |
Authentication
Browsers can’t set custom headers on the WebSocket handshake, so the signed-request
flow moves to query params. The signature covers
WS\nPATH\nSORTED_QUERY (excluding key_id/ts/sig)\nTIMESTAMP.
The official SDKs sign the handshake for you. The raw recipe below is for
integrations without an SDK.
The authenticated user must own subaccount_id — otherwise the connection is closed with code 4401. A missing or malformed subaccount_id is closed with 4400.
Protocol
All frames are JSON. Server frames are bytes (orjson-serialized UTF-8). Client frames are accepted but ignored — there is no subscribe/unsubscribe action; the subaccount is fixed at handshake time.
Server → client
connected is sent immediately after the handshake completes.
snapshot follows once, listing orders currently in pending, resting, or partially_filled for this subaccount. The client always sees state, then deltas — never the other way around.
order frames deliver every user-visible status transition. The internal processing status is never forwarded.
reconnect is sent during graceful pod shutdown. Reconnect with a small jitter.
Statuses
| Status | Meaning |
|---|
pending | Accepted by the API; not yet on the exchange book. |
resting | Live on the exchange book. Might have traded some quantity. |
pending_amend | A PATCH /v1/orders/{id} edit request is in flight on the exchange. Transitions back to resting (or a terminal state) once the exchange responds. |
partially_filled | Some quantity has traded; the rest is cancelled. |
executed | Fully filled. Terminal. |
cancelled | Cancelled before full execution. Terminal. |
rejected | Rejected by the exchange or risk checks. Terminal. |
Iceberg child tranches arrive as ordinary order frames — clients can’t tell them apart from user-placed simple orders.
Order payload
Default fields (always sent):
When connected with ?extra_information=true, every row additionally carries:
average_price is null until the first fill. traded_qty and fees_paid default to 0. complex_order_ids lists attached take-profit / stop-loss conditional-order ids by side; both buckets are empty when nothing is attached. order_type and time_in_force are the canonical enum names (LIMIT, MARKET, GTC, IOC, FOK, …).
Keepalive
Liveness is handled at the WebSocket protocol layer (RFC 6455 PING/PONG control frames). Standard clients (Python websockets, browser WebSocket) reply to server PINGs automatically — no application-level heartbeat is needed.
Minimal client
Using the SDK (handles signing automatically):
Or signing the handshake manually:
Errors
Recoverable problems arrive as an error frame followed by a close. code is stable and safe to branch on; message is human-readable.
code | When |
|---|
unauthorized | API key / JWT was missing or invalid. |
missing_subaccount_id | ?subaccount_id= was not supplied on the handshake. |
invalid_subaccount_id | subaccount_id is not a valid UUID. |
subaccount_forbidden | The subaccount does not belong to the authenticated user. |
snapshot_failed | Initial open-orders snapshot could not be loaded; the connection stays open and live updates resume. |
Close codes
| Code | Meaning |
|---|
1000 | Normal closure |
1011 | Server-side overflow (client couldn’t keep up with the send rate) |
4400 | Bad request (missing/invalid subaccount_id) |
4401 | Missing or invalid authentication, or subaccount does not belong to the user |
4503 | Server draining for deploy — reconnect with jitter |