SDK WebSocket usage

Use SDK WebSocket helpers when you want reconnection handling, message typing, and subscription state in application code.

import { OxArchiveWs } from "@0xarchive/sdk";

async function main() {
  const apiKey = process.env.OXARCHIVE_API_KEY;
  if (!apiKey) throw new Error("Set OXARCHIVE_API_KEY");

  const ws = new OxArchiveWs({ apiKey });
  ws.onOrderbook((coin, data) => {
    console.log(coin, data.midPrice);
  });

  await ws.connect();
  ws.subscribeOrderbook("BTC");
}

void main();

Python

import asyncio
from os import environ
from oxarchive import OxArchiveWs, WsOptions

async def main():
    ws = OxArchiveWs(WsOptions(api_key=environ["OXARCHIVE_API_KEY"]))

    ws.on_historical_data(lambda symbol, timestamp, data: print(symbol, timestamp))
    ws.on_gap(lambda channel, symbol, start, end, minutes: print("gap", channel, symbol, minutes))

    await ws.connect()
    await ws.replay(
        "orderbook",
        "BTC",
        start=1704067200000,
        end=1704153600000,
        speed=10,
    )

asyncio.run(main())

Connection

Raw WebSocket connection pattern.

Replay

Historical playback commands and gap handling.

SDK Responsibilities

An SDK WebSocket helper should reduce boilerplate without hiding stream risk. The caller still needs to know when the socket opened, which channels are active, whether a replay is running, and whether a gap or reconnect made local state unsafe. Use helpers for connection setup, subscription state, typed messages, and reconnection. Keep application-level policy in your code: whether to pause, resync, rebuild a book, retry a replay window, or mark output incomplete. That separation keeps market-data correctness visible in code review.

Connection Contract

Use connection callbacks to record stream state instead of treating connect() as the whole workflow.

ws.connect({
  onOpen: () => console.log("connected"),
  onClose: (code, reason) => console.log("closed", code, reason),
  onError: (error) => console.error("websocket error", error)
});

Track active subscriptions, latest message time, reconnect count, and unsafe symbols in application state. SDK reconnect behavior can restore transport, but the app still decides whether a local book, alert, or replay output is safe after a close or gap.

Replay And Gap Callbacks

Historical replay data arrives through replay-specific callbacks, not through the same live subscription callbacks. The typed onHistoricalData callback receives coin, timestamp, and data, but not channel. Use the generic onMessage callback when a multi-channel run or a run manifest must retain the channel field.

ws.onHistoricalData((coin, timestamp, data) => {
  console.log(new Date(timestamp).toISOString(), coin, data);
});

ws.onGap((channel, coin, gapStart, gapEnd, durationMinutes) => {
  console.warn("gap", channel, coin, gapStart, gapEnd, durationMinutes);
});

ws.replay("orderbook", "BTC", {
  start: Date.now() - 86_400_000,
  end: Date.now(),
  speed: 10
});

For standard timed replay, store channel, symbol, start, end, and speed with the output. Treat the value as the effective speed reported by replay_started; it does not apply to core L4. For core L4, store delivery: checkpoint_anchored_bulk and checkpoint metadata instead. Also retain the l4_snapshot anchor and ordered l4_batch count. Preserve gap callbacks and the output destination for either delivery model. Use WebSocket replay when the event sequence is the product requirement. For multi-channel replay, send a bounded non-empty channels list with one symbol. The server rejects duplicate channels, mixed exchange families, and core L4 channels in a multi-channel request; core L4 replay is single-channel only. Keep channel and channels mutually exclusive in application code even though the server gives channels precedence when both are sent.

SDK Event Checklist

SDK helpers may wrap raw WebSocket messages, but the underlying event model still matters.

Event class	What to preserve
Connection	open time, close code, close reason, retry count, and active subscriptions
Live data	channel, symbol, venue family, timestamp, and latest applied state
Replay start	channel or channels, symbol, start, end, delivery model, standard replay speed when applicable, and output destination
Standard replay snapshot	`replay_snapshot` baseline before `historical_data` messages
Core L4 baseline	`l4_snapshot` before one or more `l4_batch` events
Replay data	timestamp, channel, symbol, event type, and emitted order
Gaps	`gap_detected` interval, duration, affected output, and rebuild decision
Terminal state	`replay_completed`, `replay_stopped`, retry budget exhausted, or consumer stopped

The TypeScript client exposes l4_snapshot and l4_batch through its generic onMessage handler rather than a dedicated typed L4 callback. Python provides dedicated L4 snapshot and batch callbacks, while Rust delivers decoded server messages through OxArchiveWs.rx. In all runtimes, apply a core L4 snapshot before its ordered batches and rebuild after an unsafe sequence or reconnect.

Testing A Stream

Test with one channel and one symbol before widening. Confirm open, message, close, reconnect, unsubscribe, and gap paths. For standard replay, store the input window and speed with the output. For core L4, store the input window, delivery model, and checkpoint metadata. For live streams, store the first snapshot timestamp and the latest applied update timestamp.

Bulk WebSocket operation

Some SDK releases still expose stream or multiStream methods for compatibility. The backend currently rejects stream and stream.stop with an error because bulk WebSocket streaming was discontinued. Use the Data Catalog for large file delivery; do not treat a successful socket connection as evidence that this operation is available.

Subscription Methods

Keep helper names tied to venue family.

Workflow	Example helper
Hyperliquid core order book	`ws.subscribeOrderbook("BTC")`
Live trades	`ws.subscribeTrades("ETH")`
HIP-4 live outcome trades	`ws.subscribeHip4("hip4_trades", "0")`
Spot pair	`ws.subscribeSpot("orderbook", "HYPE-USDC")`
Replay	`ws.replay("orderbook", "BTC", { start, end, speed })`

If a helper does not cover a route family, fall back to the raw WebSocket docs or REST/OpenAPI until the package exposes that route family.

Review Rule

WebSocket helper examples should never end at console.log. They should explain what happens after the message arrives: update UI state, append to a replay output, apply a book diff, mark a gap, or trigger a resync. Pair helpers with tests that simulate close, reconnect, replay snapshots, historical data, gap messages, and terminal replay events. A stream helper should show how the application behaves when history is incomplete, a socket closes, a replay pauses, or a resync starts.

API reference

SDKs & tooling

AI & agents

SDK WebSocket usage

Connection

Replay

SDK Responsibilities

Connection Contract

Replay And Gap Callbacks

SDK Event Checklist

Testing A Stream

Bulk WebSocket operation

Subscription Methods

Review Rule

Connection

Replay

​SDK Responsibilities

​Connection Contract

​Replay And Gap Callbacks

​SDK Event Checklist

​Testing A Stream

​Bulk WebSocket operation

​Subscription Methods

​Review Rule

SDK Responsibilities

Connection Contract

Replay And Gap Callbacks

SDK Event Checklist

Testing A Stream

Bulk WebSocket operation

Subscription Methods

Review Rule