@0xarchive/sdk 0.8.2 → 0.9.0

package/dist/index.mjs

@@ -12,7 +12,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) {
@@ -217,7 +217,26 @@ var CandleSchema = z.object({
   quoteVolume: z.number().optional(),
   tradeCount: z.number().optional()
 });
-var WsChannelSchema = z.enum(["orderbook", "trades", "candles", "liquidations", "ticker", "all_tickers"]);
+var WsChannelSchema = 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 = z.enum(["connecting", "connected", "disconnected", "reconnecting"]);
 var WsSubscribedSchema = z.object({
   type: z.literal("subscribed"),
@@ -252,17 +271,17 @@ var WsReplayStartedSchema = z.object({
 });
 var WsReplayPausedSchema = z.object({
   type: z.literal("replay_paused"),
-  currentTimestamp: z.number()
+  current_timestamp: z.number()
 });
 var WsReplayResumedSchema = z.object({
   type: z.literal("replay_resumed"),
-  currentTimestamp: z.number()
+  current_timestamp: z.number()
 });
 var WsReplayCompletedSchema = z.object({
   type: z.literal("replay_completed"),
   channel: WsChannelSchema,
   coin: z.string(),
-  snapshotsSent: z.number()
+  snapshots_sent: z.number()
 });
 var WsReplayStoppedSchema = z.object({
   type: z.literal("replay_stopped")
@@ -274,6 +293,13 @@ var WsHistoricalDataSchema = z.object({
   timestamp: z.number(),
   data: z.unknown()
 });
+var WsReplaySnapshotSchema = z.object({
+  type: z.literal("replay_snapshot"),
+  channel: WsChannelSchema,
+  coin: z.string(),
+  timestamp: z.number(),
+  data: z.unknown()
+});
 var WsStreamStartedSchema = z.object({
   type: z.literal("stream_started"),
   channel: WsChannelSchema,
@@ -283,7 +309,7 @@ var WsStreamStartedSchema = z.object({
 });
 var WsStreamProgressSchema = z.object({
   type: z.literal("stream_progress"),
-  snapshotsSent: z.number()
+  snapshots_sent: z.number()
 });
 var TimestampedRecordSchema = z.object({
   timestamp: z.number(),
@@ -299,11 +325,11 @@ var WsStreamCompletedSchema = z.object({
   type: z.literal("stream_completed"),
   channel: WsChannelSchema,
   coin: z.string(),
-  snapshotsSent: z.number()
+  snapshots_sent: z.number()
 });
 var WsStreamStoppedSchema = z.object({
   type: z.literal("stream_stopped"),
-  snapshotsSent: z.number()
+  snapshots_sent: z.number()
 });
 var WsServerMessageSchema = z.discriminatedUnion("type", [
   WsSubscribedSchema,
@@ -316,6 +342,7 @@ var WsServerMessageSchema = z.discriminatedUnion("type", [
   WsReplayResumedSchema,
   WsReplayCompletedSchema,
   WsReplayStoppedSchema,
+  WsReplaySnapshotSchema,
   WsHistoricalDataSchema,
   WsStreamStartedSchema,
   WsStreamProgressSchema,
@@ -334,6 +361,70 @@ var OpenInterestResponseSchema = ApiResponseSchema(OpenInterestSchema);
 var OpenInterestArrayResponseSchema = ApiResponseSchema(z.array(OpenInterestSchema));
 var CandleArrayResponseSchema = ApiResponseSchema(z.array(CandleSchema));
 var LiquidationArrayResponseSchema = ApiResponseSchema(z.array(LiquidationSchema));
+var LiquidationVolumeSchema = z.object({
+  coin: z.string(),
+  timestamp: z.string(),
+  totalUsd: z.number(),
+  longUsd: z.number(),
+  shortUsd: z.number(),
+  count: z.number(),
+  longCount: z.number(),
+  shortCount: z.number()
+});
+var LiquidationVolumeArrayResponseSchema = z.object({
+  success: z.boolean().optional(),
+  data: z.array(LiquidationVolumeSchema),
+  meta: ApiMetaSchema.optional()
+});
+var DataTypeFreshnessInfoSchema = z.object({
+  lastUpdated: z.string().nullable().optional(),
+  lagMs: z.number().nullable().optional()
+});
+var CoinFreshnessSchema = z.object({
+  coin: z.string(),
+  exchange: z.string(),
+  measuredAt: z.string(),
+  orderbook: DataTypeFreshnessInfoSchema,
+  trades: DataTypeFreshnessInfoSchema,
+  funding: DataTypeFreshnessInfoSchema,
+  openInterest: DataTypeFreshnessInfoSchema,
+  liquidations: DataTypeFreshnessInfoSchema.optional()
+});
+var CoinFreshnessResponseSchema = z.object({
+  success: z.boolean().optional(),
+  data: CoinFreshnessSchema,
+  meta: ApiMetaSchema.optional()
+});
+var CoinSummarySchema = z.object({
+  coin: z.string(),
+  timestamp: z.string(),
+  markPrice: z.string().nullable().optional(),
+  oraclePrice: z.string().nullable().optional(),
+  midPrice: z.string().nullable().optional(),
+  fundingRate: z.string().nullable().optional(),
+  premium: z.string().nullable().optional(),
+  openInterest: z.string().nullable().optional(),
+  volume24h: z.string().nullable().optional(),
+  liquidationVolume24h: z.number().nullable().optional(),
+  longLiquidationVolume24h: z.number().nullable().optional(),
+  shortLiquidationVolume24h: z.number().nullable().optional()
+});
+var CoinSummaryResponseSchema = z.object({
+  success: z.boolean().optional(),
+  data: CoinSummarySchema,
+  meta: ApiMetaSchema.optional()
+});
+var PriceSnapshotSchema = z.object({
+  timestamp: z.string(),
+  markPrice: z.string().nullable().optional(),
+  oraclePrice: z.string().nullable().optional(),
+  midPrice: z.string().nullable().optional()
+});
+var PriceSnapshotArrayResponseSchema = z.object({
+  success: z.boolean().optional(),
+  data: z.array(PriceSnapshotSchema),
+  meta: ApiMetaSchema.optional()
+});
 
 // src/orderbook-reconstructor.ts
 var OrderBookReconstructor = class {
@@ -1077,6 +1168,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
@@ -1181,7 +1293,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
     );
   }
@@ -1308,7 +1420,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);
@@ -1319,6 +1433,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 {
   /**
@@ -1546,6 +1706,7 @@ var OxArchiveWs = class {
   batchHandlers = [];
   replayStartHandlers = [];
   replayCompleteHandlers = [];
+  replaySnapshotHandlers = [];
   streamStartHandlers = [];
   streamProgressHandlers = [];
   streamCompleteHandlers = [];
@@ -1726,6 +1887,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
    */
@@ -1782,6 +1978,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
    */
@@ -1823,6 +2056,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
    */
@@ -1981,6 +2237,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) {
@@ -2032,6 +2295,11 @@ export {
   CandleArrayResponseSchema,
   CandleIntervalSchema,
   CandleSchema,
+  CoinFreshnessResponseSchema,
+  CoinFreshnessSchema,
+  CoinSummaryResponseSchema,
+  CoinSummarySchema,
+  DataTypeFreshnessInfoSchema,
   FundingRateArrayResponseSchema,
   FundingRateResponseSchema,
   FundingRateSchema,
@@ -2045,6 +2313,8 @@ export {
   LiquidationArrayResponseSchema,
   LiquidationSchema,
   LiquidationSideSchema,
+  LiquidationVolumeArrayResponseSchema,
+  LiquidationVolumeSchema,
   OpenInterestArrayResponseSchema,
   OpenInterestResponseSchema,
   OpenInterestSchema,
@@ -2056,6 +2326,8 @@ export {
   OxArchiveError,
   OxArchiveWs,
   PriceLevelSchema,
+  PriceSnapshotArrayResponseSchema,
+  PriceSnapshotSchema,
   TimestampedRecordSchema,
   TradeArrayResponseSchema,
   TradeDirectionSchema,
@@ -2071,6 +2343,7 @@ export {
   WsReplayCompletedSchema,
   WsReplayPausedSchema,
   WsReplayResumedSchema,
+  WsReplaySnapshotSchema,
   WsReplayStartedSchema,
   WsReplayStoppedSchema,
   WsServerMessageSchema,