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.

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 the generated 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.

Log Packet

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

Review Packet

Turn the first request into a short review note 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.

Activation Packet

Use this packet when a signup, trial, notebook, dashboard job, or agent workflow stalls before the first successful response. It separates account setup from actual API activation.

State	Evidence to capture	Next route
`api_key_created`	Key source 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 failed or successful request ID	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 the packet stops at api_key_created, do not assume the user is activated. If it stops at first_authenticated_call, preserve the status code and request ID so the next call can route to Errors And Request IDs, Rate Limits, or Venue Coverage. If it reaches first_successful_response, 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 assuming the market is unsupported. 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 the generated reference before building abstractions on top.

Hand-Off

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.

Implementation guides

Documentation Index

​Response Shape To Inspect

​Next

Quickstart

REST API

​What The First Request Should Teach You

​Log Packet

​Review Packet

​Activation Packet

​Common Follow-Ups

​Success Criteria

​Hand-Off