Package Exports
- @0xarchive/sdk
Readme
@0xarchive/sdk
Official TypeScript/JavaScript SDK for 0xarchive - Hyperliquid Historical Data API.
Installation
npm install @0xarchive/sdk
# or
yarn add @0xarchive/sdk
# or
pnpm add @0xarchive/sdkQuick Start
import { OxArchive } from '@0xarchive/sdk';
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}`);
// Get historical order book snapshots
const history = await client.orderbook.history('ETH', {
start: Date.now() - 86400000, // 24 hours ago
end: Date.now(),
limit: 100
});Configuration
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
});API Reference
Order Book
// Get current order book
const orderbook = await client.orderbook.get('BTC');
// Get order book at specific timestamp
const historical = await client.orderbook.get('BTC', {
timestamp: 1704067200000,
depth: 20 // Number of levels per side
});
// Get historical snapshots
const history = await client.orderbook.history('BTC', {
start: '2024-01-01',
end: '2024-01-02',
limit: 1000
});Trades
// 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,
end: Date.now(),
side: 'buy' // Optional: filter by side
});Instruments
// List all instruments
const instruments = await client.instruments.list();
// Get specific instrument
const btc = await client.instruments.get('BTC');Funding Rates
// Get current funding rate
const current = await client.funding.current('BTC');
// Get funding rate history
const history = await client.funding.history('ETH', {
start: Date.now() - 86400000 * 7,
end: Date.now()
});Open Interest
// Get current open interest
const current = await client.openInterest.current('BTC');
// Get open interest history
const history = await client.openInterest.history('ETH', {
start: Date.now() - 86400000,
end: Date.now()
});WebSocket Streaming
For real-time data, use the WebSocket client:
import { OxArchiveWs } from '@0xarchive/sdk';
const ws = new OxArchiveWs({ apiKey: 'ox_your_api_key' });
// Connect and set up handlers
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
ws.subscribeOrderbook('BTC');
ws.subscribeOrderbook('ETH');
// Subscribe to trades
ws.subscribeTrades('BTC');
// Subscribe to all tickers
ws.subscribeAllTickers();
// Typed handlers for specific data
ws.onOrderbook((coin, data) => {
console.log(`${coin} orderbook: ${data.mid_price}`);
});
ws.onTrades((coin, trades) => {
console.log(`${coin} new trades: ${trades.length}`);
});
// Unsubscribe
ws.unsubscribeOrderbook('ETH');
// Disconnect when done
ws.disconnect();Historical Replay (like Tardis.dev)
Replay historical data with timing preserved:
const ws = new OxArchiveWs({ apiKey: 'ox_...' });
ws.connect();
// Handle replay data
ws.onHistoricalData((coin, timestamp, data) => {
console.log(`${new Date(timestamp)}: ${data.mid_price}`);
});
ws.onReplayStart((channel, coin, start, end, speed) => {
console.log(`Starting replay from ${start} to ${end} at ${speed}x`);
});
ws.onReplayComplete((channel, coin, recordsSent) => {
console.log(`Replay complete: ${recordsSent} records`);
});
// Start replay at 10x speed
ws.replay('orderbook', 'BTC', {
start: Date.now() - 86400000, // 24 hours ago
speed: 10
});
// Control playback
ws.replayPause();
ws.replayResume();
ws.replaySeek(1704067200000); // Jump to timestamp
ws.replayStop();Bulk Streaming (like Databento)
Fast bulk download for data pipelines:
const ws = new OxArchiveWs({ apiKey: 'ox_...' });
ws.connect();
const allData: OrderBook[] = [];
// Handle batched data
ws.onBatch((coin, records) => {
allData.push(...records.map(r => r.data));
});
ws.onStreamProgress((snapshotsSent) => {
console.log(`Sent: ${snapshotsSent} snapshots`);
});
ws.onStreamComplete((channel, coin, recordsSent) => {
console.log(`Downloaded ${recordsSent} records`);
});
// Start bulk stream
ws.stream('orderbook', 'ETH', {
start: Date.now() - 3600000, // 1 hour ago
end: Date.now(),
batchSize: 1000
});
// Stop stream if needed
ws.streamStop();WebSocket Configuration
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)
});Available Channels
| Channel | Description | Requires Coin |
|---|---|---|
orderbook |
L2 order book updates | Yes |
trades |
Trade/fill updates | Yes |
ticker |
Price and 24h volume | Yes |
all_tickers |
All market tickers | No |
Error Handling
import { OxArchive, OxArchiveError } from '@0xarchive/sdk';
try {
const orderbook = await client.orderbook.get('INVALID');
} catch (error) {
if (error instanceof OxArchiveError) {
console.error(`API Error: ${error.message}`);
console.error(`Status Code: ${error.code}`);
console.error(`Request ID: ${error.requestId}`);
}
}TypeScript Support
Full TypeScript support with exported types:
import type {
OrderBook,
Trade,
Instrument,
FundingRate,
OpenInterest
} from '@0xarchive/sdk';Requirements
- Node.js 18+
- Modern browsers with
fetchsupport
License
MIT