Replay and reconstruction

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
Bounded historical pull	REST history: Pull historical market data
Event-order playback	WebSocket replay
Local book maintenance	WebSocket channels and diffs: WebSocket L4 order book
Reconstruction helpers	SDK reconstruction
File-style rebuild	Data Catalog export plus schema metadata: Export schemas

For a reproducible backtest window, Prepare data for a reproducible backtest 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.

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

{
  "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.

Start

Concepts

Plans and limits

Policies

Guides

Replay and reconstruction

Choose the primitive

Source metadata

State boundaries

When not to use replay

Minimal run manifest

Next step

​Choose the primitive

​Source metadata

​State boundaries

​When not to use replay

​Minimal run manifest

​Next step

Choose the primitive

Source metadata

State boundaries

When not to use replay

Minimal run manifest

Next step