Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt

Use this file to discover all available pages before exploring further.

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

CommandPurposeRequired fields
subscribeStart a live stream for one channel and symbolop, channel, symbol
unsubscribeStop a live streamop, channel, symbol
replayReplay a historical stream windowop, channel or channels, symbol, start, end
replay.pausePause the active replayop
replay.resumeResume the active replayop
replay.seekMove replay to a timestampop, timestamp
replay.stopStop replayop
pingKeep the connection alive where the client does not rely on native ping/pongop
{
  "op": "subscribe",
  "channel": "orderbook",
  "symbol": "BTC"
}

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

​
Server Events

EventPurposeClient behavior
subscribedConfirms a live subscriptionMark the stream active
unsubscribedConfirms a stopped subscriptionStop processing the channel
dataSends live stream data for ordinary channelsApply by channel semantics and preserve timestamp or symbol context
l4_snapshotSends initial L4 state for an order-level channelReplace local L4 state for that channel
l4_batchSends ordered L4 diffs after an L4 snapshotApply diffs in order and stop on unsafe gaps
replay_startedConfirms replay window and speedStart run logging
replay_snapshotSends initial state before replay timeline dataBuild baseline state before processing historical_data
historical_dataSends replay timeline recordsApply in emitted order and preserve timestamp
historical_tick_dataSends Lighter tick-mode checkpoint and deltasApply checkpoint before deltas and preserve ordering metadata
replay_pausedConfirms replay pauseKeep state but stop time advancement
replay_resumedConfirms replay resumeContinue processing
replay_completedConfirms replay reached the configured endClose the run and label output state
replay_stoppedConfirms replay stopClose the run cleanly
gap_detectedMarks a missing or discontinuous intervalMark output incomplete or rebuild
errorReports a command or auth failureLog 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.
​
type
string
Event name emitted by the server, such as data, l4_snapshot, replay_snapshot, historical_data, gap_detected, or error.
​
channel
string
Market-data channel associated with the event. Replay-control events may use replay-specific event names.
​
symbol
string
Symbol or pair in the route-family format selected by the client.
​
timestamp
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 Packet

Review this packet before generating WebSocket commands.
FieldRequired check
Operationsubscribe, unsubscribe, replay, replay control, or ping
Channel fieldSingle channel or bounded channels list, not both by accident
Symbol formatFamily-specific symbol, pair, builder prefix, outcome ID, or Lighter market
Replay windowExplicit start, end, and speed for replay jobs
Error pathLog command errors, auth failures, close events, and request or correlation IDs
Gap pathMark output incomplete or rebuild when gap_detected appears
Event namesParse 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.
Last modified on May 18, 2026