Control messages

Control messages are JSON frames distinguished from event envelopes by the presence of a top-level type field without a schema field. Event envelopes always carry "schema": "ws.firm.v1".

Server → client

`connected`

Sent exactly once, immediately after the upgrade succeeds.

{
  "type": "connected",
  "firm_id": "660e8400-e29b-41d4-a716-446655440001",
  "seq": 1048380
}

Field	Description
`firm_id`	The firm the gateway resolved from your credentials.
`seq`	Current JetStream cursor at the moment of connect. Useful as a starting checkpoint if no events arrive before disconnect.

`scope.confirmed`

Sent in response to every accepted scope.set.

{
  "type": "scope.confirmed",
  "scope": "account",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "entity": "",
  "subscription": "ws.firm.v1.660e8400-….550e8400-….6ba7b810-….>"
}

`pong`

Reply to client ping.

{ "type": "pong", "ts": "2026-04-09T14:00:00.123Z" }

`error`

Advisory error for the client. Does not close the socket on its own — the server may follow with a close frame (4001 for auth, 4002 for backpressure).

{ "type": "error", "message": "user not in firm scope" }

Client → server

`scope.set`

See Subscription scopes for the full schema. A second scope.set replaces the previous subscription.

{
  "type": "scope.set",
  "scope": "account",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

`ping`

Application-level keepalive. Send every 20–30 seconds. The server also sends standard WebSocket control ping frames at ~30s intervals — most client libraries auto-respond to those.

{ "type": "ping" }

Ordering guarantees

The server processes client frames in order. scope.set takes effect before any subsequent event is delivered.
Event envelopes are delivered in JetStream seq order per subject. Across subjects, ordering is best-effort; rely on seq per stream and on ts for cross-subject reasoning.

Overview

Account Provisioning

Terminal Embed

Firm & Users

Staff & RBAC

Offerings & Acceptance

API Keys

Webhooks

Realtime WebSocket

Operations

Firm Backoffice Reads

Terminal Onboarding (JWT)

Control messages

Server → client

`connected`

`scope.confirmed`

`pong`

`error`

Client → server

`scope.set`

`ping`

Ordering guarantees

​Server → client

​connected

​scope.confirmed

​pong

​error

​Client → server

​scope.set

​ping

​Ordering guarantees

Server → client

`connected`

`scope.confirmed`

`pong`

`error`

Client → server

`scope.set`

`ping`

Ordering guarantees