WebSocket connection and authentication

Connect when you need streaming data or replay control. Use REST for one-off snapshots. This connection setup uses the same 0xArchive API-key credential as other clients, supplied in the opening handshake as Authorization: Bearer $OXARCHIVE_API_KEY rather than the REST X-API-Key header. Use API keys and credential safety for creation, storage, and rotation.

Keep WebSocket credentials on the server. Browser WebSocket clients cannot set a custom Authorization header, so browser apps should connect through your backend. Never expose a real API key in browser code, public prompts, logs, screenshots, or shared notebooks.

Open the socket

import WebSocket from "ws";

const apiKey = process.env.OXARCHIVE_API_KEY;
if (!apiKey) throw new Error("Set OXARCHIVE_API_KEY");

const ws = new WebSocket("wss://api.0xarchive.io/ws", {
  headers: { Authorization: `Bearer ${apiKey}` }
});

Wait for the transport to open

ws.onopen = () => {
  // `open` confirms transport and authentication only.
  ws.send(JSON.stringify({ op: "subscribe", channel: "orderbook", symbol: "BTC" }));
};

Confirm the requested operation

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === "subscribed") console.log("subscription accepted");
  if (message.type === "error") console.error(message.message);
};

A successful handshake is not a successful subscription or replay. Wait for subscribed after subscribe, or replay_started after replay.

Reconnect with backoff

Reconnect after close or network failure with capped backoff. Resubscribe only after the new socket opens, then rebuild state that depended on the old stream.

Connection Setup

Connect with Authorization: Bearer $OXARCHIVE_API_KEY in the opening handshake. The socket URL is wss://api.0xarchive.io/ws. The shell variable keeps the real credential out of the copied command. Use a server-side WebSocket library that supports custom headers. Browser clients should connect through your backend so the API key remains server-side. Decide these before you open the socket.

Decision	Why it matters
Stream or replay	Live subscriptions and replay use different command and event flows
Channel family	Keeps core, Spot, HIP-3, HIP-4, and Lighter subscriptions from mixing
Symbol format	Keeps pair symbols, builder prefixes, and outcome identifiers intact
Consumer capacity	Prevents message backlog and stale local state
Reconnect and gap policy	Decides when a downstream job continues, pauses, or rebuilds

Keep Alive

The server sends a WebSocket ping frame every 30 seconds and tracks pong activity. A connection with active subscriptions can be closed after 60 seconds without activity; a connection with no subscriptions has a 300-second idle window. WebSocket libraries normally answer native ping frames automatically. The application {"op":"ping"} command receives {"type":"pong"} and can measure one client’s application round-trip time. Treat that as a client-side observation, not a published platform latency percentile.

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

ws.onclose = () => clearInterval(pingTimer);

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

For server-side clients, send Authorization: Bearer $OXARCHIVE_API_KEY during the opening handshake. Load the key from the environment or application secret store, and never expose it in browser URLs, logs, telemetry, or copied prompts. Browser clients should connect through your backend.

Message Loop

Parse every message defensively. Expected classes include subscription acknowledgements, snapshots, updates, replay messages, pings or pongs, gap signals, and errors. The WebSocket error event contains a human-readable message; preserve it with the connection state. 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 standard 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.

Connect

Stream

Replay

Webhooks

WebSocket connection and authentication

Connection Setup

Keep Alive

Reconnect Policy

Auth And Secrets

Message Loop

Connection State Object

Failure Classes

Review Rule

​Connection Setup

​Subscribe after open

​Keep Alive

​Reconnect Policy

​Auth And Secrets

​Message Loop

​Connection State Object

​Failure Classes

​Review Rule

Connection Setup

Subscribe after open

Keep Alive

Reconnect Policy

Auth And Secrets

Message Loop

Connection State Object

Failure Classes

Review Rule