# 0xArchive - Developer References

## What is 0xArchive?
0xArchive provides market data across two top-level venue APIs: Hyperliquid and Lighter. Hyperliquid core perps, Hyperliquid Spot, HIP-3 builder perps, and HIP-4 outcome markets are separate Hyperliquid-scoped route families. Lighter has two deployments: Lighter mainnet under `/v1/lighter` and Lighter on Robinhood Chain under `/v1/rh-lighter`. Account positions are available for Hyperliquid core, HIP-3, and both Lighter deployments. 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.

## Machine contracts
- OpenAPI 3.0 spec: https://0xarchive.io/openapi.json. Full REST contract for endpoints, schemas, authentication, and examples
- AsyncAPI 3.0 spec: https://0xarchive.io/asyncapi.yaml. WebSocket channels, messages, live and replay availability, and signed webhook deliveries
- MCP server (canonical, hosted): https://mcp.0xarchive.io/mcp. Market-data discovery and retrieval for MCP clients; the base scope is `mcp:market.read`, with optional `mcp:webhooks.read` and `mcp:webhooks.write` when enabled. Webhook writes change account state. Read the live scope list at https://mcp.0xarchive.io/.well-known/oauth-protected-resource; setup docs at https://docs.0xarchive.io/mcp-server; setup uses client-managed OAuth and requires no 0xArchive API key
- API-key boundary: `X-API-Key` applies to direct REST market-data requests and is not the hosted MCP credential. Hosted MCP uses client-managed OAuth and requires no 0xArchive API key.
- Agent resource catalog (ARD): https://0xarchive.io/.well-known/ai-catalog.json. REST, WebSocket, hosted MCP, x402, exports, coverage, samples, and OKF resources
- Knowledge bundle (OKF): https://0xarchive.io/okf.tar.gz (one fetch) or https://0xarchive.io/okf/ (browsable). Venues, coverage, entitlement, and pricing as typed concepts
- Public coverage manifest: https://0xarchive.io/.well-known/data-coverage.json. Verified Hyperliquid and Lighter BTC dataset availability and earliest published coverage
- Fixed public BTC samples: https://0xarchive.io/.well-known/data-samples.json. Versioned Hyperliquid and Lighter Parquet samples, browser previews, checksums, and offline Hyperliquid L4 and Lighter L3 reconstruction proofs; no account or API key required

## Choose the right surface
- REST integration: start with https://docs.0xarchive.io/quickstart and https://docs.0xarchive.io/authentication, then use https://0xarchive.io/openapi.json for the complete request and schema contract. Direct REST market-data requests use `X-API-Key`.
- Production REST behavior: use https://docs.0xarchive.io/errors, https://docs.0xarchive.io/rest-api/reliability, and https://docs.0xarchive.io/rate-limits for exact status codes, `Retry-After`, bounded retries, backoff, and limits.
- Continuous real-time streaming and historical replay: use https://docs.0xarchive.io/websocket/real-time. WebSocket clients send `Authorization: Bearer <API_KEY>` during the handshake.
- Hosted agent tools: use https://docs.0xarchive.io/mcp-server. Hosted MCP uses client-managed OAuth and requires no 0xArchive API key.
- Autonomous 30-day Build or Pro access: use https://0xarchive.io/facilitator for the current x402 payment contract.
- One-off Parquet exports: use https://0xarchive.io/data for catalog discovery, checkout, processing, and delivery.

## When to use 0xArchive
Use 0xArchive when an application or agent needs historical or real-time market data from Hyperliquid or Lighter through a stable integration surface.
- Query trades, candles, funding, open interest, order books, order history, and liquidation datasets through REST.
- Look up account positions by wallet address (Hyperliquid, HIP-3) or account index (Lighter): current and as-of state, hourly history, the position change log, and market-wide listings.
- Stream current market data and replay historical channels through WebSocket.
- Download Parquet exports for larger historical workflows.
- Connect agent tools through the hosted MCP server with client-managed OAuth.
- Check coverage and freshness before choosing a market, dataset, or time window.

## When not to use 0xArchive
0xArchive does not place or manage orders, hold funds, or operate a trading venue.
- Do not treat static coverage dates as current service health. Check https://0xarchive.io/status and the data-quality routes before operational use.
- The WebSocket section below lists live subscription and replay channels by venue and dataset.

## Try without an account
Fetch https://0xarchive.io/.well-known/data-samples.json for fixed Hyperliquid and Lighter BTC samples, checksums, previews, and offline reconstruction proofs. The samples require no account or API key. Use https://0xarchive.io/signup when you need the live REST, WebSocket, or export workflows.

## 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
- 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

## Editorial Resources
- Resources hub: https://0xarchive.io/resources
- Original research: https://0xarchive.io/resources/research
- Market data guides: https://0xarchive.io/resources/market-data-guides
- Verified work powered by 0xArchive: https://0xarchive.io/resources/built-with-0xarchive
- Major product and coverage updates: https://0xarchive.io/resources/product-updates
- Published Resource Article URLs use `https://0xarchive.io/resources/<primary-type>/<slug>`. Legacy `/blog/<slug>` citations redirect one-to-one to their exact canonical Resource Article.

Use the Resources collections for evidence-led market studies and practical methods. Use the developer portal for implementation contracts, endpoint details, and setup instructions.

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
- 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` is the primary automated-client URL for the REST API reference.

## API Basics
- Base URL: `https://api.0xarchive.io`
- API-key boundary: `X-API-Key` applies to direct REST market-data requests and REST-based SDK, CLI, and Claude Code Skill calls. Hosted MCP uses client-managed OAuth and requires no 0xArchive API key.
- WebSocket authentication: send `Authorization: Bearer <API_KEY>` during the handshake at `wss://api.0xarchive.io/ws` (separate from hosted MCP OAuth). The legacy `apiKey` query parameter is compatibility-only for private server-side scripts; keep credentials out of browser-facing URLs and logs.
- Health check: `GET /health` is unauthenticated
- Data quality: `/v1/data-quality/*`
- Response shape: successful JSON responses use `success`, `data`, and `meta`, with `meta.request_id` on every response. Errors return `success: false`, `code` (the HTTP status), `error_code` (a stable machine-readable code), `error` (a readable message), and `request_id`; some errors add `param` naming the parameter at fault.
- 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 mainnet: `/v1/lighter/*`
- Lighter on Robinhood Chain: `/v1/rh-lighter/*`
- Account positions: `/wallets/{address}/positions` and `/positions/{symbol}` under `/v1/hyperliquid` and `/v1/hyperliquid/hip3`; `/accounts/{account_index}/positions` and `/positions/{symbol}` under `/v1/lighter` and `/v1/rh-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 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.
- Lighter has two deployments: Lighter mainnet (`/v1/lighter`) and Lighter on Robinhood Chain (`/v1/rh-lighter`). Lighter on Robinhood Chain is a second deployment of Lighter, not a third peer venue.
- Lighter on Robinhood Chain symbols can match mainnet Lighter symbols but name different markets: BTC under `/v1/rh-lighter` is not BTC under `/v1/lighter`. Perpetuals use uppercase symbols (BTC); spot pairs are dashed and USDG-quoted (AAPL-USDG).

## Data Quality Guidance
- Check `/health` for service liveness.
- Check `/v1/data-quality/status` before operational use.
- Data-quality routes report coverage dates and capture freshness for historical queries.
- 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/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 all-level aggregated L2 derived from L4 data from March 11, 2026 01:03 UTC onward where available.
- Use `/orderbook/{symbol}/l2/history` for all-level 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 include all served price levels on `/v1/lighter/orderbook/{symbol}`. Lighter L3 returns up to 250 resting orders per side.
- Lighter on Robinhood Chain serves L2 only (`/v1/rh-lighter/orderbook/{symbol}`); L3 order-level data is not captured on that deployment.

## 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 all-level L2 snapshot derived from L4 (March 11, 2026+)
- GET /v1/hyperliquid/orderbook/{symbol}/l2/history - Primary all-level L2 checkpoint history derived from L4 (March 11, 2026+)
- GET /v1/hyperliquid/orderbook/{symbol}/l2/diffs - All-level 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/{symbol}/levels - Projected forced-liquidation price levels
- GET /v1/hyperliquid/liquidations/{symbol}/levels/history - Historical projected forced-liquidation price levels
- 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/cvd/{symbol} - Cumulative volume delta buckets (1m-1w intervals; page with `cursor` and `limit`, default 500 and max 10000 buckets, until `meta.next_cursor` is absent; `cumulative_delta` restarts on each page, so rebuild it from `delta` when joining pages)
- GET /v1/hyperliquid/orders/{symbol}/history - Order history with user attribution
- GET /v1/hyperliquid/orders/{symbol}/flow - Order flow aggregation (`interval`: 1m default, 5m, 15m, or 1h; `granularity` is accepted as an alias)
- GET /v1/hyperliquid/orders/{symbol}/tpsl - TP/SL order history
- GET /v1/hyperliquid/twap/{symbol} - TWAP order status events for one market (`start`, `end`, `cursor`, `limit` up to 1000)
- GET /v1/hyperliquid/twap/user/{user} - TWAP order status events for one wallet address
- GET /v1/hyperliquid/wallets/{address}/profile - Behavioral metrics for one wallet over the last `hours` (default 24, maximum 168), optionally for one `coin`
- GET /v1/hyperliquid/orderbook/{symbol}/l4 - L4 orderbook reconstruction with user attribution; optional `timestamp` and `depth` query parameters
- 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; optional `timestamp` and `depth` query parameters
- 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 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/liquidations/{symbol} - Liquidation history
- GET /v1/lighter/liquidations/{symbol}/volume - Aggregated liquidation volume
- 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} - Current L3 order-level orderbook; optional `timestamp`, `account`, and `depth` query parameters (`limit` is not supported)
- GET /v1/lighter/l3orderbook/{symbol}/history - Historical L3 snapshots with `start`, `end`, `cursor`, `limit`, and `account` query parameters; snapshots are checkpoints; limit defaults to 100 and is capped at 1000
- Lighter L3 order rows expose `order_index`, `owner_account_index`, `side`, `price`, `remaining_size`, and `original_size`. `order_index` is the venue's numeric order index; `owner_account_index` is a numeric account index, not an address.

## Lighter on Robinhood Chain Endpoints (/v1/rh-lighter)
The second Lighter deployment: 84 USDG-quoted markets (57 perpetuals, 27 spot). Same routes and response shapes as `/v1/lighter`, without L3.
- GET /v1/rh-lighter/instruments - List all instruments (`market_type` perp or spot)
- GET /v1/rh-lighter/instruments/{symbol} - Single instrument details
- GET /v1/rh-lighter/orderbook/{symbol} - Current order book
- GET /v1/rh-lighter/orderbook/{symbol}/history - Historical order book
- GET /v1/rh-lighter/trades/{symbol} - Trade history (canonical up to `meta.finalized_through`)
- GET /v1/rh-lighter/trades/{symbol}/recent - Recent trades (preliminary tier, `meta.preliminary_row_count`)
- GET /v1/rh-lighter/candles/{symbol} - OHLCV candles (answers with an error until candles are enabled for this deployment)
- GET /v1/rh-lighter/funding/{symbol} - Funding rate history (perpetuals)
- GET /v1/rh-lighter/funding/{symbol}/current - Current funding rate (perpetuals)
- GET /v1/rh-lighter/openinterest/{symbol} - Open interest history (perpetuals)
- GET /v1/rh-lighter/openinterest/{symbol}/current - Current open interest (perpetuals)
- GET /v1/rh-lighter/liquidations/{symbol} - Liquidation history (perpetuals)
- GET /v1/rh-lighter/liquidations/{symbol}/volume - Aggregated liquidation volume (perpetuals)
- GET /v1/rh-lighter/freshness/{symbol} - Data freshness
- GET /v1/rh-lighter/summary/{symbol} - Combined market summary
- GET /v1/rh-lighter/prices/{symbol} - Price history

## Account Positions Endpoints
Hyperliquid core (`/v1/hyperliquid`) and HIP-3 (`/v1/hyperliquid/hip3`, optional `dex` filter) key positions by wallet address:
- GET /wallets/{address}/positions - Current positions, or the state at `timestamp` (epoch ms)
- GET /wallets/{address}/positions/history - Hourly position rows in `[start, end)`
- GET /wallets/{address}/positions/changes - Position change log in `[start, end)`
- GET /wallets/{address}/account - Current account summary
- GET /wallets/{address}/account/history - Hourly account summaries
Lighter mainnet (`/v1/lighter`) and Lighter on Robinhood Chain (`/v1/rh-lighter`) key positions by integer account index:
- GET /accounts/{account_index}/positions, /positions/history, /positions/changes - Same semantics as the wallet routes
- GET /accounts/{account_index}/account and /account/history - Position aggregates only
- GET /v1/lighter/accounts?l1_address=0x... - Account indices owned by an L1 address (Lighter mainnet only)
Every venue:
- GET /positions/{symbol} - Every open position in one market (latest live snapshot or `hour`), largest first, totals in `meta.totals`
- GET /positions/{symbol}/summary - Long/short counts, sizes, values, average entries, and top-10 share, now or hourly
- GET /positions - Every open position at one committed hour (bulk; `format=arrow` where enabled)
- Responses carry `meta.as_of`, `meta.snapshot_ts`, `meta.source` (`snapshot`, `reconstructed`, or `changes`), `meta.quality`, `meta.stale`, `meta.built_through`, and `meta.finalized_through`. Numbers are decimal strings. Cursors are signed and bound to the request; a replaced market snapshot returns 409 `snapshot_advanced`.

## 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 all-level L2 snapshot derived from L4 (March 11, 2026+)
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/l2/history - Primary all-level L2 checkpoint history derived from L4 (March 11, 2026+)
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/l2/diffs - All-level 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/liquidations/{symbol}/levels - Projected forced-liquidation price levels
- GET /v1/hyperliquid/hip3/liquidations/{symbol}/levels/history - Historical projected forced-liquidation price levels
- 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/cvd/{symbol} - Cumulative volume delta buckets (same intervals and paging as the core CVD route)
- GET /v1/hyperliquid/hip3/orders/{symbol}/history - Order history
- GET /v1/hyperliquid/hip3/orders/{symbol}/flow - Order flow aggregation (`interval`: 1m default, 5m, 15m, or 1h; `granularity` is accepted as an alias)
- GET /v1/hyperliquid/hip3/orders/{symbol}/tpsl - TP/SL order history
- GET /v1/hyperliquid/hip3/twap/{symbol} - TWAP order status events for one market
- GET /v1/hyperliquid/hip3/twap/user/{user} - TWAP order status events for one wallet address
- GET /v1/hyperliquid/hip3/wallets/{address}/profile - Behavioral metrics for one wallet on HIP-3 markets
- GET /v1/hyperliquid/hip3/orderbook/{symbol}/l4 - L4 orderbook reconstruction; optional `timestamp` and `depth` query parameters
- 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 (`interval`: 1m default, 5m, 15m, or 1h; `granularity` is accepted as an alias)
- GET /v1/hyperliquid/hip4/orders/{symbol}/tpsl - TP/SL order history
- GET /v1/hyperliquid/hip4/twap/{symbol} - TWAP order status events for one outcome side
- GET /v1/hyperliquid/hip4/twap/user/{user} - TWAP order status events for one wallet address
- GET /v1/hyperliquid/hip4/orderbook/{symbol}/l4 - L4 orderbook reconstruction; optional `timestamp` and `depth` query parameters
- 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/capabilities - What each venue serves: REST routes, WebSocket channels with live and replay support, first served instant, cadence, page limit, and intervals (no API key required)
- 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
- GET /v1/data-quality/positions - Account positions freshness per product

## Route-Level Access
- Self-serve plans share every market, route family, schema, and served depth across REST and WebSocket; plans gate capacity and Free's 30-day history window.
- One WebSocket channel is not on every plan: `mempool`, the live stream of pending Hyperliquid transactions, is included with Pro, Scale, and Enterprise. Every other route and channel is on every plan, Free included.
- Free includes every market, route, schema, and served depth, with history limited to the most recent rolling 30 days and a maximum 30-day span per request or replay. Build and above keep the full retained archive.
- Build, Pro, and Scale keep the full retained archive and 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 is required for these wallet-auth endpoints. SIWE supports existing-wallet sign-in and key management; new wallet accounts use paid x402 access. Unknown wallets receive an account and API key only after successful settlement. Standard Free accounts use https://0xarchive.io/signup.
- POST /v1/auth/web3/challenge - Get a single-use SIWE challenge message (requires: address)
- POST /v1/auth/web3/verify - Sign in an existing active wallet account (requires: signed SIWE message; unknown wallets receive 403 wallet_account_required)
- POST /v1/web3/signup - Retired compatibility endpoint (always returns 410 wallet_free_signup_retired and creates nothing)
- POST /v1/web3/keys - List all API keys for an existing wallet account (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; disabled existing wallets are rejected before settlement)

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

## Data Coverage (Hyperliquid)
- Order Book: from April 15, 2023 (snapshot spacing varies by market activity and query window)
- Trades: Core from April 15, 2023.
- Candles: from March 22, 2025 12:00 UTC. Older bars exist but are not served.
- Funding Rates: from May 20, 2023
- Open Interest: from May 20, 2023
- Liquidations: from December 22, 2025. Older rows exist but are not served.
- L4 order book, L4 diffs, and order events: from March 11, 2026 01:03 UTC
- TWAP order status events: from June 17, 2026 18:00 UTC
- Use `GET /v1/hyperliquid/instruments` for the current market list

## Data Coverage (Lighter)
- Trades: observed global floor January 17, 2025; exact starts vary by market (more than 2 billion records)
- L2 Order Book: from January 29, 2026
- Candles: from August 1, 2025
- Open Interest and Funding: from August 25, 2025
- L3 Order Book: from March 5, 2026
- Liquidations: from June 10, 2026 (live capture only)

## Data Coverage (Lighter on Robinhood Chain)
- Trades and liquidations: from the venue launch on June 26, 2026 20:10:26 UTC. Liquidation rows from before live capture began on August 22, 2026 were backfilled from the venue's finalized export and carry `source: "bucket"` and an empty `raw_json`; live-captured rows carry `source: "ws"`.
- L2 Order Book, Open Interest, Funding: from August 22, 2026 18:43 UTC
- Candles: from June 26, 2026, once enabled for this deployment
- No L3 order book

## Data Coverage (Account Positions)
- Hyperliquid core: change log from May 25, 2025 15:00 UTC; hourly history from June 7, 2026 18:00 UTC; live snapshots every 5 minutes
- HIP-3: change log from October 13, 2025; hourly history from June 7, 2026 18:00 UTC (later for some dexes); live snapshots every 5 minutes
- Lighter mainnet: change log and hourly history from January 17, 2025; live snapshots every 2 minutes
- Lighter on Robinhood Chain: change log and hourly history from June 26, 2026; live snapshots every 2 minutes
- A request before coverage returns an empty result with `meta.notice` and `meta.coverage_from`.
- Lighter and Robinhood Chain: snapshots from the latest day, before the venue's daily trade reconcile, can read `degraded` in `meta.quality` with rows marked `preliminary`; they read `complete` after the reconcile.
- Hyperliquid: a small number of positions around three short windows in June and July 2025, where Hyperliquid's published fill data has gaps, are marked `partial`.

## Data Coverage (HIP-3 Builder Perps)
- Trades: observed global floor October 13, 2025; exact starts vary by symbol
- Native L2 order book, funding, and open interest: observed global floor February 16, 2026; exact starts vary by symbol and schema
- Candles and liquidations: from December 22, 2025
- L4 order book, L4 diffs, and order events: from March 11, 2026 01:03 UTC; actual symbol coverage differs by schema
- TWAP order status events: from June 17, 2026 18:00 UTC
- Use `/v1/symbols` `coverage_by_type` and HIP-3 instrument discovery for the current inventory and schema-specific dates before choosing a window

## Data Coverage (HIP-4 Outcome Markets)
- L4 checkpoints: 2026-05-02 07:47 UTC - Present
- L4 orders: 2026-05-02 07:49 UTC - Present
- L4 diffs: 2026-05-02 07:50 UTC - Present
- Candles: 2026-05-02 08:00 UTC - Present
- Trades: 2026-05-02 08:00 UTC - Present
- Native L2 order book: 2026-05-02 16:51 UTC - Present
- Open interest: 2026-05-02 16:51 UTC - Present
- No funding, no liquidations (fully-collateralized binary outcomes, by design). Candle prices are 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
- Authentication: send `Authorization: Bearer <API_KEY>` during the WebSocket handshake; this is separate from hosted MCP OAuth.
- Compatibility: The legacy `apiKey` query parameter is compatibility-only for private server-side scripts; keep credentials out of browser-facing URLs and logs.
- One connection model for real-time subscriptions and historical replay
- Real-time streaming (subscribe to real-time market data)
- Timed replay: Hyperliquid core and HIP-3 orderbook, trades, candles, funding, open_interest, and liquidation channels; Lighter orderbook, L3 orderbook, trades, candles, funding, and open_interest channels; and HIP-4 orderbook, trades, and open-interest channels. Lighter liquidation events are REST-only.
- L4 and full-depth replay: l4_diffs, l4_orders, and orderbook_full (Hyperliquid core); hip3_l4_diffs, hip3_l4_orders, and hip3_orderbook_full (HIP-3); spot_l4_diffs and spot_l4_orders (Spot); and hip4_l4_diffs and hip4_l4_orders (HIP-4) replay as a checkpoint-anchored, single-channel bulk stream. A replay opens with the nearest L4 checkpoint at or before `start` as an `l4_snapshot`, then sends `l4_batch` pages of up to 5,000 events in block order; the replay speed parameter is ignored and `replay.seek` is refused. Replay history starts 2026-03-11 01:03 UTC for Hyperliquid core, HIP-3, and Spot, and 2026-05-02 07:47 UTC for HIP-4; `GET /v1/capabilities` publishes the current floor of every channel (L4 channels are available on every tier)
- Real-time only: ticker, all_tickers, spot_orderbook, and spot_trades
- spot_twap, hip4_orderbook, and hip4_open_interest accept live subscriptions but deliver no live messages today. Replay hip4_orderbook and hip4_open_interest, use hip4_l4_diffs for a live HIP-4 book, and use the REST TWAP routes for Spot TWAP.
- Replay only: candles, hip3_candles, lighter_candles, lighter_l3_orderbook, rh_lighter_candles.
- `GET /v1/capabilities` lists every channel with its live and replay support and its first served instant.
- Lighter live channels: lighter_orderbook, lighter_trades, lighter_open_interest, and lighter_funding support real-time subscriptions as well as replay, on wss://api.0xarchive.io/ws only. lighter_candles and lighter_l3_orderbook are replay-only. Use the symbols from GET /v1/lighter/instruments; subscribe is case-insensitive and acknowledgements echo the symbol in uppercase, for example `{"op":"subscribe","channel":"lighter_orderbook","symbol":"BTC"}`.
- Lighter live messages use the same `data` envelope as Hyperliquid live data. Lighter replay keeps its existing `historical_data` row shapes, which differ from the live shapes below, unless the connection URL selects `version=2026-10-01`; then Lighter and Lighter on Robinhood Chain replay rows use the live shapes.
- lighter_orderbook: every message is a full book (not a diff) of up to 20 levels per side, with `levels[0]` the bids and `levels[1]` the asks, each side best price first. `px` and `sz` are decimal strings as Lighter publishes them and `n` is always 1. Example `data` payload, trimmed to one level per side: `{"coin":"BTC","time":1790294171459,"levels":[[{"px":"84368.7","sz":"0.00020","n":1}],[{"px":"84368.8","sz":"0.05720","n":1}]]}`. The newest book is sent at most once per interval: one per second by default, or pass `interval_ms` from 100 to 5000 (accepted on lighter_orderbook only). Each book sent is one metered message. The current book is sent on subscribe when one is available.
- lighter_trades: two fill rows per trade, one per side, sharing a `tid`. Count trades by distinct `tid` and sum `sz` over one leg per `tid` for volume. `crossed: true` marks the taker leg and `users` holds the Lighter account index. `fee`, `fee_token`, `closed_pnl`, and `dir` are always null on the live stream. Example `data` payload for one trade: `[{"coin":"BTC","side":"A","px":"84367.9","sz":"0.00003","time":1790294182211,"hash":"0000001dc8774b28000001a0d5d94943000000000000000000000000000000000000000000000000","tid":31944180930,"oid":562953419896990,"crossed":false,"dir":null,"fee":null,"fee_token":null,"closed_pnl":null,"start_position":"109.79011","users":["281474976623827"]},{"coin":"BTC","side":"B","px":"84367.9","sz":"0.00003","time":1790294182211,"hash":"0000001dc8774b28000001a0d5d94943000000000000000000000000000000000000000000000000","tid":31944180930,"oid":844421425107071,"crossed":true,"dir":null,"fee":null,"fee_token":null,"closed_pnl":null,"start_position":"0.03940","users":["713845"]}]`. Live trades are preliminary; GET /v1/lighter/trades/{symbol} returns only reconciled trades (see `meta.finalized_through`) and GET /v1/lighter/trades/{symbol}/recent serves the preliminary tier.
- lighter_open_interest and lighter_funding carry the same message, a `ctx` object with `openInterest`, `funding` (a fraction), `premium` (a fraction), `markPx`, `oraclePx` (Lighter's index price), `midPx`, `dayNtlVlm` (24h quote volume), `dayBaseVlm` (24h base volume), and `prevDayPx`. `impactPxs` is always null. Example `data` payload: `{"coin":"BTC","ctx":{"openInterest":"172706178.266310","funding":"0.000012","premium":"-0.000327","markPx":"84363.5","oraclePx":"84397.0","midPx":"84368.8","dayNtlVlm":"908611371.550746","dayBaseVlm":"10808.97087","prevDayPx":"84285.9","impactPxs":null}}`. Updates arrive as Lighter publishes them, about once per second per market, and the latest values are sent on subscribe when available.
- Lighter on Robinhood Chain channels: rh_lighter_orderbook, rh_lighter_trades, rh_lighter_open_interest, and rh_lighter_funding support real-time subscriptions and replay, on wss://api.0xarchive.io/ws only; their live messages have the same shapes as the lighter_* live messages above, and rh_lighter_orderbook accepts `interval_ms` from 100 to 5000 (default 1000). rh_lighter_candles is replay-only. Use the symbols from GET /v1/rh-lighter/instruments. Multi-channel replay cannot mix Lighter mainnet and Robinhood Chain channels.
- A connection that falls behind lighter_trades or the Lighter stats channels receives an error notice counting the messages it missed; persistent lag stops that subscription until the client re-subscribes. lighter_orderbook never replaces a newer book with an older one.
- Hyperliquid core `liquidations` and HIP-3 `hip3_liquidations` channels are live: each event is a fill row with `is_liquidation: true`, the same wire shape as trades. They also continue to flow on `trades` and `hip3_trades` for backward compatibility; dedupe on `tid` if subscribing to both.
- Mempool: the `mempool` channel streams signed Hyperliquid transactions (orders, cancels, modifies, TWAPs, leverage changes, transfers, and other actions) as our Hyperliquid node receives them, before they are in a block, for perps, HIP-3, HIP-4, and Spot. Pending is not executed: a transaction can still be rejected, expire, or never land. It is live only and never stored (no replay, history, REST route, or export), it is served only on wss://stream.0xarchive.io/ws with the same API key, and it is included with Pro, Scale, and Enterprise. `symbol` is optional: `{"op":"subscribe","channel":"mempool"}` streams every pending transaction our Hyperliquid node receives, and `{"op":"subscribe","channel":"mempool","symbol":"BTC"}` only actions that reference BTC. Each `data` message holds one item per signed action with `received_at`, `received_at_ms`, `symbols`, `action` (exactly as signed), `nonce`, `vault_address`, `expires_after_ms`, and `signature`. Details: https://docs.0xarchive.io/websocket/mempool
- HIP-4 outcome markets: subscribe with raw `#0` form in the JSON (`{"op":"subscribe","channel":"hip4_trades","symbol":"#0"}`). REST routes accept the bare numeric form (`/hip4/orderbook/0`).
- WebSocket access is available on every tier, including Free, with every channel except `mempool`, which is included with Pro, Scale, and Enterprise

## 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, history limited to the most recent rolling 30 days with a maximum 30-day span per request or replay
- Build ($49/mo): 80M credits/month, 50 req/sec, 10 concurrent, 500 WebSocket subscriptions, 10 API keys, $50/mo export credits, 50x WebSocket replay, full retained archive
- 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, full retained archive, live mempool stream, 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, full retained archive, live mempool stream, priority email support
- Enterprise: Custom pricing, custom credits/RPS/concurrency, 200 API keys, unlimited WebSockets, live mempool stream, unlimited export credits, dedicated infrastructure, dedicated support, SLA from 99.5%
- Account positions routes bill 1 credit per 1,000 rows returned (minimum 1 credit per request), the same rate as trades. Account summaries and the Lighter L1 resolver bill 1 credit per request.

## SDKs, CLI & Automation
- Python: pip install oxarchive
- TypeScript: npm install @0xarchive/sdk
- Rust: cargo add oxarchive
- CLI: npm install -g @0xarchive/cli (command: oxa)
- SDKs, CLI, and Claude Code Skill call the REST API and use API-key auth.
- MCP Server (canonical, hosted): https://mcp.0xarchive.io/mcp. Typed tools for market-data discovery and retrieval in Claude and other MCP clients use `mcp:market.read`. Optional `mcp:webhooks.read` and `mcp:webhooks.write` scopes are offered when enabled. Webhook writes change account state. Use the live protected-resource metadata and discovered tool schemas for current scope and tool availability. Hosted setup uses client-managed OAuth and requires no 0xArchive API key.
- Claude Code Skill: curl + jq based REST access without running MCP; it uses REST API-key auth
- Hosted 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 mainnet
lighter_ob = client.lighter.orderbook.get("BTC")

# Lighter on Robinhood Chain (second Lighter deployment, USDG-quoted)
rh_ob = client.rh_lighter.orderbook.get("AAPL-USDG")

# Account positions (wallet address on Hyperliquid, account index on Lighter)
positions = client.hyperliquid.positions.get("0x31ca8395cf837de08b24da3f660e77761dfb974b")

# 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