Skip to main content
All Realtime WebSocket traffic enters the API gateway at the same host as REST. There is no separate ingress, and direct connections to the internal firm-ws service port are not supported.

​
Endpoint

Optional query parameter:

​
Firm API key (primary)

Send the firm key as a header on the upgrade request. The gateway validates it, resolves the firm, and injects X-Firm-ID before forwarding to firm-ws.
Or equivalently:
/v1/firm-ws is on the gateway firm-key allowlist.

​
Staff session (secondary)

Browser-based staff users authenticate through /v1/auth/* and present a session cookie or bearer token. Staff sessions must also send the firm header so the gateway can resolve RBAC:

​
After the upgrade

Once the WebSocket is established, the server sends a single control frame to confirm the firm scope and the current JetStream cursor:
No trading or user events are delivered until the client sends scope.set. The connected frame is the only thing you will receive otherwise.

​
Close codes

In addition to application-level ping/pong, the server sends standard WebSocket control ping frames roughly every 30 seconds. Most client libraries respond to these automatically.

​
Hydration vs replay

  • Replay (within ~24h): reconnect with ?last_seq= and the server resumes from where you left off.
  • Hydration (gap beyond retention, or first connect): fetch current state via HTTP in parallel — /v1/firm-control/users, /v1/firm-control/relationships, Trading API reads — then send scope.set and process the live stream from DeliverNew.