0xarchive

# 0xArchive API Skill Query historical and real-time crypto market data from **0xArchive** using `curl`. 0xArchive exposes two top-level venue APIs: **Hyperliquid** and **Lighter.xyz**. **HIP-3** builder perps live under the Hyperliquid namespace at `/v1/hyperliquid/hip3`. **HIP-4** outcome markets (binary prediction markets) live at `/v1/hyperliquid/hip4`. **Hyperliquid Spot** (294 pairs) lives at `/v1/hyperliquid/spot`. Data types: orderbooks, trades, candles, funding rates, open interest, liquidations, outcome markets, spot, TWAP, and data quality metrics. Orderbook depth limits apply to L2 snapshot endpoints only. ## 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/..." ``` ## Venue Scopes & Coin Naming | Scope | Path prefix | Coin format | Examples | |----------|-------------|-------------|---------| | Hyperliquid | `/v1/hyperliquid` | UPPERCASE | `BTC`, `ETH`, `SOL` | | Hyperliquid HIP-3 | `/v1/hyperliquid/hip3` | Case-sensitive, `builder:NAME` | `km:US500`, `xyz:GOLD`, `hyna:BTC`, `vntl:SPACEX`, `flx:TSLA`, `cash:NVDA` | | Hyperliquid HIP-4 | `/v1/hyperliquid/hip4` | Bare numeric `<10*outcome_id + side>` (legacy `#0` / `%230` also accepted) | `0`, `1`, `10`, `11` | | Hyperliquid Spot | `/v1/hyperliquid/spot` | Dashed canonical `BASE-QUOTE` | `HYPE-USDC`, `PURR-USDC`, `AAPL-USDC` | | Lighter | `/v1/lighter` | UPPERCASE | `BTC`, `ETH` | Hyperliquid and Lighter auto-uppercase the symbol server-side. HIP-3 coin names are passed through as-is. HIP-4 coins encode outcome and side: `0` is outcome 0 / side 0 (YES), `1` is outcome 0 / side 1 (NO), `10` is outcome 1 / side 0, etc. The bare numeric form is canonical; the legacy `#0` and `%230` forms still work for backward compatibility. Spot symbols are dashed (`HYPE-USDC`, `PURR-USDC`, `AAPL-USDC`); the server resolves the dashed form to the wire format (`PURR/USDC`, `@107`) internally, so always use the dashed form. ## 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 | | `GET /orders/{symbol}/history` | `start`, `end`, `user`, `status`, `order_type`, `limit`, `cursor` | Order history with user attribution (Build+) | | `GET /orders/{symbol}/flow` | `start`, `end`, `interval`, `limit` | Order flow aggregation (Build+) | | `GET /orders/{symbol}/tpsl` | `start`, `end`, `user`, `triggered`, `limit`, `cursor` | TP/SL order history (Pro+) | | `GET /orderbook/{symbol}/l4` | `timestamp`, `depth` | L4 orderbook reconstruction (Pro+) | | `GET /orderbook/{symbol}/l4/diffs` | `start`, `end`, `limit`, `cursor` | L4 orderbook diffs (Pro+) | | `GET /orderbook/{symbol}/l4/history` | `start`, `end`, `limit`, `cursor` | L4 orderbook checkpoints (Pro+) | | `GET /orderbook/{symbol}/l2` | `timestamp`, `depth` | L2 full-depth orderbook derived from L4 (Build+) | | `GET /orderbook/{symbol}/l2/history` | `start`, `end`, `limit`, `cursor`, `depth` | L2 full-depth checkpoints (Build+) | | `GET /orderbook/{symbol}/l2/diffs` | `start`, `end`, `limit`, `cursor` | L2 tick-level diffs (Pro+) | ### HIP-3 (`/v1/hyperliquid/hip3`) Coin names are **case-sensitive** (e.g., `km:US500`). Free tier includes km:US500 for orderbook and orderbook history; Build+ includes the broader HIP-3 symbol set. | Endpoint | Params | Notes | |----------|--------|-------| | `GET /instruments` | -- | List HIP-3 instruments | | `GET /instruments/{coin}` | -- | Single instrument | | `GET /orderbook/{coin}` | `timestamp`, `depth` | Free: km:US500 only. Build+: all HIP-3 symbols. | | `GET /orderbook/{coin}/history` | `start`, `end`, `limit`, `cursor`, `depth` | Free: km:US500 only. Build+: all HIP-3 symbols. | | `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 /liquidations/{coin}` | `start`, `end`, `limit`, `cursor` | Liquidation events | | `GET /liquidations/{coin}/volume` | `start`, `end`, `limit`, `cursor`, `interval` | Aggregated liquidation volume (USD) | | `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 | | `GET /orders/{coin}/history` | `start`, `end`, `user`, `status`, `order_type`, `limit`, `cursor` | Order history with user attribution (Build+) | | `GET /orders/{coin}/flow` | `start`, `end`, `interval`, `limit` | Order flow aggregation (Build+) | | `GET /orders/{coin}/tpsl` | `start`, `end`, `user`, `triggered`, `limit`, `cursor` | TP/SL order history (Pro+) | | `GET /orderbook/{coin}/l4` | `timestamp`, `depth` | L4 orderbook reconstruction (Pro+) | | `GET /orderbook/{coin}/l4/diffs` | `start`, `end`, `limit`, `cursor` | L4 orderbook diffs (Pro+) | | `GET /orderbook/{coin}/l4/history` | `start`, `end`, `limit`, `cursor` | L4 orderbook checkpoints (Pro+) | | `GET /orderbook/{coin}/l2` | `timestamp`, `depth` | L2 full-depth orderbook derived from L4 (Build+) | | `GET /orderbook/{coin}/l2/history` | `start`, `end`, `limit`, `cursor`, `depth` | L2 full-depth checkpoints (Build+) | | `GET /orderbook/{coin}/l2/diffs` | `start`, `end`, `limit`, `cursor` | L2 tick-level diffs (Pro+) | ### HIP-4 (`/v1/hyperliquid/hip4`) Outcome markets are binary prediction markets (e.g. "Will BTC be >= $X by date Y?"). Coin names are bare numerics `<10*outcome_id + side>` (e.g. `0`, `1`, `10`); the legacy `#0` / `%230` forms are still accepted. HIP-4 has **no funding rates, no liquidations, and no candles** -- those endpoints do not exist on this venue. The `mark_price` field on HIP-4 instruments and prices is an **implied probability in the range 0..1**, not a USD price. | Endpoint | Params | Notes | |----------|--------|-------| | `GET /outcomes` | -- | List all outcome markets (HIP-4 only; not present on other venues) | | `GET /outcomes/{outcome_id}` | -- | Single outcome market detail (HIP-4 only) | | `GET /instruments` | -- | List HIP-4 instruments (one per side per outcome) | | `GET /instruments/{coin}` | -- | Single instrument. Coin is the bare numeric (e.g. `0`); legacy `%230` also accepted. | | `GET /orderbook/{coin}` | `timestamp`, `depth` | Latest or at timestamp |