First authenticated REST request

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.

Set the key

export OXARCHIVE_API_KEY="0xa_your_api_key"

Call a market-state route

curl -sS "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=20" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Inspect the fields

Confirm this market-data route returns success, data, and meta.request_id before adding pagination, SDKs, or WebSocket.

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. See REST authentication for the exact header and 401 response.

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.

{
  "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.

Quickstart

Same path with language examples.

REST API

Open Endpoint Reference.

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, Rate limits, or 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 before concluding that no current route covers the market. If it fails with 429, add backoff and read 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. 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.

​Response Shape To Inspect

​Next

Quickstart

REST API

​What The First Request Should Teach You

​What To Log

​Before Adding Abstractions

​Diagnosing A Stalled First Request

​Common Follow-Ups

​Success Criteria

​Sharing The First Request