WebSocket message schema

The WebSocket surface is a command-and-event API. Use this page as the human-readable schema contract for clients, coding agents, and test harnesses. REST route map stays in OpenAPI; WebSocket message shape lives here until a standalone machine contract is published.

Client Commands

Command	Purpose	Required fields
`subscribe`	Start a live stream for one channel and symbol	`op`, `channel`, `symbol`
`unsubscribe`	Stop a live stream	`op`, `channel`, `symbol`
`replay`	Replay a historical stream window	`op`, `channel` or `channels`, `symbol`, `start`, `end`
`replay.pause`	Pause the active replay	`op`
`replay.resume`	Resume the active replay	`op`
`replay.seek`	Move replay to a timestamp	`op`, `timestamp`
`replay.stop`	Stop replay	`op`
`ping`	Keep the connection alive where the client does not rely on native ping/pong	`op`

{
  "op": "subscribe",
  "channel": "orderbook",
  "symbol": "BTC"
}

{
  "op": "replay",
  "channels": ["orderbook", "trades"],
  "symbol": "BTC",
  "start": 1767225600000,
  "end": 1767229200000,
  "speed": 10
}

Server Events

Event	Purpose	Client behavior
`subscribed`	Confirms a live subscription	Mark the stream active
`unsubscribed`	Confirms a stopped subscription	Stop processing the channel
`data`	Sends live stream data for ordinary channels	Apply by channel semantics and preserve timestamp or symbol context
`l4_snapshot`	Sends initial L4 state for an order-level channel	Replace local L4 state for that channel
`l4_batch`	Sends ordered L4 diffs after an L4 snapshot	Apply diffs in order and stop on unsafe gaps; when an item carries `insertBefore` (optional), insert the new order ahead of that oid within its price level instead of appending
`replay_started`	Confirms replay window and speed	Start run logging
`replay_snapshot`	Sends initial state before replay timeline data	Build baseline state before processing `historical_data`
`historical_data`	Sends replay timeline records	Apply in emitted order and preserve timestamp
`historical_tick_data`	Sends Lighter tick-mode checkpoint and deltas	Apply checkpoint before deltas and preserve ordering metadata
`replay_paused`	Confirms replay pause	Keep state but stop time advancement
`replay_resumed`	Confirms replay resume	Continue processing
`replay_completed`	Confirms replay reached the configured end	Close the run and label output state
`replay_stopped`	Confirms replay stop	Close the run cleanly
`gap_detected`	Marks a missing or discontinuous interval	Mark output incomplete or rebuild
`error`	Reports a command or auth failure	Log code, message, and request or correlation ID

{
  "type": "gap_detected",
  "channel": "orderbook",
  "symbol": "BTC",
  "gap_start": 1767226200000,
  "gap_end": 1767226260000
}

Message Envelope

WebSocket events should be processed with the same discipline as REST responses: preserve symbol, channel, venue family, timestamp, request or correlation IDs when present, and any data-quality or gap state. Do not assume every channel has the same payload shape. Order-book snapshots, trades, funding, and replay controls carry different fields. Client commands and server events use different naming patterns. Dotted names such as replay.pause, replay.resume, replay.seek, and replay.stop are commands sent by the client. Underscore names such as replay_paused, replay_resumed, replay_snapshot, historical_data, and replay_completed are events received from the server.

string

Event name emitted by the server, such as data, l4_snapshot, replay_snapshot, historical_data, gap_detected, or error.

string

Market-data channel associated with the event. Replay-control events may use replay-specific event names.

string

Symbol or pair in the route-family format selected by the client.

number

Event timestamp when the channel emits one. Store it in the same run manifest as the replay or live stream.

Client Contract

Clients should validate outbound commands before sending them. A command with no symbol, no channel, or an unbounded replay window is a client bug. For production jobs, keep a local state object with connection status, active subscriptions, last event timestamp, replay window, gap events, and reconnect count.

Command Review Checklist

Review this checklist before generating WebSocket commands.

Field	Required check
Operation	`subscribe`, `unsubscribe`, `replay`, replay control, or `ping`
Channel field	Single `channel` or bounded `channels` list, not both by accident
Symbol format	Family-specific symbol, pair, builder prefix, outcome ID, or Lighter market
Replay window	Explicit `start`, `end`, and `speed` for replay jobs
Error path	Log command errors, auth failures, close events, and request or correlation IDs
Gap path	Mark output incomplete or rebuild when `gap_detected` appears
Event names	Parse underscore replay event names; do not wait for dotted command names as server events

Use Connection for auth and reconnect behavior, Channels for channel selection, Replay for historical event streams, and Limits for subscription and throughput sizing.

​Client Commands

​Server Events

​Message Envelope

​Client Contract

​Command Review Checklist

Client Commands

Server Events

Message Envelope

Client Contract

Command Review Checklist