@0xarchive/sdk 0.8.3 → 0.9.1

package/dist/index.js

@@ -25,6 +25,11 @@ __export(index_exports, {
   CandleArrayResponseSchema: () => CandleArrayResponseSchema,
   CandleIntervalSchema: () => CandleIntervalSchema,
   CandleSchema: () => CandleSchema,
+  CoinFreshnessResponseSchema: () => CoinFreshnessResponseSchema,
+  CoinFreshnessSchema: () => CoinFreshnessSchema,
+  CoinSummaryResponseSchema: () => CoinSummaryResponseSchema,
+  CoinSummarySchema: () => CoinSummarySchema,
+  DataTypeFreshnessInfoSchema: () => DataTypeFreshnessInfoSchema,
   FundingRateArrayResponseSchema: () => FundingRateArrayResponseSchema,
   FundingRateResponseSchema: () => FundingRateResponseSchema,
   FundingRateSchema: () => FundingRateSchema,
@@ -38,6 +43,8 @@ __export(index_exports, {
   LiquidationArrayResponseSchema: () => LiquidationArrayResponseSchema,
   LiquidationSchema: () => LiquidationSchema,
   LiquidationSideSchema: () => LiquidationSideSchema,
+  LiquidationVolumeArrayResponseSchema: () => LiquidationVolumeArrayResponseSchema,
+  LiquidationVolumeSchema: () => LiquidationVolumeSchema,
   OpenInterestArrayResponseSchema: () => OpenInterestArrayResponseSchema,
   OpenInterestResponseSchema: () => OpenInterestResponseSchema,
   OpenInterestSchema: () => OpenInterestSchema,
@@ -49,6 +56,8 @@ __export(index_exports, {
   OxArchiveError: () => OxArchiveError,
   OxArchiveWs: () => OxArchiveWs,
   PriceLevelSchema: () => PriceLevelSchema,
+  PriceSnapshotArrayResponseSchema: () => PriceSnapshotArrayResponseSchema,
+  PriceSnapshotSchema: () => PriceSnapshotSchema,
   TimestampedRecordSchema: () => TimestampedRecordSchema,
   TradeArrayResponseSchema: () => TradeArrayResponseSchema,
   TradeDirectionSchema: () => TradeDirectionSchema,
@@ -64,6 +73,7 @@ __export(index_exports, {
   WsReplayCompletedSchema: () => WsReplayCompletedSchema,
   WsReplayPausedSchema: () => WsReplayPausedSchema,
   WsReplayResumedSchema: () => WsReplayResumedSchema,
+  WsReplaySnapshotSchema: () => WsReplaySnapshotSchema,
   WsReplayStartedSchema: () => WsReplayStartedSchema,
   WsReplayStoppedSchema: () => WsReplayStoppedSchema,
   WsServerMessageSchema: () => WsServerMessageSchema,
@@ -93,7 +103,7 @@ var OxArchiveError = class extends Error {
 
 // src/http.ts
 function snakeToCamel(str) {
-  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+  return str.replace(/_([a-z0-9])/g, (_, char) => char.toUpperCase());
 }
 function transformKeys(obj) {
   if (obj === null || obj === void 0) {
@@ -298,7 +308,26 @@ var CandleSchema = import_zod.z.object({
   quoteVolume: import_zod.z.number().optional(),
   tradeCount: import_zod.z.number().optional()
 });
-var WsChannelSchema = import_zod.z.enum(["orderbook", "trades", "candles", "liquidations", "ticker", "all_tickers"]);
+var WsChannelSchema = import_zod.z.enum([
+  "orderbook",
+  "trades",
+  "candles",
+  "liquidations",
+  "ticker",
+  "all_tickers",
+  "open_interest",
+  "funding",
+  "lighter_orderbook",
+  "lighter_trades",
+  "lighter_candles",
+  "lighter_open_interest",
+  "lighter_funding",
+  "hip3_orderbook",
+  "hip3_trades",
+  "hip3_candles",
+  "hip3_open_interest",
+  "hip3_funding"
+]);
 var WsConnectionStateSchema = import_zod.z.enum(["connecting", "connected", "disconnected", "reconnecting"]);
 var WsSubscribedSchema = import_zod.z.object({
   type: import_zod.z.literal("subscribed"),
@@ -333,17 +362,17 @@ var WsReplayStartedSchema = import_zod.z.object({
 });
 var WsReplayPausedSchema = import_zod.z.object({
   type: import_zod.z.literal("replay_paused"),
-  currentTimestamp: import_zod.z.number()
+  current_timestamp: import_zod.z.number()
 });
 var WsReplayResumedSchema = import_zod.z.object({
   type: import_zod.z.literal("replay_resumed"),
-  currentTimestamp: import_zod.z.number()
+  current_timestamp: import_zod.z.number()
 });
 var WsReplayCompletedSchema = import_zod.z.object({
   type: import_zod.z.literal("replay_completed"),
   channel: WsChannelSchema,
   coin: import_zod.z.string(),
-  snapshotsSent: import_zod.z.number()
+  snapshots_sent: import_zod.z.number()
 });
 var WsReplayStoppedSchema = import_zod.z.object({
   type: import_zod.z.literal("replay_stopped")
@@ -355,6 +384,13 @@ var WsHistoricalDataSchema = import_zod.z.object({
   timestamp: import_zod.z.number(),
   data: import_zod.z.unknown()
 });
+var WsReplaySnapshotSchema = import_zod.z.object({
+  type: import_zod.z.literal("replay_snapshot"),
+  channel: WsChannelSchema,
+  coin: import_zod.z.string(),
+  timestamp: import_zod.z.number(),
+  data: import_zod.z.unknown()
+});
 var WsStreamStartedSchema = import_zod.z.object({
   type: import_zod.z.literal("stream_started"),
   channel: WsChannelSchema,
@@ -364,7 +400,7 @@ var WsStreamStartedSchema = import_zod.z.object({
 });
 var WsStreamProgressSchema = import_zod.z.object({
   type: import_zod.z.literal("stream_progress"),
-  snapshotsSent: import_zod.z.number()
+  snapshots_sent: import_zod.z.number()
 });
 var TimestampedRecordSchema = import_zod.z.object({
   timestamp: import_zod.z.number(),
@@ -380,11 +416,11 @@ var WsStreamCompletedSchema = import_zod.z.object({
   type: import_zod.z.literal("stream_completed"),
   channel: WsChannelSchema,
   coin: import_zod.z.string(),
-  snapshotsSent: import_zod.z.number()
+  snapshots_sent: import_zod.z.number()
 });
 var WsStreamStoppedSchema = import_zod.z.object({
   type: import_zod.z.literal("stream_stopped"),
-  snapshotsSent: import_zod.z.number()
+  snapshots_sent: import_zod.z.number()
 });
 var WsServerMessageSchema = import_zod.z.discriminatedUnion("type", [
   WsSubscribedSchema,
@@ -397,6 +433,7 @@ var WsServerMessageSchema = import_zod.z.discriminatedUnion("type", [
   WsReplayResumedSchema,
   WsReplayCompletedSchema,
   WsReplayStoppedSchema,
+  WsReplaySnapshotSchema,
   WsHistoricalDataSchema,
   WsStreamStartedSchema,
   WsStreamProgressSchema,
@@ -415,6 +452,70 @@ var OpenInterestResponseSchema = ApiResponseSchema(OpenInterestSchema);
 var OpenInterestArrayResponseSchema = ApiResponseSchema(import_zod.z.array(OpenInterestSchema));
 var CandleArrayResponseSchema = ApiResponseSchema(import_zod.z.array(CandleSchema));
 var LiquidationArrayResponseSchema = ApiResponseSchema(import_zod.z.array(LiquidationSchema));
+var LiquidationVolumeSchema = import_zod.z.object({
+  coin: import_zod.z.string(),
+  timestamp: import_zod.z.string(),
+  totalUsd: import_zod.z.number(),
+  longUsd: import_zod.z.number(),
+  shortUsd: import_zod.z.number(),
+  count: import_zod.z.number(),
+  longCount: import_zod.z.number(),
+  shortCount: import_zod.z.number()
+});
+var LiquidationVolumeArrayResponseSchema = import_zod.z.object({
+  success: import_zod.z.boolean().optional(),
+  data: import_zod.z.array(LiquidationVolumeSchema),
+  meta: ApiMetaSchema.optional()
+});
+var DataTypeFreshnessInfoSchema = import_zod.z.object({
+  lastUpdated: import_zod.z.string().nullable().optional(),
+  lagMs: import_zod.z.number().nullable().optional()
+});
+var CoinFreshnessSchema = import_zod.z.object({
+  coin: import_zod.z.string(),
+  exchange: import_zod.z.string(),
+  measuredAt: import_zod.z.string(),
+  orderbook: DataTypeFreshnessInfoSchema,
+  trades: DataTypeFreshnessInfoSchema,
+  funding: DataTypeFreshnessInfoSchema,
+  openInterest: DataTypeFreshnessInfoSchema,
+  liquidations: DataTypeFreshnessInfoSchema.optional()
+});
+var CoinFreshnessResponseSchema = import_zod.z.object({
+  success: import_zod.z.boolean().optional(),
+  data: CoinFreshnessSchema,
+  meta: ApiMetaSchema.optional()
+});
+var CoinSummarySchema = import_zod.z.object({
+  coin: import_zod.z.string(),
+  timestamp: import_zod.z.string(),
+  markPrice: import_zod.z.string().nullable().optional(),
+  oraclePrice: import_zod.z.string().nullable().optional(),
+  midPrice: import_zod.z.string().nullable().optional(),
+  fundingRate: import_zod.z.string().nullable().optional(),
+  premium: import_zod.z.string().nullable().optional(),
+  openInterest: import_zod.z.string().nullable().optional(),
+  volume24h: import_zod.z.string().nullable().optional(),
+  liquidationVolume24h: import_zod.z.number().nullable().optional(),
+  longLiquidationVolume24h: import_zod.z.number().nullable().optional(),
+  shortLiquidationVolume24h: import_zod.z.number().nullable().optional()
+});
+var CoinSummaryResponseSchema = import_zod.z.object({
+  success: import_zod.z.boolean().optional(),
+  data: CoinSummarySchema,
+  meta: ApiMetaSchema.optional()
+});
+var PriceSnapshotSchema = import_zod.z.object({
+  timestamp: import_zod.z.string(),
+  markPrice: import_zod.z.string().nullable().optional(),
+  oraclePrice: import_zod.z.string().nullable().optional(),
+  midPrice: import_zod.z.string().nullable().optional()
+});
+var PriceSnapshotArrayResponseSchema = import_zod.z.object({
+  success: import_zod.z.boolean().optional(),
+  data: import_zod.z.array(PriceSnapshotSchema),
+  meta: ApiMetaSchema.optional()
+});
 
 // src/orderbook-reconstructor.ts
 var OrderBookReconstructor = class {
@@ -1158,6 +1259,27 @@ var LiquidationsResource = class {
       nextCursor: response.meta.nextCursor
     };
   }
+  /**
+   * Get aggregated liquidation volume in time-bucketed intervals
+   *
+   * Returns pre-aggregated data with total/long/short USD volumes per bucket,
+   * reducing data transfer by 100-1000x compared to individual liquidation records.
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @param params - Time range, cursor, and interval parameters
+   * @returns CursorResponse with liquidation volume buckets
+   */
+  async volume(coin, params) {
+    const response = await this.http.get(
+      `${this.basePath}/liquidations/${coin.toUpperCase()}/volume`,
+      params,
+      this.http.validationEnabled ? LiquidationVolumeArrayResponseSchema : void 0
+    );
+    return {
+      data: response.data,
+      nextCursor: response.meta.nextCursor
+    };
+  }
 };
 
 // src/resources/data-quality.ts
@@ -1262,7 +1384,7 @@ var DataQualityResource = class {
    */
   async symbolCoverage(exchange, symbol, options) {
     return this.http.get(
-      `${this.basePath}/coverage/${exchange.toLowerCase()}/${symbol.toUpperCase()}`,
+      `${this.basePath}/coverage/${exchange.toLowerCase()}/${symbol}`,
       options
     );
   }
@@ -1389,7 +1511,9 @@ var HyperliquidClient = class {
    * HIP-3 builder-deployed perpetuals (February 2026+)
    */
   hip3;
+  http;
   constructor(http) {
+    this.http = http;
     const basePath = "/v1/hyperliquid";
     this.orderbook = new OrderBookResource(http, basePath);
     this.trades = new TradesResource(http, basePath);
@@ -1400,6 +1524,52 @@ var HyperliquidClient = class {
     this.liquidations = new LiquidationsResource(http, basePath);
     this.hip3 = new Hip3Client(http);
   }
+  /**
+   * Get per-coin data freshness across all data types
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @returns Per-coin freshness with last_updated and lag_ms for each data type
+   */
+  async freshness(coin) {
+    const response = await this.http.get(
+      `/v1/hyperliquid/freshness/${coin.toUpperCase()}`,
+      void 0,
+      this.http.validationEnabled ? CoinFreshnessResponseSchema : void 0
+    );
+    return response.data;
+  }
+  /**
+   * Get combined market summary (price, funding, OI, volume, liquidations) in one call
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @returns Combined market summary
+   */
+  async summary(coin) {
+    const response = await this.http.get(
+      `/v1/hyperliquid/summary/${coin.toUpperCase()}`,
+      void 0,
+      this.http.validationEnabled ? CoinSummaryResponseSchema : void 0
+    );
+    return response.data;
+  }
+  /**
+   * Get mark/oracle/mid price history (projected from OI data)
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @param params - Time range, cursor, and interval parameters
+   * @returns CursorResponse with price snapshots
+   */
+  async priceHistory(coin, params) {
+    const response = await this.http.get(
+      `/v1/hyperliquid/prices/${coin.toUpperCase()}`,
+      params,
+      this.http.validationEnabled ? PriceSnapshotArrayResponseSchema : void 0
+    );
+    return {
+      data: response.data,
+      nextCursor: response.meta.nextCursor
+    };
+  }
 };
 var Hip3Client = class {
   /**
@@ -1426,7 +1596,9 @@ var Hip3Client = class {
    * OHLCV candle data
    */
   candles;
+  http;
   constructor(http) {
+    this.http = http;
     const basePath = "/v1/hyperliquid/hip3";
     const coinTransform = (c) => c;
     this.instruments = new Hip3InstrumentsResource(http, basePath, coinTransform);
@@ -1436,6 +1608,52 @@ var Hip3Client = class {
     this.openInterest = new OpenInterestResource(http, basePath, coinTransform);
     this.candles = new CandlesResource(http, basePath, coinTransform);
   }
+  /**
+   * Get per-coin data freshness across all data types
+   *
+   * @param coin - The coin symbol (case-sensitive, e.g., 'km:US500')
+   * @returns Per-coin freshness with last_updated and lag_ms for each data type
+   */
+  async freshness(coin) {
+    const response = await this.http.get(
+      `/v1/hyperliquid/hip3/freshness/${coin}`,
+      void 0,
+      this.http.validationEnabled ? CoinFreshnessResponseSchema : void 0
+    );
+    return response.data;
+  }
+  /**
+   * Get combined market summary (price, funding, OI) in one call
+   *
+   * @param coin - The coin symbol (case-sensitive, e.g., 'km:US500')
+   * @returns Combined market summary
+   */
+  async summary(coin) {
+    const response = await this.http.get(
+      `/v1/hyperliquid/hip3/summary/${coin}`,
+      void 0,
+      this.http.validationEnabled ? CoinSummaryResponseSchema : void 0
+    );
+    return response.data;
+  }
+  /**
+   * Get mark/oracle/mid price history (projected from OI data)
+   *
+   * @param coin - The coin symbol (case-sensitive, e.g., 'km:US500')
+   * @param params - Time range, cursor, and interval parameters
+   * @returns CursorResponse with price snapshots
+   */
+  async priceHistory(coin, params) {
+    const response = await this.http.get(
+      `/v1/hyperliquid/hip3/prices/${coin}`,
+      params,
+      this.http.validationEnabled ? PriceSnapshotArrayResponseSchema : void 0
+    );
+    return {
+      data: response.data,
+      nextCursor: response.meta.nextCursor
+    };
+  }
 };
 var LighterClient = class {
   /**
@@ -1462,7 +1680,9 @@ var LighterClient = class {
    * OHLCV candle data
    */
   candles;
+  http;
   constructor(http) {
+    this.http = http;
     const basePath = "/v1/lighter";
     this.orderbook = new OrderBookResource(http, basePath);
     this.trades = new TradesResource(http, basePath);
@@ -1471,6 +1691,52 @@ var LighterClient = class {
     this.openInterest = new OpenInterestResource(http, basePath);
     this.candles = new CandlesResource(http, basePath);
   }
+  /**
+   * Get per-coin data freshness across all data types
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @returns Per-coin freshness with last_updated and lag_ms for each data type
+   */
+  async freshness(coin) {
+    const response = await this.http.get(
+      `/v1/lighter/freshness/${coin.toUpperCase()}`,
+      void 0,
+      this.http.validationEnabled ? CoinFreshnessResponseSchema : void 0
+    );
+    return response.data;
+  }
+  /**
+   * Get combined market summary (price, funding, OI) in one call
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @returns Combined market summary
+   */
+  async summary(coin) {
+    const response = await this.http.get(
+      `/v1/lighter/summary/${coin.toUpperCase()}`,
+      void 0,
+      this.http.validationEnabled ? CoinSummaryResponseSchema : void 0
+    );
+    return response.data;
+  }
+  /**
+   * Get mark/oracle price history (projected from OI data)
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @param params - Time range, cursor, and interval parameters
+   * @returns CursorResponse with price snapshots
+   */
+  async priceHistory(coin, params) {
+    const response = await this.http.get(
+      `/v1/lighter/prices/${coin.toUpperCase()}`,
+      params,
+      this.http.validationEnabled ? PriceSnapshotArrayResponseSchema : void 0
+    );
+    return {
+      data: response.data,
+      nextCursor: response.meta.nextCursor
+    };
+  }
 };
 
 // src/client.ts
@@ -1627,6 +1893,7 @@ var OxArchiveWs = class {
   batchHandlers = [];
   replayStartHandlers = [];
   replayCompleteHandlers = [];
+  replaySnapshotHandlers = [];
   streamStartHandlers = [];
   streamProgressHandlers = [];
   streamCompleteHandlers = [];
@@ -1807,6 +2074,41 @@ var OxArchiveWs = class {
       interval: options.interval
     });
   }
+  /**
+   * Start a multi-channel historical replay with timing preserved.
+   * Data from all channels is interleaved chronologically. Before the timeline
+   * begins, `replay_snapshot` messages provide initial state for each channel.
+   *
+   * @param channels - Array of data channels to replay simultaneously
+   * @param coin - Trading pair (e.g., 'BTC', 'ETH')
+   * @param options - Replay options
+   *
+   * @example
+   * ```typescript
+   * ws.onReplaySnapshot((channel, coin, timestamp, data) => {
+   *   console.log(`Initial ${channel} state at ${new Date(timestamp).toISOString()}`);
+   * });
+   * ws.onHistoricalData((coin, timestamp, data) => {
+   *   // Interleaved data from all channels
+   * });
+   * ws.multiReplay(['orderbook', 'trades', 'funding'], 'BTC', {
+   *   start: Date.now() - 86400000,
+   *   speed: 10
+   * });
+   * ```
+   */
+  multiReplay(channels, coin, options) {
+    this.send({
+      op: "replay",
+      channels,
+      coin,
+      start: options.start,
+      end: options.end,
+      speed: options.speed ?? 1,
+      granularity: options.granularity,
+      interval: options.interval
+    });
+  }
   /**
    * Pause the current replay
    */
@@ -1863,6 +2165,43 @@ var OxArchiveWs = class {
       interval: options.interval
     });
   }
+  /**
+   * Start a multi-channel bulk stream for fast data download.
+   * Data from all channels arrives in batches without timing delays.
+   * Before batches begin, `replay_snapshot` messages provide initial state
+   * for each channel.
+   *
+   * @param channels - Array of data channels to stream simultaneously
+   * @param coin - Trading pair (e.g., 'BTC', 'ETH')
+   * @param options - Stream options
+   *
+   * @example
+   * ```typescript
+   * ws.onReplaySnapshot((channel, coin, timestamp, data) => {
+   *   console.log(`Initial ${channel} state`);
+   * });
+   * ws.onBatch((coin, records) => {
+   *   // Batches contain data from all requested channels
+   * });
+   * ws.multiStream(['orderbook', 'trades', 'open_interest'], 'BTC', {
+   *   start: Date.now() - 3600000,
+   *   end: Date.now(),
+   *   batchSize: 1000
+   * });
+   * ```
+   */
+  multiStream(channels, coin, options) {
+    this.send({
+      op: "stream",
+      channels,
+      coin,
+      start: options.start,
+      end: options.end,
+      batch_size: options.batchSize ?? 1e3,
+      granularity: options.granularity,
+      interval: options.interval
+    });
+  }
   /**
    * Stop the current bulk stream
    */
@@ -1904,6 +2243,29 @@ var OxArchiveWs = class {
   onReplayComplete(handler) {
     this.replayCompleteHandlers.push(handler);
   }
+  /**
+   * Handle replay snapshot events (multi-channel mode).
+   * Called with the initial state for each channel before the replay/stream
+   * timeline begins. Use this to initialize local state (e.g., set the current
+   * orderbook or latest funding rate) before `historical_data` messages start
+   * arriving.
+   *
+   * @param handler - Callback receiving channel, coin, timestamp (ms), and data payload
+   *
+   * @example
+   * ```typescript
+   * ws.onReplaySnapshot((channel, coin, timestamp, data) => {
+   *   if (channel === 'orderbook') {
+   *     currentOrderbook = data;
+   *   } else if (channel === 'funding') {
+   *     currentFundingRate = data;
+   *   }
+   * });
+   * ```
+   */
+  onReplaySnapshot(handler) {
+    this.replaySnapshotHandlers.push(handler);
+  }
   /**
    * Handle stream started event
    */
@@ -2062,6 +2424,13 @@ var OxArchiveWs = class {
         }
         break;
       }
+      case "replay_snapshot": {
+        const msg = message;
+        for (const handler of this.replaySnapshotHandlers) {
+          handler(msg.channel, msg.coin, msg.timestamp, msg.data);
+        }
+        break;
+      }
       case "stream_started": {
         const msg = message;
         for (const handler of this.streamStartHandlers) {
@@ -2114,6 +2483,11 @@ var OxArchiveWs = class {
   CandleArrayResponseSchema,
   CandleIntervalSchema,
   CandleSchema,
+  CoinFreshnessResponseSchema,
+  CoinFreshnessSchema,
+  CoinSummaryResponseSchema,
+  CoinSummarySchema,
+  DataTypeFreshnessInfoSchema,
   FundingRateArrayResponseSchema,
   FundingRateResponseSchema,
   FundingRateSchema,
@@ -2127,6 +2501,8 @@ var OxArchiveWs = class {
   LiquidationArrayResponseSchema,
   LiquidationSchema,
   LiquidationSideSchema,
+  LiquidationVolumeArrayResponseSchema,
+  LiquidationVolumeSchema,
   OpenInterestArrayResponseSchema,
   OpenInterestResponseSchema,
   OpenInterestSchema,
@@ -2138,6 +2514,8 @@ var OxArchiveWs = class {
   OxArchiveError,
   OxArchiveWs,
   PriceLevelSchema,
+  PriceSnapshotArrayResponseSchema,
+  PriceSnapshotSchema,
   TimestampedRecordSchema,
   TradeArrayResponseSchema,
   TradeDirectionSchema,
@@ -2153,6 +2531,7 @@ var OxArchiveWs = class {
   WsReplayCompletedSchema,
   WsReplayPausedSchema,
   WsReplayResumedSchema,
+  WsReplaySnapshotSchema,
   WsReplayStartedSchema,
   WsReplayStoppedSchema,
   WsServerMessageSchema,