WebSocket API - 0xArchive

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

Connect

Open the socket, authenticate, keep it alive, and reconnect cleanly.

Connecting

Startup checklist for URL, auth, close handling, and reconnect rules.

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.

Minimal Connection

const ws = new WebSocket("wss://api.0xarchive.io/ws?apiKey=0xa_your_api_key");

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. 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 Packet

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

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 packet, timestamps, gap events, and request or correlation IDs

If the packet 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.

Review Rule

Choose WebSocket because a stream is needed, not because it feels more advanced than REST. If a snapshot route answers the question, use REST. If local state, replay order, or live updates matter, WebSocket is the right primitive.

Documentation Index