Pull historical market data

Historical jobs should be narrow first: one venue family, one symbol, one data family, one time window.

Choose the venue family

Use Venue coverage to pick Hyperliquid core, Hyperliquid Spot, HIP-3, HIP-4, or Lighter.

Check coverage and incidents

Use Data quality before pulling long windows.

Pull one bounded window

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

Paginate deliberately

Follow meta.next_cursor until it is absent, then store the request IDs with the output.

Route Choice

Need	Start with
Hyperliquid perp history	`/v1/hyperliquid/*`
Hyperliquid Spot history	`/v1/hyperliquid/spot/*`
HIP-3 builder perp history	`/v1/hyperliquid/hip3/*`
HIP-4 outcome-market history	`/v1/hyperliquid/hip4/*`
Lighter history	`/v1/lighter/*`
Sequenced replay	WebSocket replay

Parameter Rules

Most REST history routes use Unix milliseconds for start, end, and cursor-like pagination values. The response envelope can include meta.count, meta.next_cursor, and meta.request_id. Store those values with the output, especially when the job will feed a notebook, backtest, dashboard, or export comparison. Do not mix timestamp formats inside one job. If a human chooses an ISO window, convert it once at the edge, store both the original human window and the Unix millisecond values sent to the API, then use the API values in retries and cursor loops.

Output Contract

Historical output should include the input route, query parameters, start and end window, cursor chain, venue family, symbol, and request IDs. That metadata is what lets another engineer, researcher, or agent reproduce the pull later. Without it, a backtest file becomes detached from the API behavior that created it.

{
  "route": "/v1/hyperliquid/trades/BTC",
  "query": {
    "start": 1767225600000,
    "end": 1767229200000,
    "limit": 1000
  },
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "cursor_chain": ["1767226500000_123456789"],
  "request_ids": ["req_..."],
  "quality_gate": "coverage and incidents checked before use"
}

Data-Quality Gate

Use status, coverage, freshness, and incidents before downstream use. If a requested window overlaps a known incident or stale period, mark the output or rerun a narrower window. Do not fill missing market data with synthetic rows unless the downstream consumer explicitly understands that transformation.

Interface Choice

Use REST for bounded records, WebSocket replay for ordered event streams, SDKs for application code, CLI for shell/CI jobs, and OpenAPI for generated clients. The same historical workflow can start in curl and later move to a stronger interface without changing the route-family decision.

Review Rule

Review historical jobs by input and output. Inputs are route, symbol, window, cursor, and key. Outputs are records, request IDs, data-quality state, and any gap or incident annotation. If either side is missing, the dataset is not reproducible enough for serious research or backtesting.

​Route Choice

​Parameter Rules

​Output Contract

​Data-Quality Gate

​Interface Choice

​Review Rule