GET /v1/ws upgrades to a WebSocket. Anyone may connect. For your account's
channel, pass a session token at connect, as
Authorization: Bearer <token> or ?token=<token>. The
streaming guide walks through a client.hello giving the stream position the
gateway is at:1{ "type": "hello", "seq": 1834, "pos": 918274 }
12{ "op": "subscribe", "channel": "book:7:859008923130267914" } { "op": "unsubscribe", "channel": "book:7:859008923130267914" }
| Channel | What it carries |
book:<underlyingKey>:<specifier> | One contract's book: a snapshot, then every changed level |
book:<underlyingKey> | Every contract of one underlying: a snapshot of all of them, then every changed level |
prints:<underlyingKey>:<specifier> | One contract's trades |
reference:<underlyingKey> | The underlying's reference values and price |
account:<address> | Your account's events. Needs a session for that address. |
book: channel, and otherwise:1{ "type": "subscribed", "channel": "prints:7:859008923130267914", "pos": 918274 }
{"type": "unsubscribed", "channel": "…"}.{"type": "error", "channel": "…", "error": "…"}, and the
connection stays open:error | Why |
channel is book:<uk>, book:<uk>:<spec>, … | The channel name is malformed. |
no such contract, no such underlying | A book: channel names nothing listed. |
a session for this address is required | An account: channel without a session for that address. |
too many channels | The connection already holds 256. |
op is subscribe or unsubscribe |
book:<uk>:<spec> snapshot:12345{ "type": "book", "channel": "book:7:859008923130267914", "pos": 918274, "seq": 1834, "bids": [{ "price": 19000, "quantity": 40 }], "asks": [{ "price": 20000, "quantity": 15 }] }
book:<uk> snapshot holds every contract, by specifier:123456{ "type": "book", "channel": "book:7", "pos": 918274, "seq": 1834, "instruments": [ { "specifier": 859008921287065866, "bids": [], "asks": [{ "price": 31000, "quantity": 5 }] } ] }
quantity: 0 means the level is
empty. On a book:<uk> channel the frame also names the specifier.12{ "type": "level", "channel": "book:7", "pos": 918275, "seq": 1835, "specifier": 859008923130267914, "side": 0, "price": 19500, "quantity": 3 }
side is 0 for bids and 1 for asks. Every level frame after a snapshot has a
pos at or after the snapshot's, so applying them in order keeps the book exact.book: channel that covers it says
so:12{ "type": "delisted", "channel": "book:7", "pos": 918400, "seq": 1902, "specifier": 859008923130267914, "reason": "instrumentSettled" }
reason is instrumentSettled (it settled, at expiry or forced early) or
instrumentUnregistered (an administrator removed it). Drop the contract: it
takes no more orders, and it is gone from
GET /v1/instruments. A settled contract's price is
on GET /v1/settlements.1{ "type": "fill", "channel": "prints:7:859008923130267914", "event": { "type": "fill", "…": "…" } }
Event type | Channels | Carries |
fill | prints:, account: | price, size, side (the maker's), maker, taker, makerNonce, takerNonce, makerFee, takerFee |
reference | reference: | price, valid |
inserted | account: | An order rested: orderId, nonce, side, size, price |
cancelled | account: | An order was cancelled |
expired | account: | An order's lifetime ended, including the remainder of a zero-lifetime order |
refused | account: | The engine refused an order: nonce, code |
orderSettled | account: | A resting order ended at settlement |
positionSettled | account: | A position settled: amount |
funds | account: | A deposit, withdrawal or other movement of cash: amount, freeCash |
quoteRequest | book:, account: | A request for quote on the contract: side, sided (whether a side is named), size. On book: channels without the requester; your own on your account: channel in full |
seq, ts (engine ms), pos, underlyingKey and
specifier where they apply. An account: event whose output moved the
account's cash also carries balances (freeCash, collateral, security)
after it.account: channel:fill carries your balances after it (makerBalances or takerBalances:
freeCash, collateral, security), and effect: how much of the fill
closed an existing position, how much opened a new one, and the position after.prints: channels carry
neither.pos is a position in the exchange's output stream. It is the same on every
gateway, so it orders everything you receive.seq is the sequence number of the input that caused the output.4008, behind the stream: resubscribe. To recover, reconnect and
resubscribe: the snapshots bring you back to an exact state.| Code | Reason | What to do |
4008 | behind the stream: resubscribe | Reconnect and resubscribe at once. |
4401 | the session has expired or its signing key is revoked: sign in again | The token is dead: the gateway checks it every few seconds. Sign in again, then reconnect with the new token. Reconnecting with the old one opens a connection without your account. |
1008 | too many requests | The client sent subscribes and unsubscribes faster than 10 a second, past a burst of 64. Slow down before reconnecting. |
429 with
Retry-After: 5: a place frees when a connection closes.1008.