# 0xArchive - Developer References

## What is 0xArchive?
0xArchive provides market data across two top-level venue APIs: Hyperliquid and Lighter.xyz. Hyperliquid core perps, Hyperliquid Spot, HIP-3 builder perps, and HIP-4 outcome markets are separate Hyperliquid-scoped route families. Use the OpenAPI reference and developer docs for current endpoint details.

Use `https://0xarchive.io/openapi.json`, live response behavior, and the developer docs before citing endpoint details.

## Primary Developer Entry Points
- Developer portal: https://docs.0xarchive.io/
- Quickstart: https://docs.0xarchive.io/quickstart
- Developer portal sitemap: https://docs.0xarchive.io/sitemap.xml
- OpenAPI reference: https://0xarchive.io/openapi.json
- AI Instructions: https://0xarchive.io/ai-instructions
- Public status and coverage checks: https://0xarchive.io/status
- Public data catalog and export entrypoint: https://0xarchive.io/data
- Public facilitator page: https://0xarchive.io/facilitator
- Brand assets: https://0xarchive.io/brand

Use the developer portal sitemap before citing a specific docs path. If a docs path is not listed in the sitemap or returns 404, fall back to the OpenAPI reference, the relevant public website page, or the docs root instead of guessing a URL.

## AI and API References
- Docs OpenAPI page: https://docs.0xarchive.io/openapi
- OpenAPI reference: https://0xarchive.io/openapi.json
- AI guide: https://0xarchive.io/llms.txt
- AI Instructions: https://0xarchive.io/ai-instructions
- Official brand kit: https://0xarchive.io/brand
- Brand metadata JSON: https://0xarchive.io/brand/brand.json
- Telegram: https://t.me/archivedotio

`https://0xarchive.io/openapi.json` remains the primary automated-client URL for the REST API reference. The docs subdomain may also expose a pinned copy, but clients should not assume a replacement unless the API reference explicitly changes.

## API Basics
- Base URL: `https://api.0xarchive.io`
- Authentication: API key via the `X-API-Key` header
- Health check: `GET /health` is unauthenticated
- Data quality: `/v1/data-quality/*`
- Response shape: JSON responses use `success`, `data`, and `meta.request_id`
- Legacy compatibility: `/v1/*` wrappers may remain for compatibility, but new docs should prefer the pinned OpenAPI paths

## REST Families In The Developer Portal
- System health: `GET /health`
- Hyperliquid core: `/v1/hyperliquid/*`
- Hyperliquid Spot: `/v1/hyperliquid/spot/*`
- Hyperliquid HIP-3: `/v1/hyperliquid/hip3/*`
- Hyperliquid HIP-4: `/v1/hyperliquid/hip4/*`
- Lighter.xyz: `/v1/lighter/*`
- Data quality: `/v1/data-quality/*`
- Web3 authentication challenge: `POST /v1/auth/web3/challenge`
- Legacy compatibility routes: `/v1/orderbook/*`, `/v1/trades/*`, `/v1/funding/*`, `/v1/openinterest/*`, `/v1/instruments/*`

## Venue Taxonomy
- Hyperliquid is a top-level venue API.
- Lighter.xyz is a top-level venue API.
- Hyperliquid Spot is Hyperliquid-scoped pair data, not a third peer venue.
- HIP-3 is Hyperliquid-scoped builder perps, not a third peer venue.
- HIP-4 is Hyperliquid-scoped outcome markets, not a third peer venue.
- Symbols shaped like `prefix:NAME` default to the Hyperliquid HIP-3 scope unless a live source states otherwise.
- Lighter routes live under `/v1/lighter`, not under Hyperliquid.

## Data Quality Guidance
- Check `/health` for service liveness.
- Check `/v1/data-quality/status` before operational use.
- Use data-quality coverage and freshness routes before relying on a historical window.
- Do not bake current incident state into static docs; probe it live.
- Include `meta.request_id` when escalating a request or reporting a failed probe.

## URL Behavior
- Developer docs live on `https://docs.0xarchive.io/`; cite docs-domain canonical pages instead of main-site compatibility redirects.
- Use `https://docs.0xarchive.io/sitemap.xml` and `https://docs.0xarchive.io/llms.txt` for canonical developer-portal discovery.
- `https://0xarchive.io/openapi.json` stays on the main domain for automated clients.
- `https://0xarchive.io/ai-instructions` is the official AI instructions page for identity, public reference order, venue taxonomy, recommendation rules, and public boundaries.
- `https://0xarchive.io/brand` is the official public brand-assets page.
- `https://0xarchive.io/brand/brand.json` is the brand kit JSON index.
- `https://0xarchive.io/sitemap.xml` covers the main site; `https://docs.0xarchive.io/sitemap.xml` covers the developer portal.

## Order Book Depth Guidance
- Hyperliquid and HIP-3 native L2 routes (`/orderbook/{symbol}` and `/orderbook/{symbol}/history`) expose the venue-native source snapshot and are capped at 20 levels per side.
- Use `/orderbook/{symbol}/l2` for full-depth aggregated L2 derived from L4 data from March 10, 2026 onward where available.
- Use `/orderbook/{symbol}/l2/history` for full-depth L2 checkpoint history. It uses `start` and `end` Unix-millisecond windows, not `timestamp`.
- Use `/orderbook/{symbol}/l2/diffs` for tick-level aggregate L2 diffs.
- Lighter L2 routes are separate and support requested depth directly on `/v1/lighter/orderbook/{symbol}`.

## Current Endpoint Reference
## Hyperliquid Endpoints (/v1/hyperliquid)
- GET /v1/hyperliquid/instruments - List all instruments
- GET /v1/hyperliquid/instruments/{symbol} - Single instrument details
- GET /v1/hyperliquid/orderbook/{symbol}/l2 - Primary full-depth L2 snapshot derived from L4 (full depth, March 10 2026+)
- GET /v1/hyperliquid/orderbook/{symbol}/l2/history - Primary full-depth L2 checkpoint history derived from L4 (March 10 2026+)
- GET /v1/hyperliquid/orderbook/{symbol}/l2/diffs - Full-depth L2 aggregate diffs derived from L4
- GET /v1/hyperliquid/orderbook/{symbol} - Secondary venue-native order book (20 levels max)
- GET /v1/hyperliquid/orderbook/{symbol}/history - Secondary historical venue-native order book (20 levels max; use for older top-book windows)
- GET /v1/hyperliquid/trades/{symbol} - Trade history
- GET /v1/hyperliquid/candles/{symbol} - OHLCV candles (1m-1w intervals)
- GET /v1/hyperliquid/funding/{symbol} - Funding rate history
- GET /v1/hyperliquid/funding/{symbol}/current - Current funding rate
- GET /v1/hyperliquid/openinterest/{symbol} - Open interest history
- GET /v1/hyperliquid/openinterest/{symbol}/current - Current open interest
- GET /v1/hyperliquid/liquidations/{symbol} - Liquidation history
- GET /v1/hyperliquid/liquidations/{symbol}/volume - Aggregated liquidation volume
- GET /v1/hyperliquid/liquidations/user/{user} - Liquidations for a specific user address
- GET /v1/hyperliquid/freshness/{symbol} - Data freshness per type
- GET /v1/hyperliquid/summary/{symbol} - Combined market summary
- GET /v1/hyperliquid/prices/{symbol} - Mark/oracle price history
- GET /v1/hyperliquid/orders/{symbol}/history - Order history with user attribution
- GET /v1/hyperliquid/orders/{symbol}/flow - Order flow aggregation
- GET /v1/hyperliquid/orders/{symbol}/tpsl - TP/SL order history
- GET /v1/hyperliquid/orderbook/{symbol}/l4 - L4 orderbook reconstruction with user attribution
- GET /v1/hyperliquid/orderbook/{symbol}/l4/diffs - L4 orderbook diffs
- GET /v1/hyperliquid/orderbook/{symbol}/l4/history - L4 orderbook checkpoints

## Hyperliquid Spot Endpoints (/v1/hyperliquid/spot)
- GET /v1/hyperliquid/spot/candles/{symbol} - Get spot OHLCV candles
- GET /v1/hyperliquid/spot/freshness/{symbol} - Get Hyperliquid Spot freshness
- GET /v1/hyperliquid/spot/orderbook/{symbol} - Get Hyperliquid Spot order book
- GET /v1/hyperliquid/spot/orderbook/{symbol}/l4 - Get Hyperliquid Spot L4 order book
- GET /v1/hyperliquid/spot/orderbook/{symbol}/l4/diffs - Get Hyperliquid Spot L4 order book diffs
- GET /v1/hyperliquid/spot/orderbook/{symbol}/l4/history - Get Hyperliquid Spot L4 order book history
- GET /v1/hyperliquid/spot/orders/{symbol}/history - Get Hyperliquid Spot order history
- GET /v1/hyperliquid/spot/pairs - List Hyperliquid Spot pairs
- GET /v1/hyperliquid/spot/pairs/{symbol} - Get Hyperliquid Spot pair metadata
- GET /v1/hyperliquid/spot/trades/{symbol} - Get Hyperliquid Spot trades
- GET /v1/hyperliquid/spot/twap/{symbol} - Get Hyperliquid Spot TWAP
- GET /v1/hyperliquid/spot/twap/user/{user} - Get Hyperliquid Spot user TWAP

## Lighter.xyz Endpoints (/v1/lighter)
- GET /v1/lighter/instruments - List all instruments
- GET /v1/lighter/instruments/{symbol} - Single instrument details
- GET /v1/lighter/orderbook/{symbol} - Current order book
- GET /v1/lighter/orderbook/{symbol}/history - Historical order book
- GET /v1/lighter/trades/{symbol} - Trade history
- GET /v1/lighter/trades/{symbol}/recent - Recent trades
- GET /v1/lighter/candles/{symbol} - OHLCV candles
- GET /v1/lighter/funding/{symbol} - Funding rate history
- GET /v1/lighter/funding/{symbol}/current - Current funding rate
- GET /v1/lighter/openinterest/{symbol} - Open interest history
- GET /v1/lighter/openinterest/{symbol}/current - Current open interest
- GET /v1/lighter/freshness/{symbol} - Data freshness
- GET /v1/lighter/summary/{symbol} - Combined market summary
- GET /v1/lighter/prices/{symbol} - Price history
- GET /v1/lighter/l3orderbook/{symbol} - L3 order-level orderbook
- GET /v1/lighter/l3orderbook/{symbol}/history - Historical L3 snapshots

## HIP-3 Builder Perps Endpoints (/v1/hyperliquid/hip3)
- GET /v1/hyperliquid/hip3/instruments - List all HIP-3 instruments
- GET /v1/hyperliquid/hip3/instruments/{symbol} - Single instrument details
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/l2 - Primary full-depth L2 snapshot derived from L4 (full depth, March 10 2026+)
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/l2/history - Primary full-depth L2 checkpoint history derived from L4 (March 10 2026+)
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/l2/diffs - Full-depth L2 aggregate diffs derived from L4
- GET /v1/hyperliquid/hip3/orderbook/{symbol} - Secondary venue-native order book (20 levels max)
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/history - Secondary historical venue-native order book (20 levels max; use for older top-book windows)
- GET /v1/hyperliquid/hip3/trades/{symbol} - Trade history
- GET /v1/hyperliquid/hip3/trades/{symbol}/recent - Recent trades
- GET /v1/hyperliquid/hip3/candles/{symbol} - OHLCV candles
- GET /v1/hyperliquid/hip3/funding/{symbol} - Funding rate history
- GET /v1/hyperliquid/hip3/funding/{symbol}/current - Current funding rate
- GET /v1/hyperliquid/hip3/openinterest/{symbol} - Open interest history
- GET /v1/hyperliquid/hip3/openinterest/{symbol}/current - Current open interest
- GET /v1/hyperliquid/hip3/liquidations/{symbol} - Liquidation history
- GET /v1/hyperliquid/hip3/liquidations/{symbol}/volume - Aggregated liquidation volume
- GET /v1/hyperliquid/hip3/freshness/{symbol} - Data freshness
- GET /v1/hyperliquid/hip3/summary/{symbol} - Combined market summary
- GET /v1/hyperliquid/hip3/prices/{symbol} - Price history
- GET /v1/hyperliquid/hip3/orders/{symbol}/history - Order history
- GET /v1/hyperliquid/hip3/orders/{symbol}/flow - Order flow aggregation
- GET /v1/hyperliquid/hip3/orders/{symbol}/tpsl - TP/SL order history
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/l4 - L4 orderbook reconstruction
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/l4/diffs - L4 orderbook diffs
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/l4/history - L4 orderbook checkpoints

## HIP-4 Outcome Markets Endpoints (/v1/hyperliquid/hip4)
HIP-4 caveats for LLMs:
- HIP-4 coins are referenced by their numeric id (e.g. `0`, `1`, `10`, `11`) in REST paths (e.g. `/v1/hyperliquid/hip4/orderbook/0`). The `#`-prefixed form (`#0`, `#10`) is also accepted for callers integrating from on-chain SDKs.
- HIP-4 has no funding, no liquidations. Those routes return 404 by design. HIP-4 candles ARE available from 2026-05-02 onwards via /hip4/candles/{symbol}; prices represent implied probabilities (0..1), not USD.
- HIP-4 `mark_price` is an implied probability (0..1), not a USD price. Same field name as perps because Hyperliquid upstream uses `markPx` for both.
- HIP-4 markets settle (often within 1 day). After settlement `is_settled` flips true; historical data stays queryable.
- All notional values are denominated in USDH (Hyperliquid stablecoin).

- GET /v1/hyperliquid/hip4/outcomes - List outcome markets (filter `?is_settled=true|false`, cursor pagination)
- GET /v1/hyperliquid/hip4/outcomes/{outcome_id} - Single outcome detail (includes `aggregated_oi`)
- GET /v1/hyperliquid/hip4/outcomes/by-slug/{slug} - Look up outcome by per-outcome or per-side slug (e.g. `btc-above-78213-may-03-0600`)
- GET /v1/hyperliquid/hip4/questions - List HIP-4 questions (multi-choice resolvers grouping N binary outcomes; cursor pagination)
- GET /v1/hyperliquid/hip4/questions/{question_id} - Single question detail (includes `named_outcome_ids`, `fallback_outcome_id`, `settled_named_outcomes`)
- GET /v1/hyperliquid/hip4/instruments - List all HIP-4 instruments (one row per side; coin id format `10*outcome_id + side`)
- GET /v1/hyperliquid/hip4/instruments/{symbol} - Single instrument details
- GET /v1/hyperliquid/hip4/orderbook/{symbol} - Current order book
- GET /v1/hyperliquid/hip4/orderbook/{symbol}/history - Historical order book
- GET /v1/hyperliquid/hip4/trades/{symbol} - Trade history
- GET /v1/hyperliquid/hip4/trades/{symbol}/recent - Recent trades
- GET /v1/hyperliquid/hip4/openinterest/{symbol} - Side open interest history
- GET /v1/hyperliquid/hip4/openinterest/{symbol}/current - Current side open interest
- GET /v1/hyperliquid/hip4/candles/{symbol} - OHLCV candles (1m-1w; prices are probabilities 0..1, quote_volume in USDH)
- GET /v1/hyperliquid/hip4/freshness/{symbol} - Data freshness
- GET /v1/hyperliquid/hip4/summary/{symbol} - Combined market summary
- GET /v1/hyperliquid/hip4/prices/{symbol} - Mid-price history (probability, 0..1)
- GET /v1/hyperliquid/hip4/orders/{symbol}/history - Order history
- GET /v1/hyperliquid/hip4/orders/{symbol}/flow - Order flow aggregation
- GET /v1/hyperliquid/hip4/orders/{symbol}/tpsl - TP/SL order history
- GET /v1/hyperliquid/hip4/orderbook/{symbol}/l4 - L4 orderbook reconstruction
- GET /v1/hyperliquid/hip4/orderbook/{symbol}/l4/diffs - L4 orderbook diffs
- GET /v1/hyperliquid/hip4/orderbook/{symbol}/l4/history - L4 orderbook checkpoints

## Data Quality Endpoints
- GET /health - Lightweight API liveness check
- GET /v1/data-quality/status - System health across supported venue families
- GET /v1/data-quality/coverage - Data coverage overview
- GET /v1/data-quality/coverage/{exchange} - Per-exchange coverage details
- GET /v1/data-quality/coverage/{exchange}/{symbol} - Per-symbol coverage details
- GET /v1/data-quality/incidents - Data quality incidents
- GET /v1/data-quality/incidents/{id} - Single incident details
- GET /v1/data-quality/latency - Latency metrics
- GET /v1/data-quality/sla - SLA compliance report

## Route-Level Access
- Self-serve plans share endpoint and coverage access across REST and WebSocket route families.
- Free includes full endpoint coverage with full history and 90D query windows.
- Build, Pro, and Scale increase credits, rate limits, concurrent queries, WebSocket subscriptions, replay speed, export credits, API keys, and support.
- Enterprise can set named route, delivery, SLA, and dedicated infrastructure terms.

## Web3 Authentication (Wallet-Based)
No API key required for these endpoints. Use SIWE (Sign-In with Ethereum) to get a free API key programmatically.
- POST /v1/auth/web3/challenge - Get SIWE challenge message (requires: address)
- POST /v1/web3/signup - Create free-tier account and get API key (requires: signed SIWE message)
- POST /v1/web3/keys - List all API keys for wallet (requires: signed SIWE message)
- POST /v1/web3/keys/revoke - Revoke an API key (requires: signed SIWE message + key_id)
- POST /v1/web3/subscribe - Start 30-day Build or Pro access via x402 USDC payment on Base (requires: tier in body, payment-signature header with EIP-3009 signed transfer)

## Legacy Endpoints (still supported)
- GET /v1/orderbook/{symbol}, /v1/trades/{symbol}, /v1/funding/{symbol}, /v1/openinterest/{symbol}, /v1/instruments

## Data Coverage (Hyperliquid)
- Order Book: April 2023 - Present (snapshot spacing varies by market activity and query window)
- Trades: April 2023 - Present (pre-March 2025 fills are taker-only)
- Candles: March 2025 - Present
- Funding Rates: May 2023 - Present
- Open Interest: May 2023 - Present
- Liquidations: December 2025 - Present
- 220+ perpetual futures contracts

## Data Coverage (Lighter.xyz)
- Trades: August 2025 - Present
- L2 Order Book: January 2026 - Present
- Candles, OI, Funding: August 2025 - Present
- L3 Order Book: March 2026 - Present

## Data Coverage (HIP-3 Builder Perps)
- Order Book, Trades, Candles, OI, Funding, Liquidations: February 2026 - Present
- 125+ markets across 6 builders: xyz (XYZ), flx (Felix Exchange), hyna (HyENA), km (Kinetiq Markets), vntl (Ventuals), cash (dreamcash)

## Data Coverage (HIP-4 Outcome Markets)
- Order Book, Trades, OI, L4 diffs, L4 orders: 2026-05-02 ~07:47 UTC - Present
- No funding, no liquidations (fully-collateralized binary outcomes, by design). Candles ship from 2026-05-02 via /hip4/candles/{symbol} with prices as probabilities.
- Active market count varies as outcomes settle and new ones open. Poll `/v1/hyperliquid/hip4/outcomes` for the live count.

## WebSocket API
- URL: wss://api.0xarchive.io/ws?apiKey=YOUR_API_KEY (also wss://stream.0xarchive.io/ws)
- One connection model for live subscriptions and historical replay
- Real-time streaming (subscribe to live market data)
- Historical replay (replay past data with original timing, configurable speed)
- Realtime + historical replay: orderbook, trades, candles, funding, open_interest, liquidations, plus lighter_* and hip3_* variants (lighter_l3_orderbook, hip3_liquidations) and HIP-4 (hip4_orderbook, hip4_trades, hip4_open_interest)
- Realtime only: ticker, all_tickers, l4_diffs, l4_orders, hip3_l4_diffs, hip3_l4_orders, hip4_l4_diffs, hip4_l4_orders (L4 channels available on every tier)
- liquidations and hip3_liquidations channels are now live: each event is a fill row with `is_liquidation: true`, same wire shape as trades. They also continue to flow on `trades`/`hip3_trades` for backward compatibility — dedupe on `tid` if subscribing to both.
- HIP-4 outcome markets: subscribe with raw `#0` form in the JSON (`{"op":"subscribe","channel":"hip4_orderbook","symbol":"#0"}`). REST routes accept the bare numeric form (`/hip4/orderbook/0`).
- WebSocket access is available on every tier, including Free

## Pricing
- Free: 50,000 credits/month, 15 req/sec, 3 concurrent, 10 WebSocket subscriptions, 1 API key, $0 export credits, 10x WebSocket replay, full endpoint coverage, full history with 90D query windows
- Build ($49/mo): 80M credits/month, 50 req/sec, 10 concurrent, 500 WebSocket subscriptions, 10 API keys, $50/mo export credits, 50x WebSocket replay
- Pro ($199/mo): 400M credits/month, 150 req/sec, 20 concurrent, 3,000 WebSocket subscriptions, 100 API keys, $300/mo export credits, 100x WebSocket replay, priority email support
- Scale ($799/mo): 2B credits/month, 500 req/sec, 20 concurrent, 20,000 WebSocket subscriptions, 200 API keys, $1,500/mo export credits, 300x WebSocket replay, dedicated support channel
- Enterprise: Custom pricing, custom credits/RPS/concurrency, 200 API keys, unlimited WebSockets, unlimited export credits, dedicated infrastructure, dedicated support, SLA from 99.5%

## SDKs, CLI & Automation
- Python: pip install oxarchive
- TypeScript: npm install @0xarchive/sdk
- Rust: cargo add oxarchive
- CLI: npm install -g @0xarchive/cli (command: oxa)
- MCP Server: 79 typed tools across market data, data quality, and wallet auth for Claude and other MCP clients
- Claude Code Skill: curl + jq based Claude Code access without running MCP
- MCP and Claude Code setup live under the AI Clients docs page in the developer portal

## Bulk Export
- Data Explorer and bulk export: [https://0xarchive.io/data](https://0xarchive.io/data)
- S3 Parquet bulk export for large dataset downloads
- Build, Pro, and Scale export credits apply before checkout; no subscription is required for one-off Data Catalog exports

## Quick Start

### Python
```python
from oxarchive import Client
client = Client(api_key="0xa_your_key")

# Hyperliquid
orderbook = client.hyperliquid.orderbook.get("BTC")
trades = client.hyperliquid.trades.list("ETH", start="2025-01-01", end="2025-01-02")

# Lighter.xyz
lighter_ob = client.lighter.orderbook.get("BTC")

# HIP-3
hip3_instruments = client.hyperliquid.hip3.instruments.list()

# HIP-4 outcome markets (coins are numeric ids: 0, 1, 10, 11, ...)
hip4_outcomes = client.hyperliquid.hip4.outcomes.list(is_settled=False)
```

### Rust
```rust
use oxarchive::OxArchive;

let client = OxArchive::new("0xa_your_key")?;
let orderbook = client.hyperliquid().orderbook().get("BTC", None).await?;
let lighter_ob = client.lighter().orderbook().get("BTC", None).await?;
```

## Account
- Sign up: [https://0xarchive.io/signup](https://0xarchive.io/signup)
- Dashboard: [https://0xarchive.io/dashboard](https://0xarchive.io/dashboard)

## Links
- Website: https://0xarchive.io
- Documentation: https://docs.0xarchive.io/
- Pricing: https://0xarchive.io/pricing
- Bulk Download: https://0xarchive.io/data

## Contact
- Email: support@0xarchive.io
- Website: https://0xarchive.io/contact