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

Use replay when the order of events changes the answer, and reconstruction when you maintain a local order book from a baseline plus ordered changes. Both are stricter than an ordinary historical pull: 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 |
| - | - |
| One current snapshot | REST snapshot: [Order book routes](/rest-api/order-books) |
| Bounded historical pull | REST history: [Pull historical market data](/guides/historical-market-data) |
| Event-order playback | [WebSocket replay](/websocket/replay) |
| Local book maintenance | WebSocket channels and diffs: [WebSocket L4 order book](/websocket/l4-orderbook) |
| Reconstruction helpers | [SDK reconstruction](/sdks/reconstruction) |
| File-style rebuild | Data Catalog export plus schema metadata: [Export schemas](/export-schemas) |

For a reproducible backtest window, [Prepare data for a reproducible backtest](/guides/point-in-time-backtesting) combines these steps.

## Source metadata

Record these for every replay or reconstruction run:

* venue and market type, 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 the two 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 and end, whether the run stopped, and the rebuild decision |
| Output state | Complete, partial, rejected, or rebuilt from a named checkpoint |

State labels matter to downstream users. A chart can show a partial replay window, but a trading model or backtest should not treat a partial reconstruction as clean input. Handle a gap as described in [Data quality](/data-quality#handle-gaps).

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

If the same workflow later moves from WebSocket replay to 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 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.

## Next step

Start a replay, with its snapshot and timing, in [WebSocket replay](/websocket/replay).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.