Point-In-Time Backtesting

Outcome

Produce one reproducible Point-In-Time Backtesting run for a bounded Hyperliquid core BTC trades window.

Backtest Contract

Declare the venue family, symbol, data family, route, integer-millisecond window, page budget, quality gate, output schema, and request IDs before the run starts. Keep raw API rows separate from derived features or strategy output.

Prerequisites

Choose one hypothesis that can be tested with one data family.
Complete Choose venue and market family when the symbol namespace is not known.
Check /v1/data-quality/status and the selected symbol’s coverage before using the window.
Set a finite page budget, gap policy, and output path.

Inputs

Field	Bounded value
Venue family	Hyperliquid core
Symbol	`BTC`
Data family	Trades
Route	`/v1/hyperliquid/trades/BTC`
Window	`start=1767225600000&end=1767229200000`
Page size	`limit=1000`
Stop rule	Window exhausted, page budget reached, or a quality or replay gap requires a stop

Steps

Freeze the inputs

Save the family, symbol, data family, numeric window, page size, quality threshold, gap policy, and output path before calling the API.

Check data quality

Call /v1/data-quality/status and the exact symbol-coverage route. Keep those responses with the run even when the job later stops.

Pull one bounded page

Use the exact request in the next section. Do not add concurrency until the first response and its request ID are saved.

Follow only returned cursors

If meta.next_cursor is present, send that exact value within the declared page budget. Do not generate an unbounded loop.

Choose the event surface when needed

If event order rather than returned rows is the requirement, stop the REST run and continue with WebSocket replay. Record the channel, numeric window, replay controls, gaps, and request IDs for that separate run.

REST Window Example

curl -sS "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?start=1767225600000&end=1767229200000&limit=1000" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Parse an ISO date-time into Unix epoch milliseconds before sending a request. The runnable example sends integer milliseconds, not ISO text. Save the exact query string and the request ID returned by the route.

Expected state

The run has a route-specific response with success, a data array of trade rows, and request metadata. It is complete only when the requested window is exhausted within the page budget and the quality decision allows use. A returned gap, stale state, or remaining cursor makes the run partial or stopped.

Verification

Check the first and last returned timestamps against the numeric bounds. If pagination occurs, keep the cursor chain and request IDs per page. If the run uses derived features, keep them in a separate artifact and retain the raw response and quality responses unchanged.

Failure and recovery

400: fix the numeric bounds, symbol, or named parameter before retrying.
401: repair the key source or header.
429: honor Retry-After when present, otherwise use capped exponential backoff with jitter inside the retry budget.
A remaining cursor at the page budget: mark the run partial and resume under a new bounded manifest.
A quality or gap_detected result: stop the derived calculation, narrow the window, or rebuild the relevant state from the documented checkpoint path.
Missing rights for the intended use: stop and read Data rights before creating a benchmark, index, financial product, or bulk distribution.

Backtest Generation Checklist

Venue family and symbol remain literal.
Route, integer start, integer end, and limit are saved.
Page budget, cursor behavior, and request IDs are saved.
/v1/data-quality/status, coverage, freshness, and incident decisions are attached when used.
Raw rows remain separate from derived features.
Do not generate unbounded loops.
A gap or stale result changes the run status instead of being silently filled.

Saved run metadata

Run Manifest

{
  "purpose": "btc_trade_backtest_hour_001",
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "data_family": "trades",
  "surface": "REST",
  "route": "/v1/hyperliquid/trades/BTC",
  "window": {
    "start": 1767225600000,
    "end": 1767229200000
  },
  "limit": 1000,
  "page_budget": "record the finite page count",
  "quality_gate": {
    "status_route": "/v1/data-quality/status",
    "coverage_route": "/v1/data-quality/coverage/hyperliquid/BTC",
    "decision": "record the returned decision"
  },
  "request_ids": ["00000000-0000-0000-0000-000000000000"],
  "output": "./artifacts/btc-trade-backtest-hour-001.json",
  "run_status": "complete | partial | stopped"
}

The zero UUID is a shape placeholder only. Replace it with the UUID returned by each request. Keep the route, numeric window, quality source, and output path together.

Next task

Use Historical market data for cursor mechanics, Reliability and data gaps for partial runs, or WebSocket replay when event order is part of the hypothesis.

​Outcome

​Backtest Contract

​Prerequisites

​Inputs

​Steps

​REST Window Example

​Expected state

​Verification

​Failure and recovery

​Backtest Generation Checklist

​Saved run metadata

​Run Manifest

​Next task