Connect
Open a WebSocket to the/v3/ws endpoint for your environment:
public/login) or attach a read-only JWT to the URL.
See Authentication for the full model.
- JWT on the URL (read-only)
Send JSON-RPC frames
Send each request as a JSON text frame. Responses correlate byid;
subscription updates arrive as separate notification frames (see
Subscriptions).
Heartbeat
The server drives a heartbeat loop and expects the client to stay responsive.1
Server pings
On each heartbeat interval the server sends a WebSocket Ping frame. Your
client library normally answers with a Pong automatically. Any inbound
text frame from you also counts as liveness.
2
Application-level ping (optional)
You may send the text frame
ping; the server replies with pong.3
Miss the window and you're dropped
If no activity is seen within the heartbeat window, the server closes the
connection.
Heartbeat re-authentication
On each heartbeat tick, a logged-in connection is silently re-authenticated — the server re-runs your stored login signature check against current account state. If the session key has expired, been revoked, or falls outside its IP allow-list, the connection is closed. Long-lived connections therefore pick up permission changes without you reconnecting.Connection limits
Concurrent WebSocket connections are capped per source IP (deployment-configured, currently 4 per IP). When the cap is exceeded the server sends a text frame and then closes the socket:-32100 “Number of concurrent websocket clients limit exceeded”.
The exact heartbeat window and per-IP connection cap are deployment-specific
config values. The values above reflect current deployments; see Rate
limits for the per-IP connection cap and read your live budget
from
public/getRateLimits.Reconnection guidance
Sessions do not survive a dropped socket. On reconnect:1
Re-open the socket
Dial the same
/v3/ws endpoint, with backoff (exponential + jitter) so a
server restart doesn’t produce a reconnect storm that trips the per-IP cap.2
Re-authenticate
Re-send
public/login (or reconnect with a fresh ?token=). Nothing from
the previous session — auth, subscriptions — is retained.3
Re-subscribe and resync
Re-establish every channel from Subscriptions, then reload
state (open orders, positions) over REST or private reads, since you may
have missed updates while disconnected.
Cancel on disconnect
Cancel-on-disconnect automatically cancels your resting orders, quotes, and trigger orders when a connection drops. It is a persisted account setting — see Cancel on disconnect for the full behaviour and theprivate/set_cancel_on_disconnect request.