Skip to main content
Use WebSocket when you need a stream instead of a single REST response. The same surface supports 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.

​
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.
FieldExample
ModeLive subscription or historical replay
Venue familyHyperliquid core, Spot, HIP-3, HIP-4, or Lighter
Channel and symbolorderbook + BTC, HIP-3 L4 diffs + km:US500, or Lighter order book + BTC
State modelSnapshot only, local book, alert stream, replay output, or dashboard state
Gap policyMark unsafe, rebuild from snapshot, rerun replay, or stop the job
LimitOne channel-symbol pair, bounded replay window, retry budget, and output destination
MetadataConnection 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.
Last modified on July 4, 2026