@0xarchive/sdk 0.2.1 → 0.3.0

package/dist/index.d.mts

@@ -30,21 +30,23 @@ interface ApiResponse<T> {
 }
 /**
  * Pagination parameters for list endpoints
+ * @deprecated Use cursor-based pagination instead (CursorPaginationParams)
  */
 interface PaginationParams {
     /** Maximum number of results to return */
     limit?: number;
-    /** Number of results to skip */
+    /** @deprecated Use cursor instead. Number of results to skip */
     offset?: number;
 }
 /**
  * Time range parameters for historical queries
+ * @deprecated Use CursorPaginationParams for better performance with large datasets
  */
 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
@@ -129,10 +131,43 @@ interface Trade {
     /** User's wallet address */
     user_address?: string;
 }
+/**
+ * @deprecated Use GetTradesCursorParams instead for better performance with large datasets
+ */
 interface GetTradesParams extends TimeRangeParams {
     /** Filter by side */
     side?: TradeSide;
 }
+/**
+ * Cursor-based pagination parameters for trades (recommended)
+ * More efficient than offset-based pagination for large datasets.
+ * The cursor is a timestamp - use the `nextCursor` from the response to get the next page.
+ */
+interface CursorPaginationParams {
+    /** Start timestamp (Unix ms or ISO string) - REQUIRED */
+    start: number | string;
+    /** End timestamp (Unix ms or ISO string) - REQUIRED */
+    end: number | string;
+    /** Cursor from previous response's nextCursor (timestamp). If not provided, starts from the beginning of the range. */
+    cursor?: number | string;
+    /** Maximum number of results to return (default: 100, max: 1000) */
+    limit?: number;
+}
+/**
+ * Parameters for getting trades with cursor-based pagination (recommended)
+ */
+interface GetTradesCursorParams extends CursorPaginationParams {
+    /** Filter by side */
+    side?: TradeSide;
+}
+/**
+ * Response with cursor for pagination
+ */
+interface CursorResponse<T> {
+    data: T;
+    /** Cursor for next page (use as cursor parameter) */
+    nextCursor?: string;
+}
 /** Instrument type */
 type InstrumentType = 'perp' | 'spot';
 /**
@@ -467,10 +502,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[]>;
 }
 
 /**
@@ -481,25 +516,60 @@ declare class OrderBookResource {
  * // Get recent trades
  * const trades = await client.trades.recent('BTC');
  *
- * // Get trade history with time range
- * const history = await client.trades.list('ETH', {
- *   start: Date.now() - 3600000,
+ * // Get trade history with cursor-based pagination (recommended)
+ * let result = await client.trades.list('BTC', {
+ *   start: Date.now() - 86400000,
  *   end: Date.now(),
- *   limit: 500
+ *   limit: 1000
  * });
+ *
+ * // Get all pages
+ * const allTrades = [...result.data];
+ * while (result.nextCursor) {
+ *   result = await client.trades.list('BTC', {
+ *     start: Date.now() - 86400000,
+ *     end: Date.now(),
+ *     cursor: result.nextCursor,
+ *     limit: 1000
+ *   });
+ *   allTrades.push(...result.data);
+ * }
  * ```
  */
 declare class TradesResource {
     private http;
     constructor(http: HttpClient);
     /**
-     * Get trade history for a coin
+     * Get trade history for a coin using cursor-based pagination
+     *
+     * Uses cursor-based pagination by default, which is more efficient for large datasets.
+     * Use the `nextCursor` from the response as the `cursor` parameter to get the next page.
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
-     * @returns Array of trades
+     * @param params - Time range and cursor pagination parameters (start and end are required)
+     * @returns Object with trades array and nextCursor for pagination
+     *
+     * @example
+     * ```typescript
+     * // First page
+     * let result = await client.trades.list('BTC', {
+     *   start: Date.now() - 86400000,
+     *   end: Date.now(),
+     *   limit: 1000
+     * });
+     *
+     * // Subsequent pages
+     * while (result.nextCursor) {
+     *   result = await client.trades.list('BTC', {
+     *     start: Date.now() - 86400000,
+     *     end: Date.now(),
+     *     cursor: result.nextCursor,
+     *     limit: 1000
+     *   });
+     * }
+     * ```
      */
-    list(coin: string, params?: GetTradesParams): Promise<Trade[]>;
+    list(coin: string, params: GetTradesCursorParams): Promise<CursorResponse<Trade[]>>;
     /**
      * Get most recent trades for a coin
      *
@@ -508,6 +578,26 @@ declare class TradesResource {
      * @returns Array of recent trades
      */
     recent(coin: string, limit?: number): Promise<Trade[]>;
+    /**
+     * Get trade history using cursor-based pagination (explicit endpoint)
+     *
+     * @deprecated Use `list()` instead - it now uses cursor-based pagination by default.
+     *
+     * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+     * @param params - Cursor pagination parameters (start and end are required)
+     * @returns Object with trades array and nextCursor for pagination
+     */
+    listWithCursor(coin: string, params: GetTradesCursorParams): Promise<CursorResponse<Trade[]>>;
+    /**
+     * Get trade history using offset-based pagination
+     *
+     * @deprecated Use `list()` with cursor-based pagination instead for better performance.
+     *
+     * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+     * @param params - Time range and offset pagination parameters
+     * @returns Array of trades (without cursor response wrapper)
+     */
+    listWithOffset(coin: string, params: GetTradesParams): Promise<Trade[]>;
 }
 
 /**
@@ -562,10 +652,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 +688,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
      *

package/dist/index.d.ts

@@ -30,21 +30,23 @@ interface ApiResponse<T> {
 }
 /**
  * Pagination parameters for list endpoints
+ * @deprecated Use cursor-based pagination instead (CursorPaginationParams)
  */
 interface PaginationParams {
     /** Maximum number of results to return */
     limit?: number;
-    /** Number of results to skip */
+    /** @deprecated Use cursor instead. Number of results to skip */
     offset?: number;
 }
 /**
  * Time range parameters for historical queries
+ * @deprecated Use CursorPaginationParams for better performance with large datasets
  */
 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
@@ -129,10 +131,43 @@ interface Trade {
     /** User's wallet address */
     user_address?: string;
 }
+/**
+ * @deprecated Use GetTradesCursorParams instead for better performance with large datasets
+ */
 interface GetTradesParams extends TimeRangeParams {
     /** Filter by side */
     side?: TradeSide;
 }
+/**
+ * Cursor-based pagination parameters for trades (recommended)
+ * More efficient than offset-based pagination for large datasets.
+ * The cursor is a timestamp - use the `nextCursor` from the response to get the next page.
+ */
+interface CursorPaginationParams {
+    /** Start timestamp (Unix ms or ISO string) - REQUIRED */
+    start: number | string;
+    /** End timestamp (Unix ms or ISO string) - REQUIRED */
+    end: number | string;
+    /** Cursor from previous response's nextCursor (timestamp). If not provided, starts from the beginning of the range. */
+    cursor?: number | string;
+    /** Maximum number of results to return (default: 100, max: 1000) */
+    limit?: number;
+}
+/**
+ * Parameters for getting trades with cursor-based pagination (recommended)
+ */
+interface GetTradesCursorParams extends CursorPaginationParams {
+    /** Filter by side */
+    side?: TradeSide;
+}
+/**
+ * Response with cursor for pagination
+ */
+interface CursorResponse<T> {
+    data: T;
+    /** Cursor for next page (use as cursor parameter) */
+    nextCursor?: string;
+}
 /** Instrument type */
 type InstrumentType = 'perp' | 'spot';
 /**
@@ -467,10 +502,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[]>;
 }
 
 /**
@@ -481,25 +516,60 @@ declare class OrderBookResource {
  * // Get recent trades
  * const trades = await client.trades.recent('BTC');
  *
- * // Get trade history with time range
- * const history = await client.trades.list('ETH', {
- *   start: Date.now() - 3600000,
+ * // Get trade history with cursor-based pagination (recommended)
+ * let result = await client.trades.list('BTC', {
+ *   start: Date.now() - 86400000,
  *   end: Date.now(),
- *   limit: 500
+ *   limit: 1000
  * });
+ *
+ * // Get all pages
+ * const allTrades = [...result.data];
+ * while (result.nextCursor) {
+ *   result = await client.trades.list('BTC', {
+ *     start: Date.now() - 86400000,
+ *     end: Date.now(),
+ *     cursor: result.nextCursor,
+ *     limit: 1000
+ *   });
+ *   allTrades.push(...result.data);
+ * }
  * ```
  */
 declare class TradesResource {
     private http;
     constructor(http: HttpClient);
     /**
-     * Get trade history for a coin
+     * Get trade history for a coin using cursor-based pagination
+     *
+     * Uses cursor-based pagination by default, which is more efficient for large datasets.
+     * Use the `nextCursor` from the response as the `cursor` parameter to get the next page.
      *
      * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Time range and pagination parameters
-     * @returns Array of trades
+     * @param params - Time range and cursor pagination parameters (start and end are required)
+     * @returns Object with trades array and nextCursor for pagination
+     *
+     * @example
+     * ```typescript
+     * // First page
+     * let result = await client.trades.list('BTC', {
+     *   start: Date.now() - 86400000,
+     *   end: Date.now(),
+     *   limit: 1000
+     * });
+     *
+     * // Subsequent pages
+     * while (result.nextCursor) {
+     *   result = await client.trades.list('BTC', {
+     *     start: Date.now() - 86400000,
+     *     end: Date.now(),
+     *     cursor: result.nextCursor,
+     *     limit: 1000
+     *   });
+     * }
+     * ```
      */
-    list(coin: string, params?: GetTradesParams): Promise<Trade[]>;
+    list(coin: string, params: GetTradesCursorParams): Promise<CursorResponse<Trade[]>>;
     /**
      * Get most recent trades for a coin
      *
@@ -508,6 +578,26 @@ declare class TradesResource {
      * @returns Array of recent trades
      */
     recent(coin: string, limit?: number): Promise<Trade[]>;
+    /**
+     * Get trade history using cursor-based pagination (explicit endpoint)
+     *
+     * @deprecated Use `list()` instead - it now uses cursor-based pagination by default.
+     *
+     * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+     * @param params - Cursor pagination parameters (start and end are required)
+     * @returns Object with trades array and nextCursor for pagination
+     */
+    listWithCursor(coin: string, params: GetTradesCursorParams): Promise<CursorResponse<Trade[]>>;
+    /**
+     * Get trade history using offset-based pagination
+     *
+     * @deprecated Use `list()` with cursor-based pagination instead for better performance.
+     *
+     * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+     * @param params - Time range and offset pagination parameters
+     * @returns Array of trades (without cursor response wrapper)
+     */
+    listWithOffset(coin: string, params: GetTradesParams): Promise<Trade[]>;
 }
 
 /**
@@ -562,10 +652,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 +688,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
      *

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) {
@@ -140,18 +140,44 @@ var TradesResource = class {
     this.http = http;
   }
   /**
-   * Get trade history for a coin
+   * Get trade history for a coin using cursor-based pagination
+   *
+   * Uses cursor-based pagination by default, which is more efficient for large datasets.
+   * Use the `nextCursor` from the response as the `cursor` parameter to get the next page.
    *
    * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-   * @param params - Time range and pagination parameters
-   * @returns Array of trades
+   * @param params - Time range and cursor pagination parameters (start and end are required)
+   * @returns Object with trades array and nextCursor for pagination
+   *
+   * @example
+   * ```typescript
+   * // First page
+   * let result = await client.trades.list('BTC', {
+   *   start: Date.now() - 86400000,
+   *   end: Date.now(),
+   *   limit: 1000
+   * });
+   *
+   * // Subsequent pages
+   * while (result.nextCursor) {
+   *   result = await client.trades.list('BTC', {
+   *     start: Date.now() - 86400000,
+   *     end: Date.now(),
+   *     cursor: result.nextCursor,
+   *     limit: 1000
+   *   });
+   * }
+   * ```
    */
   async list(coin, params) {
     const response = await this.http.get(
       `/v1/trades/${coin.toUpperCase()}`,
       params
     );
-    return response.data;
+    return {
+      data: response.data,
+      nextCursor: response.meta.next_cursor
+    };
   }
   /**
    * Get most recent trades for a coin
@@ -167,6 +193,34 @@ var TradesResource = class {
     );
     return response.data;
   }
+  /**
+   * Get trade history using cursor-based pagination (explicit endpoint)
+   *
+   * @deprecated Use `list()` instead - it now uses cursor-based pagination by default.
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @param params - Cursor pagination parameters (start and end are required)
+   * @returns Object with trades array and nextCursor for pagination
+   */
+  async listWithCursor(coin, params) {
+    return this.list(coin, params);
+  }
+  /**
+   * Get trade history using offset-based pagination
+   *
+   * @deprecated Use `list()` with cursor-based pagination instead for better performance.
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @param params - Time range and offset pagination parameters
+   * @returns Array of trades (without cursor response wrapper)
+   */
+  async listWithOffset(coin, params) {
+    const response = await this.http.get(
+      `/v1/trades/${coin.toUpperCase()}`,
+      params
+    );
+    return response.data;
+  }
 };
 
 // src/resources/instruments.ts
@@ -208,7 +262,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 +295,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 +371,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;
@@ -730,8 +821,9 @@ var OxArchiveWs = class {
       }
       case "data": {
         if (message.channel === "orderbook") {
+          const orderbook = transformOrderbook(message.coin, message.data);
           for (const handler of this.orderbookHandlers) {
-            handler(message.coin, message.data);
+            handler(message.coin, orderbook);
           }
         } else if (message.channel === "trades") {
           for (const handler of this.tradesHandlers) {