WebSocket API - 0xArchive

Use WebSocket when you need a stream instead of a single REST response. The same socket runs live subscriptions and replay workflows.

Connect

Decide what to set before you connect, then open the socket, authenticate, keep it alive, and reconnect cleanly.

Keep alive

Ping/pong, idle timeout, backoff, and resubscription discipline.

Channels

Subscribe to order books, trades, L4 diffs, HIP-3, HIP-4, and Lighter channels.

Real-time streams

Choose WebSocket when live updates and sequence matter.

L4 order book

Maintain stateful L4 books with snapshots, diffs, gaps, and replay.

Replay

Play historical sequences at a controlled speed and handle gap messages.

Backtesting

Use replay windows for deterministic research and strategy checks.

Message schema

Use documented command and event shapes for clients and agents.

Limits

Size subscriptions, replay jobs, and reconnection behavior for your plan.

Tier limits

Match subscription count, replay speed, and concurrency to plan limits.

Latency, freshness, and infrastructure boundaries

The canonical customer endpoint is wss://api.0xarchive.io/ws. Current WebSocket health is an HTTP service check, not a client connection-time or round-trip measurement. The service does not publish a stable numeric WebSocket latency claim. Keep these measurements separate: HTTP service health, server-side REST handler timing, stored-data freshness, ingest lag, WebSocket upgrade/connect time, application ping/pong round-trip time, and client processing lag. In the data-quality response, websocket.current_ms is the latest stored order-book freshness value, not client WebSocket round-trip time. There is no published end-to-end WebSocket latency percentile today. A client can measure one session with the native application ping/pong messages. Send {"op":"ping"} and time the response {"type":"pong"}. That result describes the requesting client’s path and processing, not a platform-wide claim. 0xArchive does not sell a general Hyperliquid node or RPC service and does not publish deployment topology here. The docs do not make region, co-location, or root-cause claims about infrastructure.

Server-Side Smoke Test

This query-string form is for server-side smoke tests and private scripts. Do not paste a real API key into browser code, public prompts, logs, screenshots, or shared notebooks; browser apps should connect through your backend.

const apiKey = process.env.OXARCHIVE_API_KEY;
const ws = new WebSocket(`wss://api.0xarchive.io/ws?apiKey=${encodeURIComponent(apiKey)}`);

ws.onopen = () => {
  ws.send(JSON.stringify({ op: "subscribe", channel: "orderbook", symbol: "BTC" }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log(message);
};

When To Use WebSocket

Use WebSocket when sequence matters. Live subscriptions are useful for monitors, dashboards, and local books that need updates after an initial state. Replay is useful for backtests, incident review, reconstruction, and workflows where event order carries meaning. If the job only needs one current order-book snapshot or one bounded trade list, REST is usually simpler and easier to retry. For a Hyperliquid-focused overview of live channels, replay speeds, and depth choices, start with the Hyperliquid WebSocket Streaming API. Every WebSocket client should implement four paths: open and authenticate, subscribe or start replay, handle messages, and recover from close or gap signals. A client that only handles happy-path messages will eventually corrupt a local stateful workflow. Keep reconnection and resubscription explicit, and route gap handling to the same data-quality policy used by REST jobs.

Stream Execution Checklist

Before writing WebSocket code or handing the task to an agent, capture the stream checklist.

Field	Example
Mode	Live subscription or historical replay
Venue family	Hyperliquid core, Spot, HIP-3, HIP-4, or Lighter
Channel and symbol	`orderbook` + `BTC`, HIP-3 L4 diffs + `km:US500`, or Lighter order book + `BTC`
State model	Snapshot only, local book, alert stream, replay output, or dashboard state
Gap policy	Mark unsafe, rebuild from snapshot, rerun replay, or stop the job
Limit	One channel-symbol pair, bounded replay window, retry budget, and output destination
Metadata	Connection id, active subscription checklist, timestamps, gap events, and request or correlation IDs

If the checklist is incomplete, start with REST or a one-channel sample instead of a broad streaming client.

Contract Boundaries

WebSocket is a command-and-event surface. Client commands use op values such as subscribe, unsubscribe, replay, replay.pause, replay.resume, replay.seek, replay.stop, and ping. Server replay events use event names such as replay_started, replay_snapshot, historical_data, replay_completed, and gap_detected. Use WebSocket message schema before building typed handlers. Do not infer event names from the replay-control command names; replay.pause is a client command, while replay_paused is a server event.

Message Discipline

Do not mix venue families inside one channel assumption. A HIP-3 channel should use HIP-3 symbols such as km:US500. Lighter channels should stay in the Lighter namespace. If the stream feeds a model, alert, or strategy harness, store enough message metadata to reconstruct what channel, symbol, time window, and request produced the state.

Choosing Between REST And WebSocket

Use WebSocket when sequence matters or live updates drive the job. Use REST when a single snapshot or bounded historical window answers the question. If local state, replay order, or continuous updates matter, WebSocket is the right surface. If not, a REST call is simpler to retry and audit.

Connect

Keep alive

Channels

Real-time streams

L4 order book

Replay

Backtesting

Message schema

Limits

Tier limits

​Latency, freshness, and infrastructure boundaries

​Server-Side Smoke Test

​When To Use WebSocket

​Stream Execution Checklist

​Contract Boundaries

​Message Discipline

​Choosing Between REST And WebSocket

Latency, freshness, and infrastructure boundaries

Server-Side Smoke Test

When To Use WebSocket

Stream Execution Checklist

Contract Boundaries

Message Discipline

Choosing Between REST And WebSocket