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

# Coding agents

> Let Claude Code, Codex, Cursor, and other coding-agent hosts run 0xArchive requests: one complete first job, the fields every job needs, and recovery rules.

Let a coding agent run 0xArchive requests, or write code that does, without guessing routes or exposing keys. Start it on one complete job, check the result, and widen only after that. To set up an assistant that answers questions and plans from the docs, see [AI assistants and agents](/ai-clients).

## First bounded request

This first job fetches the latest Hyperliquid core BTC order book, saves it, and stops. Set the key in the agent's environment, then give it the prompt:

```bash theme={"theme":"github-dark"}
export OXARCHIVE_API_KEY="0xa_your_api_key"
```

<Prompt description="Using 0xArchive, fetch the Hyperliquid core BTC order book with depth 1 from GET /v1/hyperliquid/orderbook/BTC. Read the API key from the environment and send it in the X-API-Key header. Make one request, save the response to btc-orderbook.json, print the HTTP status and the request ID, then stop.">Using 0xArchive, fetch the Hyperliquid core BTC order book with depth 1 from GET /v1/hyperliquid/orderbook/BTC. Read the API key from the environment and send it in the X-API-Key header. Make one request, save the response to btc-orderbook.json, print the HTTP status and the request ID, then stop.</Prompt>

An agent with a terminal runs two commands: the request, which saves the body and prints the HTTP status, then `jq`, which prints the request ID from the saved body.

```bash theme={"theme":"github-dark"}
curl -sS -o btc-orderbook.json -w "%{http_code}\n" \
  "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
jq -r '.meta.request_id // .request_id' btc-orderbook.json
```

The job is done when the commands print `200` and a request ID, and `btc-orderbook.json` holds `success: true`, an order book in `data` with one bid level and one ask level, and that ID in `meta.request_id`. On an error, the status is not `200`, the file holds the error body, and `jq` prints its top-level `request_id`. Check that the path names the venue family and that the symbol was not recased or stripped. A successful first call says nothing about another venue family or data type.

The agent needs three pages for this job: the [Hyperliquid REST guide](/rest-api/hyperliquid) for the route family, the [Hyperliquid native L2 endpoint](/api-reference/hyperliquid--order-book/get-hyperliquid-native-l2-order-book-20-levels) for the exact parameters, and [REST authentication](/rest-api/authentication) for the `X-API-Key` header.

When the job needs history, make that a second bounded request with explicit Unix-millisecond bounds. This window, the five minutes that ended one hour ago, is inside every plan's history, including Free's most recent 30 days:

```bash theme={"theme":"github-dark"}
END=$(( ($(date +%s) - 3600) * 1000 ))
START=$(( END - 5 * 60 * 1000 ))

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

When `meta.has_more` is `true`, the response carries `meta.next_cursor`; log it, and pass it back as `cursor` with the same bounds for the next page. Add pagination loops, batching, and retries only after one page parses correctly.

## Job checklist

Give the agent these fields with every job. If one is missing, the agent should ask rather than guess a venue family, broaden a symbol list, or start calling the API.

* **Job and stop condition:** what to fetch and when to stop, such as "one request, then save and stop".
* **Venue family:** `hyperliquid`, `hyperliquid/hip3`, `hyperliquid/hip4`, `hyperliquid/spot`, or `lighter`. This is the REST path prefix after `/v1/`, and it decides the route.
* **Symbol:** `BTC`, `xyz:XYZ100` for HIP-3, `HYPE-USDC` for Spot, or an outcome side such as `#0` for HIP-4. REST also accepts `0` and `%230` for that side; the WebSocket takes only `#0`.
* **Output destination:** where the result and its request IDs are written, such as a file, a notebook, a warehouse table, or a support case.

A history job also needs its window: `start`, `end`, and `limit`, plus where the cursor is kept.

## Pick the interface

* **The agent runs shell commands:** the [CLI](/cli) for JSON output, or `curl` against REST as above.
* **The agent edits and runs application code:** an [SDK](/sdks), or a client generated from [OpenAPI](/openapi).
* **The agent calls MCP tools:** the [MCP server](/mcp-server), which signs in through the client's built-in OAuth flow and needs no 0xArchive API key.
* **The agent loads Skills (`SKILL.md` workflows):** the [Agent skill](/skill), for reusable request recipes.
* **The agent only reads and writes files:** docs Markdown and OpenAPI, with the agent writing code for you to run.

Claude Code, Codex, Cursor, Windsurf, Copilot, Gemini CLI, Devin, OpenCode, and similar coding agents can usually run commands and edit code, and most can call MCP tools. OpenClaw can also load the Agent skill. Pick one interface for the first run.

## Control what the agent can reach

These rules apply to every job, whichever interface runs it.

* **Routes:** the agent takes the venue family from [Venue coverage](/venue-coverage), and the exact path and parameters from [OpenAPI](/openapi) or the matching REST page. It never builds a path from a guess.
* **Credentials:** API keys for REST, SDK, CLI, Agent skill, or WebSocket work stay in the host environment or a secret manager. The hosted MCP server uses OAuth instead. Never paste a key into a prompt, generated source, or a saved response.
* **Data check:** when the output feeds a backtest, alert, export, dashboard, or model, the agent runs the [Data quality](/data-quality#check-one-window-before-use) checks for the same window and stores the result with the output.
* **Payments and wallets:** [Facilitator](/facilitator) covers x402 payment infrastructure and [SIWE verification](/wallet-automation) covers wallet-owned account verification. Neither changes routes, schemas, or freshness checks.

## Use a different path when

Do not use 0xArchive for venue data outside Hyperliquid and Lighter, wallet transaction history, contract-event indexing, RPC archive reads, transaction submission, order execution, account trading, or broad CEX price coverage. Route benchmark, index, financial-product, standalone or substitute market-data, raw-redistribution, white-label, and OEM uses to [Data rights](/data-rights).

## Recovery rules

* **`401`:** stop and fix the key source or the `X-API-Key` header.
* **`403`:** read the error body and keep the original scope. Do not switch routes on an assumed upgrade path.
* **`404`:** check the namespace and symbol format in [Venue coverage](/venue-coverage) before retrying.
* **`429`:** read the `error_code`. Retry `rate_limited` within a bounded budget, after its `retry_after` seconds when it has one; stop on `insufficient_credits`. [When you reach a limit](/rate-limits#when-you-reach-a-limit) has the full rule.
* **Unsure of the route:** ask for the venue family, then use its page in the [Endpoint reference](/api-reference).
* **Unsure of a field:** read the endpoint's schema in OpenAPI instead of inventing fields.
* **Missing or stale quality decision:** stop downstream writes and apply the gap policy in [Data quality](/data-quality#handle-gaps).

## Next step

For each new job, have the agent take the exact route and parameters from the [Endpoint reference](/api-reference), then run it as one bounded request before it widens.


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