Skip to main content
Public market prices use a separate socket: Market data.

Subscribe

Send one frame after the upgrade:
Response:
Send it within 10 seconds. A first frame that is late, malformed or has unknown fields closes with INVALID_SUBSCRIPTION. A subscription your key may not use closes with SUBSCRIPTION_DENIED. There is no unsubscribe: close the socket.

Frames

Every server frame is { "channel": ..., "data": ... }.
event_type selects the shape of payload. Ignore event types you do not recognize.

Snapshot

The snapshot is your current state and the cursor it matches. Replace your local state with it, then apply events after that cursor. A class cut short is listed in truncated with the route that pages the rest:
Read the rest from that route, starting at its first page. An href with a {placeholder} is per resource: fill it in for each item. Balances, positions and maker capital are not snapshot classes: read them over HTTP when you connect, and again on their events.

Apply events

  • Delivery is at least once. Skip an event whose event_id you have seen, or whose cursor.sequence is not above yours.
  • Apply events in sequence order. Sequences skip numbers; a skipped number is not a gap.
  • Save the event’s cursor after you apply it.

Resume

Send your last applied cursor. Resuming needs replay:read.
The stream is the only replay; there is no HTTP event log. The replay window is on Limits.

Heartbeats, drain and reset

  • The server sends a WebSocket ping every heartbeat_interval_ms. Answer with a pong within 5 seconds, or the server drops the connection.
  • Most WebSocket APIs answer pings for you and never show them, so a ping can’t tell you a socket died. Subscribe with publication_freshness: true and treat a few missed heartbeats as a dead socket: close it and resume from your cursor. Give up the same way on a connect whose subscriptionResponse doesn’t arrive. The SDK does both.
  • On drain, open a new connection, resume from your cursor, then close the old one. The server closes it with CONNECTION_DRAIN by deadline.
  • On reset, discard local state and reconnect without a cursor.
Every close carries a code from Errors as its reason. Its retry says what to do: An account holds at most 4 open streams. With an API key, a fifth is refused with 429 and Retry-After. A wallet session’s fifth replaces its oldest, which closes with STREAM_REPLACED. A dropped stream can hold its slot for up to 30 seconds.