Connection lifecycle

A connection runs from the WELCOME frame the server sends on connect to the GOODBYE it sends just before closing. This page covers everything that happens at the connection level, independent of any individual subscription.

`WELCOME`

Immediately after the upgrade succeeds, the server sends a WELCOME frame:

{
  "type": "WELCOME",
  "v": 1,
  "serverTimestamp": 1748020034123,
  "credentialId": "9a4b7e2c-1a64-4dca-9d6e-1b8c2d3f4a5b",
  "connectionId": "1d3a9c44-cf21-4f33-9211-2b9b1adf67e8",
  "activeConnections": 1,
  "limits": { "maxSubscriptionsPerConnection": 200, "maxConnections": 20, "connectionTtlSeconds": 28800 }
}

Field	Meaning
`credentialId`	Opaque identifier of the credential this connection signs as.
`connectionId`	This connection’s identifier. Quote it in any support request so we can find your session in our logs.
`activeConnections`	How many connections your account currently holds, including this one.
`limits`	The caps that apply to this connection. See below.

Treat WELCOME as the signal that the connection is ready: wait for it before sending your first SUBSCRIBE.

Connection limits

The welcome.limits object reports the caps for your connection:

Field	Meaning
`maxSubscriptionsPerConnection`	Maximum active `(market, channel)` subscriptions on this connection (currently 200). Exceeding it yields a `QUOTA_EXCEEDED` error.
`maxConnections`	Maximum simultaneous connections for your account across the whole service (currently 20). A connect attempt past it is rejected with HTTP `429` at the WebSocket handshake.
`connectionTtlSeconds`	The connection’s maximum lifetime. See Connection lifetime.

Scaling past the subscription cap is by design: open multiple connections. Spread your markets across connections; one API key authenticates all of them, up to your maxConnections. The defaults give one account up to 20 × 200 = 4,000 simultaneous (market, channel) subscriptions. If you need more, reach out and we can raise your account’s connection limit. Dropped or unresponsive connections are cleaned up automatically within about 90 seconds and stop counting against maxConnections. Three further limits bound what a connection may send. A SUBSCRIBE frame may name at most maxSubscriptionsPerConnection markets; a larger frame is refused whole with QUOTA_EXCEEDED and nothing in it is subscribed. Control frames (SUBSCRIBE, UNSUBSCRIBE, LIST, PING) are accepted at 10 per second with a burst of 20; past that, a frame is answered with QUOTA_EXCEEDED and the socket stays open. An inbound frame larger than 64 KiB is refused at the protocol layer and the connection closes with code 1009; a 200-market subscribe is well under that.

Keepalive

The server sends WebSocket-protocol pings every 30 seconds; any standard WebSocket client answers them automatically. A connection that stops answering is treated as idle and closed with IDLE_TIMEOUT. You can also send an application-level PING and get a PONG back, useful as an explicit liveness check or to keep an otherwise-quiet connection active:

{ "type": "PING", "requestId": "…" }

{ "type": "PONG", "v": 1, "serverTimestamp": 1748020034300, "requestId": "…" }

The requestId you send is echoed on the PONG. This is independent of the WebSocket-protocol pings above.

Connection lifetime and `GOODBYE`

Just before the server closes a connection, it sends a GOODBYE frame with a reason, then closes the socket. Reconnect on a GOODBYE or any unexpected close, except AUTH_REVOKED and KICKED.

{ "type": "GOODBYE", "v": 1, "serverTimestamp": 1748020034400, "reason": "TTL" }

`reason`	Meaning	What to do
`TTL`	The connection reached `connectionTtlSeconds`.	Reconnect. Schedule this proactively before the TTL to avoid a visible gap.
`SHUTDOWN`	The serving task is shutting down (deploy or scale-in).	Reconnect; you land on another task. Data keeps flowing briefly after the warning, so you have time to reconnect cleanly.
`NO_ACTIVE_SUBS`	The connection sat with zero subscriptions past a grace period.	Reconnect when you next need data; keep at least one subscription otherwise.
`IDLE_TIMEOUT`	The connection was idle / unresponsive to pings.	Reconnect; make sure your client answers WebSocket pings.
`AUTH_REVOKED`	The API key was revoked.	Stop reconnecting with that key; register a new one.
`KICKED`	The server refused this connection. A slow reader that falls too far behind is closed without a `GOODBYE`, so it sees a plain close instead.	Stop reconnecting on a `KICKED` frame. On a plain close, reconnect and make sure you drain the socket fast enough.

Reconnect guidance

Reconnect with backoff on any close, but reconnect immediately (after a short jitter) on TTL and SHUTDOWN. Those are routine.
A 503 during the upgrade means the gateway is at capacity. Back off briefly and retry; you’ll be routed to fresh capacity.
A 429 during the upgrade means your account is at its maxConnections limit. Retrying does not help. Close a connection you no longer need (or wait ~90 seconds after an ungraceful drop for its slot to free), and contact us if you need the limit raised.
On reconnect, re-SUBSCRIBE to your markets. Each book subscription replays a fresh SNAPSHOT, so your state rebuilds automatically. There is no resume-from-offset to manage.
Don’t reconnect on AUTH_REVOKED; the key is dead.

Get started

Connecting

Market data

Reference

Connection lifecycle

`WELCOME`

Connection limits

Keepalive

Connection lifetime and `GOODBYE`

Reconnect guidance

​WELCOME

​Connection limits

​Keepalive

​Connection lifetime and GOODBYE

​Reconnect guidance

`WELCOME`

Connection limits

Keepalive

Connection lifetime and `GOODBYE`

Reconnect guidance