WebSocket connection and authentication

Connect when you need streaming data or replay control. Use REST for one-off snapshots. WebSocket uses the same 0xArchive API-key credential as other clients, but supplies it during connection setup rather than through the REST X-API-Key header. Use API keys and credential safety for creation, storage, and rotation.

These query-string examples are 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.

Open the socket

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

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.

Before you connect

Connect to wss://api.0xarchive.io/ws. For server-side clients, prefer an Authorization: Bearer <api-key> handshake when the WebSocket library supports custom headers. The query-string API-key form remains a compatibility path for private server-side scripts; never expose it in browser code, logs, telemetry, or copied prompts. Decide these before you open the socket.

Decision	Why it matters
Stream or replay	Live subscriptions, replay, and a one-off REST pull each set the socket up differently
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 application {"op":"ping"} command and {"type":"pong"} response can measure one client’s application round-trip time. Treat that as a client-side observation, not a published platform latency percentile.

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

For server-side clients, prefer an Authorization: Bearer <api-key> handshake when the WebSocket library supports custom headers. The query-string apiKey form remains a compatibility path for private server-side scripts. 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. 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.

​Before you connect

​Keep Alive

​Reconnect Policy

​Auth And Secrets

​Message Loop

​Connection State Object

​Failure Classes

​Review Rule

Before you connect

Keep Alive

Reconnect Policy

Auth And Secrets

Message Loop

Connection State Object

Failure Classes

Review Rule