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";

const ws = new OxArchiveWs({
  apiKey: process.env.OXARCHIVE_API_KEY!
});

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

ws.onOrderbook((symbol, data) => {
  console.log(symbol, data.midPrice);
});

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.

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

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

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

Store replay channel, symbol, start, end, speed, gap callbacks, and output destination with the result. Use WebSocket replay when the event sequence is the product requirement.

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, speed, and output destination
Replay snapshots	`replay_snapshot` baseline before `historical_data` messages
Replay data	timestamp, channel, symbol, 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

If the SDK only exposes higher-level callbacks, attach this checklist in the application logs or result manifest.

Testing A Stream

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

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 outcome market	`ws.subscribeHip4("hip4_orderbook", "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

Subscription Methods

Review Rule

Connection

Replay

​SDK Responsibilities

​Connection Contract

​Replay And Gap Callbacks

​SDK Event Checklist

​Testing A Stream

​Subscription Methods

​Review Rule

SDK Responsibilities

Connection Contract

Replay And Gap Callbacks

SDK Event Checklist

Testing A Stream

Subscription Methods

Review Rule