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