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, with a symbol for coin-specific channels	`op`, `channel`; `symbol` for coin-specific channels; optional `interval_ms` on `lighter_orderbook` and `rh_lighter_orderbook` only
`unsubscribe`	Stop a live stream	`op`, `channel`; `symbol` for coin-specific channels
`replay`	Replay a historical stream window	`op`, exactly one non-empty `channel` or `channels`, `symbol`, `start`; `end` is optional
`replay.pause`	Pause standard or core L4 replay	`op`
`replay.resume`	Resume standard or core L4 replay	`op`
`replay.seek`	Move standard replay to a timestamp. Standard replay only; core L4 rejects seek	`op`, `timestamp`
`replay.stop`	Stop standard or core L4 replay	`op`
`ping`	Keep the connection alive where the client does not rely on native ping/pong	`op`

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

interval_ms sets the maximum lighter_orderbook or rh_lighter_orderbook book rate, from 100 to 5000. Leave it out for one book per second. Any other channel rejects it.

{
  "op": "subscribe",
  "channel": "lighter_orderbook",
  "symbol": "BTC",
  "interval_ms": 250
}

{
  "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 an unsafe sequence or block gap; when an item carries `insert_before` (optional), insert the new order ahead of that order ID within its price level instead of appending
`replay_started`	Confirms replay window and standard replay speed when applicable	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, authentication, access, or data error, or a live-stream lag notice	Log the returned `message`. Stop the affected workflow for a rejected command; for a lag notice, follow the recovery documented for that channel

{
  "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. Live Lighter data payloads also differ from Lighter replay historical_data rows; see Lighter WebSocket channels for both. 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 coin-specific command with no symbol, a replay with no symbol or start, or an unbounded replay window is a client bug. all_tickers is the exception for subscriptions and may omit symbol. 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	For a bounded run, use Explicit `start` and `end`; include `speed` for standard timed replay or checkpoint metadata for core L4
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.

Connect

Stream

Replay

Webhooks

WebSocket message schema

Client Commands

Server Events

Message Envelope

Client Contract

Command Review Checklist

​Client Commands

​Server Events

​Message Envelope

​Client Contract

​Command Review Checklist

Client Commands

Server Events

Message Envelope

Client Contract

Command Review Checklist