Connect when you need streaming data or replay control. Use REST for one-off snapshots.
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
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
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()
};
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. 
