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

# Replay and reconstruction

> Decide when to use REST history, WebSocket replay, L3/L4 routes, diffs, and SDK reconstruction for stateful market-data workflows.

Replay and reconstruction are the right primitives when sequence, local state, gap handling, or order-book rebuilding matters more than a single response.

Replay and reconstruction are stricter than ordinary historical pulls. If a model, chart, or strategy depends on event order, every message and request must carry enough metadata to reproduce the sequence.

## Choose The Primitive

| Need                    | Primitive                                | Start                                                    |
| ----------------------- | ---------------------------------------- | -------------------------------------------------------- |
| One current snapshot    | REST snapshot                            | [Order book routes](/rest-api/order-books)               |
| Bounded historical pull | REST history                             | [Historical market data](/guides/historical-market-data) |
| Event-order playback    | WebSocket replay                         | [WebSocket replay](/websocket/replay)                    |
| Local book maintenance  | WebSocket channels and diffs             | [WebSocket L4 order book](/websocket/l4-orderbook)       |
| Reconstruction helpers  | SDK reconstruction                       | [SDK reconstruction](/sdks/reconstruction)               |
| File-style rebuild      | Data Catalog export plus schema metadata | [Export schemas](/export-schemas)                        |

## Source Metadata

Every replay or reconstruction workflow should record:

* venue family and symbol
* route, channel, or export schema key
* start and end time
* cursor or replay sequence
* snapshot source
* diff or event source
* gap, reconnect, and retry events
* data-quality result
* `meta.request_id` where REST is involved

## State Boundaries

Replay sends ordered historical events. Reconstruction turns a baseline plus ordered changes into local state. Keep those concepts separate in code and output labels. A replay file can be correct while a reconstruction is unsafe if the client applied messages out of order, ignored a gap, or rebuilt from the wrong snapshot.

| Boundary     | Record                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------- |
| Baseline     | snapshot route, replay snapshot, checkpoint, timestamp, and request ID when REST is used |
| Updates      | channel, diff source, cursor, replay window, and message order                           |
| Gap behavior | gap start/end, whether the run stopped, and rebuild decision                             |
| Output state | complete, partial, rejected, or rebuilt from a named checkpoint                          |

State labels matter for downstream users. A chart can show a partial replay window, but a trading model or backtest should not treat partial reconstruction as clean input.

## When Not To Use Replay

Do not use replay when a REST snapshot answers the question. Replay is heavier and stricter because sequence mistakes can silently corrupt local state. Use it when timing, causality, diffs, or historical event order are part of the product requirement.

If the same workflow later moves from WebSocket replay into exported files, keep the replay metadata with the file output so the rebuild can be explained later.

## Minimal Run Manifest

```json theme={"theme":"github-dark"}
{
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "primitive": "websocket_replay",
  "channels": ["orderbook", "trades"],
  "window": { "start": 1681516800000, "end": 1681603200000 },
  "baseline": "replay_snapshot",
  "gap_events": [],
  "output_state": "complete"
}
```

Use the same manifest idea for SDK reconstruction and export-backed rebuilds. The exact fields can vary, but the file should name the source, window, gap state, and output state.

## Related Pages

<CardGroup cols={2}>
  <Card title="WebSocket backtesting" icon="rotate-ccw" href="/websocket/backtesting">
    Replay historical windows for backtests and incident review.
  </Card>

  <Card title="SDK reconstruction" icon="blocks" href="/sdks/reconstruction">
    Client-side reconstruction patterns and state handling.
  </Card>

  <Card title="Responses" icon="braces" href="/responses">
    Envelope, request ID, pagination, error, and parser rules.
  </Card>

  <Card title="Data gaps" icon="triangle-alert" href="/core-concepts/data-gaps">
    Treat gaps as data, not as parser noise.
  </Card>
</CardGroup>