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

# First authenticated REST request

> Make one authenticated 0xArchive REST request, inspect the response envelope, verify metadata, and log request IDs for debugging.

A first authenticated request should confirm the base URL, API key, response envelope, request ID, and one route family before a larger client is wired.

<Steps>
  <Step title="Set the key">
    ```bash theme={"theme":"github-dark"}
    export OXARCHIVE_API_KEY="0xa_your_api_key"
    ```
  </Step>

  <Step title="Call a market-state route">
    ```bash theme={"theme":"github-dark"}
    curl -sS "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=20" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```
  </Step>

  <Step title="Inspect the fields">
    Confirm this market-data route returns `success`, `data`, and `meta.request_id` before adding pagination, SDKs, or WebSocket.
  </Step>
</Steps>

Do not use `GET /health` as the key check. It is an unauthenticated liveness route. Use an authenticated market-data route when you need to confirm the key, header name, and account access.

## Response Shape To Inspect

The Hyperliquid order-book route returns an API response envelope around an `OrderBook` body. For the first request, inspect the shape rather than copying prices from a stale example.

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": {
    "symbol": "BTC",
    "timestamp": "2025-01-21T10:30:45.123Z",
    "bids": [
      { "px": "42150.00", "sz": "1.5", "n": 15 }
    ],
    "asks": [
      { "px": "42151.00", "sz": "1.2", "n": 12 }
    ],
    "mid_price": "42150.50",
    "spread": "1.00",
    "spread_bps": "2.37"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000000"
  }
}
```

The OpenAPI schema also allows `meta.count` and `meta.next_cursor` on paginated routes. A latest order-book snapshot is not a pagination test; use a history route when you need cursor behavior.

## Next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Same path with language examples.
  </Card>

  <Card title="REST API" icon="square-terminal" href="/rest-api">
    Open Endpoint Reference.
  </Card>
</CardGroup>

## What The First Request Should Teach You

The first request confirms the account key, the header name, the base URL, the route namespace, and the response envelope. It should also establish a logging pattern before any larger job exists. Store the request method, path, symbol, status, and `meta.request_id`.

Do not immediately widen from one successful request to a multi-symbol historical job. First choose whether the next task is route exploration, historical retrieval, streaming, CLI automation, MCP tool calls, Skill workflows, SDK integration, or OpenAPI code generation. Each path has a different failure mode.

## What To Log

| Field                   | Why it matters                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| Method and path         | Reconstructs the exact route without exposing the API key                                         |
| Venue family and symbol | Prevents `BTC`, `HYPE-USDC`, `km:US500`, and HIP-4 IDs from being mixed later                     |
| Query parameters        | Captures `depth`, `timestamp`, window, cursor, and limit decisions                                |
| Status code             | Separates auth, route, limit, and upstream failures                                               |
| Request handle          | `meta.request_id` from an envelope response or `x-request-id` from a simpler auth/system response |
| Response timestamp      | Shows whether the data body matched the requested time behavior                                   |

## Before Adding Abstractions

Answer these questions before adding a wrapper, SDK, scheduled job, or agent-generated script.

| Question                             | Good answer                                                                                    |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Which route family was called?       | Hyperliquid core, Spot, HIP-3, HIP-4, or Lighter is named in the path and notes                |
| Which market identity was used?      | Symbol, pair, builder prefix, or outcome context is preserved exactly                          |
| What did the response envelope show? | `success`, `data`, `error`, and `meta.request_id` handling is understood                       |
| What is the next workflow?           | Route exploration, history, streaming, replay, export, SDK, CLI, MCP Server, Skill, or OpenAPI |
| What could fail next?                | Auth, namespace, limits, pagination, freshness, or data-rights boundary is named               |

If the answer to any row is vague, do not hide it behind a helper function yet. Keep the curl command visible and inspect the generated endpoint page first.

## Diagnosing A Stalled First Request

If a signup, trial, notebook, or agent workflow stalls before the first successful response, check which step is incomplete.

| State                       | Evidence to check                                                                  | Next action                                                                   |
| --------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `api_key_created`           | Key exists in the dashboard, secret manager, notebook secret, or local environment | Make the smallest authenticated market-data request                           |
| `first_authenticated_call`  | Request method, path, venue family, symbol, status, and request ID are recorded    | Inspect auth, namespace, and limits before widening                           |
| `first_successful_response` | `success`, `data`, response timestamp, and `meta.request_id` are understood        | Move to route exploration, SDK, CLI, MCP Server, Skill, WebSocket, or OpenAPI |

If stalled at `api_key_created`, the key has not been tested against any authenticated route. If stalled at `first_authenticated_call`, preserve the status code and request ID and route to [Errors and request IDs](/errors), [Rate limits](/rate-limits), or [Venue coverage](/venue-coverage). Once `first_successful_response` is reached, keep the exact curl command and response envelope before building abstractions.

## Common Follow-Ups

If the first request fails with `401`, inspect the key source and `X-API-Key` header, then store the `x-request-id` response header if the body does not include `meta.request_id`. If it fails with `404`, check [Venue coverage](/venue-coverage) before assuming the market is unsupported. If it fails with `429`, add backoff and read [Rate limits](/rate-limits). If it succeeds, preserve the request ID and move to the smallest route that matches the real job.

## Success Criteria

A first request is complete only when the response can be explained. Confirm the selected route family, symbol, response timestamp, payload shape, and request ID. If any field is surprising, stop and inspect Endpoint Reference before building abstractions on top.

## Sharing The First Request

When passing the request to another engineer or agent, include the exact curl command and the reason that route family was chosen. That avoids repeating the same auth and namespace discovery work.