> ## 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.

# WebSocket Message Schema

> Use the documented WebSocket command and event shapes for connection, subscription, replay, gaps, and errors.

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`                                                    |

```json theme={"theme":"github-dark"}
{
  "op": "subscribe",
  "channel": "orderbook",
  "symbol": "BTC"
}
```

```json theme={"theme":"github-dark"}
{
  "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                        |
| `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                    |

```json theme={"theme":"github-dark"}
{
  "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.

<ResponseField name="type" type="string">
  Event name emitted by the server, such as `data`, `l4_snapshot`, `replay_snapshot`, `historical_data`, `gap_detected`, or `error`.
</ResponseField>

<ResponseField name="channel" type="string">
  Market-data channel associated with the event. Replay-control events may use replay-specific event names.
</ResponseField>

<ResponseField name="symbol" type="string">
  Symbol or pair in the route-family format selected by the client.
</ResponseField>

<ResponseField name="timestamp" type="number">
  Event timestamp when the channel emits one. Store it in the same run manifest as the replay or live stream.
</ResponseField>

## 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.

| 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](/websocket/connection) for auth and reconnect behavior, [Channels](/websocket/channels) for channel selection, [Replay](/websocket/replay) for historical event streams, and [Limits](/websocket/limits) for subscription and throughput sizing.