WebSocket Connection

Connect when you need streaming data or replay control. Use REST for one-off snapshots.

Open the socket

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

Subscribe after open

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

Parse every message

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

Reconnect with backoff

Reconnect after close or network failure with capped backoff. Resubscribe only after the new socket opens.

Keep Alive

setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ op: "ping" }));
  }
}, 25_000);

Reconnect Policy

Reconnect with capped exponential backoff and jitter. Do not reconnect in a tight loop. After a new socket opens, resubscribe explicitly and rebuild any local state that depended on the previous stream. If the stream feeds a local book, replay window, alert, or model, treat the reconnect as a state transition that needs logging.

Auth And Secrets

Use an API key from the environment or application secret store. The inline apiKey example is useful for a minimal connection, but production clients should avoid leaking keys into logs, browser URLs, telemetry, or copied prompts. If the client runs in a browser, proxy through your backend rather than exposing the key to users.

Message Loop

Parse every message defensively. Expected classes include subscription acknowledgements, snapshots, updates, replay messages, pings or pongs, gap signals, and errors. Preserve any request or correlation identifiers that appear in the message so a streaming issue can be tied back to the connection session.

Connection State Object

Use a local state object so reconnects and support logs describe the same stream.

const streamState = {
  status: "connecting",
  activeSubscriptions: new Map(),
  lastMessageAt: null,
  retryCount: 0,
  gapEvents: [],
  unsafeSymbols: new Set()
};

Update it inside onopen, onmessage, onerror, and onclose. When the socket closes, clear old timers, move the status to reconnecting, open a new socket with backoff, then restore subscriptions from activeSubscriptions. If a gap arrives for a stateful channel, add the symbol to unsafeSymbols until the client rebuilds from a snapshot or replay checkpoint.

Failure Classes

Failure	Client response
Auth or command error	Stop widening the stream and inspect key, command, channel, and symbol
Network close	Reconnect with capped backoff and restore tracked subscriptions
Repeated close loop	Stop after the configured retry budget and alert the owning job
Gap event	Mark derived local state incomplete until it is rebuilt
Consumer backlog	Reduce channel count, slow replay, or move heavy work off the message callback

Review Rule

Connection examples should include close and error handling before they are copied into an application that maintains state. The reconnect path should recreate subscriptions from tracked state, not by replaying stale assumptions. Log close code, reason, retry count, and restored subscriptions so support can distinguish normal network churn from a broken consumer or bad auth state.

Documentation Index

​Keep Alive

​Reconnect Policy

​Auth And Secrets

​Message Loop

​Connection State Object

​Failure Classes

​Review Rule