@0xarchive/sdk 0.6.3 → 0.6.5

package/README.md

@@ -153,14 +153,24 @@ const tickData = await client.lighter.orderbook.historyTick('BTC', {
 console.log(`Checkpoint: ${tickData.checkpoint.bids.length} bids`);
 console.log(`Deltas: ${tickData.deltas.length} updates`);
 
-// Option 3: Memory-efficient iteration (for large datasets)
+// 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 4: Get only final state (most efficient)
+// Option 5: Get only final state (most efficient)
 const final = reconstructor.reconstructFinal(tickData.checkpoint, tickData.deltas);
 
 // Check for sequence gaps
@@ -173,10 +183,13 @@ if (gaps.length > 0) {
 **Methods:**
 | Method | Description |
 |--------|-------------|
-| `historyTick(coin, params)` | Get raw checkpoint + deltas for custom reconstruction |
-| `historyReconstructed(coin, params, options)` | Get fully reconstructed snapshots |
+| `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 |
 |--------|---------|-------------|
@@ -211,6 +224,8 @@ while (result.nextCursor) {
 const recent = await client.lighter.trades.recent('BTC', 100);
 ```
 
+**Note:** The `recent()` method is only available for Lighter.xyz (`client.lighter.trades.recent()`). Hyperliquid does not have a recent trades endpoint - use `list()` with a time range instead.
+
 ### Instruments
 
 ```typescript

package/dist/index.d.mts

@@ -1203,6 +1203,37 @@ declare class OrderBookResource {
      * ```
      */
     createReconstructor(): OrderBookReconstructor;
+    /**
+     * Iterate over tick-level orderbook history with automatic pagination (Enterprise tier only).
+     *
+     * This async generator automatically handles pagination, fetching up to 1,000 deltas
+     * per API request and yielding reconstructed orderbook snapshots one at a time.
+     * Memory-efficient for processing large time ranges.
+     *
+     * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+     * @param params - Time range parameters
+     * @param depth - Maximum price levels to include in output snapshots
+     * @yields Reconstructed orderbook snapshots
+     *
+     * @example
+     * ```typescript
+     * // Process 24 hours of tick data with automatic pagination
+     * for await (const snapshot of client.lighter.orderbook.iterateTickHistory('BTC', {
+     *   start: Date.now() - 86400000,
+     *   end: Date.now()
+     * })) {
+     *   console.log(snapshot.timestamp, 'Mid:', snapshot.midPrice);
+     *   if (someCondition) break; // Early exit supported
+     * }
+     *
+     * // Collect all snapshots (caution: may use significant memory for large ranges)
+     * const allSnapshots: ReconstructedOrderBook[] = [];
+     * for await (const snapshot of client.lighter.orderbook.iterateTickHistory('BTC', { start, end })) {
+     *   allSnapshots.push(snapshot);
+     * }
+     * ```
+     */
+    iterateTickHistory(coin: string, params: TickHistoryParams, depth?: number): AsyncGenerator<ReconstructedOrderBook, void, undefined>;
 }
 
 /**

package/dist/index.d.ts

@@ -1203,6 +1203,37 @@ declare class OrderBookResource {
      * ```
      */
     createReconstructor(): OrderBookReconstructor;
+    /**
+     * Iterate over tick-level orderbook history with automatic pagination (Enterprise tier only).
+     *
+     * This async generator automatically handles pagination, fetching up to 1,000 deltas
+     * per API request and yielding reconstructed orderbook snapshots one at a time.
+     * Memory-efficient for processing large time ranges.
+     *
+     * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+     * @param params - Time range parameters
+     * @param depth - Maximum price levels to include in output snapshots
+     * @yields Reconstructed orderbook snapshots
+     *
+     * @example
+     * ```typescript
+     * // Process 24 hours of tick data with automatic pagination
+     * for await (const snapshot of client.lighter.orderbook.iterateTickHistory('BTC', {
+     *   start: Date.now() - 86400000,
+     *   end: Date.now()
+     * })) {
+     *   console.log(snapshot.timestamp, 'Mid:', snapshot.midPrice);
+     *   if (someCondition) break; // Early exit supported
+     * }
+     *
+     * // Collect all snapshots (caution: may use significant memory for large ranges)
+     * const allSnapshots: ReconstructedOrderBook[] = [];
+     * for await (const snapshot of client.lighter.orderbook.iterateTickHistory('BTC', { start, end })) {
+     *   allSnapshots.push(snapshot);
+     * }
+     * ```
+     */
+    iterateTickHistory(coin: string, params: TickHistoryParams, depth?: number): AsyncGenerator<ReconstructedOrderBook, void, undefined>;
 }
 
 /**

package/dist/index.js

@@ -690,13 +690,14 @@ var OrderBookResource = class {
         granularity: "tick"
       }
     );
-    if (!response.checkpoint || !response.deltas) {
+    const tickData = response.data;
+    if (!tickData?.checkpoint || !tickData?.deltas) {
       const errorMsg = response.error || response.message || "Tick-level orderbook data requires Enterprise tier. Upgrade your subscription or use a different granularity.";
       throw new Error(errorMsg);
     }
     return {
-      checkpoint: response.checkpoint,
-      deltas: response.deltas
+      checkpoint: tickData.checkpoint,
+      deltas: tickData.deltas
     };
   }
   /**
@@ -766,6 +767,72 @@ var OrderBookResource = class {
   createReconstructor() {
     return new OrderBookReconstructor();
   }
+  /**
+   * Iterate over tick-level orderbook history with automatic pagination (Enterprise tier only).
+   *
+   * This async generator automatically handles pagination, fetching up to 1,000 deltas
+   * per API request and yielding reconstructed orderbook snapshots one at a time.
+   * Memory-efficient for processing large time ranges.
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @param params - Time range parameters
+   * @param depth - Maximum price levels to include in output snapshots
+   * @yields Reconstructed orderbook snapshots
+   *
+   * @example
+   * ```typescript
+   * // Process 24 hours of tick data with automatic pagination
+   * for await (const snapshot of client.lighter.orderbook.iterateTickHistory('BTC', {
+   *   start: Date.now() - 86400000,
+   *   end: Date.now()
+   * })) {
+   *   console.log(snapshot.timestamp, 'Mid:', snapshot.midPrice);
+   *   if (someCondition) break; // Early exit supported
+   * }
+   *
+   * // Collect all snapshots (caution: may use significant memory for large ranges)
+   * const allSnapshots: ReconstructedOrderBook[] = [];
+   * for await (const snapshot of client.lighter.orderbook.iterateTickHistory('BTC', { start, end })) {
+   *   allSnapshots.push(snapshot);
+   * }
+   * ```
+   */
+  async *iterateTickHistory(coin, params, depth) {
+    const startTs = typeof params.start === "string" ? new Date(params.start).getTime() : params.start;
+    const endTs = typeof params.end === "string" ? new Date(params.end).getTime() : params.end;
+    let cursor = startTs;
+    const reconstructor = new OrderBookReconstructor();
+    const MAX_DELTAS_PER_PAGE = 1e3;
+    let isFirstPage = true;
+    while (cursor < endTs) {
+      const tickData = await this.historyTick(coin, {
+        start: cursor,
+        end: endTs,
+        depth: params.depth
+      });
+      if (tickData.deltas.length === 0) {
+        if (isFirstPage) {
+          reconstructor.initialize(tickData.checkpoint);
+          yield reconstructor.getSnapshot(depth);
+        }
+        break;
+      }
+      let skipFirst = !isFirstPage;
+      for (const snapshot of reconstructor.iterate(tickData.checkpoint, tickData.deltas, { depth })) {
+        if (skipFirst) {
+          skipFirst = false;
+          continue;
+        }
+        yield snapshot;
+      }
+      isFirstPage = false;
+      const lastDelta = tickData.deltas[tickData.deltas.length - 1];
+      cursor = lastDelta.timestamp + 1;
+      if (tickData.deltas.length < MAX_DELTAS_PER_PAGE) {
+        break;
+      }
+    }
+  }
 };
 
 // src/resources/trades.ts