Events

Everything the client surfaces splits into two kinds: server frames, keyed by the frame’s type, and lifecycle events, connection-level signals the client raises itself. How you receive them is the one place the two SDKs differ in shape.

# An async iterator: one loop, branch on the type.
async for frame in stream:
    if frame.type == "SNAPSHOT":
        # frame is a SnapshotFrame: frame.subscription_id, frame.bids, frame.asks, frame.seq...
        ...

/* An event emitter: one handler per frame type. */
stream.on("SNAPSHOT", (frame) => {
  /* frame is a SnapshotFrame: frame.subscriptionId, frame.bids, frame.asks, frame.seq... */
});

In TypeScript, on returns an unsubscribe function. Call it to remove that handler:

const off = stream.on("TRADE", (frame) => console.log(frame));
off(); /* stop listening */

In Python there is nothing to remove: stop handling a frame type by not branching on it. Frames you never match are discarded when the loop moves on.

Server frames

Every frame carries type, a v version, and a server timestamp (serverTimestamp in TypeScript, server_timestamp in Python). The table lists the additional fields you’ll use most; the WebSocket API’s Message catalog documents each frame in full.

Frame	When it fires	Key fields
`WELCOME`	Once, right after connect	`credentialId`, `connectionId`, `activeConnections`, `limits`
`SUBSCRIBED`	Ack of a `SUBSCRIBE` (one per market)	`subscriptionId`, `market`, `channel`, `snapshotPending`
`UNSUBSCRIBED`	Ack of an `UNSUBSCRIBE`	`subscriptionId`, `market`, `channel`
`SNAPSHOT`	Full book state, once per book subscription	`subscriptionId`, `seq`, `bids`, `asks`, `status`
`DELTA`	Incremental book changes	`subscriptionId`, `seq`, `changes`
`TRADE`	A public trade on the `TRADE` channel	`subscriptionId` and trade fields
`STATUS`	A subscription’s health changed	`subscriptionId`, `state`, `reason?`
`ERROR`	A request failed or a subscription errored	`code`, `message`, `subscriptionId?`, `market?`
`GOODBYE`	Server is about to close the connection	`reason`
`SUBSCRIPTIONS`	Reply to `LIST`, the connection’s active subscriptions	the subscription list
`PONG`	Reply to a `PING`	`requestId?`

Field names are camelCase on the wire and in TypeScript, and snake_case on the Python models: subscriptionId is subscription_id, snapshotPending is snapshot_pending. A few notes:

SNAPSHOT / DELTA are the orderbook. Apply the snapshot first, then each delta (a change with size 0 deletes that price level). seq is a per-subscription monotonic counter for detecting gaps. See Orderbook channel.
status reports LIVE, RESYNCING, CLOSED, UNSUPPORTED, or UNAVAILABLE. When the server retires a subscription (CLOSED/UNSUPPORTED) the client drops it from its resubscribe set so it isn’t replayed on reconnect.
ERROR frames raised during subscription creation carry the market and channel that failed (there’s no subscription id yet); the client prunes that market so it won’t be retried on reconnect. That pruning is by market, not by code, so a market refused with MARKET_NOT_YET_OPEN is dropped from the resubscribe set too: the client will not pick it up on its own once the book opens, and you subscribe again when the event is close to starting. See Errors for the code values.
GOODBYE precedes a close. Some reasons are terminal. See Reconnection & lifecycle.

Lifecycle events

These are raised by the client, not sent by the server. They are distinct from the server’s ERROR and GOODBYE frames, and the two SDKs expose a different set. TypeScript raises five through the same on surface:

Event	Payload	Meaning
`OPEN`	none	The socket opened (before the `WELCOME` frame).
`CLOSE`	`{ code, reason }`	The socket closed. The client may reconnect (see below).
`SOCKET_ERROR`	the transport error	A transport-level error (distinct from a server `ERROR` frame).
`RECONNECTING`	`{ attempt, delayMs }`	A reconnect was scheduled; `attempt` counts consecutive tries.
`TERMINATED`	`{ reason }`	The client gave up and will not reconnect. Create a new client.

Python takes three callbacks on the constructor, because a lifecycle event describes the connection rather than the market and so does not belong in a stream of market frames:

Callback	Payload	Meaning
`on_reconnecting`	`Reconnecting(attempt, delay_seconds)`	A reconnect was scheduled.
`on_terminated`	`Terminated(reason)`	The client gave up and will not reconnect.
`on_unparseable`	the raw frame text	A frame arrived that did not match the schema, and was dropped.

stream = StreamClient(
    on_reconnecting=lambda event: print(
        f"reconnecting (attempt {event.attempt}) in {event.delay_seconds}s"
    ),
    on_terminated=lambda event: print(f"stream terminated: {event.reason}"),
    on_unparseable=lambda raw: print(f"dropped an unrecognised frame: {raw}"),
)

stream.on("OPEN", () => console.log("connected"));
stream.on("RECONNECTING", ({ attempt, delayMs }) =>
  console.warn(`reconnecting (attempt ${attempt}) in ${delayMs}ms`),
);
stream.on("TERMINATED", ({ reason }) => console.error(`stream terminated: ${reason}`));

Python has no OPEN, CLOSE or SOCKET_ERROR equivalent. A socket that closes and reconnects is reported through on_reconnecting; one that will not come back ends the iteration, and on_terminated says why. Python also reports a terminal failure by raising from the loop, so a try/except around async for catches what on_terminated reports:

try:
    async for frame in stream:
        ...
except Exception as error:
    print("stream failed:", error)

See Reconnection & lifecycle for exactly when a reconnect is scheduled versus given up on.

Reference

Streaming

Server frames

Lifecycle events

​Server frames

​Lifecycle events

Server frames

Lifecycle events