> ## 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 route-safe 0xArchive REST, WebSocket, CLI, MCP, Skill, and agent examples that preserve venue family, auth, response IDs, and freshness checks.

Examples should teach the safe request pattern before a reader opens the generated endpoint reference: pick venue family, keep the symbol format intact, use auth correctly, inspect the response envelope, and log request IDs. Use [Example Responses](/response-examples) when you need payload shapes before writing parsers or tests.

For exact parameters and schema details, use the generated REST reference or [OpenAPI](/openapi). For broad jobs, use these examples only as the first bounded probe.

## REST Examples

<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/km:US500?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>

## Freshness Gate Example

Before a backtest, alert, export, dashboard, or model job trusts a result, check data quality for the relevant 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 are outside the job tolerance, stop, narrow the request, or mark the output. Do not silently fill gaps.

Data-quality coverage responses can be resource-specific bodies instead of ordinary `success`, `data`, and `meta` envelopes. For those routes, store the coverage payload, route, parameters, and downstream market-data request ID rather than forcing envelope parsing.

## Historical Pagination Example

Historical routes should start with a bounded window and preserve cursor state.

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?start=1767225600000&end=1767229200000&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, and window. Store each cursor and `meta.request_id` beside the output so a later run can explain how many pages produced the dataset.

## Export Workflow Example

When you need historical files, start with Data Catalog and Export Schemas so the workflow keeps market, schema key, UTC range, credits, delivery state, and data-rights decisions together.

```text theme={"theme":"github-dark"}
Market: Hyperliquid Spot HYPE-USDC
Schemas: trades, l2_orderbook
Range: 2026-05-01 to 2026-05-07 UTC
Delivery: Data Catalog Parquet export
Preflight: check coverage, estimate size, review credits, record data-rights decision
Docs: /data-catalog, /export-schemas, /export-checkout, /data-rights
```

## Response Handling Example

```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) {
  throw new Error(`${response.status} ${body.error?.code || "unknown"} request_id=${body.meta?.request_id || "missing"}`);
}

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 clients. Prices, sizes, funding rates, open interest, spreads, and probability-like HIP-4 fields should not be casually converted through floating-point math when precision matters.

## WebSocket Example

```javascript theme={"theme":"github-dark"}
const ws = new WebSocket(`wss://api.0xarchive.io/ws?apiKey=${process.env.OXARCHIVE_API_KEY}`);

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

Production WebSocket clients also need keep-alive, reconnect backoff, subscription restore, unsubscribe behavior, and output backpressure handling.

## Example Selection Rule

Use REST examples for one bounded response, SDK examples when the call belongs inside application code, CLI examples for shell and CI jobs, WebSocket examples when stream order matters, and Data Catalog examples when the desired artifact is a file export. The example should match the runtime that will own retries, metadata, and output storage.

## Agent Prompt Example

<Prompt>
  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>

## Next Step

Use [Responses](/responses) for parsing behavior, [Example Responses](/response-examples) for payload shapes, [Schemas](/schemas) for shared fields, [Export Schemas](/export-schemas) for file datasets, and the generated [REST API](/rest-api) reference for exact route parameters.