Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt

Use this file to discover all available pages before exploring further.

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 requirement0xArchive surfaceWhat to record
Bounded recordsREST history routesRoute, query parameters, cursor chain, request IDs
Event orderWebSocket replayChannel, speed, start/end, gap events, replay controls
Venue taxonomyVenue coverage docsFamily, symbol style, route prefix
Freshness and gapsData-quality routesStatus, incident overlap, stale windows
Application codeSDKs or generated clientsPackage version, OpenAPI version, response schema
Shell jobsCLI JSON outputCommand, env key source, stdout file, exit code

​
Build The First Run

1

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.
2

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.
3

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.
4

Pull a bounded window

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

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 Packet

Generated backtest examples should start from a bounded packet, not from a broad loop.
FieldCapture
Venue family and symbolHyperliquid core BTC, Spot pair, HIP-3 builder symbol, HIP-4 outcome, or Lighter symbol
Data familyTrades, order books, candles, funding, OI, replay, L3, L4, or reconstruction
WindowExplicit 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 fieldsRoute, channel, request IDs, cursor chain, code version, OpenAPI version, and output path
Stop ruleDo 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 turning research output into a customer-facing download.
Last modified on May 18, 2026