@0xarchive/sdk

August 31, 2026 · View on GitHub

TypeScript client for 0xArchive market data in Node services, dashboards, coding-agent workflows, and agent backends.

0xArchive is granular market data infrastructure for Hyperliquid and Lighter.xyz. Hyperliquid includes core perps (/v1/hyperliquid), HIP-3 builder perps (/v1/hyperliquid/hip3), HIP-4 outcome markets (/v1/hyperliquid/hip4), and Hyperliquid Spot (/v1/hyperliquid/spot). Lighter.xyz is the second top-level venue API at /v1/lighter. In this SDK these map to client.hyperliquid, client.hyperliquid.hip3, client.hyperliquid.hip4, client.spot, and client.lighter.

Use this SDK when the integration belongs in TypeScript or JavaScript code and you want typed REST helpers, WebSocket support, replay workflows, and order-book reconstruction utilities.

Installation

npm install @0xarchive/sdk
# or
yarn add @0xarchive/sdk
# or
pnpm add @0xarchive/sdk

Quick Start

import { OxArchive } from '@0xarchive/sdk';

const client = new OxArchive({ apiKey: '0xa_your_api_key' });

// First successful call: Hyperliquid BTC order book
const hlOrderbook = await client.hyperliquid.orderbook.get('BTC');
console.log(`Hyperliquid BTC mid price: ${hlOrderbook.midPrice}`);

// Lighter.xyz uses its own venue client
const lighterOrderbook = await client.lighter.orderbook.get('BTC');
console.log(`Lighter BTC mid price: ${lighterOrderbook.midPrice}`);

// Hyperliquid HIP-3 builder perps stay under client.hyperliquid.hip3
const hip3Instruments = await client.hyperliquid.hip3.instruments.list();
const hip3Orderbook = await client.hyperliquid.hip3.orderbook.get('km:US500');
const hip3Trades = await client.hyperliquid.hip3.trades.recent('km:US500');
const hip3Funding = await client.hyperliquid.hip3.funding.current('xyz:XYZ100');
const hip3Oi = await client.hyperliquid.hip3.openInterest.current('xyz:XYZ100');

// Hyperliquid Spot lives at client.spot. Symbols are dashed canonical (HYPE-USDC).
const spotPairs = await client.spot.pairs.list();
const spotOrderbook = await client.spot.orderbook.get('HYPE-USDC');
const spotTrades = await client.spot.trades.recent('HYPE-USDC');
const spotCandles = await client.spot.candles.history('HYPE-USDC', {
  start: Date.parse('2025-03-22T10:50:22Z'),
  end: Date.now(),
  interval: '1h',
});

// Get historical order book snapshots
const history = await client.hyperliquid.orderbook.history('ETH', {
  start: Date.now() - 86400000, // 24 hours ago
  end: Date.now(),
  limit: 100
});

Choose Your Next Path

Need	Link
First authenticated route	Quick Start
SDK install and route docs	SDK docs
Claude Code, ChatGPT Codex, and coding-agent workflows	AI Clients
Example notebooks	Examples
File-based historical pulls	Data Catalog
Route contract and machine context	OpenAPI, llms.txt

Data Coverage

Venue	Coverage	Notes
Hyperliquid	April 2023+	Core perpetual markets; coverage varies by schema and route.
Hyperliquid HIP-3	February 2026+ for served history	Builder perps with family-specific schema coverage; funding and trade history begin in February 2026.
Hyperliquid HIP-4	May 2026+	Outcome markets. Candles and outcome-side open interest are served from 2026-05-02; OI updates at ~10s. No funding.
Hyperliquid Spot	Candles from 2025-03-22T10:50:22Z; trades from March 2025; orderbook, L4, TWAP from May 2026	326 authenticated inventory rows using dashed symbols (`HYPE-USDC`, `PURR-USDC`). Candle intervals are 1m/5m/15m/30m/1h/4h/1d/1w with max `limit` 1000 and opaque cursors. No funding, OI, or liquidations.
Lighter.xyz	Candles served from 2025-08-01; observed global fill floor August 27, 2025; exact starts vary by market. L3 orderbooks from March 5, 2026+	Perpetuals. Fills carry maker/taker context where served; L3 is capped at 250 orders per side and funding/OI update at approximately 10s.

Configuration

const client = new OxArchive({
  apiKey: '0xa_your_api_key',       // Required
  baseUrl: 'https://api.0xarchive.io',  // Optional
  timeout: 30000,                   // Optional, request timeout in ms (default: 30000)
  validate: false,                  // Optional, enable Zod schema validation
});

REST API Reference

Core resources (orderbook, trades, instruments, funding, openInterest, candles, freshness, summary, priceHistory) are exposed on the venue and family clients where the route is supported. Hyperliquid core, HIP-3, HIP-4, Spot, and Lighter have different resource subsets; see each section for details.

Order Book

// Get current order book (Hyperliquid)
const orderbook = await client.hyperliquid.orderbook.get('BTC');

// Get current order book (Lighter.xyz)
const lighterOb = await client.lighter.orderbook.get('BTC');

// Get order book at specific timestamp with custom depth
const historical = await client.hyperliquid.orderbook.get('BTC', {
  timestamp: 1704067200000,
  depth: 20  // Number of levels per side
});

// Get historical snapshots (start is required)
const history = await client.hyperliquid.orderbook.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 1000
});

Orderbook Depth

The depth parameter controls how many price levels are returned per side. Depth limits are route-specific.

Note: Hyperliquid native L2 source data contains ~20 levels. Dedicated L2 routes derived from L4 can return all available levels where supported. Lighter L3 is individual order-level data capped at 250 orders per side, not an unlimited full-depth book. Depth limits apply to L2 snapshot endpoints only — L4 and L2 diff endpoints return full data.

Lighter Orderbook Granularity

Lighter.xyz orderbook history supports a granularity parameter for different data resolutions.

Granularity	Interval	Credit Multiplier
`checkpoint`	~60s	1x
`30s`	30s	2x
`10s`	10s	3x
`1s`	1s	10x
`tick`	tick-level	20x

// Get Lighter orderbook history with 10s resolution
const history = await client.lighter.orderbook.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  granularity: '10s'
});

// Get 1-second resolution
const history = await client.lighter.orderbook.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  granularity: '1s'
});

// Tick-level data - returns checkpoint + raw deltas
const history = await client.lighter.orderbook.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  granularity: 'tick'
});

Note: The granularity parameter is ignored for Hyperliquid orderbook history.

Orderbook Reconstruction

For tick-level data, the SDK provides client-side orderbook reconstruction. This efficiently reconstructs full orderbook state from a checkpoint and incremental deltas.

import { OrderBookReconstructor } from '@0xarchive/sdk';

// Option 1: Get fully reconstructed snapshots (simplest)
const snapshots = await client.lighter.orderbook.historyReconstructed('BTC', {
  start: Date.now() - 3600000,
  end: Date.now()
});

for (const ob of snapshots) {
  console.log(`${ob.timestamp}: bid=${ob.bids[0]?.px} ask=${ob.asks[0]?.px}`);
}

// Option 2: Get raw tick data for custom reconstruction
const tickData = await client.lighter.orderbook.historyTick('BTC', {
  start: Date.now() - 3600000,
  end: Date.now()
});

console.log(`Checkpoint: ${tickData.checkpoint.bids.length} bids`);
console.log(`Deltas: ${tickData.deltas.length} updates`);

// Option 3: Auto-paginating iterator (recommended for large time ranges)
// Automatically handles pagination, fetching up to 1,000 deltas per request
for await (const snapshot of client.lighter.orderbook.iterateTickHistory('BTC', {
  start: Date.now() - 86400000, // 24 hours of data
  end: Date.now()
})) {
  console.log(snapshot.timestamp, 'Mid:', snapshot.midPrice);
  if (someCondition(snapshot)) break; // Early exit supported
}

// Option 4: Manual iteration (single page, for custom logic)
const reconstructor = client.lighter.orderbook.createReconstructor();
for (const snapshot of reconstructor.iterate(tickData.checkpoint, tickData.deltas)) {
  // Process each snapshot without loading all into memory
  if (someCondition(snapshot)) break; // Early exit if needed
}

// Option 5: Get only final state (most efficient)
const final = reconstructor.reconstructFinal(tickData.checkpoint, tickData.deltas);

// Check for sequence gaps
const gaps = OrderBookReconstructor.detectGaps(tickData.deltas);
if (gaps.length > 0) {
  console.warn('Sequence gaps detected:', gaps);
}

Methods:

Method	Description
`historyTick(coin, params)`	Get raw checkpoint + deltas (single page, max 1,000 deltas)
`historyReconstructed(coin, params, options)`	Get fully reconstructed snapshots (single page)
`iterateTickHistory(coin, params, depth?)`	Auto-paginating async iterator for large time ranges
`createReconstructor()`	Create a reconstructor instance for manual control

Note: The API returns a maximum of 1,000 deltas per request. For time ranges with more deltas, use iterateTickHistory() which handles pagination automatically.

ReconstructOptions:

Option	Default	Description
`depth`	all	Maximum price levels in output
`emitAll`	`true`	If `false`, only return final state

Trades

The trades API uses cursor-based pagination for efficient retrieval of large datasets.

// Get trade history with cursor-based pagination
let result = await client.hyperliquid.trades.list('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 1000
});

// Paginate through all results
const allTrades = [...result.data];
while (result.nextCursor) {
  result = await client.hyperliquid.trades.list('BTC', {
    start: Date.now() - 86400000,
    end: Date.now(),
    cursor: result.nextCursor,
    limit: 1000
  });
  allTrades.push(...result.data);
}

// Get recent trades (Lighter only - has real-time data)
const recent = await client.lighter.trades.recent('BTC', 100);

Note: The recent() method is available for Lighter.xyz (client.lighter.trades.recent()), HIP-3 (client.hyperliquid.hip3.trades.recent()), and HIP-4 (client.hyperliquid.hip4.trades.recent() / getTradesRecent()) -- all three have real-time ingestion. Hyperliquid does not have a recent trades endpoint (it uses hourly S3 backfill); calling client.hyperliquid.trades.recent() throws a structured OxArchiveError directing you to use list() with a time range instead.

Lighter trades are fill-grain: describe the returned records as per fill · maker + taker where that context is served. Do not describe them as every order, a complete order history, or an unlimited trade archive.

Instruments

// List all trading instruments (Hyperliquid)
const instruments = await client.hyperliquid.instruments.list();

// Get specific instrument details
const btc = await client.hyperliquid.instruments.get('BTC');
console.log(`BTC size decimals: ${btc.szDecimals}`);

Lighter.xyz Instruments

Lighter instruments have a different schema with additional fields for fees, market IDs, and minimum order amounts:

// List Lighter instruments (returns LighterInstrument, not Instrument)
const lighterInstruments = await client.lighter.instruments.list();

// Get specific Lighter instrument
const eth = await client.lighter.instruments.get('ETH');
console.log(`ETH taker fee: ${eth.takerFee}`);
console.log(`ETH maker fee: ${eth.makerFee}`);
console.log(`ETH market ID: ${eth.marketId}`);
console.log(`ETH min base amount: ${eth.minBaseAmount}`);

Key differences:

Field	Hyperliquid (`Instrument`)	Lighter (`LighterInstrument`)
Symbol	`name`	`symbol`
Size decimals	`szDecimals`	`sizeDecimals`
Fee info	Not available	`takerFee`, `makerFee`, `liquidationFee`
Market ID	Not available	`marketId`
Min amounts	Not available	`minBaseAmount`, `minQuoteAmount`

HIP-3 Instruments

HIP-3 instruments are derived from live market data and include mark price, open interest, and mid price:

// List all HIP-3 instruments
const hip3Instruments = await client.hyperliquid.hip3.instruments.list();
for (const inst of hip3Instruments) {
  console.log(`${inst.coin} (${inst.namespace}:${inst.ticker}): mark=${inst.markPrice}, OI=${inst.openInterest}`);
}

// Get specific HIP-3 instrument (case-sensitive)
const us500 = await client.hyperliquid.hip3.instruments.get('km:US500');
console.log(`Mark price: ${us500.markPrice}`);

Available HIP-3 Coins:

Builder	Coins
xyz (Hyperliquid)	`xyz:XYZ100`
km (Kinetiq Markets)	`km:US500`, `km:SMALL2000`, `km:GOOGL`, `km:USBOND`, `km:GOLD`, `km:USTECH`, `km:NVDA`, `km:SILVER`, `km:BABA`

HIP-4 Outcome Markets

HIP-4 is Hyperliquid's binary outcome-market namespace. Each outcome has 2 sides (#0 = Yes / side 0, #1 = No / side 1, etc.). Markets are fully collateralized so there are no funding rates or liquidations. Candle history and outcome-side open interest are served from 2026-05-02; OI updates at ~10s. mark_price, midPrice, and candle OHLC values are implied probabilities in [0, 1], not USD prices.

Path encoding: the backend accepts both the bare numeric form ('0', '1', ...) and the on-chain #-prefixed form ('#0', '#1', ...) — and #-prefixed is the canonical form returned by the API in coin fields. The SDK URL-encodes the value on the wire (# becomes %23) so the # form survives fetch (the WHATWG URL parser would otherwise treat # as a fragment delimiter and silently drop the rest of the path). Both forms are equivalent at the API; pass whichever is convenient.

// Per-side instruments (one row per #N coin)
const sides = await client.hyperliquid.hip4.instruments.list();
for (const s of sides) {
  console.log(`${s.symbol} (outcome ${s.outcomeId}/${s.side}): ${s.displayTitle}`);
  console.log(`  slug: ${s.slug}, settled: ${s.isSettled}`);
}

// Per-outcome aggregates (one row per outcome)
const outcomes = await client.hyperliquid.hip4.listOutcomes({ isSettled: false, limit: 50 });
for (const o of outcomes.data) {
  console.log(`outcome ${o.outcomeId}: ${o.displayTitle}`);
  console.log(`  pair: ${o.outcomePair?.[0]} / ${o.outcomePair?.[1]}`);
  console.log(`  expiry: ${o.expiry}, target: ${o.targetPrice}`);
}

// Detail (includes aggregatedOi)
const detail = await client.hyperliquid.hip4.getOutcome(0);
console.log(detail.aggregatedOi?.outcomeDisplayOpenInterestContracts);

// Slug-based lookup (per-outcome OR per-side slug)
const bySlug = await client.hyperliquid.hip4.getOutcomeBySlug('btc-above-78213-may-04-0600');

// Slug-filter on listOutcomes
const filtered = await client.hyperliquid.hip4.listOutcomes({
  slug: 'btc-above-78213-may-04-0600',
});

// Orderbook. Bare numeric form is recommended.
const ob = await client.hyperliquid.hip4.getOrderbook('0');
// ob.midPrice is a probability ∈ [0, 1] — implied YES probability for #0.

// Trades, OI, and prices
const trades = await client.hyperliquid.hip4.getTradesRecent('0', 50);
const oiNow = await client.hyperliquid.hip4.getOpenInterestCurrent('0');
const prices = await client.hyperliquid.hip4.getPrices('0', {
  start: Date.now() - 86400000,
  end: Date.now(),
});

// Candle history (served from 2026-05-02; OHLC values are probabilities)
const candles = await client.hyperliquid.hip4.candles.history('0', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '1m',
});

// Convenience
const summary = await client.hyperliquid.hip4.getSummary('0');
const fresh = await client.hyperliquid.hip4.getFreshness('0');

// L4
const l4 = await client.hyperliquid.hip4.getL4Orderbook('0');
const orders = await client.hyperliquid.hip4.getOrderHistory('0', {
  start: Date.now() - 3600000,
  end: Date.now(),
});

No HIP-4 funding or liquidations. HIP-4 candles and outcome-side open interest are available through the routes documented above; the SDK intentionally does not expose a HIP-4 funding resource.

Hyperliquid Spot

Spot pairs live at /v1/hyperliquid/spot and client.spot. Symbols are dashed canonical (HYPE-USDC, PURR-USDC); the server resolves the dashed form to Hyperliquid's wire formats (PURR/USDC, @107) internally.

Spot has no funding, open interest, or liquidations. Candle history is served through GET /v1/hyperliquid/spot/candles/{symbol} and client.spot.candles.history(), with coverage from 2025-03-22T10:50:22Z. The candle route accepts 1m, 5m, 15m, 30m, 1h, 4h, 1d, and 1w, with a maximum limit of 1000 and opaque pagination cursors.

// Pairs (one row per dashed symbol)
const pairs = await client.spot.pairs.list();
const hype = await client.spot.pairs.get('HYPE-USDC');
console.log(`${hype.symbol}: mark=${hype.markPrice}, mid=${hype.midPrice}`);

// Orderbook (live from 2026-05-05)
const ob = await client.spot.orderbook.get('HYPE-USDC');
console.log(`${ob.coin} mid: ${ob.midPrice}`);

// Orderbook history
const obHistory = await client.spot.orderbook.history('HYPE-USDC', {
  start: Date.now() - 3600000,
  end: Date.now(),
  limit: 100,
});

// Trade history (S3 backfill from 2025-03-22)
const trades = await client.spot.trades.list('HYPE-USDC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 1000,
});

// Recent trades (real-time)
const recent = await client.spot.trades.recent('HYPE-USDC', 100);

// Candle history (served from 2025-03-22T10:50:22Z)
const candles = await client.spot.candles.history('HYPE-USDC', {
  start: Date.parse('2025-03-22T10:50:22Z'),
  end: Date.now(),
  interval: '1h',
  limit: 1000,
});

// L4 reconstruction (live from 2026-05-05)
const l4 = await client.spot.l4Orderbook.get('HYPE-USDC');
const diffs = await client.spot.l4Orderbook.diffs('HYPE-USDC', {
  start: Date.now() - 3600000,
  end: Date.now(),
});

// Order lifecycle events
const orders = await client.spot.orders.history('HYPE-USDC', {
  start: Date.now() - 86400000,
  end: Date.now(),
});

// TWAP statuses by symbol or by user wallet
const bySymbol = await client.spot.twap.bySymbol('HYPE-USDC', {
  start: Date.now() - 86400000,
  end: Date.now(),
});
const byUser = await client.spot.twap.byUser('0xabc...', {
  start: Date.now() - 86400000,
  end: Date.now(),
});

// Per-symbol freshness across all spot data types
const fresh = await client.spot.freshness('HYPE-USDC');
console.log(`Orderbook last updated: ${fresh.orderbook.lastUpdated}`);

Coverage caveats. Spot candle history is served from 2025-03-22T10:50:22Z through GET /v1/hyperliquid/spot/candles/{symbol}. The route supports 1m, 5m, 15m, 30m, 1h, 4h, 1d, and 1w intervals, up to 1000 rows per request; cursors are opaque. Spot trades go back to 2025-03-22 (the earliest date Hyperliquid published S3 spot fills). Pre-March 2025 spot history is unrecoverable from any free public archive. Spot orderbook, L4, and TWAP data are live-only from 2026-05-05; Hyperliquid does not publish historical spot orderbook data.

Funding Rates

// Get current funding rate
const current = await client.hyperliquid.funding.current('BTC');

// Get funding rate history (start is required)
const history = await client.hyperliquid.funding.history('ETH', {
  start: Date.now() - 86400000 * 7,
  end: Date.now()
});

// Get funding rate history with aggregation interval
const hourly = await client.hyperliquid.funding.history('BTC', {
  start: Date.now() - 86400000 * 7,
  end: Date.now(),
  interval: '1h'
});

Funding History Parameters

Parameter	Type	Required	Description
`start`	`number \| string`	Yes	Start timestamp (Unix ms or ISO string)
`end`	`number \| string`	Yes	End timestamp (Unix ms or ISO string)
`cursor`	`number \| string`	No	Cursor from previous response for pagination
`limit`	`number`	No	Max results (default: 100, max: 1000)
`interval`	`OiFundingInterval`	No	Aggregation interval: `'5m'`, `'15m'`, `'30m'`, `'1h'`, `'4h'`, `'1d'`. When omitted, the route's native/default cadence is returned.

Funding cadence is family-specific: Hyperliquid core is approximately 1 minute, HIP-3 is approximately 10 seconds, and Lighter is approximately 10 seconds. HIP-4 does not expose a funding route.

Open Interest

// Get current open interest
const current = await client.hyperliquid.openInterest.current('BTC');

// Get open interest history (start is required)
const history = await client.hyperliquid.openInterest.history('ETH', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 100
});

// Get open interest history with aggregation interval
const hourly = await client.hyperliquid.openInterest.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '1h'
});

Open Interest History Parameters

Parameter	Type	Required	Description
`start`	`number \| string`	Yes	Start timestamp (Unix ms or ISO string)
`end`	`number \| string`	Yes	End timestamp (Unix ms or ISO string)
`cursor`	`number \| string`	No	Cursor from previous response for pagination
`limit`	`number`	No	Max results (default: 100, max: 1000)
`interval`	`OiFundingInterval`	No	Aggregation interval: `'5m'`, `'15m'`, `'30m'`, `'1h'`, `'4h'`, `'1d'`. When omitted, the route's native/default cadence is returned.

Open-interest cadence is family-specific. HIP-4 outcome-side OI is served from 2026-05-02 at ~10s, and Lighter OI updates at approximately 10 seconds. Do not infer a universal one-minute cadence from this shared type.

Liquidations

Get historical liquidation events. Data available from May 2025 onwards for Hyperliquid, and from February 2026 for HIP-3.

// Get liquidation history for a coin (Hyperliquid)
const liquidations = await client.hyperliquid.liquidations.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 100
});

// Paginate through all results
const allLiquidations = [...liquidations.data];
while (liquidations.nextCursor) {
  const next = await client.hyperliquid.liquidations.history('BTC', {
    start: Date.now() - 86400000,
    end: Date.now(),
    cursor: liquidations.nextCursor,
    limit: 1000
  });
  allLiquidations.push(...next.data);
}

// Get liquidations for a specific user
const userLiquidations = await client.hyperliquid.liquidations.byUser('0x1234...', {
  start: Date.now() - 86400000 * 7,
  end: Date.now(),
  coin: 'BTC'  // optional filter
});

// HIP-3 liquidations (case-sensitive coins)
const hip3Liquidations = await client.hyperliquid.hip3.liquidations.history('km:US500', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 100
});

Liquidation Volume

Get pre-aggregated liquidation volume in time-bucketed intervals. Returns total, long, and short USD volumes per bucket -- 100-1000x less data than individual liquidation records.

// Get hourly liquidation volume for the last week (Hyperliquid)
const volume = await client.hyperliquid.liquidations.volume('BTC', {
  start: Date.now() - 86400000 * 7,
  end: Date.now(),
  interval: '1h'  // 5m, 15m, 30m, 1h, 4h, 1d
});

for (const bucket of volume.data) {
  console.log(`${bucket.timestamp}: total=$${bucket.totalUsd}, long=$${bucket.longUsd}, short=$${bucket.shortUsd}`);
}

// HIP-3 liquidation volume (case-sensitive coins)
const hip3Volume = await client.hyperliquid.hip3.liquidations.volume('km:US500', {
  start: Date.now() - 86400000 * 7,
  end: Date.now(),
  interval: '1h'
});

Orders

Access order history, order flow aggregations, and TP/SL (take-profit/stop-loss) orders. Available for Hyperliquid and HIP-3.

// Get order history for a coin
const orders = await client.hyperliquid.orders.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 1000,
  user: '0x1234...',    // optional: filter by user address
  status: 'filled',     // optional: filter by status
  order_type: 'limit',  // optional: filter by order type
});

// Paginate through all results
const allOrders = [...orders.data];
while (orders.nextCursor) {
  const next = await client.hyperliquid.orders.history('BTC', {
    start: Date.now() - 86400000,
    end: Date.now(),
    cursor: orders.nextCursor,
    limit: 1000
  });
  allOrders.push(...next.data);
}

// Get order flow (aggregated order activity over time)
const flow = await client.hyperliquid.orders.flow('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '1h',  // optional aggregation interval
  limit: 100
});

// Get TP/SL orders
const tpsl = await client.hyperliquid.orders.tpsl('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  user: '0x1234...',  // optional: filter by user
  triggered: true,    // optional: filter by triggered status
});

// HIP-3 orders (case-sensitive coins)
const hip3Orders = await client.hyperliquid.hip3.orders.history('km:US500', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 1000
});

const hip3Flow = await client.hyperliquid.hip3.orders.flow('km:US500', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '1h'
});

const hip3Tpsl = await client.hyperliquid.hip3.orders.tpsl('km:US500', {
  start: Date.now() - 86400000,
  end: Date.now()
});

L4 Order Book

Access L4 orderbook snapshots, diffs, and history. L4 data includes user attribution (who placed each order). Available for Hyperliquid and HIP-3.

// Get current L4 orderbook snapshot
const l4Ob = await client.hyperliquid.l4Orderbook.get('BTC');

// Get L4 orderbook at a specific timestamp with custom depth
const l4Historical = await client.hyperliquid.l4Orderbook.get('BTC', {
  timestamp: 1704067200000,
  depth: 20
});

// Get L4 orderbook diffs (incremental updates)
const diffs = await client.hyperliquid.l4Orderbook.diffs('BTC', {
  start: Date.now() - 3600000,
  end: Date.now(),
  limit: 1000
});

// Paginate through diffs
const allDiffs = [...diffs.data];
while (diffs.nextCursor) {
  const next = await client.hyperliquid.l4Orderbook.diffs('BTC', {
    start: Date.now() - 3600000,
    end: Date.now(),
    cursor: diffs.nextCursor,
    limit: 1000
  });
  allDiffs.push(...next.data);
}

// Get L4 orderbook history (full snapshots over time)
const l4History = await client.hyperliquid.l4Orderbook.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 1000
});

// HIP-3 L4 orderbook (case-sensitive coins)
const hip3L4 = await client.hyperliquid.hip3.l4Orderbook.get('km:US500');

const hip3L4Diffs = await client.hyperliquid.hip3.l4Orderbook.diffs('km:US500', {
  start: Date.now() - 3600000,
  end: Date.now(),
  limit: 1000
});

const hip3L4History = await client.hyperliquid.hip3.l4Orderbook.history('km:US500', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 1000
});

L3 Order Book (Lighter only)

Access L3 orderbook snapshots and history from Lighter.xyz. L3 data contains individual resting orders and is capped at 250 orders per side. It is not an unlimited all-orders book.

// Get current L3 orderbook
const l3Ob = await client.lighter.l3Orderbook.get('BTC');

// Get L3 orderbook at a specific timestamp with custom depth
const l3Historical = await client.lighter.l3Orderbook.get('BTC', {
  timestamp: '2026-03-05T00:00:00Z',
  depth: 250
});

// Get L3 orderbook history
const l3History = await client.lighter.l3Orderbook.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 1000
});

// Paginate through L3 history
const allL3 = [...l3History.data];
while (l3History.nextCursor) {
  const next = await client.lighter.l3Orderbook.history('BTC', {
    start: Date.now() - 86400000,
    end: Date.now(),
    cursor: l3History.nextCursor,
    limit: 1000
  });
  allL3.push(...next.data);
}

L2 Order Book (Full-Depth)

Access L2 full-depth orderbook derived from L4 data. Available for Hyperliquid and HIP-3.

// L2 full-depth orderbook
const l2 = await client.hyperliquid.l2Orderbook.get('BTC');

// L2 orderbook at a specific timestamp with depth
const l2Historical = await client.hyperliquid.l2Orderbook.get('BTC', {
  timestamp: 1704067200000,
  depth: 50
});

// L2 orderbook history
const l2History = await client.hyperliquid.l2Orderbook.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  limit: 1000
});

// L2 tick-level diffs
const l2Diffs = await client.hyperliquid.l2Orderbook.diffs('BTC', {
  start: Date.now() - 3600000,
  end: Date.now(),
  limit: 1000
});

// HIP-3 L2 orderbook
const hip3L2 = await client.hyperliquid.hip3.l2Orderbook.get('km:US500');

Freshness

Check when each data type was last updated for a specific coin. Useful for verifying data recency before pulling it. Available across venue APIs.

// Hyperliquid
const freshness = await client.hyperliquid.freshness('BTC');
console.log(`Orderbook last updated: ${freshness.orderbook.lastUpdated}, lag: ${freshness.orderbook.lagMs}ms`);
console.log(`Trades last updated: ${freshness.trades.lastUpdated}, lag: ${freshness.trades.lagMs}ms`);
console.log(`Funding last updated: ${freshness.funding.lastUpdated}`);
console.log(`OI last updated: ${freshness.openInterest.lastUpdated}`);

// Lighter.xyz
const lighterFreshness = await client.lighter.freshness('BTC');

// HIP-3 (case-sensitive coins)
const hip3Freshness = await client.hyperliquid.hip3.freshness('km:US500');

Summary

Get a combined market snapshot in a single call -- mark/oracle price, funding rate, open interest, 24h volume, and 24h liquidation volumes.

// Hyperliquid (includes volume + liquidation data)
const summary = await client.hyperliquid.summary('BTC');
console.log(`Mark price: ${summary.markPrice}`);
console.log(`Oracle price: ${summary.oraclePrice}`);
console.log(`Funding rate: ${summary.fundingRate}`);
console.log(`Open interest: ${summary.openInterest}`);
console.log(`24h volume: ${summary.volume24h}`);
console.log(`24h liquidation volume: $${summary.liquidationVolume24h}`);
console.log(`  Long: $${summary.longLiquidationVolume24h}`);
console.log(`  Short: $${summary.shortLiquidationVolume24h}`);

// Lighter.xyz (price, funding, OI — no volume/liquidation data)
const lighterSummary = await client.lighter.summary('BTC');

// HIP-3 (includes mid_price — case-sensitive coins)
const hip3Summary = await client.hyperliquid.hip3.summary('km:US500');
console.log(`Mid price: ${hip3Summary.midPrice}`);

Price History

Get mark, oracle, and mid price history over time. Supports aggregation intervals. Data projected from open interest records.

// Hyperliquid: available from April 2023
const prices = await client.hyperliquid.priceHistory('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '1h'  // 5m, 15m, 30m, 1h, 4h, 1d
});

for (const snapshot of prices.data) {
  console.log(`${snapshot.timestamp}: mark=${snapshot.markPrice}, oracle=${snapshot.oraclePrice}, mid=${snapshot.midPrice}`);
}

// Lighter.xyz
const lighterPrices = await client.lighter.priceHistory('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '1h'
});

// HIP-3 (case-sensitive coins)
const hip3Prices = await client.hyperliquid.hip3.priceHistory('km:US500', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '1d'
});

// Paginate for larger ranges
let result = await client.hyperliquid.priceHistory('BTC', {
  start: Date.now() - 86400000 * 30,
  end: Date.now(),
  interval: '4h',
  limit: 1000
});
while (result.nextCursor) {
  result = await client.hyperliquid.priceHistory('BTC', {
    start: Date.now() - 86400000 * 30,
    end: Date.now(),
    interval: '4h',
    cursor: result.nextCursor,
    limit: 1000
  });
}

Candles (OHLCV)

Get historical OHLCV candle data aggregated from trades.

// Get candle history (start is required)
const candles = await client.hyperliquid.candles.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '1h',  // 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
  limit: 100
});

// Iterate through candles
for (const candle of candles.data) {
  console.log(`${candle.timestamp}: O=${candle.open} H=${candle.high} L=${candle.low} C=${candle.close} V=${candle.volume}`);
}

// Cursor-based pagination for large datasets
let result = await client.hyperliquid.candles.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '1m',
  limit: 1000
});
const allCandles = [...result.data];
while (result.nextCursor) {
  result = await client.hyperliquid.candles.history('BTC', {
    start: Date.now() - 86400000,
    end: Date.now(),
    interval: '1m',
    cursor: result.nextCursor,
    limit: 1000
  });
  allCandles.push(...result.data);
}

// Lighter.xyz candles
const lighterCandles = await client.lighter.candles.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  interval: '15m'
});

// Hyperliquid Spot candles (served from 2025-03-22T10:50:22Z)
const spotCandles = await client.spot.candles.history('HYPE-USDC', {
  start: '2025-03-22T10:50:22Z',
  end: new Date().toISOString(),
  interval: '1h',
  limit: 1000,
});

Available Intervals

Interval	Description
`1m`	1 minute
`5m`	5 minutes
`15m`	15 minutes
`30m`	30 minutes
`1h`	1 hour (default)
`4h`	4 hours
`1d`	1 day
`1w`	1 week

nextCursor values are opaque server tokens; pass them back unchanged as cursor when requesting the next page. Hyperliquid Spot candle history starts at 2025-03-22T10:50:22Z, and its route accepts up to 1000 rows per request.

Data Quality Monitoring

Monitor data coverage, incidents, latency, and SLA compliance across venue APIs.

// Get overall system health status
const status = await client.dataQuality.status();
console.log(`System status: ${status.status}`);
for (const [exchange, info] of Object.entries(status.exchanges)) {
  console.log(`  ${exchange}: ${info.status}`);
}

// Get data coverage summary for venue APIs
const coverage = await client.dataQuality.coverage();
for (const exchange of coverage.exchanges) {
  console.log(`${exchange.exchange}:`);
  for (const [dtype, info] of Object.entries(exchange.dataTypes)) {
    console.log(`  ${dtype}: ${info.totalRecords.toLocaleString()} records, ${info.completeness}% complete`);
  }
}

// Get symbol-specific coverage with gap detection
const btc = await client.dataQuality.symbolCoverage('hyperliquid', 'BTC');
const oi = btc.dataTypes.open_interest;
console.log(`BTC OI completeness: ${oi.completeness}%`);
console.log(`Historical coverage: ${oi.historicalCoverage}%`);  // Hour-level granularity
console.log(`Gaps found: ${oi.gaps.length}`);
for (const gap of oi.gaps.slice(0, 5)) {
  console.log(`  ${gap.durationMinutes} min gap: ${gap.start} -> ${gap.end}`);
}

// Check empirical data cadence (when available)
const ob = btc.dataTypes.orderbook;
if (ob.cadence) {
  console.log(`Orderbook cadence: ~${ob.cadence.medianIntervalSeconds}s median, p95=${ob.cadence.p95IntervalSeconds}s`);
}

// Time-bounded gap detection (last 7 days)
const weekAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
const btc7d = await client.dataQuality.symbolCoverage('hyperliquid', 'BTC', {
  from: weekAgo,
  to: Date.now(),
});

// List incidents with filtering
const result = await client.dataQuality.listIncidents({ status: 'open' });
for (const incident of result.incidents) {
  console.log(`[${incident.severity}] ${incident.title}`);
}

// Get latency metrics
const latency = await client.dataQuality.latency();
for (const [exchange, metrics] of Object.entries(latency.exchanges)) {
  console.log(`${exchange}: OB lag ${metrics.dataFreshness.orderbookLagMs}ms`);
}

// Get SLA compliance metrics for a specific month
const sla = await client.dataQuality.sla({ year: 2026, month: 1 });
console.log(`Period: ${sla.period}`);
console.log(`Uptime: ${sla.actual.uptime}% (${sla.actual.uptimeStatus})`);
console.log(`API P99: ${sla.actual.apiLatencyP99Ms}ms (${sla.actual.latencyStatus})`);

Data Quality Endpoints

Method	Description
`status()`	Overall system health and per-exchange status
`coverage()`	Data coverage summary for venue APIs
`exchangeCoverage(exchange)`	Coverage details for a specific exchange
`symbolCoverage(exchange, symbol, options?)`	Coverage with gap detection, cadence, and historical coverage
`listIncidents(params)`	List incidents with filtering and pagination
`getIncident(incidentId)`	Get specific incident details
`latency()`	Current latency metrics (WebSocket, REST, data freshness)
`sla(params)`	SLA compliance metrics for a specific month

Note: Data Quality endpoints (coverage(), exchangeCoverage(), symbolCoverage()) perform complex aggregation queries and may take 30-60 seconds on first request (results are cached server-side for 5 minutes). If you encounter timeout errors, create a client with a longer timeout:

const client = new OxArchive({
  apiKey: '0xa_your_api_key',
  timeout: 60000  // 60 seconds for data quality endpoints
});

Web3 Authentication

Get API keys programmatically using an Ethereum wallet. No browser or email required.

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. Plans gate capacity and Free's 30-day history window, not route families, schemas, or served depth. See Pricing for plan capacity.

Free Tier (SIWE)

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { mainnet } from 'viem/chains';

const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');
const walletClient = createWalletClient({ account, chain: mainnet, transport: http() });

// 1. Get SIWE challenge
const challenge = await client.web3.challenge(account.address);

// 2. Sign with personal_sign (EIP-191)
const signature = await walletClient.signMessage({ message: challenge.message });

// 3. Submit → receive API key
const result = await client.web3.signup(challenge.message, signature);
console.log(result.apiKey); // "0xa_..."

Paid Tier (x402 USDC on Base)

import { createWalletClient, http, encodePacked } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';
import crypto from 'crypto';

const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');
const walletClient = createWalletClient({ account, chain: base, transport: http() });

const USDC_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';

// 1. Get pricing
const quote = await client.web3.subscribeQuote('build');
// quote.amount = "49000000" (\$49 USDC), quote.payTo = "0x..."

// 2. Build & sign EIP-3009 transferWithAuthorization
const nonce = `0x${crypto.randomBytes(32).toString('hex')}` as `0x${string}`;
const validAfter = 0n;
const validBefore = BigInt(Math.floor(Date.now() / 1000) + 3600);

const signature = await walletClient.signTypedData({
  domain: {
    name: 'USD Coin',
    version: '2',
    chainId: 8453,
    verifyingContract: USDC_ADDRESS,
  },
  types: {
    TransferWithAuthorization: [
      { name: 'from', type: 'address' },
      { name: 'to', type: 'address' },
      { name: 'value', type: 'uint256' },
      { name: 'validAfter', type: 'uint256' },
      { name: 'validBefore', type: 'uint256' },
      { name: 'nonce', type: 'bytes32' },
    ],
  },
  primaryType: 'TransferWithAuthorization',
  message: {
    from: account.address,
    to: quote.payTo as `0x${string}`,
    value: BigInt(quote.amount),
    validAfter,
    validBefore,
    nonce,
  },
});

// 3. Build x402 payment envelope and base64-encode
const paymentPayload = btoa(JSON.stringify({
  x402Version: 2,
  payload: {
    signature,
    authorization: {
      from: account.address,
      to: quote.payTo,
      value: quote.amount,
      validAfter: '0',
      validBefore: validBefore.toString(),
      nonce,
    },
  },
}));

// 4. Submit payment → receive API key + subscription
const sub = await client.web3.subscribe('build', paymentPayload);
console.log(sub.apiKey, sub.tier, sub.expiresAt);

Key Management

// List and revoke keys (requires a fresh SIWE signature)
const keys = await client.web3.listKeys(challenge.message, signature);
await client.web3.revokeKey(challenge.message, signature, keys.keys[0].id);

Legacy API (Deprecated)

The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:

// Deprecated - use client.hyperliquid.orderbook.get() instead
const orderbook = await client.orderbook.get('BTC');

// Deprecated - use client.hyperliquid.trades.list() instead
const trades = await client.trades.list('BTC', { start, end });

WebSocket Client

The WebSocket client supports two modes: real-time streaming and historical replay. For file-based historical exports, use the Data Catalog.

import { OxArchiveWs } from '@0xarchive/sdk';

const ws = new OxArchiveWs({ apiKey: '0xa_your_api_key' });

Real-time Streaming

Subscribe to live market data from Hyperliquid.

ws.connect({
  onOpen: () => console.log('Connected'),
  onClose: (code, reason) => console.log(`Disconnected: ${code}`),
  onError: (error) => console.error('Error:', error),
});

// Subscribe to channels
ws.subscribeOrderbook('BTC');
ws.subscribeTrades('ETH');
ws.subscribeTicker('SOL');
ws.subscribeAllTickers();

// Handle real-time data with typed callbacks
ws.onOrderbook((coin, data) => {
  console.log(`${coin} mid price: ${data.midPrice}`);
});

ws.onTrades((coin, trades) => {
  console.log(`${coin} new trades: ${trades.length}`);
});

// Unsubscribe when done
ws.unsubscribeOrderbook('BTC');

// Disconnect
ws.disconnect();

Historical Replay

Replay historical data with original timing preserved. Perfect for backtesting.

Important: Replay data is delivered via onHistoricalData(), NOT onTrades() or onOrderbook(). The real-time callbacks only receive live market data from subscriptions.

const ws = new OxArchiveWs({ apiKey: 'ox_...' });
ws.connect();

// Handle replay data - this is where historical records arrive
ws.onHistoricalData((coin, timestamp, data) => {
  console.log(`${new Date(timestamp).toISOString()}: ${data.midPrice}`);
});

// Replay lifecycle events
ws.onReplayStart((channel, coin, start, end, speed) => {
  console.log(`Starting replay: ${channel}/${coin} at ${speed}x`);
});

ws.onReplayComplete((channel, coin, recordsSent) => {
  console.log(`Replay complete: ${recordsSent} records`);
});

// Start replay at 10x speed
ws.replay('orderbook', 'BTC', {
  start: Date.now() - 86400000,  // 24 hours ago
  end: Date.now(),               // Optional, defaults to now
  speed: 10                       // Optional, defaults to 1x
});

// Lighter.xyz replay with granularity
ws.replay('orderbook', 'BTC', {
  start: Date.now() - 86400000,
  speed: 10,
  granularity: '10s'  // Options: 'checkpoint', '30s', '10s', '1s', 'tick'
});

// Handle tick-level data (granularity='tick')
ws.onHistoricalTickData((coin, checkpoint, deltas) => {
  console.log(`Checkpoint: ${checkpoint.bids.length} bids`);
  console.log(`Deltas: ${deltas.length} updates`);
  // Apply deltas to checkpoint to reconstruct orderbook at any point
});

// Control playback
ws.replayPause();
ws.replayResume();
ws.replaySeek(1704067200000);  // Jump to timestamp
ws.replayStop();

Gap Detection

During historical replay, the server automatically detects gaps in the data and notifies the client. This helps identify periods where data may be missing.

// Handle gap notifications during replay
ws.onGap((channel, coin, gapStart, gapEnd, durationMinutes) => {
  console.log(`Gap detected in ${channel}/${coin}:`);
  console.log(`  From: ${new Date(gapStart).toISOString()}`);
  console.log(`  To: ${new Date(gapEnd).toISOString()}`);
  console.log(`  Duration: ${durationMinutes} minutes`);
});

// Start replay - gaps will be reported via onGap callback
ws.replay('orderbook', 'BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  speed: 10
});

Gap thresholds vary by channel:

orderbook, candles, liquidations: 2 minutes
trades: 60 minutes (trades can naturally have longer gaps during low activity periods)

WebSocket Configuration

const ws = new OxArchiveWs({
  apiKey: '0xa_your_api_key',          // Required
  wsUrl: 'wss://api.0xarchive.io/ws', // Optional
  autoReconnect: true,                // Auto-reconnect on disconnect (default: true)
  reconnectDelay: 1000,               // Initial reconnect delay in ms (default: 1000)
  maxReconnectAttempts: 10,           // Max reconnect attempts (default: 10)
  pingInterval: 30000,                // Keep-alive ping interval in ms (default: 30000)
});

Available Channels

Hyperliquid Channels

Channel	Description	Requires Coin	Mode
`orderbook`	L2 order book updates	Yes	Realtime + replay
`trades`	Trade/fill updates	Yes	Realtime + replay
`candles`	OHLCV candle data	Yes	Replay only
`liquidations`	Liquidation events (May 2025+)	Yes	Realtime + replay (live as of 1.6.0)
`open_interest`	Open interest snapshots	Yes	Replay/stream only
`funding`	Funding rate snapshots	Yes	Replay/stream only
`ticker`	Price and 24h volume	Yes	Real-time only
`all_tickers`	All market tickers	No	Real-time only
`l4_diffs`	L4 orderbook diffs with user attribution	Yes	Real-time only
`l4_orders`	Order lifecycle events with user attribution	Yes	Real-time only

Each liquidations data message is a fill row with is_liquidation: true — the wire shape matches trades exactly. Use onLiquidations to receive a parsed Trade[].

HIP-3 Builder Perps Channels

Channel	Description	Requires Coin	Mode
`hip3_orderbook`	HIP-3 L2 order book snapshots	Yes	Realtime + replay
`hip3_trades`	HIP-3 trade/fill updates	Yes	Realtime + replay
`hip3_candles`	HIP-3 OHLCV candle data	Yes	Realtime + replay
`hip3_open_interest`	HIP-3 open interest snapshots	Yes	Replay/stream only
`hip3_funding`	HIP-3 funding rate snapshots	Yes	Replay/stream only
`hip3_liquidations`	HIP-3 liquidation events (Feb 2026+)	Yes	Realtime + replay (live as of 1.6.0)
`hip3_l4_diffs`	HIP-3 L4 orderbook diffs	Yes	Real-time only
`hip3_l4_orders`	HIP-3 order lifecycle events	Yes	Real-time only

Note: HIP-3 coins are case-sensitive (e.g., km:US500, xyz:XYZ100). Do not uppercase them.

HIP-4 Outcome-Market Channels

Channel	Description	Requires Coin	Mode
`hip4_orderbook`	HIP-4 L2 order book snapshots	Yes	Stored replay only; live bridge paused
`hip4_trades`	HIP-4 trade/fill updates	Yes	Realtime + replay
`hip4_open_interest`	HIP-4 open interest (per side)	Yes	Stored replay only; live bridge paused
`hip4_l4_diffs`	HIP-4 L4 orderbook diffs	Yes	Real-time only
`hip4_l4_orders`	HIP-4 order lifecycle events	Yes	Real-time only

HIP-4 has no funding or liquidation channel. Candle history and current outcome-side OI are available through REST from 2026-05-02; OI updates at ~10s. Stored WebSocket replay is available for HIP-4 order-book and OI history, but their live bridges are paused. HIP-4 mark_price, midPrice, and candle OHLC values are implied probabilities in [0, 1], not USD prices.

HIP-4 coins can be passed in either the bare numeric form ('0', '1') or the canonical #-prefixed form ('#0', '#1'). The SDK URL-encodes # to %23 on the wire so the path survives fetch parsing — pass whichever form is convenient.

ws.onTrades((coin, trades) => {
  console.log(`${coin}: ${trades.length} HIP-4 fills`);
});
ws.subscribeHip4('hip4_trades', '#1');

// Settlement signal — terminal for the coin
ws.onOutcomeSettled((coin, outcomeId, side, value, at) => {
  console.log(`${coin} (outcome ${outcomeId} side ${side}) settled: ${value} at ${at}`);
});

Hyperliquid Spot Channels

Channel	Description	Requires Coin	Mode
`spot_orderbook`	Spot L2 order book snapshots	Yes	Real-time only
`spot_trades`	Spot trade/fill updates	Yes	Real-time only
`spot_l4_diffs`	Spot L4 orderbook diffs	Yes	Real-time only
`spot_l4_orders`	Spot order lifecycle events	Yes	Real-time only
`spot_twap`	Spot TWAP statuses	Yes	Real-time only

Spot symbols are dashed canonical (HYPE-USDC, PURR-USDC). The server resolves the dashed form to wire format internally. Spot has no funding, open interest, or liquidations; candle history is REST-only through client.spot.candles and has no spot_candles WebSocket channel.

ws.onOrderbook((coin, ob) => {
  console.log(`${coin} mid: ${ob.midPrice}`);
});
ws.onTrades((coin, trades) => {
  console.log(`${coin} got ${trades.length} trades`);
});

await ws.connect();
ws.subscribeSpot('orderbook', 'HYPE-USDC');
ws.subscribeSpot('trades', 'HYPE-USDC');

// L4 channels
ws.subscribeSpot('l4_diffs', 'HYPE-USDC');
ws.subscribeSpot('l4_orders', 'HYPE-USDC');

// TWAP statuses
ws.subscribeSpot('twap', 'HYPE-USDC');

Live Liquidations

import { OxArchiveWs } from '@0xarchive/sdk';

const ws = new OxArchiveWs({ apiKey: 'ox_...' });
ws.onLiquidations((channel, coin, fills) => {
  for (const f of fills) {
    console.log(`${channel} ${coin}: ${f.side} ${f.size}@${f.price} liq`);
  }
});
await ws.connect();

ws.subscribeLiquidations('BTC');
ws.subscribeHip3Liquidations('hyna:BTC');

Lighter.xyz Channels

Channel	Description	Requires Coin	Historical Support
`lighter_orderbook`	Lighter L2 order book (reconstructed)	Yes	Yes
`lighter_trades`	Lighter trade/fill updates	Yes	Yes
`lighter_candles`	Lighter OHLCV candle data	Yes	Yes
`lighter_open_interest`	Lighter open interest snapshots	Yes	Replay/stream only
`lighter_funding`	Lighter funding rate snapshots	Yes	Replay/stream only
`lighter_l3_orderbook`	Lighter L3 order-level orderbook	Yes	Yes

Candle Replay/Stream

// Replay candles at 10x speed
ws.replay('candles', 'BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  speed: 10,
  interval: '15m'  // 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
});

// Lighter.xyz candles
ws.replay('lighter_candles', 'BTC', {
  start: Date.now() - 86400000,
  speed: 10,
  interval: '5m'
});

HIP-3 Replay

// Replay HIP-3 orderbook at 50x speed
ws.replay('hip3_orderbook', 'km:US500', {
  start: Date.now() - 3600000,
  end: Date.now(),
  speed: 50,
});

// HIP-3 candles
ws.replay('hip3_candles', 'km:US500', {
  start: Date.now() - 86400000,
  end: Date.now(),
  speed: 100,
  interval: '1h'
});

Multi-Channel Replay

Replay multiple data channels simultaneously with synchronized timing. Data from all channels is interleaved chronologically. Before the timeline begins, replay_snapshot messages provide the initial state for each channel at the start timestamp.

const ws = new OxArchiveWs({ apiKey: 'ox_...' });
await ws.connect();

// Handle initial snapshots (sent before timeline data)
ws.onReplaySnapshot((channel, coin, timestamp, data) => {
  console.log(`Initial ${channel} state at ${new Date(timestamp).toISOString()}`);
  if (channel === 'orderbook') {
    currentOrderbook = data;
  } else if (channel === 'funding') {
    currentFundingRate = data;
  } else if (channel === 'open_interest') {
    currentOI = data;
  }
});

// Handle interleaved historical data
ws.onHistoricalData((coin, timestamp, data) => {
  // The `channel` field on the raw message indicates which channel
  // this data point belongs to
  console.log(`${new Date(timestamp).toISOString()}: data received`);
});

ws.onReplayComplete((channel, coin, count) => {
  console.log(`Replay complete: ${count} records`);
});

// Start multi-channel replay
ws.multiReplay(['orderbook', 'trades', 'funding'], 'BTC', {
  start: Date.now() - 86400000,
  end: Date.now(),
  speed: 10
});

// Playback controls work the same as single-channel
ws.replayPause();
ws.replayResume();
ws.replaySeek(1704067200000);
ws.replayStop();

Channels available for multi-channel replay: All historical channels can be combined in a single multi-channel replay. This includes orderbook, trades, candles, liquidations, open_interest, funding, and their lighter_* and hip3_* variants.

WebSocket Connection States

ws.getState(); // 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
ws.isConnected(); // boolean

Timestamp Formats

The SDK accepts timestamps as Unix milliseconds or Date objects:

// Unix milliseconds (recommended)
client.hyperliquid.orderbook.history('BTC', {
  start: Date.now() - 86400000,
  end: Date.now()
});

// Date objects (converted automatically)
client.hyperliquid.orderbook.history('BTC', {
  start: new Date('2024-01-01'),
  end: new Date('2024-01-02')
});

// WebSocket replay also accepts both
ws.replay('orderbook', 'BTC', {
  start: Date.now() - 3600000,
  end: Date.now(),
  speed: 10
});

Error Handling

import { OxArchive, OxArchiveError } from '@0xarchive/sdk';

try {
  const orderbook = await client.orderbook.get('INVALID');
} catch (error) {
  if (error instanceof OxArchiveError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status Code: ${error.code}`);
    console.error(`Request ID: ${error.requestId}`);
  }
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  OrderBook,
  PriceLevel,
  Trade,
  Candle,
  Instrument,
  LighterInstrument,
  Hip3Instrument,
  LighterGranularity,
  FundingRate,
  OpenInterest,
  Liquidation,
  LiquidationVolume,
  CoinFreshness,
  CoinSummary,
  PriceSnapshot,
  CursorResponse,
  WsOptions,
  WsChannel,
  WsConnectionState,
  WsReplaySnapshot,
  // Orderbook reconstruction
  OrderbookDelta,
  TickData,
  ReconstructedOrderBook,
  ReconstructOptions,
  TickHistoryParams,
} from '@0xarchive/sdk';

// Import reconstructor class
import { OrderBookReconstructor } from '@0xarchive/sdk';

Runtime Validation

Enable Zod schema validation for API responses:

const client = new OxArchive({
  apiKey: '0xa_your_api_key',
  validate: true  // Enable runtime validation
});

When enabled, responses are validated against Zod schemas and throw OxArchiveError with status 422 if validation fails.

Data Catalog

For large-scale data exports (historical order books, trades, and other datasets), use the Data Catalog. It lets you choose markets, datasets, and date ranges, see a live quote, and export zstd-compressed Parquet.

Requirements

Node.js 18+ or modern browsers with fetch and WebSocket support

License

MIT