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

# Evaluate a market data API

> Make a route-first fit decision for one market-data job using bounded request, schema, quality, capacity, and rights checks.

Decide whether an API can return the record one market-data job needs, and keep the route and evidence so anyone can repeat the decision. The example evaluates one hour of Hyperliquid core BTC trades, a window every plan's history reaches, including Free's most recent 30 days.

## Before you start

* Name the record and grain: snapshot, trade, candle, funding, open interest, liquidation, order event, replay, or export.
* Name one venue and market type, symbol, and bounded time window.
* Define the required response fields, freshness tolerance, and downstream use before comparing providers.
* Separate market-data retrieval from account state and execution. Those account and execution behaviors are outside 0xArchive's market-data scope.

## Inputs

| Field | Example |
| - | - |
| Job | One-hour Hyperliquid core BTC trade pull |
| Route | `/v1/hyperliquid/trades/BTC` |
| Window | `start=$START`, `end=$END`: the hour that ended one hour ago |
| Response needs | Trade rows, cursor behavior, and request IDs |
| Quality gate | Coverage, freshness, and incident state for the same market and window |
| Decision | Use, hold for more evidence, or route to another product category |

## Steps

<Steps>
  <Step title="State the required result">
    Write the venue and market type, symbol, data family, window, required fields, freshness tolerance, and intended use in one short record.
  </Step>

  <Step title="Inspect the exact contract">
    Use [OpenAPI](/openapi) and the matching endpoint page to check the route, authentication, parameter types, response shape, pagination, errors, and request-ID location.
  </Step>

  <Step title="Run one bounded request">
    ```bash theme={"theme":"github-dark"}
    END=$(( ($(date +%s) - 3600) * 1000 ))   # one hour ago, in Unix milliseconds
    START=$(( END - 3600 * 1000 ))           # one hour earlier

    curl -sS "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?start=$START&end=$END&limit=1000" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```
  </Step>

  <Step title="Check quality and capacity">
    Compare the response with the symbol's coverage and freshness on [Data quality](/data-quality). Check your plan's limits on [Rate limits](/rate-limits) before turning one call into a recurring or wider job.
  </Step>
</Steps>

## What a complete record holds

The record contains a route-backed answer: the response has the required row shape, the requested window is represented by the returned data or an explicit empty result, the request ID is saved, and the quality decision is named. A route that exists in OpenAPI is not evidence of every symbol, date, or schema window.

## Score the API on the job

Score the API on the exact job, not on a product inventory:

| Check | Passing observation |
| - | - |
| Route and auth | The exact operation and key requirement are written down |
| Parameters | Types, bounds, and cursor behavior match the endpoint page |
| Response | Required fields and the request-ID location are observable |
| Quality | Coverage, freshness, and incident state are checked for the selected market and window |
| Capacity | Account rate, concurrency, credit, and request-span constraints are recorded |
| Rights | The downstream transformation and source-exposure decision is recorded |

Check [Data rights](/data-rights) for the use-permission decision. Internal research and Parquet exports are permitted. Materially transformed derived products and ordinary customer-facing use are permitted when they do not expose or allow reconstruction of original records. Benchmarks, indices, financial products, standalone or substitute market-data products, raw redistribution, and white-label or OEM delivery require prior written permission.

## If something fails

* `400`: fix the named parameter or time window before another call.
* `401`: repair the key source or header.
* `403`: read the exact error for that endpoint, account, and key; the status alone does not mean a route or schema is unavailable.
* `404`: recheck the market type, symbol, and route namespace.
* `429`: honor `Retry-After` when present, otherwise use capped exponential backoff with jitter and reduce concurrency.
* Missing coverage or stale data: hold the decision, narrow the job, or mark the output. Do not replace missing rows with synthetic data.

## Saved run metadata

```json theme={"theme":"github-dark"}
{
  "job": "btc_trade_api_fit_001",
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "data_family": "trades",
  "route": "/v1/hyperliquid/trades/BTC",
  "query": {
    "start": "START in Unix ms",
    "end": "END in Unix ms",
    "limit": 1000
  },
  "request_ids": ["00000000-0000-0000-0000-000000000000"],
  "quality_source": "record the exact coverage, freshness, and incident responses",
  "decision": "record use, hold, or route elsewhere"
}
```

The zero UUID is a shape placeholder only. Replace it with the returned UUID and keep the API key out of the record. When the result feeds a backtest, [Prepare data for a reproducible backtest](/guides/point-in-time-backtesting) adds the replay and manifest steps.

## Next step

Implement the selected pull with [Pull historical market data](/guides/historical-market-data).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.