Point-In-Time Backtesting

Backtests are only useful when another engineer can reconstruct what the strategy saw at the time. 0xArchive gives you the route families, historical windows, replay primitives, and data-quality checks to build that audit trail across Hyperliquid core, Hyperliquid Spot, HIP-3, HIP-4, and Lighter. Point-in-time backtesting is for strategy research, model validation, historical reconstruction, incident review, and every workflow where “latest available data” is not enough.

Backtest Contract

Every run should declare the market family, symbol, data family, time window, route or channel, cursor behavior, freshness gate, and output schema before it starts. That turns a notebook into an executable research artifact instead of a one-off query.

Backtest requirement	0xArchive surface	What to record
Bounded records	REST history routes	Route, query parameters, cursor chain, request IDs
Event order	WebSocket replay	Channel, speed, start/end, gap events, replay controls
Venue taxonomy	Venue coverage docs	Family, symbol style, route prefix
Freshness and gaps	Data-quality routes	Status, incident overlap, stale windows
Application code	SDKs or generated clients	Package version, OpenAPI version, response schema
Shell jobs	CLI JSON output	Command, env key source, stdout file, exit code

Build The First Run

Choose one venue family

Start with the exact family: Hyperliquid core perps, Hyperliquid Spot, HIP-3 builder perps, HIP-4 outcome markets, or Lighter. Do not normalize symbols before you know which namespace they belong to.

Select the data family

Trades, order books, candles, funding, open interest, liquidations, L3/L4, and replay answer different research questions. Pick the narrowest one that can test the hypothesis.

Check quality before the pull

Call /v1/data-quality/status and any route-specific freshness endpoint before using the window. Store that result with the run.

Pull a bounded window

Use start, end, limit, and cursor handling. Avoid unbounded loops. Save request IDs and pagination state.

Freeze the run manifest

Store the run manifest beside the output. Include the OpenAPI/spec version, code version, and any data-quality notes.

REST Window Example

curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?start=2026-01-01T00:00:00Z&end=2026-01-01T01:00:00Z&limit=1000" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

For the first run, inspect payload shape before adding concurrency. Confirm success, data, and meta.request_id, then decide whether the route returns meta.next_cursor for pagination. Store the exact query string. Backtests often become impossible to debug because the dataset kept the rows but not the request that produced them.

Replay Example

Use WebSocket replay when the order of messages is part of the strategy. REST history can answer “what trades happened in this window?” Replay is better for “what would the book handler have seen as events arrived?”

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

Handle gap_detected messages as part of the backtest result. A gap is not just a transport event; it changes the meaning of the derived metrics. Mark the run incomplete, narrow the window, or rebuild from a checkpoint.

Point-In-Time Rules

Do not mix current metadata into historical evaluation unless the model is explicitly allowed to know it. Keep symbol lookup, market family, instrument metadata, and data-quality state tied to the run time where possible. If a route returns current metadata for convenience, store that fact in the manifest so a reviewer understands the boundary. Do not fill missing market data with synthetic records inside the raw dataset. If a strategy layer interpolates or imputes, keep that as a separate derived artifact and label it. The raw pull should stay as close as possible to the API response plus reproducibility metadata.

Backtest Generation Checklist

Generated backtest examples should start from a bounded checklist, not from a broad loop.

Field	Capture
Venue family and symbol	Hyperliquid core `BTC`, Spot pair, HIP-3 builder symbol, HIP-4 outcome, or Lighter symbol
Data family	Trades, order books, candles, funding, OI, replay, L3, L4, or reconstruction
Window	Explicit `start`, `end`, `limit`, cursor behavior, and replay speed when applicable
Quality check	`/v1/data-quality/status`, freshness, coverage, incident overlap, or replay gap handling
Trace fields	Route, channel, request IDs, cursor chain, code version, OpenAPI version, and output path
Stop rule	Do not generate unbounded loops; widen only after the first bounded run is inspectable

Run Manifest

{
  "purpose": "btc_trade_backtest_hour_001",
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "surface": "REST",
  "route": "/v1/hyperliquid/trades/BTC",
  "window": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-01T01:00:00Z"
  },
  "quality_gate": {
    "checked": true,
    "status_route": "/v1/data-quality/status"
  },
  "request_ids": ["req_..."],
  "output": "s3://example/backtests/btc/hour-001.parquet"
}

Next Steps

Use Historical market data for bounded REST pulls, WebSocket replay for ordered streams, SDK reconstruction for local order-book state, and Data rights before creating benchmarks, indices, or financial products, or publishing bulk raw-data downloads, bulk republication, API mirrors, substitute feeds, or white-label or OEM delivery.

​Backtest Contract

​Build The First Run

​REST Window Example

​Replay Example

​Point-In-Time Rules

​Backtest Generation Checklist

​Run Manifest

​Next Steps