@0xarchive/sdk 0.3.3 → 0.3.5

package/README.md

@@ -21,7 +21,7 @@ const client = new OxArchive({ apiKey: 'ox_your_api_key' });
 
 // Get current order book
 const orderbook = await client.orderbook.get('BTC');
-console.log(`BTC mid price: ${orderbook.mid_price}`);
+console.log(`BTC mid price: ${orderbook.midPrice}`);
 
 // Get historical order book snapshots
 const history = await client.orderbook.history('ETH', {
@@ -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.midPrice}`);
 });
 
 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.midPrice}`);
 });
 
+// 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