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

# Pull Historical Market Data

> Pull bounded historical market-data windows for research, backtesting, and migration checks.

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

<Steps>
  <Step title="Choose the venue family">
    Use [Venue Coverage](/venue-coverage) to pick Hyperliquid core, Hyperliquid Spot, HIP-3, HIP-4, or Lighter.
  </Step>

  <Step title="Check coverage and incidents">
    Use [Data Quality](/data-quality) before pulling long windows.
  </Step>

  <Step title="Pull one bounded window">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?start=1767225600000&end=1767229200000&limit=1000" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```
  </Step>

  <Step title="Paginate deliberately">
    Follow `meta.next_cursor` until it is absent, then store the request IDs with the output.
  </Step>
</Steps>

## 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](/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.

```json theme={"theme":"github-dark"}
{
  "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.