> ## 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, set it in your environment, and call the BTC order book.

**Start building with a Free key**

Create a key, make the BTC request below, and take the response into your own code. No card required.

[Create a key](https://0xarchive.io/dashboard?utm_source=docs\&utm_medium=referral\&utm_campaign=docs_referral\&utm_content=quickstart_create_key)
[Authentication](https://docs.0xarchive.io/rest-api/authentication.md)

```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](https://docs.0xarchive.io/api-reference/hyperliquid--order-book/get-hyperliquid-native-l2-order-book-20-levels.md) 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](https://docs.0xarchive.io/responses.md) covers the envelope in full.

The same call in Python and JavaScript:

```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);
```

The [SDKs](https://docs.0xarchive.io/sdks.md) 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](https://docs.0xarchive.io/venue-coverage.md). The Free plan reads the most recent 30 days. The same key works for [WebSocket streams and replay](https://docs.0xarchive.io/websocket/connection.md), the [CLI](https://docs.0xarchive.io/cli.md), and the [Agent skill](https://docs.0xarchive.io/skill.md).

## 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](https://docs.0xarchive.io/rest-api/authentication.md). If the code is `subscription_past_due` or `subscription_inactive`, the key is fine and the plan's billing needs attention: open the `billing_url` in the body. |
| `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 except four Build-and-above datasets (trade intent, USDC flows, breadth above the moving average and positioning); plans set history and capacity. |
| `429` | A rate, concurrency, or credit limit was reached. Retry `rate_limited` after its `retry_after` seconds. When it carries `max_concurrent` instead, retry once one of your in-flight requests finishes and cap your concurrency at that limit. Stop on `insufficient_credits`. See [When you reach a limit](https://docs.0xarchive.io/rate-limits.md#when-you-reach-a-limit). |

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

## Next step

**Build on your first request**

Find the next route for your project, with its parameters, response schema and example request beside it.

[Find your next route](https://docs.0xarchive.io/api-reference.md)


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