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

# Quickstart

> Create a key, make one authenticated request, read the response, and handle the errors you are most likely to see.

Create an API key in the [dashboard](https://0xarchive.io/dashboard?utm_source=docs\&utm_medium=referral\&utm_campaign=docs_referral\&utm_content=quickstart_create_key) (the Free plan needs no card), then set it and call the BTC order book:

```bash theme={"theme":"github-dark"}
export OXARCHIVE_API_KEY="0xa_your_api_key"
curl "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

## The response

This [native Hyperliquid L2 route](/api-reference/hyperliquid--order-book/get-hyperliquid-native-l2-order-book-20-levels) returns the order book in `data`, here with one level per side. Values change with the market:

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": {
    "coin": "BTC",
    "symbol": "BTC",
    "timestamp": "2026-10-06T11:46:06.500Z",
    "bids": [
      { "px": "86336", "sz": "6.91814", "n": 26 }
    ],
    "asks": [
      { "px": "86337", "sz": "0.99133", "n": 11 }
    ],
    "mid_price": "86336.5",
    "spread": "1",
    "spread_bps": "0.11582586739096441"
  },
  "meta": {
    "count": 1,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "symbol": "BTC",
    "venue": "hyperliquid"
  }
}
```

* `px` and `sz` are decimal strings. Parse them as decimals, not floats, when you need exact values.
* `n` is the number of resting orders at that price level.
* Keep `meta.request_id`, or the `x-request-id` response header, with the route and symbol. [Responses](/responses) covers the envelope in full.

The same call in Python and JavaScript:

<CodeGroup>
  ```python Python theme={"theme":"github-dark"}
  import os
  import requests

  res = requests.get(
      "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=1",
      headers={"X-API-Key": os.environ["OXARCHIVE_API_KEY"]},
      timeout=20,
  )
  res.raise_for_status()
  payload = res.json()
  book = payload["data"]
  print(book["symbol"], book["mid_price"], payload["meta"]["request_id"])
  ```

  ```javascript JavaScript theme={"theme":"github-dark"}
  const res = await fetch("https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=1", {
    headers: { "X-API-Key": process.env.OXARCHIVE_API_KEY }
  });

  if (!res.ok) throw new Error(`0xArchive request failed: ${res.status}`);
  const payload = await res.json();
  console.log(payload.data.symbol, payload.data.mid_price, payload.meta.request_id);
  ```
</CodeGroup>

The [SDKs](/sdks) wrap this call in typed clients for Python, TypeScript, and Rust.

## Confirm success

The first call is complete when it returns HTTP `200`, `success: true`, an order-book object in `data`, and a UUID-shaped `meta.request_id`.

Do not use `GET /health` as the key check. It is an unauthenticated liveness route, so it succeeds with or without a valid key.

Before you add another symbol or a historical window, confirm its namespace and history in [Venue coverage](/venue-coverage). The Free plan reads the most recent 30 days. The same key works for [WebSocket streams and replay](/websocket/connection), the [CLI](/cli), and the [Agent skill](/skill).

## When a call fails

Every error returns the same flat JSON body: `success: false`, the HTTP status in `code`, a stable `error_code`, a readable `error` message, and a top-level `request_id`. A call without a key returns:

```json theme={"theme":"github-dark"}
{
  "success": false,
  "code": 401,
  "error_code": "unauthorized",
  "error": "Missing authentication credentials. Provide X-API-Key header or Bearer token.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

| Status | What it means and what to do |
| - | - |
| `400` | A bad parameter, symbol, or interval (`invalid_query_params`, `invalid_symbol`, `invalid_interval`). The `error` message names the field; fix the request before retrying. |
| `401` | The key is missing or invalid (`unauthorized`). Check the `X-API-Key` header and that the key is active; see [REST authentication](/rest-api/authentication). |
| `403` | The window is older than your plan's history or wider than its span (`history_window_exceeded`, `request_range_exceeded`), or the key cannot use the route (`forbidden`). Every plan can call every route; plans set history and capacity. |
| `429` | A rate, concurrency, or credit limit was reached. Retry `rate_limited` after its `retry_after` seconds; stop on `insufficient_credits`. See [When you reach a limit](/rate-limits#when-you-reach-a-limit). |

[Errors](/errors) lists every code with its retry rule, and [Rate limits](/rate-limits) gives each plan's credits and concurrency. Quote the failed `request_id` or `x-request-id` when you contact support.

## Next step

Browse the [Endpoint reference](/api-reference) to find the next route for your job. Every endpoint page lists its parameters, response schema, and an example request.


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