Skills
skills/openclaw/skills/0xarchive

0xarchive

SKILL.md

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, 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:

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"   // 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: 
    {
  "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
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.

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).

Pagination

When meta.next_cursor is present in the response, more data is available. Append &cursor=VALUE to fetch the next page:

# First page
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
  "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?start=$START&end=$END&limit=1000"

# Next page (use next_cursor from previous response)
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 50 levels checkpoint, 30s, 10s 1 year 50 RPS
Pro $199/mo All 100 levels + 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

# List Hyperliquid instruments
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
  "https://api.0xarchive.io/v1/hyperliquid/instruments" | jq '.data | length'

# Current BTC orderbook (top 10 levels)
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
  "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC?depth=10" | jq '.data'

# ETH trades from the last hour
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'

# SOL 4h candles for the last week
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'

# Current BTC funding rate
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
  "https://api.0xarchive.io/v1/hyperliquid/funding/BTC/current" | jq '.data'

# BTC open interest aggregated to 1h intervals (last week)
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'

# ETH funding rates aggregated to 4h intervals (last 30 days)
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'

# HIP-3 km:US500 candles (last 24h, 1h interval)
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'

# Lighter BTC orderbook history (30s granularity, last hour)
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'

# System health status
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
  "https://api.0xarchive.io/v1/data-quality/status" | jq '.'

# SLA report for current month
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
  "https://api.0xarchive.io/v1/data-quality/sla" | jq '.'

# BTC market summary (price, funding, OI, volume, liquidations in one call)
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
  "https://api.0xarchive.io/v1/hyperliquid/summary/BTC" | jq '.data'

# BTC data freshness (lag per data type)
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
  "https://api.0xarchive.io/v1/hyperliquid/freshness/BTC" | jq '.data'

# BTC price history (mark/oracle/mid) aggregated to 1h
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'

# BTC liquidation volume aggregated to 4h buckets
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'

# Data coverage for Hyperliquid BTC
curl -s -H "x-api-key: $OXARCHIVE_API_KEY" \
  "https://api.0xarchive.io/v1/data-quality/coverage/hyperliquid/BTC" | jq '.'
Weekly Installs
5
Repository
openclaw/skills
GitHub Stars
3.8K
First Seen
Feb 23, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
opencode5
gemini-cli5
amp5
github-copilot5
codex5
kimi-cli5