First authenticated REST request

Outcome

Reach one first successful response from an API-key-authenticated market-data route and save the exact request needed to reproduce it.

Prerequisites

Create an API key in the 0xArchive dashboard.
Load it into OXARCHIVE_API_KEY or an equivalent secret store. Do not paste the raw key into source or logs.
Use an authenticated market-data route, not the liveness route, to test the key.
Use REST authentication, Errors and request IDs, and Rate limits for the transport and recovery contract.
Record the milestones api_key_created, first_authenticated_call, and first_successful_response as the request progresses.
Use Venue coverage to check the selected family and symbol before widening the request.

Inputs

Field	Value
Method	`GET`
Route	`/v1/hyperliquid/orderbook/BTC`
Query	`depth=1`
Header	`X-API-Key: $OXARCHIVE_API_KEY`
Completion condition	HTTP success, endpoint response body, and request ID are saved

Steps

Load the key

export OXARCHIVE_API_KEY="0xa_your_api_key"

Use a shell environment or secret manager. Never commit or print the value.

Call one authenticated route

curl -sS -D response.headers -o response.json \
  "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Inspect the response

Confirm the route-specific response body, the selected family and symbol, and the request identifier. Keep x-request-id response header when the body does not expose meta.request_id.

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

Expected state

For this route, the response is an object with success, an order-book data object, and meta.request_id. The response contract is specific: this market-data route returns success, data, and meta.request_id. The values vary by request. The following is a representative shape, not a response to copy into a client:

{
  "success": true,
  "data": {
    "symbol": "BTC",
    "timestamp": "2026-01-01T00:00:00.000Z",
    "bids": [],
    "asks": []
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000000"
  }
}

The zero UUID is a shape placeholder only. Replace it with the UUID returned by the response. Do not send it as a request value.

Verification

The first successful response is complete only when the saved record names the route family, symbol, query, HTTP status, response timestamp, and request ID. Check OpenAPI before adding pagination, an SDK, a WebSocket subscription, or a wider symbol loop.

Failure and recovery

401: compare the key source, X-API-Key header, and returned error body. Keep the x-request-id response header.
403: inspect the exact endpoint/account/key response. Do not assume the status means a route upgrade is required.
404: check the venue namespace and symbol format in Venue coverage.
429: honor Retry-After when present. Otherwise use capped exponential backoff with jitter and lower concurrency.
Unexpected fields or an unexpected response body: stop and read the endpoint reference before writing a wrapper.

Saved run metadata

{
  "milestone": "first_successful_response",
  "method": "GET",
  "route": "/v1/hyperliquid/orderbook/BTC",
  "query": { "depth": 1 },
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "status": 200,
  "request_ids": ["00000000-0000-0000-0000-000000000000"],
  "body_file": "./artifacts/first-orderbook.json",
  "header_file": "./artifacts/first-orderbook.headers"
}

Replace the zero UUID with the returned UUID and keep the API key out of both files.

Next task

When first successful response is saved, continue with Historical market data, Choose a tooling workflow, or Venue coverage. If the milestone is stuck, route the status and request ID to Errors and request IDs.

​Outcome

​Prerequisites

​Inputs

​Steps

​Expected state

​Verification

​Failure and recovery

​Saved run metadata

​Next task