@0xarchive/sdk 0.2.0 → 0.2.2

package/README.md

@@ -77,19 +77,6 @@ const trades = await client.trades.list('ETH', {
 });
 ```
 
-### Candles (OHLCV)
-
-```typescript
-// Get hourly candles
-const candles = await client.candles.list('BTC', {
-  interval: '1h',
-  start: Date.now() - 86400000,
-  end: Date.now()
-});
-
-// Available intervals: '1m', '5m', '15m', '1h', '4h', '1d'
-```
-
 ### Instruments
 
 ```typescript
@@ -183,8 +170,8 @@ ws.onHistoricalData((coin, timestamp, data) => {
   console.log(`${new Date(timestamp)}: ${data.mid_price}`);
 });
 
-ws.onReplayStart((channel, coin, totalRecords, speed) => {
-  console.log(`Starting replay of ${totalRecords} records at ${speed}x`);
+ws.onReplayStart((channel, coin, start, end, speed) => {
+  console.log(`Starting replay from ${start} to ${end} at ${speed}x`);
 });
 
 ws.onReplayComplete((channel, coin, recordsSent) => {
@@ -219,8 +206,8 @@ ws.onBatch((coin, records) => {
   allData.push(...records.map(r => r.data));
 });
 
-ws.onStreamProgress((sent, total, pct) => {
-  console.log(`Progress: ${pct.toFixed(1)}%`);
+ws.onStreamProgress((snapshotsSent) => {
+  console.log(`Sent: ${snapshotsSent} snapshots`);
 });
 
 ws.onStreamComplete((channel, coin, recordsSent) => {
@@ -284,7 +271,6 @@ Full TypeScript support with exported types:
 import type {
   OrderBook,
   Trade,
-  Candle,
   Instrument,
   FundingRate,
   OpenInterest

package/dist/index.d.mts

@@ -41,10 +41,10 @@ interface PaginationParams {
  * Time range parameters for historical queries
  */
 interface TimeRangeParams extends PaginationParams {
-    /** Start timestamp (Unix ms or ISO string) */
-    start?: number | string;
-    /** End timestamp (Unix ms or ISO string) */
-    end?: number | string;
+    /** Start timestamp (Unix ms or ISO string) - REQUIRED for history endpoints */
+    start: number | string;
+    /** End timestamp (Unix ms or ISO string) - REQUIRED for history endpoints */
+    end: number | string;
 }
 /**
  * A price level in the order book
@@ -142,15 +142,15 @@ interface Instrument {
     /** Instrument symbol (e.g., BTC) */
     name: string;
     /** Size decimal precision */
-    sz_decimals: number;
+    szDecimals: number;
     /** Maximum leverage allowed */
-    max_leverage?: number;
+    maxLeverage?: number;
     /** If true, only isolated margin mode is allowed */
-    only_isolated?: boolean;
+    onlyIsolated?: boolean;
     /** Type of instrument */
-    instrument_type?: InstrumentType;
+    instrumentType?: InstrumentType;
     /** Whether the instrument is currently tradeable */
-    is_active: boolean;
+    isActive: boolean;
 }
 /**
  * Funding rate record
@@ -467,10 +467,10 @@ declare class OrderBookResource {
      * Get historical order book snapshots
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
+     * @param params - Time range and pagination parameters (start is required)
      * @returns Array of order book snapshots
      */
-    history(coin: string, params?: OrderBookHistoryParams): Promise<OrderBook[]>;
+    history(coin: string, params: OrderBookHistoryParams): Promise<OrderBook[]>;
 }
 
 /**
@@ -496,10 +496,10 @@ declare class TradesResource {
      * Get trade history for a coin
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
+     * @param params - Time range and pagination parameters (start is required)
      * @returns Array of trades
      */
-    list(coin: string, params?: GetTradesParams): Promise<Trade[]>;
+    list(coin: string, params: GetTradesParams): Promise<Trade[]>;
     /**
      * Get most recent trades for a coin
      *
@@ -562,10 +562,10 @@ declare class FundingResource {
      * Get funding rate history for a coin
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
+     * @param params - Time range and pagination parameters (start is required)
      * @returns Array of funding rate records
      */
-    history(coin: string, params?: TimeRangeParams): Promise<FundingRate[]>;
+    history(coin: string, params: TimeRangeParams): Promise<FundingRate[]>;
     /**
      * Get current funding rate for a coin
      *
@@ -598,10 +598,10 @@ declare class OpenInterestResource {
      * Get open interest history for a coin
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
+     * @param params - Time range and pagination parameters (start is required)
      * @returns Array of open interest records
      */
-    history(coin: string, params?: TimeRangeParams): Promise<OpenInterest[]>;
+    history(coin: string, params: TimeRangeParams): Promise<OpenInterest[]>;
     /**
      * Get current open interest for a coin
      *
@@ -727,6 +727,15 @@ declare class OxArchiveWs {
     private reconnectAttempts;
     private pingTimer;
     private reconnectTimer;
+    private historicalDataHandlers;
+    private batchHandlers;
+    private replayStartHandlers;
+    private replayCompleteHandlers;
+    private streamStartHandlers;
+    private streamProgressHandlers;
+    private streamCompleteHandlers;
+    private orderbookHandlers;
+    private tradesHandlers;
     constructor(options: WsOptions);
     /**
      * Connect to the WebSocket server
@@ -897,6 +906,7 @@ declare class OxArchiveWs {
     private resubscribe;
     private scheduleReconnect;
     private clearReconnectTimer;
+    private handleMessage;
 }
 
 export { type ApiError, type ApiMeta, type ApiResponse, type ClientOptions, type DataSource, type FundingRate, type GetOrderBookParams, type GetTradesParams, type Instrument, type InstrumentType, type OpenInterest, type OrderBook, type OrderBookHistoryParams, OxArchive, OxArchiveError, OxArchiveWs, type PaginationParams, type PriceLevel, type TimeRangeParams, type Timestamp, type TimestampedRecord, type Trade, type TradeDirection, type TradeSide, type WsChannel, type WsClientMessage, type WsConnectionState, type WsData, type WsError, type WsEventHandlers, type WsHistoricalBatch, type WsHistoricalData, type WsOptions, type WsPing, type WsPong, type WsReplay, type WsReplayCompleted, type WsReplayPause, type WsReplayPaused, type WsReplayResume, type WsReplayResumed, type WsReplaySeek, type WsReplayStarted, type WsReplayStop, type WsReplayStopped, type WsServerMessage, type WsStream, type WsStreamCompleted, type WsStreamProgress, type WsStreamStarted, type WsStreamStop, type WsStreamStopped, type WsSubscribe, type WsSubscribed, type WsUnsubscribe, type WsUnsubscribed, OxArchive as default };

package/dist/index.d.ts

@@ -41,10 +41,10 @@ interface PaginationParams {
  * Time range parameters for historical queries
  */
 interface TimeRangeParams extends PaginationParams {
-    /** Start timestamp (Unix ms or ISO string) */
-    start?: number | string;
-    /** End timestamp (Unix ms or ISO string) */
-    end?: number | string;
+    /** Start timestamp (Unix ms or ISO string) - REQUIRED for history endpoints */
+    start: number | string;
+    /** End timestamp (Unix ms or ISO string) - REQUIRED for history endpoints */
+    end: number | string;
 }
 /**
  * A price level in the order book
@@ -142,15 +142,15 @@ interface Instrument {
     /** Instrument symbol (e.g., BTC) */
     name: string;
     /** Size decimal precision */
-    sz_decimals: number;
+    szDecimals: number;
     /** Maximum leverage allowed */
-    max_leverage?: number;
+    maxLeverage?: number;
     /** If true, only isolated margin mode is allowed */
-    only_isolated?: boolean;
+    onlyIsolated?: boolean;
     /** Type of instrument */
-    instrument_type?: InstrumentType;
+    instrumentType?: InstrumentType;
     /** Whether the instrument is currently tradeable */
-    is_active: boolean;
+    isActive: boolean;
 }
 /**
  * Funding rate record
@@ -467,10 +467,10 @@ declare class OrderBookResource {
      * Get historical order book snapshots
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
+     * @param params - Time range and pagination parameters (start is required)
      * @returns Array of order book snapshots
      */
-    history(coin: string, params?: OrderBookHistoryParams): Promise<OrderBook[]>;
+    history(coin: string, params: OrderBookHistoryParams): Promise<OrderBook[]>;
 }
 
 /**
@@ -496,10 +496,10 @@ declare class TradesResource {
      * Get trade history for a coin
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
+     * @param params - Time range and pagination parameters (start is required)
      * @returns Array of trades
      */
-    list(coin: string, params?: GetTradesParams): Promise<Trade[]>;
+    list(coin: string, params: GetTradesParams): Promise<Trade[]>;
     /**
      * Get most recent trades for a coin
      *
@@ -562,10 +562,10 @@ declare class FundingResource {
      * Get funding rate history for a coin
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
+     * @param params - Time range and pagination parameters (start is required)
      * @returns Array of funding rate records
      */
-    history(coin: string, params?: TimeRangeParams): Promise<FundingRate[]>;
+    history(coin: string, params: TimeRangeParams): Promise<FundingRate[]>;
     /**
      * Get current funding rate for a coin
      *
@@ -598,10 +598,10 @@ declare class OpenInterestResource {
      * Get open interest history for a coin
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
+     * @param params - Time range and pagination parameters (start is required)
      * @returns Array of open interest records
      */
-    history(coin: string, params?: TimeRangeParams): Promise<OpenInterest[]>;
+    history(coin: string, params: TimeRangeParams): Promise<OpenInterest[]>;
     /**
      * Get current open interest for a coin
      *
@@ -727,6 +727,15 @@ declare class OxArchiveWs {
     private reconnectAttempts;
     private pingTimer;
     private reconnectTimer;
+    private historicalDataHandlers;
+    private batchHandlers;
+    private replayStartHandlers;
+    private replayCompleteHandlers;
+    private streamStartHandlers;
+    private streamProgressHandlers;
+    private streamCompleteHandlers;
+    private orderbookHandlers;
+    private tradesHandlers;
     constructor(options: WsOptions);
     /**
      * Connect to the WebSocket server
@@ -897,6 +906,7 @@ declare class OxArchiveWs {
     private resubscribe;
     private scheduleReconnect;
     private clearReconnectTimer;
+    private handleMessage;
 }
 
 export { type ApiError, type ApiMeta, type ApiResponse, type ClientOptions, type DataSource, type FundingRate, type GetOrderBookParams, type GetTradesParams, type Instrument, type InstrumentType, type OpenInterest, type OrderBook, type OrderBookHistoryParams, OxArchive, OxArchiveError, OxArchiveWs, type PaginationParams, type PriceLevel, type TimeRangeParams, type Timestamp, type TimestampedRecord, type Trade, type TradeDirection, type TradeSide, type WsChannel, type WsClientMessage, type WsConnectionState, type WsData, type WsError, type WsEventHandlers, type WsHistoricalBatch, type WsHistoricalData, type WsOptions, type WsPing, type WsPong, type WsReplay, type WsReplayCompleted, type WsReplayPause, type WsReplayPaused, type WsReplayResume, type WsReplayResumed, type WsReplaySeek, type WsReplayStarted, type WsReplayStop, type WsReplayStopped, type WsServerMessage, type WsStream, type WsStreamCompleted, type WsStreamProgress, type WsStreamStarted, type WsStreamStop, type WsStreamStopped, type WsSubscribe, type WsSubscribed, type WsUnsubscribe, type WsUnsubscribed, OxArchive as default };

package/dist/index.js

@@ -122,7 +122,7 @@ var OrderBookResource = class {
    * Get historical order book snapshots
    *
    * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-   * @param params - Time range and pagination parameters
+   * @param params - Time range and pagination parameters (start is required)
    * @returns Array of order book snapshots
    */
   async history(coin, params) {
@@ -143,7 +143,7 @@ var TradesResource = class {
    * Get trade history for a coin
    *
    * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-   * @param params - Time range and pagination parameters
+   * @param params - Time range and pagination parameters (start is required)
    * @returns Array of trades
    */
   async list(coin, params) {
@@ -208,7 +208,7 @@ var FundingResource = class {
    * Get funding rate history for a coin
    *
    * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-   * @param params - Time range and pagination parameters
+   * @param params - Time range and pagination parameters (start is required)
    * @returns Array of funding rate records
    */
   async history(coin, params) {
@@ -241,7 +241,7 @@ var OpenInterestResource = class {
    * Get open interest history for a coin
    *
    * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-   * @param params - Time range and pagination parameters
+   * @param params - Time range and pagination parameters (start is required)
    * @returns Array of open interest records
    */
   async history(coin, params) {
@@ -317,6 +317,43 @@ var DEFAULT_WS_URL = "wss://api.0xarchive.io/ws";
 var DEFAULT_PING_INTERVAL = 3e4;
 var DEFAULT_RECONNECT_DELAY = 1e3;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS = 10;
+function transformOrderbook(coin, raw) {
+  if ("bids" in raw && "asks" in raw) {
+    return raw;
+  }
+  const levels = raw.levels;
+  const time = raw.time;
+  const bids = [];
+  const asks = [];
+  if (levels && levels.length >= 2) {
+    for (const level of levels[0] || []) {
+      bids.push({ px: level.px, sz: level.sz, n: level.n });
+    }
+    for (const level of levels[1] || []) {
+      asks.push({ px: level.px, sz: level.sz, n: level.n });
+    }
+  }
+  let mid_price;
+  let spread;
+  let spread_bps;
+  if (bids.length > 0 && asks.length > 0) {
+    const bestBid = parseFloat(bids[0].px);
+    const bestAsk = parseFloat(asks[0].px);
+    const mid = (bestBid + bestAsk) / 2;
+    mid_price = mid.toString();
+    spread = (bestAsk - bestBid).toString();
+    spread_bps = ((bestAsk - bestBid) / mid * 1e4).toFixed(2);
+  }
+  return {
+    coin,
+    timestamp: time ? new Date(time).toISOString() : (/* @__PURE__ */ new Date()).toISOString(),
+    bids,
+    asks,
+    mid_price,
+    spread,
+    spread_bps
+  };
+}
 var OxArchiveWs = class {
   ws = null;
   options;
@@ -326,6 +363,16 @@ var OxArchiveWs = class {
   reconnectAttempts = 0;
   pingTimer = null;
   reconnectTimer = null;
+  // Typed event handlers (separate from WsEventHandlers to avoid wrapping issues)
+  historicalDataHandlers = [];
+  batchHandlers = [];
+  replayStartHandlers = [];
+  replayCompleteHandlers = [];
+  streamStartHandlers = [];
+  streamProgressHandlers = [];
+  streamCompleteHandlers = [];
+  orderbookHandlers = [];
+  tradesHandlers = [];
   constructor(options) {
     this.options = {
       apiKey: options.apiKey,
@@ -369,7 +416,7 @@ var OxArchiveWs = class {
     this.ws.onmessage = (event) => {
       try {
         const message = JSON.parse(event.data);
-        this.handlers.onMessage?.(message);
+        this.handleMessage(message);
       } catch {
       }
     };
@@ -549,92 +596,43 @@ var OxArchiveWs = class {
    * Handle historical data points (replay mode)
    */
   onHistoricalData(handler) {
-    const originalHandler = this.handlers.onMessage;
-    this.handlers.onMessage = (message) => {
-      if (message.type === "historical_data") {
-        const msg = message;
-        handler(msg.coin, msg.timestamp, msg.data);
-      }
-      originalHandler?.(message);
-    };
+    this.historicalDataHandlers.push(handler);
   }
   /**
    * Handle batched data (bulk stream mode)
    */
   onBatch(handler) {
-    const originalHandler = this.handlers.onMessage;
-    this.handlers.onMessage = (message) => {
-      if (message.type === "historical_batch") {
-        const msg = message;
-        handler(msg.coin, msg.data);
-      }
-      originalHandler?.(message);
-    };
+    this.batchHandlers.push(handler);
   }
   /**
    * Handle replay started event
    */
   onReplayStart(handler) {
-    const originalHandler = this.handlers.onMessage;
-    this.handlers.onMessage = (message) => {
-      if (message.type === "replay_started") {
-        const msg = message;
-        handler(msg.channel, msg.coin, msg.start, msg.end, msg.speed);
-      }
-      originalHandler?.(message);
-    };
+    this.replayStartHandlers.push(handler);
   }
   /**
    * Handle replay completed event
    */
   onReplayComplete(handler) {
-    const originalHandler = this.handlers.onMessage;
-    this.handlers.onMessage = (message) => {
-      if (message.type === "replay_completed") {
-        const msg = message;
-        handler(msg.channel, msg.coin, msg.snapshots_sent);
-      }
-      originalHandler?.(message);
-    };
+    this.replayCompleteHandlers.push(handler);
   }
   /**
    * Handle stream started event
    */
   onStreamStart(handler) {
-    const originalHandler = this.handlers.onMessage;
-    this.handlers.onMessage = (message) => {
-      if (message.type === "stream_started") {
-        const msg = message;
-        handler(msg.channel, msg.coin, msg.start, msg.end);
-      }
-      originalHandler?.(message);
-    };
+    this.streamStartHandlers.push(handler);
   }
   /**
    * Handle stream progress event
    */
   onStreamProgress(handler) {
-    const originalHandler = this.handlers.onMessage;
-    this.handlers.onMessage = (message) => {
-      if (message.type === "stream_progress") {
-        const msg = message;
-        handler(msg.snapshots_sent);
-      }
-      originalHandler?.(message);
-    };
+    this.streamProgressHandlers.push(handler);
   }
   /**
    * Handle stream completed event
    */
   onStreamComplete(handler) {
-    const originalHandler = this.handlers.onMessage;
-    this.handlers.onMessage = (message) => {
-      if (message.type === "stream_completed") {
-        const msg = message;
-        handler(msg.channel, msg.coin, msg.snapshots_sent);
-      }
-      originalHandler?.(message);
-    };
+    this.streamCompleteHandlers.push(handler);
   }
   /**
    * Get current connection state
@@ -658,25 +656,13 @@ var OxArchiveWs = class {
    * Helper to handle typed orderbook data
    */
   onOrderbook(handler) {
-    const originalHandler = this.handlers.onMessage;
-    this.handlers.onMessage = (message) => {
-      if (message.type === "data" && message.channel === "orderbook") {
-        handler(message.coin, message.data);
-      }
-      originalHandler?.(message);
-    };
+    this.orderbookHandlers.push(handler);
   }
   /**
    * Helper to handle typed trade data
    */
   onTrades(handler) {
-    const originalHandler = this.handlers.onMessage;
-    this.handlers.onMessage = (message) => {
-      if (message.type === "data" && message.channel === "trades") {
-        handler(message.coin, message.data);
-      }
-      originalHandler?.(message);
-    };
+    this.tradesHandlers.push(handler);
   }
   // Private methods
   send(message) {
@@ -727,6 +713,73 @@ var OxArchiveWs = class {
       this.reconnectTimer = null;
     }
   }
+  handleMessage(message) {
+    this.handlers.onMessage?.(message);
+    switch (message.type) {
+      case "historical_data": {
+        const msg = message;
+        for (const handler of this.historicalDataHandlers) {
+          handler(msg.coin, msg.timestamp, msg.data);
+        }
+        break;
+      }
+      case "historical_batch": {
+        const msg = message;
+        for (const handler of this.batchHandlers) {
+          handler(msg.coin, msg.data);
+        }
+        break;
+      }
+      case "replay_started": {
+        const msg = message;
+        for (const handler of this.replayStartHandlers) {
+          handler(msg.channel, msg.coin, msg.start, msg.end, msg.speed);
+        }
+        break;
+      }
+      case "replay_completed": {
+        const msg = message;
+        for (const handler of this.replayCompleteHandlers) {
+          handler(msg.channel, msg.coin, msg.snapshots_sent);
+        }
+        break;
+      }
+      case "stream_started": {
+        const msg = message;
+        for (const handler of this.streamStartHandlers) {
+          handler(msg.channel, msg.coin, msg.start, msg.end);
+        }
+        break;
+      }
+      case "stream_progress": {
+        const msg = message;
+        for (const handler of this.streamProgressHandlers) {
+          handler(msg.snapshots_sent);
+        }
+        break;
+      }
+      case "stream_completed": {
+        const msg = message;
+        for (const handler of this.streamCompleteHandlers) {
+          handler(msg.channel, msg.coin, msg.snapshots_sent);
+        }
+        break;
+      }
+      case "data": {
+        if (message.channel === "orderbook") {
+          const orderbook = transformOrderbook(message.coin, message.data);
+          for (const handler of this.orderbookHandlers) {
+            handler(message.coin, orderbook);
+          }
+        } else if (message.channel === "trades") {
+          for (const handler of this.tradesHandlers) {
+            handler(message.coin, message.data);
+          }
+        }
+        break;
+      }
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {