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

# Examples

> Copy working 0xArchive REST, WebSocket, and agent examples that keep the venue, symbol format, auth, and request IDs right, with links to SDK and CLI examples.

Copy a working request for REST, WebSocket, or an AI agent. Each example keeps the venue family and symbol format intact, authenticates correctly, and logs the request ID, and each one runs on a Free key. Full runnable projects are in [0xArchiveIO/examples](https://github.com/0xArchiveIO/examples); exact parameters and schemas are in the [Endpoint reference](/api-reference) and [OpenAPI](/openapi).

## REST requests

Set the API key in the environment first:

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

<CodeGroup>
  ```bash Hyperliquid core order book theme={"theme":"github-dark"}
  curl "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC" \
    -H "X-API-Key: $OXARCHIVE_API_KEY"
  ```

  ```bash Hyperliquid Spot trades theme={"theme":"github-dark"}
  curl "https://api.0xarchive.io/v1/hyperliquid/spot/trades/HYPE-USDC?limit=100" \
    -H "X-API-Key: $OXARCHIVE_API_KEY"
  ```

  ```bash HIP-3 builder trades theme={"theme":"github-dark"}
  curl "https://api.0xarchive.io/v1/hyperliquid/hip3/trades/xyz:XYZ100?limit=100" \
    -H "X-API-Key: $OXARCHIVE_API_KEY"
  ```

  ```bash Lighter order book theme={"theme":"github-dark"}
  curl "https://api.0xarchive.io/v1/lighter/orderbook/BTC" \
    -H "X-API-Key: $OXARCHIVE_API_KEY"
  ```
</CodeGroup>

## Check data quality first

Before a backtest, alert, export, dashboard, or model trusts a result, check coverage for the family and symbol:

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/data-quality/coverage/hyperliquid/BTC" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

If coverage, incidents, or freshness fall outside what the job can tolerate, stop, narrow the request, or mark the output. Do not fill gaps silently. Coverage responses have their own body instead of the `success`, `data`, and `meta` envelope, so store the coverage payload, the route and parameters, and the request ID of the market-data call it gates.

## Page through history

Start with a bounded window and keep the cursor. This window, the hour 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 - 3600 * 1000 ))

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

If the response includes `meta.next_cursor`, pass that value back as `cursor` with the same route, symbol, `START`, and `END`. Store each cursor and `meta.request_id` beside the output, so a later run can show which pages produced the dataset.

## Handle the response

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

const body = await response.json();

if (!response.ok || body.success === false) {
  // Error bodies are flat: code, error_code, error, and a top-level request_id.
  throw new Error(`${response.status} ${body.error_code} ${body.error} request_id=${body.request_id}`);
}

console.log({
  count: body.meta?.count,
  nextCursor: body.meta?.next_cursor,
  requestId: body.meta?.request_id,
  first: body.data?.[0]
});
```

Keep numeric market fields decimal-safe in production. Prices, sizes, funding rates, open interest, spreads, and HIP-4 probability prices should not pass through floating-point math when precision matters.

## Stream over WebSocket

The WebSocket takes the key in the opening handshake as `Authorization: Bearer $OXARCHIVE_API_KEY`.

<Warning>
  Keep WebSocket credentials on the server. Browser WebSocket clients cannot set the required authorization header, so browser apps should connect through your backend. Never expose a real API key in browser code, public prompts, logs, screenshots, or shared notebooks.
</Warning>

```javascript theme={"theme":"github-dark"}
import WebSocket from "ws";

const apiKey = process.env.OXARCHIVE_API_KEY;
if (!apiKey) throw new Error("Set OXARCHIVE_API_KEY");
const ws = new WebSocket("wss://api.0xarchive.io/ws", {
  headers: { Authorization: `Bearer ${apiKey}` }
});

const subscription = { op: "subscribe", channel: "orderbook", symbol: "BTC" };

ws.onopen = () => ws.send(JSON.stringify(subscription));
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "gap_detected") {
    console.warn("Unsafe stream gap", msg);
  }
};
ws.onerror = (event) => console.error("socket error", event);
ws.onclose = (event) => console.warn("socket closed", event.code, event.reason);
```

A long-running client also needs keep-alive, reconnect backoff, subscription restore, unsubscribe, and backpressure handling; see [Keep-alive](/websocket/keep-alive).

## Export files

For historical files rather than responses, build the export in the [Data Catalog](/data-catalog): choose the market (for example Hyperliquid Spot `HYPE-USDC`), the schemas (such as `trades` and `l2_orderbook`), and a UTC range, review the price in export credits, and record your data-rights decision. [Export schemas](/export-schemas) lists the columns, and [Export checkout](/export-checkout) covers payment and delivery.

## Ask an agent

<Prompt description="Use 0xArchive to pull Hyperliquid Spot HYPE-USDC trades for one bounded window. First name the route family, then show the REST path, auth header, response envelope fields to log, freshness preflight, and retry behavior.">Use 0xArchive to pull Hyperliquid Spot HYPE-USDC trades for one bounded window. First name the route family, then show the REST path, auth header, response envelope fields to log, freshness preflight, and retry behavior.</Prompt>

SDK examples are on [SDK REST usage](/sdks/rest-usage), and command-line examples on [CLI](/cli).

## Next step

See the full response for each data family in [Example responses](/response-examples).


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