| name | 0xarchive |
| version | 1.7.0 |
| description | Query historical crypto market data from 0xArchive across Hyperliquid, Lighter.xyz, and HIP-3. Covers orderbooks, trades, candles, funding rates, open interest, liquidations, and data quality. Use when the user asks about crypto market data, orderbooks, trades, funding rates, or historical prices on Hyperliquid, Lighter.xyz, or HIP-3.
|
| allowed-tools | Bash |
| argument-hint | query, e.g. 'BTC funding rate' or 'ETH 4h candles last week' |
| metadata | {"openclaw":{"requires":{"env":["OXARCHIVE_API_KEY"]},"primaryEnv":"OXARCHIVE_API_KEY"}} |
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.
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, builder:NAME | km:US500, xyz:GOLD, hyna:BTC, vntl:SPACEX, flx:TSLA, cash:NVDA |
| 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:
NOW=$(( $(date +%s) * 1000 ))
HOUR_AGO=$(( NOW - 3600000 ))
DAY_AGO=$(( NOW - 86400000 ))
WEEK_AGO=$(( NOW - 604800000 ))
Response Format
Every response follows this shape:
{
"success": true,
"data": [ ... ],
"meta": {
"count": 100,
"request_id": "uuid",
"next_cursor": "1706000000000"
}
}
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+ unlocks all HIP-3 symbols.
| 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+) |
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 |
GET /l3orderbook/{symbol} | timestamp, depth, account | L3 order-level orderbook (Pro+) |
GET /l3orderbook/{symbol}/history | start, end, limit, cursor, granularity, account | Historical L3 snapshots (Pro+) |
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 |
WebSocket Channels
Additional real-time channels available via WebSocket (wss://api.0xarchive.io/ws?apiKey=KEY):
| Channel | Notes |
|---|
l4_diffs | L4 orderbook diffs with user attribution (Pro+, real-time only) |
l4_orders | Order lifecycle events with user attribution (Pro+, real-time only) |
lighter_l3_orderbook | Lighter L3 order-level orderbook snapshots (Pro+, historical only) |
hip3_liquidations | HIP-3 liquidation events with long/short direction (Build+, historical only) |
hip3_l4_diffs | HIP-3 L4 orderbook diffs (Pro+, real-time only) |
hip3_l4_orders | HIP-3 order lifecycle events (Pro+, real-time only) |
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):
POST /web3/subscribe with { "tier": "build" } → server returns 402 with payment.amount (micro-USDC), payment.pay_to (treasury address), payment.network.- 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> }
- Build x402 v2 payment payload:
{
"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>"
}
}
}
- 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 |
|---|
start | int | Start timestamp (Unix ms). Defaults to 24h ago. |
end | int | End timestamp (Unix ms). Defaults to now. |
limit | int | Max records. Default 100, max 1000 (max 10000 for candles). |
cursor | string | Pagination cursor from meta.next_cursor. |
interval | string | Candle interval: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w. Default: 1h. For OI/funding: 5m, 15m, 30m, 1h, 4h, 1d. Omit for raw data. |
depth | int | Orderbook depth (number of price levels per side). |
granularity | string | Lighter orderbook resolution: checkpoint (default), 30s, 10s, 1s, tick. |
account | int | Lighter L3 orderbook: filter by account index (e.g., 281474976710654 for LLP vault). |
Smart Defaults
When the user does not specify a time range, default to the last 24 hours:
NOW=$(( $(date +%s) * 1000 ))
DAY_AGO=$(( NOW - 86400000 ))
For candles with no explicit range, default to a range that makes sense for the interval (e.g., last 7 days for 4h candles, last 30 days for 1d candles).
Trade Response Fields
Each trade/fill record includes:
| Field | Type | Description |
|---|
coin / symbol | string | Trading pair symbol |
side | string | B (buy) or A/S (sell) |
price | string | Execution price |
size | string | Trade size |
timestamp | string | ISO 8601 timestamp |
trade_id | integer | Unique trade ID |
order_id | integer | Associated order ID |
crossed | boolean | true = taker, false = maker |
fee | string | Base trading fee |
fee_token | string | Fee denomination (e.g., USDC) |
closed_pnl | string | Realized PnL if closing position |
direction | string | Open Long, Close Short, Long > Short, etc. |
start_position | string | Position size before trade |
user_address | string | User's wallet address |
builder_address | string | Builder address that routed this order. Only present when the order was placed through a builder. |
builder_fee | string | Builder fee charged on this fill, paid to the builder (quote currency, typically USDC). Only present when builder_address is set. |
deployer_fee | string | HIP-3 deployer fee share (quote currency). Negative for the maker side (rebate), positive for the taker side. HIP-3 only. |
priority_gas | number | Priority fee burned in HYPE (not USDC) for write priority on the Hyperliquid validator queue. Independent of builder_fee and deployer_fee — paid to the network, not to a builder or deployer. Only present when the order paid for priority. |
cloid | string | Client order ID |
twap_id | integer | TWAP execution ID |
builder_address, builder_fee, deployer_fee, priority_gas, cloid, and twap_id are optional — only present when non-zero/non-empty. deployer_fee is specific to HIP-3. priority_gas appears on any order that paid for write priority (most common on HIP-3 IOC orders).
Pagination
When meta.next_cursor is present in the response, more data is available. Append &cursor=VALUE to fetch the next page:
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/trades/BTC?start=$START&end=$END&limit=1000"
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/trades/BTC?start=$START&end=$END&limit=1000&cursor=1706000000000_12345"
Tier Limits
| Tier | Price | Coins | Orderbook Depth | Lighter Granularity | Historical Depth | Rate Limit |
|---|
| Free | $0 | BTC only (HIP-3: km:US500 only) | 20 levels | -- | 30 days | 15 RPS |
| Build | $49/mo | All | 200 levels | checkpoint, 30s, 10s | 1 year | 50 RPS |
| Pro | $199/mo | All | Full depth | + 1s | Full history | 150 RPS |
| Enterprise | Custom | All | Full depth | + tick | Full history | Custom |
Error Handling
| HTTP Status | Meaning | Action |
|---|
| 400 | Bad request / validation error | Check params (missing start/end, invalid interval) |
| 401 | Missing or invalid API key | Set $OXARCHIVE_API_KEY |
| 403 | Tier restriction | Upgrade plan (e.g., non-BTC coin on Free tier) |
| 404 | Symbol not found | Check coin name spelling and exchange |
| 429 | Rate limited | Back off and retry |
Error responses return { "code": 400, "error": "description" }.
Example Queries
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/instruments" | jq '.data | length'
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=10" | jq '.data'
NOW=$(( $(date +%s) * 1000 )); HOUR_AGO=$(( NOW - 3600000 ))
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/trades/ETH?start=$HOUR_AGO&end=$NOW&limit=100" | jq '.data'
NOW=$(( $(date +%s) * 1000 )); WEEK_AGO=$(( NOW - 604800000 ))
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/candles/SOL?start=$WEEK_AGO&end=$NOW&interval=4h" | jq '.data'
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/funding/BTC/current" | jq '.data'
NOW=$(( $(date +%s) * 1000 )); WEEK_AGO=$(( NOW - 604800000 ))
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/openinterest/BTC?start=$WEEK_AGO&end=$NOW&interval=1h" | jq '.data'
NOW=$(( $(date +%s) * 1000 )); MONTH_AGO=$(( NOW - 2592000000 ))
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/funding/ETH?start=$MONTH_AGO&end=$NOW&interval=4h" | jq '.data'
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/hip3/orderbook/km:US500" | jq '.data'
NOW=$(( $(date +%s) * 1000 )); HOUR_AGO=$(( NOW - 3600000 ))
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/hip3/orderbook/km:US500/history?start=$HOUR_AGO&end=$NOW&limit=10" | jq '.data'
NOW=$(( $(date +%s) * 1000 )); DAY_AGO=$(( NOW - 86400000 ))
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/hip3/candles/km:US500?start=$DAY_AGO&end=$NOW&interval=1h" | jq '.data'
NOW=$(( $(date +%s) * 1000 )); HOUR_AGO=$(( NOW - 3600000 ))
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/lighter/orderbook/BTC/history?start=$HOUR_AGO&end=$NOW&granularity=30s&limit=100" | jq '.data'
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/data-quality/status" | jq '.'
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/data-quality/sla" | jq '.'
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/summary/BTC" | jq '.data'
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/freshness/BTC" | jq '.data'
NOW=$(( $(date +%s) * 1000 )); DAY_AGO=$(( NOW - 86400000 ))
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/prices/BTC?start=$DAY_AGO&end=$NOW&interval=1h" | jq '.data'
NOW=$(( $(date +%s) * 1000 )); WEEK_AGO=$(( NOW - 604800000 ))
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/hyperliquid/liquidations/BTC/volume?start=$WEEK_AGO&end=$NOW&interval=4h" | jq '.data'
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
"https://api.0xarchive.io/v1/data-quality/coverage/hyperliquid/BTC" | jq '.'
