@0xarchive/sdk 0.8.3 → 0.9.1

package/README.md

@@ -303,8 +303,25 @@ 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, raw ~1 min data is returned. |
+
 ### Open Interest
 
 ```typescript
@@ -317,8 +334,25 @@ const history = await client.hyperliquid.openInterest.history('ETH', {
   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, raw ~1 min data is returned. |
+
 ### Liquidations (Hyperliquid only)
 
 Get historical liquidation events. Data available from May 2025 onwards.
@@ -351,6 +385,114 @@ const userLiquidations = await client.hyperliquid.liquidations.byUser('0x1234...
 });
 ```
 
+### Liquidation Volume (Hyperliquid only)
+
+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.
+
+```typescript
+// Get hourly liquidation volume for the last week
+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}`);
+}
+```
+
+### Freshness (Hyperliquid only)
+
+Check when each data type was last updated for a specific coin. Useful for verifying data recency before pulling it.
+
+```typescript
+// 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.
+
+```typescript
+// 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.
+
+```typescript
+// Hyperliquid — available from May 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.
@@ -691,6 +833,8 @@ const ws = new OxArchiveWs({
 | `trades` | Trade/fill updates | Yes | Yes |
 | `candles` | OHLCV candle data | Yes | Yes (replay/stream only) |
 | `liquidations` | Liquidation events (May 2025+) | Yes | Yes (replay/stream only) |
+| `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 |
 
@@ -701,6 +845,8 @@ const ws = new OxArchiveWs({
 | `hip3_orderbook` | HIP-3 L2 order book snapshots | Yes | Yes |
 | `hip3_trades` | HIP-3 trade/fill updates | Yes | Yes |
 | `hip3_candles` | HIP-3 OHLCV candle data | Yes | Yes |
+| `hip3_open_interest` | HIP-3 open interest snapshots | Yes | Replay/stream only |
+| `hip3_funding` | HIP-3 funding rate snapshots | Yes | Replay/stream only |
 
 > **Note:** HIP-3 coins are case-sensitive (e.g., `km:US500`, `xyz:XYZ100`). Do not uppercase them.
 
@@ -711,6 +857,8 @@ const ws = new OxArchiveWs({
 | `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 |
 
 #### Candle Replay/Stream
 
@@ -765,6 +913,88 @@ ws.replay('hip3_candles', 'km:US500', {
 });
 ```
 
+### 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.
+
+```typescript
+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();
+```
+
+### Multi-Channel Bulk Stream
+
+Stream multiple channels simultaneously for fast bulk download.
+
+```typescript
+const ws = new OxArchiveWs({ apiKey: 'ox_...' });
+await ws.connect();
+
+// Handle initial snapshots
+ws.onReplaySnapshot((channel, coin, timestamp, data) => {
+  console.log(`Initial ${channel} snapshot`);
+});
+
+// Handle batched data from all channels
+ws.onBatch((coin, records) => {
+  for (const record of records) {
+    // Process interleaved data from all channels
+  }
+});
+
+ws.onStreamComplete((channel, coin, count) => {
+  console.log(`Stream complete: ${count} records`);
+});
+
+// Start multi-channel stream
+ws.multiStream(['orderbook', 'trades', 'open_interest', 'funding'], 'ETH', {
+  start: Date.now() - 3600000,
+  end: Date.now(),
+  batchSize: 1000
+});
+
+// Stop if needed
+ws.streamStop();
+```
+
+**Channels available for multi-channel mode:** All historical channels can be combined in a single multi-channel replay or stream. This includes `orderbook`, `trades`, `candles`, `liquidations`, `open_interest`, `funding`, and their `lighter_*` and `hip3_*` variants.
+
 ### WebSocket Connection States
 
 ```typescript
@@ -830,10 +1060,15 @@ import type {
   FundingRate,
   OpenInterest,
   Liquidation,
+  LiquidationVolume,
+  CoinFreshness,
+  CoinSummary,
+  PriceSnapshot,
   CursorResponse,
   WsOptions,
   WsChannel,
   WsConnectionState,
+  WsReplaySnapshot,
   // Orderbook reconstruction (Enterprise)
   OrderbookDelta,
   TickData,