@0xarchive/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -9,14 +9,24 @@ interface ClientOptions {
     /** Request timeout in milliseconds (defaults to 30000) */
     timeout?: number;
 }
+/**
+ * Response metadata
+ */
+interface ApiMeta {
+    /** Number of records returned */
+    count: number;
+    /** Cursor for next page (if available) */
+    next_cursor?: string;
+    /** Unique request ID for debugging */
+    request_id: string;
+}
 /**
  * Standard API response wrapper
  */
 interface ApiResponse<T> {
     success: boolean;
     data: T;
-    count: number;
-    request_id: string;
+    meta: ApiMeta;
 }
 /**
  * Pagination parameters for list endpoints
@@ -36,19 +46,35 @@ interface TimeRangeParams extends PaginationParams {
     /** End timestamp (Unix ms or ISO string) */
     end?: number | string;
 }
-/** A price level in the order book [price, size] */
-type PriceLevel = [string, string];
+/**
+ * A price level in the order book
+ */
+interface PriceLevel {
+    /** Price at this level */
+    px: string;
+    /** Total size at this price level */
+    sz: string;
+    /** Number of orders at this level */
+    n: number;
+}
 /**
  * Order book snapshot
  */
 interface OrderBook {
+    /** Trading pair symbol (e.g., BTC, ETH) */
     coin: string;
-    timestamp: number;
+    /** Snapshot timestamp (UTC) */
+    timestamp: string;
+    /** Bid price levels (best bid first) */
     bids: PriceLevel[];
+    /** Ask price levels (best ask first) */
     asks: PriceLevel[];
-    mid_price: string;
-    spread: string;
-    spread_bps: string;
+    /** Mid price (best bid + best ask) / 2 */
+    mid_price?: string;
+    /** Spread in absolute terms (best ask - best bid) */
+    spread?: string;
+    /** Spread in basis points */
+    spread_bps?: string;
 }
 interface GetOrderBookParams {
     /** Timestamp to get order book at (Unix ms or ISO string) */
@@ -60,72 +86,112 @@ interface OrderBookHistoryParams extends TimeRangeParams {
     /** Number of price levels to return per side */
     depth?: number;
 }
+/** Trade side: 'A' (ask/sell) or 'B' (bid/buy) */
+type TradeSide = 'A' | 'B';
+/** Position direction */
+type TradeDirection = 'Open Long' | 'Open Short' | 'Close Long' | 'Close Short';
+/** Data source */
+type DataSource = 's3' | 'ws' | 'api';
 /**
- * Trade/fill record
+ * Trade/fill record with full execution details
  */
 interface Trade {
-    id: string;
+    /** Trading pair symbol */
     coin: string;
-    side: 'buy' | 'sell';
+    /** Trade side: 'A' (ask/sell) or 'B' (bid/buy) */
+    side: TradeSide;
+    /** Execution price */
     price: string;
+    /** Trade size */
     size: string;
-    value: string;
-    timestamp: number;
-    trade_type: string;
+    /** Execution timestamp (UTC) */
+    timestamp: string;
+    /** Blockchain transaction hash */
+    tx_hash?: string;
+    /** Unique trade ID */
+    trade_id?: number;
+    /** Associated order ID */
+    order_id?: number;
+    /** True if taker (crossed the spread), false if maker */
+    crossed?: boolean;
+    /** Trading fee amount */
+    fee?: string;
+    /** Fee denomination (e.g., USDC) */
+    fee_token?: string;
+    /** Realized PnL if closing a position */
+    closed_pnl?: string;
+    /** Position direction */
+    direction?: TradeDirection;
+    /** Position size before this trade */
+    start_position?: string;
+    /** Data source */
+    source?: DataSource;
+    /** User's wallet address */
+    user_address?: string;
 }
 interface GetTradesParams extends TimeRangeParams {
     /** Filter by side */
-    side?: 'buy' | 'sell';
-}
-/**
- * OHLCV candle
- */
-interface Candle {
-    coin: string;
-    interval: string;
-    timestamp: number;
-    open: string;
-    high: string;
-    low: string;
-    close: string;
-    volume: string;
-    trades: number;
-}
-type CandleInterval = '1m' | '5m' | '15m' | '1h' | '4h' | '1d';
-interface GetCandlesParams extends TimeRangeParams {
-    /** Candle interval */
-    interval?: CandleInterval;
+    side?: TradeSide;
 }
+/** Instrument type */
+type InstrumentType = 'perp' | 'spot';
 /**
  * Trading instrument metadata
  */
 interface Instrument {
-    coin: string;
+    /** Instrument symbol (e.g., BTC) */
     name: string;
+    /** Size decimal precision */
     sz_decimals: number;
-    max_leverage: number;
-    only_isolated: boolean;
+    /** Maximum leverage allowed */
+    max_leverage?: number;
+    /** If true, only isolated margin mode is allowed */
+    only_isolated?: boolean;
+    /** Type of instrument */
+    instrument_type?: InstrumentType;
+    /** Whether the instrument is currently tradeable */
     is_active: boolean;
 }
 /**
  * Funding rate record
  */
 interface FundingRate {
+    /** Trading pair symbol */
     coin: string;
+    /** Funding timestamp (UTC) */
+    timestamp: string;
+    /** Funding rate as decimal (e.g., 0.0001 = 0.01%) */
     funding_rate: string;
-    premium: string;
-    timestamp: number;
+    /** Premium component of funding rate */
+    premium?: string;
 }
 /**
- * Open interest record
+ * Open interest snapshot with market context
  */
 interface OpenInterest {
+    /** Trading pair symbol */
     coin: string;
+    /** Snapshot timestamp (UTC) */
+    timestamp: string;
+    /** Total open interest in contracts */
     open_interest: string;
-    timestamp: number;
-}
-/** WebSocket channel types */
-type WsChannel = 'orderbook' | 'trades' | 'ticker' | 'all_tickers' | 'candles' | 'funding' | 'openinterest';
+    /** Mark price used for liquidations */
+    mark_price?: string;
+    /** Oracle price from external feed */
+    oracle_price?: string;
+    /** 24-hour notional volume */
+    day_ntl_volume?: string;
+    /** Price 24 hours ago */
+    prev_day_price?: string;
+    /** Current mid price */
+    mid_price?: string;
+    /** Impact bid price for liquidations */
+    impact_bid_price?: string;
+    /** Impact ask price for liquidations */
+    impact_ask_price?: string;
+}
+/** WebSocket channel types. Note: ticker/all_tickers are real-time only. */
+type WsChannel = 'orderbook' | 'trades' | 'ticker' | 'all_tickers';
 /** Subscribe message from client */
 interface WsSubscribe {
     op: 'subscribe';
@@ -207,7 +273,7 @@ interface WsError {
     type: 'error';
     message: string;
 }
-/** Data message from server */
+/** Data message from server (real-time) */
 interface WsData<T = unknown> {
     type: 'data';
     channel: WsChannel;
@@ -219,10 +285,12 @@ interface WsReplayStarted {
     type: 'replay_started';
     channel: WsChannel;
     coin: string;
+    /** Start timestamp in milliseconds */
     start: number;
+    /** End timestamp in milliseconds */
     end: number;
+    /** Playback speed multiplier */
     speed: number;
-    total_records: number;
 }
 /** Replay paused response */
 interface WsReplayPaused {
@@ -239,7 +307,7 @@ interface WsReplayCompleted {
     type: 'replay_completed';
     channel: WsChannel;
     coin: string;
-    records_sent: number;
+    snapshots_sent: number;
 }
 /** Replay stopped response */
 interface WsReplayStopped {
@@ -258,47 +326,53 @@ interface WsStreamStarted {
     type: 'stream_started';
     channel: WsChannel;
     coin: string;
+    /** Start timestamp in milliseconds */
     start: number;
+    /** End timestamp in milliseconds */
     end: number;
-    batch_size: number;
-    total_records: number;
 }
-/** Stream progress response */
+/** Stream progress response (sent periodically during streaming) */
 interface WsStreamProgress {
     type: 'stream_progress';
-    records_sent: number;
-    total_records: number;
-    progress_pct: number;
+    snapshots_sent: number;
+}
+/** A record with timestamp for batched data */
+interface TimestampedRecord<T = unknown> {
+    timestamp: number;
+    data: T;
 }
-/** Stream batch (bulk data) */
+/** Batch of historical data (bulk streaming) */
 interface WsHistoricalBatch<T = unknown> {
     type: 'historical_batch';
     channel: WsChannel;
     coin: string;
-    batch_index: number;
-    records: Array<{
-        timestamp: number;
-        data: T;
-    }>;
+    data: TimestampedRecord<T>[];
 }
 /** Stream completed response */
 interface WsStreamCompleted {
     type: 'stream_completed';
     channel: WsChannel;
     coin: string;
-    records_sent: number;
+    snapshots_sent: number;
 }
 /** Stream stopped response */
 interface WsStreamStopped {
     type: 'stream_stopped';
+    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;
-/** WebSocket connection options */
+/**
+ * WebSocket connection options.
+ *
+ * The server sends WebSocket ping frames every 30 seconds and will disconnect
+ * idle connections after 60 seconds. The SDK automatically handles keep-alive
+ * by sending application-level pings at the configured interval.
+ */
 interface WsOptions {
     /** API key for authentication */
     apiKey: string;
-    /** WebSocket URL (defaults to wss://ws.0xarchive.io) */
+    /** WebSocket URL (defaults to wss://api.0xarchive.io/ws) */
     wsUrl?: string;
     /** Auto-reconnect on disconnect (defaults to true) */
     autoReconnect?: boolean;
@@ -306,7 +380,7 @@ interface WsOptions {
     reconnectDelay?: number;
     /** Maximum reconnect attempts (defaults to 10) */
     maxReconnectAttempts?: number;
-    /** Ping interval in ms (defaults to 30000) */
+    /** Ping interval in ms to keep connection alive (defaults to 30000). Server disconnects after 60s idle. */
     pingInterval?: number;
 }
 /** WebSocket connection state */
@@ -334,6 +408,8 @@ declare class OxArchiveError extends Error {
     requestId?: string;
     constructor(message: string, code: number, requestId?: string);
 }
+/** Timestamp can be Unix ms (number), ISO string, or Date object */
+type Timestamp = number | string | Date;
 
 interface HttpClientOptions {
     baseUrl: string;
@@ -434,38 +510,6 @@ declare class TradesResource {
     recent(coin: string, limit?: number): Promise<Trade[]>;
 }
 
-/**
- * Candles (OHLCV) API resource
- *
- * @example
- * ```typescript
- * // Get hourly candles
- * const candles = await client.candles.list('BTC', {
- *   interval: '1h',
- *   start: Date.now() - 86400000,
- *   end: Date.now()
- * });
- *
- * // Get daily candles
- * const daily = await client.candles.list('ETH', {
- *   interval: '1d',
- *   limit: 30
- * });
- * ```
- */
-declare class CandlesResource {
-    private http;
-    constructor(http: HttpClient);
-    /**
-     * Get OHLCV candles for a coin
-     *
-     * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-     * @param params - Interval, time range, and pagination parameters
-     * @returns Array of candles
-     */
-    list(coin: string, params?: GetCandlesParams): Promise<Candle[]>;
-}
-
 /**
  * Instruments API resource
  *
@@ -601,10 +645,6 @@ declare class OxArchive {
      * Trade/fill history
      */
     readonly trades: TradesResource;
-    /**
-     * OHLCV candles
-     */
-    readonly candles: CandlesResource;
     /**
      * Trading instruments metadata
      */
@@ -670,7 +710,13 @@ declare class OxArchive {
  */
 
 /**
- * WebSocket client for real-time data streaming
+ * WebSocket client for real-time data streaming.
+ *
+ * **Keep-Alive:** The server sends WebSocket ping frames every 30 seconds
+ * and will disconnect idle connections after 60 seconds. This SDK automatically
+ * handles keep-alive by sending application-level pings at the configured interval
+ * (default: 30 seconds). The browser WebSocket API automatically responds to
+ * server ping frames.
  */
 declare class OxArchiveWs {
     private ws;
@@ -806,23 +852,23 @@ declare class OxArchiveWs {
     /**
      * Handle replay started event
      */
-    onReplayStart(handler: (channel: WsChannel, coin: string, totalRecords: number, speed: number) => void): void;
+    onReplayStart(handler: (channel: WsChannel, coin: string, start: number, end: number, speed: number) => void): void;
     /**
      * Handle replay completed event
      */
-    onReplayComplete(handler: (channel: WsChannel, coin: string, recordsSent: number) => void): void;
+    onReplayComplete(handler: (channel: WsChannel, coin: string, snapshotsSent: number) => void): void;
     /**
      * Handle stream started event
      */
-    onStreamStart(handler: (channel: WsChannel, coin: string, totalRecords: number) => void): void;
+    onStreamStart(handler: (channel: WsChannel, coin: string, start: number, end: number) => void): void;
     /**
      * Handle stream progress event
      */
-    onStreamProgress(handler: (recordsSent: number, totalRecords: number, progressPct: number) => void): void;
+    onStreamProgress(handler: (snapshotsSent: number) => void): void;
     /**
      * Handle stream completed event
      */
-    onStreamComplete(handler: (channel: WsChannel, coin: string, recordsSent: number) => void): void;
+    onStreamComplete(handler: (channel: WsChannel, coin: string, snapshotsSent: number) => void): void;
     /**
      * Get current connection state
      */
@@ -853,4 +899,4 @@ declare class OxArchiveWs {
     private clearReconnectTimer;
 }
 
-export { type ApiError, type ApiResponse, type Candle, type CandleInterval, type ClientOptions, type FundingRate, type GetCandlesParams, type GetOrderBookParams, type GetTradesParams, type Instrument, type OpenInterest, type OrderBook, type OrderBookHistoryParams, OxArchive, OxArchiveError, OxArchiveWs, type PaginationParams, type PriceLevel, type TimeRangeParams, type Trade, 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 };
+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

@@ -79,7 +79,7 @@ var HttpClient = class {
         throw new OxArchiveError(
           error.error || `Request failed with status ${response.status}`,
           response.status,
-          data.request_id
+          data.meta?.request_id
         );
       }
       return data;
@@ -169,27 +169,6 @@ var TradesResource = class {
   }
 };
 
-// src/resources/candles.ts
-var CandlesResource = class {
-  constructor(http) {
-    this.http = http;
-  }
-  /**
-   * Get OHLCV candles for a coin
-   *
-   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
-   * @param params - Interval, time range, and pagination parameters
-   * @returns Array of candles
-   */
-  async list(coin, params) {
-    const response = await this.http.get(
-      `/v1/candles/${coin.toUpperCase()}`,
-      params
-    );
-    return response.data;
-  }
-};
-
 // src/resources/instruments.ts
 var InstrumentsResource = class {
   constructor(http) {
@@ -299,10 +278,6 @@ var OxArchive = class {
    * Trade/fill history
    */
   trades;
-  /**
-   * OHLCV candles
-   */
-  candles;
   /**
    * Trading instruments metadata
    */
@@ -331,7 +306,6 @@ var OxArchive = class {
     });
     this.orderbook = new OrderBookResource(this.http);
     this.trades = new TradesResource(this.http);
-    this.candles = new CandlesResource(this.http);
     this.instruments = new InstrumentsResource(this.http);
     this.funding = new FundingResource(this.http);
     this.openInterest = new OpenInterestResource(this.http);
@@ -339,7 +313,7 @@ var OxArchive = class {
 };
 
 // src/websocket.ts
-var DEFAULT_WS_URL = "wss://ws.0xarchive.io";
+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;
@@ -592,7 +566,7 @@ var OxArchiveWs = class {
     this.handlers.onMessage = (message) => {
       if (message.type === "historical_batch") {
         const msg = message;
-        handler(msg.coin, msg.records);
+        handler(msg.coin, msg.data);
       }
       originalHandler?.(message);
     };
@@ -605,7 +579,7 @@ var OxArchiveWs = class {
     this.handlers.onMessage = (message) => {
       if (message.type === "replay_started") {
         const msg = message;
-        handler(msg.channel, msg.coin, msg.total_records, msg.speed);
+        handler(msg.channel, msg.coin, msg.start, msg.end, msg.speed);
       }
       originalHandler?.(message);
     };
@@ -618,7 +592,7 @@ var OxArchiveWs = class {
     this.handlers.onMessage = (message) => {
       if (message.type === "replay_completed") {
         const msg = message;
-        handler(msg.channel, msg.coin, msg.records_sent);
+        handler(msg.channel, msg.coin, msg.snapshots_sent);
       }
       originalHandler?.(message);
     };
@@ -631,7 +605,7 @@ var OxArchiveWs = class {
     this.handlers.onMessage = (message) => {
       if (message.type === "stream_started") {
         const msg = message;
-        handler(msg.channel, msg.coin, msg.total_records);
+        handler(msg.channel, msg.coin, msg.start, msg.end);
       }
       originalHandler?.(message);
     };
@@ -644,7 +618,7 @@ var OxArchiveWs = class {
     this.handlers.onMessage = (message) => {
       if (message.type === "stream_progress") {
         const msg = message;
-        handler(msg.records_sent, msg.total_records, msg.progress_pct);
+        handler(msg.snapshots_sent);
       }
       originalHandler?.(message);
     };
@@ -657,7 +631,7 @@ var OxArchiveWs = class {
     this.handlers.onMessage = (message) => {
       if (message.type === "stream_completed") {
         const msg = message;
-        handler(msg.channel, msg.coin, msg.records_sent);
+        handler(msg.channel, msg.coin, msg.snapshots_sent);
       }
       originalHandler?.(message);
     };