Replay and reconstruction

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

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

WebSocket backtesting

Replay historical windows for backtests and incident review.

SDK reconstruction

Client-side reconstruction patterns and state handling.

Responses

Envelope, request ID, pagination, error, and parser rules.

Data gaps

Treat gaps as data, not as parser noise.

Get started

Market data

Get connected

Plans & limits

Replay and reconstruction

Choose The Primitive

Source Metadata

State Boundaries

When Not To Use Replay

Minimal Run Manifest

WebSocket backtesting

SDK reconstruction

Responses

Data gaps

​Choose The Primitive

​Source Metadata

​State Boundaries

​When Not To Use Replay

​Minimal Run Manifest

​Related Pages

WebSocket backtesting

SDK reconstruction

Responses

Data gaps

Choose The Primitive

Source Metadata

State Boundaries

When Not To Use Replay

Minimal Run Manifest

Related Pages