0xarchive

# 0xArchive API Skill Query historical and real-time crypto market data from **0xArchive** using `curl`. Three exchanges are supported: **Hyperliquid** (perps DEX), **Lighter.xyz** (order-book DEX), and **HIP-3** (Hyperliquid builder perps). Data types: orderbooks, trades, candles, funding rates, open interest, liquidations, and data quality metrics. ## Authentication All endpoints require the `x-api-key` header. The key is read from `$OXARCHIVE_API_KEY`. ```bash curl -s -H "x-api-key: $OXARCHIVE_API_KEY" "https://api.0xarchive.io/v1/..." ``` ## Exchanges & Coin Naming | Exchange | Path prefix | Coin format | Examples | |----------|-------------|-------------|---------| | Hyperliquid | `/v1/hyperliquid` | UPPERCASE | `BTC`, `ETH`, `SOL` | | HIP-3 | `/v1/hyperliquid/hip3` | Case-sensitive, `prefix:NAME` | `km:US500`, `xyz:XYZ100` | | Lighter | `/v1/lighter` | UPPERCASE | `BTC`, `ETH` | Hyperliquid and Lighter auto-uppercase the symbol server-side. HIP-3 coin names are passed through as-is. ## Timestamps All timestamps are **Unix milliseconds**. Use these shell helpers: ```bash NOW=$(( $(date +%s) * 1000 )) HOUR_AGO=$(( NOW - 3600000 )) DAY_AGO=$(( NOW - 86400000 )) WEEK_AGO=$(( NOW - 604800000 )) ``` ## Response Format Every response follows this shape: ```json { "success": true, "data": [ ... ], "meta": { "count": 100, "request_id": "uuid", "next_cursor": "1706000000000" // present when more pages exist } } ``` ## Endpoint Reference ### Hyperliquid (`/v1/hyperliquid`) | Endpoint | Params | Notes | |----------|--------|-------| | `GET /instruments` | -- | List all instruments | | `GET /instruments/{symbol}` | -- | Single instrument details | | `GET /orderbook/{symbol}` | `timestamp`, `depth` | Latest or at timestamp | | `GET /orderbook/{symbol}/history` | `start`, `end`, `limit`, `cursor`, `depth` | Historical snapshots | | `GET /trades/{symbol}` | `start`, `end`, `limit`, `cursor` | Trade history | | `GET /candles/{symbol}` | `start`, `end`, `limit`, `cursor`, `interval` | OHLCV candles | | `GET /funding/{symbol}/current` | -- | Current funding rate | | `GET /funding/{symbol}` | `start`, `end`, `limit`, `cursor`, `interval` | Funding rate history | | `GET /openinterest/{symbol}/current` | -- | Current open interest | | `GET /openinterest/{symbol}` | `start`, `end`, `limit`, `cursor`, `interval` | OI history | | `GET /liquidations/{symbol}` | `start`, `end`, `limit`, `cursor` | Liquidation events | | `GET /liquidations/{symbol}/volume` | `start`, `end`, `limit`, `cursor`, `interval` | Aggregated liquidation volume (USD) | | `GET /liquidations/user/{address}` | `start`, `end`, `limit`, `cursor`, `coin` | Liquidations for a user | | `GET /freshness/{symbol}` | -- | Data freshness per data type | | `GET /summary/{symbol}` | -- | Combined market summary (price, funding, OI, volume, liquidations) | | `GET /prices/{symbol}` | `start`, `end`, `limit`, `cursor`, `interval` | Mark/oracle/mid price history | ### HIP-3 (`/v1/hyperliquid/hip3`) Coin names are **case-sensitive** (e.g., `km:US500`). No liquidation endpoints. Orderbook requires Pro+ tier. | Endpoint | Params | Notes | |----------|--------|-------| | `GET /instruments` | -- | List HIP-3 instruments | | `GET /instruments/{coin}` | -- | Single instrument | | `GET /orderbook/{coin}` | `timestamp`, `depth` | Requires Pro+ tier | | `GET /orderbook/{coin}/history` | `start`, `end`, `limit`, `cursor`, `depth` | Requires Pro+ tier | | `GET /trades/{coin}` | `start`, `end`, `limit`, `cursor` | Trade history | | `GET /trades/{coin}/recent` | `limit` | Recent trades (no time range needed) | | `GET /candles/{coin}` | `start`, `end`, `limit`, `cursor`, `interval` | OHLCV candles | | `GET /funding/{coin}/current` | -- | Current funding rate | | `GET /funding/{coin}` | `start`, `end`, `limit`, `cursor`, `interval` | Funding history | | `GET /openinterest/{coin}/current` | -- | Current OI | | `GET /openinterest/{coin}` | `start`, `end`, `limit`, `cursor`, `interval` | OI history | | `GET /freshness/{coin}` | -- | Data freshness per data type | | `GET /summary/{coin}` | -- | Combined market summary (price, funding, OI) | | `GET /prices/{coin}` | `start`, `end`, `limit`, `cursor`, `interval` | Mark/oracle/mid price history | ### Lighter (`/v1/lighter`) Same data types as Hyperliquid except: no liquidations. Adds `granularity` on orderbook history and `/recent` trades. | Endpoint | Params | Notes | |----------|--------|-------| | `GET /instruments` | -- | List Lighter instruments | | `GET /instruments/{symbol}` | -- | Single instrument | | `GET /orderbook/{symbol}` | `timestamp`, `depth` | Latest or at timestamp | | `GET /orderbook/{symbol}/history` | `start`, `end`, `limit`, `cursor`, `depth`, `granularity` | Default granularity: `checkpoint` | | `GET /trades/{symbol}` | `start`, `end`, `limit`, `cursor` | Trade history | | `GET /trades/{symbol}/recent` | `limit` | Recent trades (no time range needed) | | `GET /candles/{symbol}` | `start`, `end`, `limit`, `cursor`, `interval` | OHLCV candles | | `GET /funding/{symbol}/current` | -- | Current funding rate | | `GET /funding/{symbol}` | `start`, `end`, `limit`, `cursor`, `interval` | Funding history | | `GET /openinterest/{symbol}/current` | -- | Current OI | | `GET /openinterest/{symbol}` | `start`, `end`, `limit`, `cursor`, `interval` | OI history | | `GET /freshness/{symbol}` | -- | Data freshness per data type | | `GET /summary/{symbol}` | -- | Combined market summary (price, funding, OI) | | `GET /prices/{symbol}` | `start`, `end`, `limit`, `cursor`, `interval` | Mark/oracle price history | ### Data Quality (`/v1/data-quality`) | Endpoint | Params | Notes | |----------|--------|-------| | `GET /status` | -- | System health status | | `GET /coverage` | -- | Coverage summary, all exchanges | | `GET /coverage/{exchange}` | -- | Coverage for one exchange | | `GET /coverage/{exchange}/{symbol}` | `from`, `to` | Symbol-level coverage + gaps | | `GET /incidents` | `status`, `exchange`, `since`, `limit`, `offset` | List incidents | | `GET /incidents/{id}` | -- | Single incident | | `GET /latency` | -- | Ingestion latency metrics | | `GET /sla` | `year`, `month` | SLA compliance report | ### Web3 Authentication (`/v1`) Get API keys programmatically using an Ethereum wallet (SIWE). No API key required for these endpoints. | Endpoint | Params | Notes | |----------|--------|-------| | `POST /auth/web3/challenge` | `address` (wallet address) | Returns SIWE message to sign | | `POST /web3/signup` | `message`, `signature` | Returns free-tier API key | | `POST /web3/keys` | `message`, `signature` | List all keys for wallet | | `POST /web3/keys/revoke` | `message`, `signature`, `key_id` | Revoke a key | | `POST /web3/subscribe` | `tier` (`build` or `pro`), `payment-signature` header | x402 USDC subscription (see flow below) | **Free-tier flow:** Call `/auth/web3/challenge` with wallet address → sign the returned message with `personal_sign` (EIP-191) → submit to `/web3/signup` with the message and signature → receive API key. **Paid-tier flow (x402):** 1. `POST /web3/subscribe` with `{ "tier": "build" }` → server returns 402 with `payment.amount` (micro-USDC), `payment.pay_to` (treasury address), `payment.network`. 2. Sign an EIP-712 `TransferWithAuthorization` (EIP-3009) on USDC Base: - Domain: `{ name: "USD Coin", version: "2", chainId: 8453, verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }` - Type: `TransferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce)` - Message: `{ from: <wallet>, to: <pay_to>, value: <amount>, validAfter: 0, validBefore: <now+3600>, nonce: <32 random bytes hex> }` 3. Build x402 v2 payment payload: ```json { "x402Version": 2, "payload": { "signature": "0x<EIP-712 signature hex>", "authorization": { "from": "0x<wallet>", "to": "0x<pay_to from step 1>", "value": "<amount as string>", "validAfter": "0", "validBefore": "<unix timestamp as string>", "nonce": "0x<64 hex chars>" } } } ``` 4. Base64-encode the JSON and retry: `POST /web3/subscribe` with `{ "tier": "build" }` and header `payment-signature: <base64 payload>` → receive API key + subscription. **Important:** All `authorization` values (`value`, `validAfter`, `validBefore`) must be strings, not numbers. See `scripts/web3_subscribe.py` for a complete working Python implementation. ## Common Parameters | Param | Type | Description |