WebSocket replay

Replay sends historical data over the WebSocket at a controlled speed. Use it when order and timing matter more than a single REST response.

Single-Channel Replay

ws.send(JSON.stringify({
  op: "replay",
  channel: "orderbook",
  symbol: "BTC",
  start: 1681516800000,
  end: 1681603200000,
  speed: 10
}));

Multi-Channel Replay

ws.send(JSON.stringify({
  op: "replay",
  channels: ["orderbook", "trades", "funding"],
  symbol: "BTC",
  start: 1681516800000,
  end: 1681603200000,
  speed: 10
}));

Multi-channel replay should keep all channels inside the same venue family. Do not combine Hyperliquid core channels with Lighter, HIP-3, HIP-4, or Spot channels in one replay command.

Controls

Pause

{"op":"replay.pause"}

Resume

{"op":"replay.resume"}

Seek

{"op":"replay.seek","timestamp":1681550000000}

Stop

{"op":"replay.stop"}

Gap Handling

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "gap_detected") {
    console.warn("Replay gap", msg.channel, msg.symbol, msg.gap_start, msg.gap_end);
  }
};

Replay Event Flow

Replay control commands use dotted op values. Server events use underscore event names.

Event	Meaning	Client behavior
`replay_started`	Replay window accepted	Start the run manifest and record channel, symbol, start, end, and speed
`replay_snapshot`	Initial state before timeline messages	Build baseline state before processing historical messages
`historical_data`	Timeline data emitted in replay order	Apply the message according to channel semantics and preserve timestamp
`gap_detected`	Missing or discontinuous interval	Mark the output incomplete, stop, or rebuild from a known checkpoint
`replay_paused`	Replay paused after `replay.pause`	Keep state but stop advancing the run clock
`replay_resumed`	Replay resumed after `replay.resume`	Continue processing from the current timestamp
`replay_completed`	Replay reached the end of the configured window	Close the manifest and label the output complete, partial, or rejected
`replay_stopped`	Replay stopped by `replay.stop`	Close the manifest as stopped and keep the stop reason

Replay Design

Replay is for workflows where event order matters: backtests, local book reconstruction, incident review, data QA, and model-input regeneration. Choose the narrowest channel set that can answer the question. A single-channel order-book replay is easier to audit than a broad multi-channel replay, and a broad replay should be split into windows that can be resumed independently.

Replay Manifest

Store a manifest beside every replay output.

{
  "surface": "websocket_replay",
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "channels": ["orderbook", "trades"],
  "window": {
    "start": 1681516800000,
    "end": 1681603200000
  },
  "speed": 10,
  "gap_events": [],
  "output": "s3://example/replay/btc-2023-04-15.jsonl"
}

Include replay controls used during the run, such as pause, resume, seek, or stop. If the client changes speed or seeks to a new timestamp, record that in the manifest so another run can explain the output sequence.

Window Sizing

Start with a narrow window and one channel. Widen only after the consumer can keep messages ordered, write output without backlog, and handle gaps. For long jobs, split replay into resumable windows and keep a cursor or output checkpoint between them.

Output Discipline

Store replay configuration with the output: channel list, symbol, start, end, speed, requested venue family, gap events, and any request or correlation IDs. If a replay emits a gap, mark the derived output as incomplete or rebuild from a safe checkpoint. Do not silently interpolate missing market events.

REST Or Replay

Use REST history when you need records from a bounded window and ordering can be handled after retrieval. Use replay when the sequence itself is the product requirement: maintaining a book, testing a strategy against event cadence, or reproducing a historical stream.

Review Rule

Replay examples should include stop conditions. A safe replay has a bounded window, controlled speed, gap handling, and a clear output destination. For backtests, store the replay config, replay events, and gap events beside the result so another engineer can inspect the run without reproducing the whole stream.

Connect

Stream

Replay

Single-Channel Replay

Multi-Channel Replay

Controls

Pause

Resume

Seek

Stop

Gap Handling

Replay Event Flow

Replay Design

Replay Manifest

Window Sizing

Output Discipline

REST Or Replay

Review Rule

​Single-Channel Replay

​Multi-Channel Replay

​Controls

Pause

Resume

Seek

Stop

​Gap Handling

​Replay Event Flow

​Replay Design

​Replay Manifest

​Window Sizing

​Output Discipline

​REST Or Replay

​Review Rule

Single-Channel Replay

Multi-Channel Replay

Controls

Gap Handling

Replay Event Flow

Replay Design

Replay Manifest

Window Sizing

Output Discipline

REST Or Replay

Review Rule