@0xarchive/sdk 0.6.0 → 0.6.2

package/README.md

@@ -519,6 +519,31 @@ ws.stream('orderbook', 'BTC', {
 ws.streamStop();
 ```
 
+### Gap Detection
+
+During historical replay and bulk streaming, the server automatically detects gaps in the data and notifies the client. This helps identify periods where data may be missing.
+
+```typescript
+// Handle gap notifications during replay/stream
+ws.onGap((channel, coin, gapStart, gapEnd, durationMinutes) => {
+  console.log(`Gap detected in ${channel}/${coin}:`);
+  console.log(`  From: ${new Date(gapStart).toISOString()}`);
+  console.log(`  To: ${new Date(gapEnd).toISOString()}`);
+  console.log(`  Duration: ${durationMinutes} minutes`);
+});
+
+// Start replay - gaps will be reported via onGap callback
+ws.replay('orderbook', 'BTC', {
+  start: Date.now() - 86400000,
+  end: Date.now(),
+  speed: 10
+});
+```
+
+Gap thresholds vary by channel:
+- **orderbook**, **candles**, **liquidations**: 2 minutes
+- **trades**: 60 minutes (trades can naturally have longer gaps during low activity periods)
+
 ### WebSocket Configuration
 
 ```typescript
@@ -539,6 +564,7 @@ const ws = new OxArchiveWs({
 | `orderbook` | L2 order book updates | Yes | Yes |
 | `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) |
 | `ticker` | Price and 24h volume | Yes | Real-time only |
 | `all_tickers` | All market tickers | No | Real-time only |
 

package/dist/index.d.mts

@@ -536,8 +536,24 @@ interface WsStreamStopped {
     type: 'stream_stopped';
     snapshots_sent: number;
 }
+/**
+ * Gap detected in historical data stream.
+ * Sent when there's a gap exceeding the threshold between consecutive data points.
+ * Thresholds: 2 minutes for orderbook/candles/liquidations, 60 minutes for trades.
+ */
+interface WsGapDetected {
+    type: 'gap_detected';
+    channel: WsChannel;
+    coin: string;
+    /** Start of the gap (last data point timestamp in ms) */
+    gap_start: number;
+    /** End of the gap (next data point timestamp in ms) */
+    gap_end: number;
+    /** Gap duration in minutes */
+    duration_minutes: number;
+}
 /** Server message union type */
-type WsServerMessage = WsSubscribed | WsUnsubscribed | WsPong | WsError | WsData | WsReplayStarted | WsReplayPaused | WsReplayResumed | WsReplayCompleted | WsReplayStopped | WsHistoricalData | WsHistoricalTickData | WsStreamStarted | WsStreamProgress | WsHistoricalBatch | WsStreamCompleted | WsStreamStopped;
+type WsServerMessage = WsSubscribed | WsUnsubscribed | WsPong | WsError | WsData | WsReplayStarted | WsReplayPaused | WsReplayResumed | WsReplayCompleted | WsReplayStopped | WsHistoricalData | WsHistoricalTickData | WsStreamStarted | WsStreamProgress | WsHistoricalBatch | WsStreamCompleted | WsStreamStopped | WsGapDetected;
 /**
  * WebSocket connection options.
  *
@@ -1679,6 +1695,7 @@ declare class OxArchiveWs {
     private streamCompleteHandlers;
     private orderbookHandlers;
     private tradesHandlers;
+    private gapHandlers;
     constructor(options: WsOptions);
     /**
      * Connect to the WebSocket server
@@ -1840,6 +1857,23 @@ declare class OxArchiveWs {
      * Handle stream completed event
      */
     onStreamComplete(handler: (channel: WsChannel, coin: string, snapshotsSent: number) => void): void;
+    /**
+     * Handle gap detected events during replay or streaming.
+     * Called when there's a gap in the historical data exceeding the threshold.
+     * Thresholds: 2 minutes for orderbook/candles/liquidations, 60 minutes for trades.
+     *
+     * @param handler - Callback receiving channel, coin, gap start/end timestamps (ms), and duration (minutes)
+     *
+     * @example
+     * ```typescript
+     * ws.onGap((channel, coin, gapStart, gapEnd, durationMinutes) => {
+     *   console.warn(`Gap detected in ${channel} ${coin}: ${durationMinutes} minutes`);
+     *   console.warn(`  From: ${new Date(gapStart).toISOString()}`);
+     *   console.warn(`  To:   ${new Date(gapEnd).toISOString()}`);
+     * });
+     * ```
+     */
+    onGap(handler: (channel: WsChannel, coin: string, gapStart: number, gapEnd: number, durationMinutes: number) => void): void;
     /**
      * Get current connection state
      */

package/dist/index.d.ts

@@ -536,8 +536,24 @@ interface WsStreamStopped {
     type: 'stream_stopped';
     snapshots_sent: number;
 }
+/**
+ * Gap detected in historical data stream.
+ * Sent when there's a gap exceeding the threshold between consecutive data points.
+ * Thresholds: 2 minutes for orderbook/candles/liquidations, 60 minutes for trades.
+ */
+interface WsGapDetected {
+    type: 'gap_detected';
+    channel: WsChannel;
+    coin: string;
+    /** Start of the gap (last data point timestamp in ms) */
+    gap_start: number;
+    /** End of the gap (next data point timestamp in ms) */
+    gap_end: number;
+    /** Gap duration in minutes */
+    duration_minutes: number;
+}
 /** Server message union type */
-type WsServerMessage = WsSubscribed | WsUnsubscribed | WsPong | WsError | WsData | WsReplayStarted | WsReplayPaused | WsReplayResumed | WsReplayCompleted | WsReplayStopped | WsHistoricalData | WsHistoricalTickData | WsStreamStarted | WsStreamProgress | WsHistoricalBatch | WsStreamCompleted | WsStreamStopped;
+type WsServerMessage = WsSubscribed | WsUnsubscribed | WsPong | WsError | WsData | WsReplayStarted | WsReplayPaused | WsReplayResumed | WsReplayCompleted | WsReplayStopped | WsHistoricalData | WsHistoricalTickData | WsStreamStarted | WsStreamProgress | WsHistoricalBatch | WsStreamCompleted | WsStreamStopped | WsGapDetected;
 /**
  * WebSocket connection options.
  *
@@ -1679,6 +1695,7 @@ declare class OxArchiveWs {
     private streamCompleteHandlers;
     private orderbookHandlers;
     private tradesHandlers;
+    private gapHandlers;
     constructor(options: WsOptions);
     /**
      * Connect to the WebSocket server
@@ -1840,6 +1857,23 @@ declare class OxArchiveWs {
      * Handle stream completed event
      */
     onStreamComplete(handler: (channel: WsChannel, coin: string, snapshotsSent: number) => void): void;
+    /**
+     * Handle gap detected events during replay or streaming.
+     * Called when there's a gap in the historical data exceeding the threshold.
+     * Thresholds: 2 minutes for orderbook/candles/liquidations, 60 minutes for trades.
+     *
+     * @param handler - Callback receiving channel, coin, gap start/end timestamps (ms), and duration (minutes)
+     *
+     * @example
+     * ```typescript
+     * ws.onGap((channel, coin, gapStart, gapEnd, durationMinutes) => {
+     *   console.warn(`Gap detected in ${channel} ${coin}: ${durationMinutes} minutes`);
+     *   console.warn(`  From: ${new Date(gapStart).toISOString()}`);
+     *   console.warn(`  To:   ${new Date(gapEnd).toISOString()}`);
+     * });
+     * ```
+     */
+    onGap(handler: (channel: WsChannel, coin: string, gapStart: number, gapEnd: number, durationMinutes: number) => void): void;
     /**
      * Get current connection state
      */

package/dist/index.js

@@ -533,7 +533,7 @@ var TradesResource = class {
    */
   async recent(coin, limit) {
     const response = await this.http.get(
-      `/v1/trades/${coin.toUpperCase()}/recent`,
+      `${this.basePath}/trades/${coin.toUpperCase()}/recent`,
       { limit },
       this.http.validationEnabled ? TradeArrayResponseSchema : void 0
     );
@@ -1175,6 +1175,7 @@ var OxArchiveWs = class {
   streamCompleteHandlers = [];
   orderbookHandlers = [];
   tradesHandlers = [];
+  gapHandlers = [];
   constructor(options) {
     this.options = {
       apiKey: options.apiKey,
@@ -1464,6 +1465,25 @@ var OxArchiveWs = class {
   onStreamComplete(handler) {
     this.streamCompleteHandlers.push(handler);
   }
+  /**
+   * Handle gap detected events during replay or streaming.
+   * Called when there's a gap in the historical data exceeding the threshold.
+   * Thresholds: 2 minutes for orderbook/candles/liquidations, 60 minutes for trades.
+   *
+   * @param handler - Callback receiving channel, coin, gap start/end timestamps (ms), and duration (minutes)
+   *
+   * @example
+   * ```typescript
+   * ws.onGap((channel, coin, gapStart, gapEnd, durationMinutes) => {
+   *   console.warn(`Gap detected in ${channel} ${coin}: ${durationMinutes} minutes`);
+   *   console.warn(`  From: ${new Date(gapStart).toISOString()}`);
+   *   console.warn(`  To:   ${new Date(gapEnd).toISOString()}`);
+   * });
+   * ```
+   */
+  onGap(handler) {
+    this.gapHandlers.push(handler);
+  }
   /**
    * Get current connection state
    */
@@ -1606,6 +1626,13 @@ var OxArchiveWs = class {
         }
         break;
       }
+      case "gap_detected": {
+        const msg = message;
+        for (const handler of this.gapHandlers) {
+          handler(msg.channel, msg.coin, msg.gap_start, msg.gap_end, msg.duration_minutes);
+        }
+        break;
+      }
       case "data": {
         if (message.channel === "orderbook") {
           const orderbook = transformOrderbook(message.coin, message.data);