@0xarchive/sdk 0.3.3 → 0.3.4

package/README.md

@@ -35,13 +35,14 @@ const history = await client.orderbook.history('ETH', {
 
 ```typescript
 const client = new OxArchive({
-  apiKey: 'ox_your_api_key',     // Required
-  baseUrl: 'https://api.0xarchive.io', // Optional, defaults to production
-  timeout: 30000,                 // Optional, request timeout in ms
+  apiKey: 'ox_your_api_key',       // Required
+  baseUrl: 'https://api.0xarchive.io',  // Optional
+  timeout: 30000,                   // Optional, request timeout in ms (default: 30000)
+  validate: false,                  // Optional, enable Zod schema validation
 });
 ```
 
-## API Reference
+## REST API Reference
 
 ### Order Book
 
@@ -49,41 +50,55 @@ const client = new OxArchive({
 // Get current order book
 const orderbook = await client.orderbook.get('BTC');
 
-// Get order book at specific timestamp
+// Get order book at specific timestamp with custom depth
 const historical = await client.orderbook.get('BTC', {
   timestamp: 1704067200000,
   depth: 20  // Number of levels per side
 });
 
-// Get historical snapshots
+// Get historical snapshots (start is required)
 const history = await client.orderbook.history('BTC', {
-  start: '2024-01-01',
-  end: '2024-01-02',
+  start: Date.now() - 86400000,
+  end: Date.now(),
   limit: 1000
 });
 ```
 
 ### Trades
 
+The trades API uses cursor-based pagination for efficient retrieval of large datasets.
+
 ```typescript
 // Get recent trades
 const recent = await client.trades.recent('BTC', 100);
 
-// Get trade history
-const trades = await client.trades.list('ETH', {
-  start: Date.now() - 3600000,
+// Get trade history with cursor-based pagination
+let result = await client.trades.list('BTC', {
+  start: Date.now() - 86400000,
   end: Date.now(),
-  side: 'buy'  // Optional: filter by side
+  limit: 1000
 });
+
+// Paginate through all results
+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);
+}
 ```
 
 ### Instruments
 
 ```typescript
-// List all instruments
+// List all trading instruments
 const instruments = await client.instruments.list();
 
-// Get specific instrument
+// Get specific instrument details
 const btc = await client.instruments.get('BTC');
 ```
 
@@ -93,7 +108,7 @@ const btc = await client.instruments.get('BTC');
 // Get current funding rate
 const current = await client.funding.current('BTC');
 
-// Get funding rate history
+// Get funding rate history (start is required)
 const history = await client.funding.history('ETH', {
   start: Date.now() - 86400000 * 7,
   end: Date.now()
@@ -106,72 +121,76 @@ const history = await client.funding.history('ETH', {
 // Get current open interest
 const current = await client.openInterest.current('BTC');
 
-// Get open interest history
+// Get open interest history (start is required)
 const history = await client.openInterest.history('ETH', {
   start: Date.now() - 86400000,
-  end: Date.now()
+  end: Date.now(),
+  limit: 100
 });
 ```
 
-## WebSocket Streaming
+## WebSocket Client
 
-For real-time data, use the WebSocket client:
+The WebSocket client supports three modes: real-time streaming, historical replay, and bulk streaming.
 
 ```typescript
 import { OxArchiveWs } from '@0xarchive/sdk';
 
 const ws = new OxArchiveWs({ apiKey: 'ox_your_api_key' });
+```
+
+### Real-time Streaming
 
-// Connect and set up handlers
+Subscribe to live market data from Hyperliquid.
+
+```typescript
 ws.connect({
   onOpen: () => console.log('Connected'),
   onClose: (code, reason) => console.log(`Disconnected: ${code}`),
   onError: (error) => console.error('Error:', error),
-  onMessage: (message) => console.log('Message:', message),
-  onStateChange: (state) => console.log('State:', state),
 });
 
-// Subscribe to order book updates
+// Subscribe to channels
 ws.subscribeOrderbook('BTC');
-ws.subscribeOrderbook('ETH');
-
-// Subscribe to trades
-ws.subscribeTrades('BTC');
-
-// Subscribe to all tickers
+ws.subscribeTrades('ETH');
+ws.subscribeTicker('SOL');
 ws.subscribeAllTickers();
 
-// Typed handlers for specific data
+// Handle real-time data with typed callbacks
 ws.onOrderbook((coin, data) => {
-  console.log(`${coin} orderbook: ${data.mid_price}`);
+  console.log(`${coin} mid price: ${data.mid_price}`);
 });
 
 ws.onTrades((coin, trades) => {
   console.log(`${coin} new trades: ${trades.length}`);
 });
 
-// Unsubscribe
-ws.unsubscribeOrderbook('ETH');
+// Unsubscribe when done
+ws.unsubscribeOrderbook('BTC');
 
-// Disconnect when done
+// Disconnect
 ws.disconnect();
 ```
 
-### Historical Replay (like Tardis.dev)
+### Historical Replay
+
+Replay historical data with original timing preserved. Perfect for backtesting.
 
-Replay historical data with timing preserved:
+> **Important:** Replay data is delivered via `onHistoricalData()`, NOT `onTrades()` or `onOrderbook()`.
+> The real-time callbacks only receive live market data from subscriptions.
 
 ```typescript
 const ws = new OxArchiveWs({ apiKey: 'ox_...' });
 ws.connect();
 
-// Handle replay data
+// Handle replay data - this is where historical records arrive
 ws.onHistoricalData((coin, timestamp, data) => {
-  console.log(`${new Date(timestamp)}: ${data.mid_price}`);
+  console.log(`${new Date(timestamp).toISOString()}: ${data.mid_price}`);
 });
 
+// Replay lifecycle events
 ws.onReplayStart((channel, coin, start, end, speed) => {
-  console.log(`Starting replay from ${start} to ${end} at ${speed}x`);
+  console.log(`Starting replay: ${channel}/${coin} at ${speed}x`);
 });
 
 ws.onReplayComplete((channel, coin, recordsSent) => {
@@ -180,20 +199,21 @@ ws.onReplayComplete((channel, coin, recordsSent) => {
 
 // Start replay at 10x speed
 ws.replay('orderbook', 'BTC', {
-  start: Date.now() - 86400000, // 24 hours ago
-  speed: 10
+  start: Date.now() - 86400000,  // 24 hours ago
+  end: Date.now(),               // Optional, defaults to now
+  speed: 10                       // Optional, defaults to 1x
 });
 
 // Control playback
 ws.replayPause();
 ws.replayResume();
-ws.replaySeek(1704067200000); // Jump to timestamp
+ws.replaySeek(1704067200000);  // Jump to timestamp
 ws.replayStop();
 ```
 
-### Bulk Streaming (like Databento)
+### Bulk Streaming
 
-Fast bulk download for data pipelines:
+Fast bulk download for data pipelines. Data arrives in batches without timing delays.
 
 ```typescript
 const ws = new OxArchiveWs({ apiKey: 'ox_...' });
@@ -207,7 +227,7 @@ ws.onBatch((coin, records) => {
 });
 
 ws.onStreamProgress((snapshotsSent) => {
-  console.log(`Sent: ${snapshotsSent} snapshots`);
+  console.log(`Progress: ${snapshotsSent} snapshots`);
 });
 
 ws.onStreamComplete((channel, coin, recordsSent) => {
@@ -216,12 +236,12 @@ ws.onStreamComplete((channel, coin, recordsSent) => {
 
 // Start bulk stream
 ws.stream('orderbook', 'ETH', {
-  start: Date.now() - 3600000, // 1 hour ago
+  start: Date.now() - 3600000,  // 1 hour ago
   end: Date.now(),
-  batchSize: 1000
+  batchSize: 1000               // Optional, defaults to 1000
 });
 
-// Stop stream if needed
+// Stop if needed
 ws.streamStop();
 ```
 
@@ -229,12 +249,12 @@ ws.streamStop();
 
 ```typescript
 const ws = new OxArchiveWs({
-  apiKey: 'ox_your_api_key',
-  wsUrl: 'wss://api.0xarchive.io/ws',  // Optional
-  autoReconnect: true,             // Auto-reconnect on disconnect
-  reconnectDelay: 1000,            // Initial reconnect delay (ms)
-  maxReconnectAttempts: 10,        // Max reconnect attempts
-  pingInterval: 30000,             // Keep-alive ping interval (ms)
+  apiKey: 'ox_your_api_key',          // Required
+  wsUrl: 'wss://api.0xarchive.io/ws', // Optional
+  autoReconnect: true,                // Auto-reconnect on disconnect (default: true)
+  reconnectDelay: 1000,               // Initial reconnect delay in ms (default: 1000)
+  maxReconnectAttempts: 10,           // Max reconnect attempts (default: 10)
+  pingInterval: 30000,                // Keep-alive ping interval in ms (default: 30000)
 });
 ```
 
@@ -247,6 +267,38 @@ const ws = new OxArchiveWs({
 | `ticker` | Price and 24h volume | Yes |
 | `all_tickers` | All market tickers | No |
 
+### WebSocket Connection States
+
+```typescript
+ws.getState(); // 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
+ws.isConnected(); // boolean
+```
+
+## Timestamp Formats
+
+The SDK accepts timestamps as Unix milliseconds or Date objects:
+
+```typescript
+// Unix milliseconds (recommended)
+client.orderbook.history('BTC', {
+  start: Date.now() - 86400000,
+  end: Date.now()
+});
+
+// Date objects (converted automatically)
+client.orderbook.history('BTC', {
+  start: new Date('2024-01-01'),
+  end: new Date('2024-01-02')
+});
+
+// WebSocket replay/stream also accepts both
+ws.replay('orderbook', 'BTC', {
+  start: Date.now() - 3600000,
+  end: Date.now(),
+  speed: 10
+});
+```
+
 ## Error Handling
 
 ```typescript
@@ -270,17 +322,34 @@ Full TypeScript support with exported types:
 ```typescript
 import type {
   OrderBook,
+  PriceLevel,
   Trade,
   Instrument,
   FundingRate,
-  OpenInterest
+  OpenInterest,
+  CursorResponse,
+  WsOptions,
+  WsChannel,
+  WsConnectionState,
 } from '@0xarchive/sdk';
 ```
 
+## Runtime Validation
+
+Enable Zod schema validation for API responses:
+
+```typescript
+const client = new OxArchive({
+  apiKey: 'ox_your_api_key',
+  validate: true  // Enable runtime validation
+});
+```
+
+When enabled, responses are validated against Zod schemas and throw `OxArchiveError` with status 422 if validation fails.
+
 ## Requirements
 
-- Node.js 18+
-- Modern browsers with `fetch` support
+- Node.js 18+ or modern browsers with `fetch` and `WebSocket` support
 
 ## License
 

package/dist/index.d.mts

@@ -94,8 +94,8 @@ interface OrderBookHistoryParams extends TimeRangeParams {
 }
 /** 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';
+/** Position direction (can include 'Open Long', 'Close Short', 'Long > Short', etc.) */
+type TradeDirection = string;
 /** Data source: 's3' (historical), 'api' (REST backfill), 'ws' (websocket), 'live' (real-time ingestion) */
 type DataSource = 's3' | 'ws' | 'api' | 'live';
 /**
@@ -1174,7 +1174,7 @@ declare const OrderBookSchema: z.ZodObject<{
     spread_bps?: string | undefined;
 }>;
 declare const TradeSideSchema: z.ZodEnum<["A", "B"]>;
-declare const TradeDirectionSchema: z.ZodEnum<["Open Long", "Open Short", "Close Long", "Close Short"]>;
+declare const TradeDirectionSchema: z.ZodString;
 declare const DataSourceSchema: z.ZodEnum<["s3", "ws", "api", "live"]>;
 declare const TradeSchema: z.ZodObject<{
     coin: z.ZodString;
@@ -1189,7 +1189,7 @@ declare const TradeSchema: z.ZodObject<{
     fee: z.ZodOptional<z.ZodString>;
     fee_token: z.ZodOptional<z.ZodString>;
     closed_pnl: z.ZodOptional<z.ZodString>;
-    direction: z.ZodOptional<z.ZodEnum<["Open Long", "Open Short", "Close Long", "Close Short"]>>;
+    direction: z.ZodOptional<z.ZodString>;
     start_position: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodEnum<["s3", "ws", "api", "live"]>>;
     user_address: z.ZodOptional<z.ZodString>;
@@ -1208,7 +1208,7 @@ declare const TradeSchema: z.ZodObject<{
     fee?: string | undefined;
     fee_token?: string | undefined;
     closed_pnl?: string | undefined;
-    direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+    direction?: string | undefined;
     start_position?: string | undefined;
     source?: "s3" | "ws" | "api" | "live" | undefined;
     user_address?: string | undefined;
@@ -1227,7 +1227,7 @@ declare const TradeSchema: z.ZodObject<{
     fee?: string | undefined;
     fee_token?: string | undefined;
     closed_pnl?: string | undefined;
-    direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+    direction?: string | undefined;
     start_position?: string | undefined;
     source?: "s3" | "ws" | "api" | "live" | undefined;
     user_address?: string | undefined;
@@ -2035,7 +2035,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee: z.ZodOptional<z.ZodString>;
         fee_token: z.ZodOptional<z.ZodString>;
         closed_pnl: z.ZodOptional<z.ZodString>;
-        direction: z.ZodOptional<z.ZodEnum<["Open Long", "Open Short", "Close Long", "Close Short"]>>;
+        direction: z.ZodOptional<z.ZodString>;
         start_position: z.ZodOptional<z.ZodString>;
         source: z.ZodOptional<z.ZodEnum<["s3", "ws", "api", "live"]>>;
         user_address: z.ZodOptional<z.ZodString>;
@@ -2054,7 +2054,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee?: string | undefined;
         fee_token?: string | undefined;
         closed_pnl?: string | undefined;
-        direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+        direction?: string | undefined;
         start_position?: string | undefined;
         source?: "s3" | "ws" | "api" | "live" | undefined;
         user_address?: string | undefined;
@@ -2073,7 +2073,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee?: string | undefined;
         fee_token?: string | undefined;
         closed_pnl?: string | undefined;
-        direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+        direction?: string | undefined;
         start_position?: string | undefined;
         source?: "s3" | "ws" | "api" | "live" | undefined;
         user_address?: string | undefined;
@@ -2107,7 +2107,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee?: string | undefined;
         fee_token?: string | undefined;
         closed_pnl?: string | undefined;
-        direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+        direction?: string | undefined;
         start_position?: string | undefined;
         source?: "s3" | "ws" | "api" | "live" | undefined;
         user_address?: string | undefined;
@@ -2134,7 +2134,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee?: string | undefined;
         fee_token?: string | undefined;
         closed_pnl?: string | undefined;
-        direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+        direction?: string | undefined;
         start_position?: string | undefined;
         source?: "s3" | "ws" | "api" | "live" | undefined;
         user_address?: string | undefined;

package/dist/index.d.ts

@@ -94,8 +94,8 @@ interface OrderBookHistoryParams extends TimeRangeParams {
 }
 /** 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';
+/** Position direction (can include 'Open Long', 'Close Short', 'Long > Short', etc.) */
+type TradeDirection = string;
 /** Data source: 's3' (historical), 'api' (REST backfill), 'ws' (websocket), 'live' (real-time ingestion) */
 type DataSource = 's3' | 'ws' | 'api' | 'live';
 /**
@@ -1174,7 +1174,7 @@ declare const OrderBookSchema: z.ZodObject<{
     spread_bps?: string | undefined;
 }>;
 declare const TradeSideSchema: z.ZodEnum<["A", "B"]>;
-declare const TradeDirectionSchema: z.ZodEnum<["Open Long", "Open Short", "Close Long", "Close Short"]>;
+declare const TradeDirectionSchema: z.ZodString;
 declare const DataSourceSchema: z.ZodEnum<["s3", "ws", "api", "live"]>;
 declare const TradeSchema: z.ZodObject<{
     coin: z.ZodString;
@@ -1189,7 +1189,7 @@ declare const TradeSchema: z.ZodObject<{
     fee: z.ZodOptional<z.ZodString>;
     fee_token: z.ZodOptional<z.ZodString>;
     closed_pnl: z.ZodOptional<z.ZodString>;
-    direction: z.ZodOptional<z.ZodEnum<["Open Long", "Open Short", "Close Long", "Close Short"]>>;
+    direction: z.ZodOptional<z.ZodString>;
     start_position: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodEnum<["s3", "ws", "api", "live"]>>;
     user_address: z.ZodOptional<z.ZodString>;
@@ -1208,7 +1208,7 @@ declare const TradeSchema: z.ZodObject<{
     fee?: string | undefined;
     fee_token?: string | undefined;
     closed_pnl?: string | undefined;
-    direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+    direction?: string | undefined;
     start_position?: string | undefined;
     source?: "s3" | "ws" | "api" | "live" | undefined;
     user_address?: string | undefined;
@@ -1227,7 +1227,7 @@ declare const TradeSchema: z.ZodObject<{
     fee?: string | undefined;
     fee_token?: string | undefined;
     closed_pnl?: string | undefined;
-    direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+    direction?: string | undefined;
     start_position?: string | undefined;
     source?: "s3" | "ws" | "api" | "live" | undefined;
     user_address?: string | undefined;
@@ -2035,7 +2035,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee: z.ZodOptional<z.ZodString>;
         fee_token: z.ZodOptional<z.ZodString>;
         closed_pnl: z.ZodOptional<z.ZodString>;
-        direction: z.ZodOptional<z.ZodEnum<["Open Long", "Open Short", "Close Long", "Close Short"]>>;
+        direction: z.ZodOptional<z.ZodString>;
         start_position: z.ZodOptional<z.ZodString>;
         source: z.ZodOptional<z.ZodEnum<["s3", "ws", "api", "live"]>>;
         user_address: z.ZodOptional<z.ZodString>;
@@ -2054,7 +2054,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee?: string | undefined;
         fee_token?: string | undefined;
         closed_pnl?: string | undefined;
-        direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+        direction?: string | undefined;
         start_position?: string | undefined;
         source?: "s3" | "ws" | "api" | "live" | undefined;
         user_address?: string | undefined;
@@ -2073,7 +2073,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee?: string | undefined;
         fee_token?: string | undefined;
         closed_pnl?: string | undefined;
-        direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+        direction?: string | undefined;
         start_position?: string | undefined;
         source?: "s3" | "ws" | "api" | "live" | undefined;
         user_address?: string | undefined;
@@ -2107,7 +2107,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee?: string | undefined;
         fee_token?: string | undefined;
         closed_pnl?: string | undefined;
-        direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+        direction?: string | undefined;
         start_position?: string | undefined;
         source?: "s3" | "ws" | "api" | "live" | undefined;
         user_address?: string | undefined;
@@ -2134,7 +2134,7 @@ declare const TradeArrayResponseSchema: z.ZodObject<{
         fee?: string | undefined;
         fee_token?: string | undefined;
         closed_pnl?: string | undefined;
-        direction?: "Open Long" | "Open Short" | "Close Long" | "Close Short" | undefined;
+        direction?: string | undefined;
         start_position?: string | undefined;
         source?: "s3" | "ws" | "api" | "live" | undefined;
         user_address?: string | undefined;

package/dist/index.js

@@ -108,7 +108,11 @@ var HttpClient = class {
     if (params) {
       for (const [key, value] of Object.entries(params)) {
         if (value !== void 0 && value !== null) {
-          url.searchParams.set(key, String(value));
+          if (value instanceof Date) {
+            url.searchParams.set(key, String(value.getTime()));
+          } else {
+            url.searchParams.set(key, String(value));
+          }
         }
       }
     }
@@ -188,12 +192,7 @@ var OrderBookSchema = import_zod.z.object({
   spread_bps: import_zod.z.string().optional()
 });
 var TradeSideSchema = import_zod.z.enum(["A", "B"]);
-var TradeDirectionSchema = import_zod.z.enum([
-  "Open Long",
-  "Open Short",
-  "Close Long",
-  "Close Short"
-]);
+var TradeDirectionSchema = import_zod.z.string();
 var DataSourceSchema = import_zod.z.enum(["s3", "ws", "api", "live"]);
 var TradeSchema = import_zod.z.object({
   coin: import_zod.z.string(),