@0xarchive/sdk 0.4.3 → 0.4.5

package/README.md

@@ -77,6 +77,19 @@ const history = await client.hyperliquid.orderbook.history('BTC', {
 });
 ```
 
+#### Orderbook Depth Limits
+
+The `depth` parameter controls how many price levels are returned per side. Tier-based limits apply:
+
+| Tier | Max Depth |
+|------|-----------|
+| Free | 20 |
+| Build | 50 |
+| Pro | 100 |
+| Enterprise | Full Depth |
+
+**Note:** Hyperliquid source data only contains 20 levels. Higher limits apply to Lighter.xyz data.
+
 #### Lighter Orderbook Granularity
 
 Lighter.xyz orderbook history supports a `granularity` parameter for different data resolutions. Tier restrictions apply.
@@ -292,6 +305,20 @@ ws.replay('orderbook', 'BTC', {
   speed: 10                       // Optional, defaults to 1x
 });
 
+// Lighter.xyz replay with granularity (tier restrictions apply)
+ws.replay('orderbook', 'BTC', {
+  start: Date.now() - 86400000,
+  speed: 10,
+  granularity: '10s'  // Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+});
+
+// Handle tick-level data (granularity='tick', Enterprise tier)
+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();
@@ -329,6 +356,13 @@ ws.stream('orderbook', 'ETH', {
   batchSize: 1000               // Optional, defaults to 1000
 });
 
+// Lighter.xyz stream with granularity (tier restrictions apply)
+ws.stream('orderbook', 'BTC', {
+  start: Date.now() - 3600000,
+  end: Date.now(),
+  granularity: '10s'  // Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+});
+
 // Stop if needed
 ws.streamStop();
 ```

package/dist/index.d.mts

@@ -293,6 +293,8 @@ interface WsReplay {
     end?: number;
     /** Playback speed multiplier (1 = real-time, 10 = 10x faster) */
     speed?: number;
+    /** Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick') */
+    granularity?: string;
 }
 /** Replay control messages */
 interface WsReplayPause {
@@ -319,6 +321,8 @@ interface WsStream {
     end: number;
     /** Batch size (records per message) */
     batch_size?: number;
+    /** Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick') */
+    granularity?: string;
 }
 /** Stream control messages */
 interface WsStreamStop {
@@ -395,6 +399,29 @@ interface WsHistoricalData<T = unknown> {
     timestamp: number;
     data: T;
 }
+/** Orderbook delta for tick-level data */
+interface OrderbookDelta {
+    /** Timestamp in milliseconds */
+    timestamp: number;
+    /** Side: 'bid' or 'ask' */
+    side: 'bid' | 'ask';
+    /** Price level */
+    price: number;
+    /** New size (0 = level removed) */
+    size: number;
+    /** Sequence number for ordering */
+    sequence: number;
+}
+/** Historical tick data (granularity='tick' mode) - checkpoint + deltas */
+interface WsHistoricalTickData {
+    type: 'historical_tick_data';
+    channel: WsChannel;
+    coin: string;
+    /** Initial checkpoint (full orderbook snapshot) */
+    checkpoint: OrderBook;
+    /** Incremental deltas to apply after checkpoint */
+    deltas: OrderbookDelta[];
+}
 /** Stream started response */
 interface WsStreamStarted {
     type: 'stream_started';
@@ -435,7 +462,7 @@ interface WsStreamStopped {
     snapshots_sent: number;
 }
 /** Server message union type */
-type WsServerMessage = WsSubscribed | WsUnsubscribed | WsPong | WsError | WsData | WsReplayStarted | WsReplayPaused | WsReplayResumed | WsReplayCompleted | WsReplayStopped | WsHistoricalData | WsStreamStarted | WsStreamProgress | WsHistoricalBatch | WsStreamCompleted | WsStreamStopped;
+type WsServerMessage = WsSubscribed | WsUnsubscribed | WsPong | WsError | WsData | WsReplayStarted | WsReplayPaused | WsReplayResumed | WsReplayCompleted | WsReplayStopped | WsHistoricalData | WsHistoricalTickData | WsStreamStarted | WsStreamProgress | WsHistoricalBatch | WsStreamCompleted | WsStreamStopped;
 /**
  * WebSocket connection options.
  *
@@ -1023,6 +1050,7 @@ declare class OxArchiveWs {
     private pingTimer;
     private reconnectTimer;
     private historicalDataHandlers;
+    private historicalTickDataHandlers;
     private batchHandlers;
     private replayStartHandlers;
     private replayCompleteHandlers;
@@ -1106,6 +1134,7 @@ declare class OxArchiveWs {
         start: number;
         end?: number;
         speed?: number;
+        granularity?: string;
     }): void;
     /**
      * Pause the current replay
@@ -1144,6 +1173,7 @@ declare class OxArchiveWs {
         start: number;
         end: number;
         batchSize?: number;
+        granularity?: string;
     }): void;
     /**
      * Stop the current bulk stream
@@ -1153,6 +1183,12 @@ declare class OxArchiveWs {
      * Handle historical data points (replay mode)
      */
     onHistoricalData<T = unknown>(handler: (coin: string, timestamp: number, data: T) => void): void;
+    /**
+     * Handle historical tick data (granularity='tick' mode)
+     * Receives a checkpoint (full orderbook) followed by incremental deltas.
+     * This is for tick-level granularity on Lighter.xyz orderbook data.
+     */
+    onHistoricalTickData(handler: (coin: string, checkpoint: OrderBook, deltas: OrderbookDelta[]) => void): void;
     /**
      * Handle batched data (bulk stream mode)
      */

package/dist/index.d.ts

@@ -293,6 +293,8 @@ interface WsReplay {
     end?: number;
     /** Playback speed multiplier (1 = real-time, 10 = 10x faster) */
     speed?: number;
+    /** Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick') */
+    granularity?: string;
 }
 /** Replay control messages */
 interface WsReplayPause {
@@ -319,6 +321,8 @@ interface WsStream {
     end: number;
     /** Batch size (records per message) */
     batch_size?: number;
+    /** Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick') */
+    granularity?: string;
 }
 /** Stream control messages */
 interface WsStreamStop {
@@ -395,6 +399,29 @@ interface WsHistoricalData<T = unknown> {
     timestamp: number;
     data: T;
 }
+/** Orderbook delta for tick-level data */
+interface OrderbookDelta {
+    /** Timestamp in milliseconds */
+    timestamp: number;
+    /** Side: 'bid' or 'ask' */
+    side: 'bid' | 'ask';
+    /** Price level */
+    price: number;
+    /** New size (0 = level removed) */
+    size: number;
+    /** Sequence number for ordering */
+    sequence: number;
+}
+/** Historical tick data (granularity='tick' mode) - checkpoint + deltas */
+interface WsHistoricalTickData {
+    type: 'historical_tick_data';
+    channel: WsChannel;
+    coin: string;
+    /** Initial checkpoint (full orderbook snapshot) */
+    checkpoint: OrderBook;
+    /** Incremental deltas to apply after checkpoint */
+    deltas: OrderbookDelta[];
+}
 /** Stream started response */
 interface WsStreamStarted {
     type: 'stream_started';
@@ -435,7 +462,7 @@ interface WsStreamStopped {
     snapshots_sent: number;
 }
 /** Server message union type */
-type WsServerMessage = WsSubscribed | WsUnsubscribed | WsPong | WsError | WsData | WsReplayStarted | WsReplayPaused | WsReplayResumed | WsReplayCompleted | WsReplayStopped | WsHistoricalData | WsStreamStarted | WsStreamProgress | WsHistoricalBatch | WsStreamCompleted | WsStreamStopped;
+type WsServerMessage = WsSubscribed | WsUnsubscribed | WsPong | WsError | WsData | WsReplayStarted | WsReplayPaused | WsReplayResumed | WsReplayCompleted | WsReplayStopped | WsHistoricalData | WsHistoricalTickData | WsStreamStarted | WsStreamProgress | WsHistoricalBatch | WsStreamCompleted | WsStreamStopped;
 /**
  * WebSocket connection options.
  *
@@ -1023,6 +1050,7 @@ declare class OxArchiveWs {
     private pingTimer;
     private reconnectTimer;
     private historicalDataHandlers;
+    private historicalTickDataHandlers;
     private batchHandlers;
     private replayStartHandlers;
     private replayCompleteHandlers;
@@ -1106,6 +1134,7 @@ declare class OxArchiveWs {
         start: number;
         end?: number;
         speed?: number;
+        granularity?: string;
     }): void;
     /**
      * Pause the current replay
@@ -1144,6 +1173,7 @@ declare class OxArchiveWs {
         start: number;
         end: number;
         batchSize?: number;
+        granularity?: string;
     }): void;
     /**
      * Stop the current bulk stream
@@ -1153,6 +1183,12 @@ declare class OxArchiveWs {
      * Handle historical data points (replay mode)
      */
     onHistoricalData<T = unknown>(handler: (coin: string, timestamp: number, data: T) => void): void;
+    /**
+     * Handle historical tick data (granularity='tick' mode)
+     * Receives a checkpoint (full orderbook) followed by incremental deltas.
+     * This is for tick-level granularity on Lighter.xyz orderbook data.
+     */
+    onHistoricalTickData(handler: (coin: string, checkpoint: OrderBook, deltas: OrderbookDelta[]) => void): void;
     /**
      * Handle batched data (bulk stream mode)
      */

package/dist/index.js

@@ -854,6 +854,7 @@ var OxArchiveWs = class {
   reconnectTimer = null;
   // Typed event handlers (separate from WsEventHandlers to avoid wrapping issues)
   historicalDataHandlers = [];
+  historicalTickDataHandlers = [];
   batchHandlers = [];
   replayStartHandlers = [];
   replayCompleteHandlers = [];
@@ -1031,7 +1032,8 @@ var OxArchiveWs = class {
       coin,
       start: options.start,
       end: options.end,
-      speed: options.speed ?? 1
+      speed: options.speed ?? 1,
+      granularity: options.granularity
     });
   }
   /**
@@ -1085,7 +1087,8 @@ var OxArchiveWs = class {
       coin,
       start: options.start,
       end: options.end,
-      batch_size: options.batchSize ?? 1e3
+      batch_size: options.batchSize ?? 1e3,
+      granularity: options.granularity
     });
   }
   /**
@@ -1103,6 +1106,14 @@ var OxArchiveWs = class {
   onHistoricalData(handler) {
     this.historicalDataHandlers.push(handler);
   }
+  /**
+   * Handle historical tick data (granularity='tick' mode)
+   * Receives a checkpoint (full orderbook) followed by incremental deltas.
+   * This is for tick-level granularity on Lighter.xyz orderbook data.
+   */
+  onHistoricalTickData(handler) {
+    this.historicalTickDataHandlers.push(handler);
+  }
   /**
    * Handle batched data (bulk stream mode)
    */
@@ -1232,6 +1243,13 @@ var OxArchiveWs = class {
         }
         break;
       }
+      case "historical_tick_data": {
+        const msg = message;
+        for (const handler of this.historicalTickDataHandlers) {
+          handler(msg.coin, msg.checkpoint, msg.deltas);
+        }
+        break;
+      }
       case "historical_batch": {
         const msg = message;
         for (const handler of this.batchHandlers) {