WebSocket Backtesting

WebSocket backtesting uses replay to support research, reconstruction, and strategy evaluation, not only a generic historical command list. Backtesting needs reproducible inputs. Use REST history when records can be retrieved and ordered after the fact. Use WebSocket replay when event cadence, sequence, local book state, or gap handling is part of the test.

REST History Versus Replay

Need	Better fit
Pull trades for a bounded window	REST history
Rebuild a local order book in event order	WebSocket replay
Test strategy reaction to event cadence	WebSocket replay
Compare daily funding or OI values	REST history
Reproduce an incident stream	WebSocket replay
Generate a static research file	REST history unless sequence matters

Backtest Input Contract

Name the route family

Store Hyperliquid core, Hyperliquid Spot, HIP-3, HIP-4, or Lighter explicitly with the backtest.

Bound the replay window

Use explicit start, end, channel, symbol, and speed values. Avoid endless replay jobs.

Handle gaps

Record gap events and decide whether the run is invalid, partial, or rebuildable.

Save replay metadata

Store channel list, symbol, timestamps, speed, request IDs, output location, and data-quality preflight.

Replay Example

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

Pair the command with stop conditions, backpressure handling, and output storage. A replay that cannot be consumed in order is not a trustworthy backtest input.

Run Metadata

Store the same metadata with every replay-backed test so results can be compared later.

Field	Example
Purpose	`btc_orderbook_reaction_test`
Venue family	`hyperliquid_core`
Symbol and channels	`BTC`, `orderbook`, `trades`
Window and speed	`1681516800000` to `1681603200000`, speed `10`
Quality checks	status, coverage, incidents, and freshness routes run before the replay
Gap policy	fail run, mark partial, or rebuild from checkpoint
Output location	JSONL, Parquet, notebook artifact, or database table
Code version	strategy commit, notebook hash, or generated-client version

Backtests should also record consumer lag. If the replay outpaces the strategy loop or output writer, the run should stop or slow down rather than silently dropping messages.

Data Quality Gate

Before using replay output as evidence, check coverage, freshness, and incidents for the relevant family and window. If a gap appears during replay, preserve it with the result. Do not silently interpolate missing market events and present the result as complete.

Result Decisions

When a replay run ends, label it as complete, partial, or rejected. Complete means the configured window ran to the stop condition without unresolved gaps or consumer backlog. Partial means the output may still be useful for review, but the manifest must name the missing interval or state rebuild. Rejected means the strategy output should not be compared against clean runs.

Next Step

Use WebSocket Replay for commands, Point-In-Time Backtesting for reproducibility, and Market Data APIs For Backtesting for evaluation criteria.

Documentation Index

​REST History Versus Replay

​Backtest Input Contract

​Replay Example

​Run Metadata

​Data Quality Gate

​Result Decisions

​Next Step