Skip to main content
Use one Relayer WebSocket connection to send control messages and receive events for subscribed topics.

​
Definition

Client-to-server messages are control messages. A control message has an action, optional requestId, and action-specific fields. Server-to-client messages are acknowledgments or pushed events.

​
Lifecycle

1

Connect

Open wss://relayer.xoxno.com/ws for subscriptions, broadcast, and relay. Use wss://relayer.xoxno.com/ws/stats only for push-only network stats.
2

Subscribe

Send {"action":"subscribe","topic":"..."} for each topic you need.
3

Read the acknowledgment

Match requestId when present. Acknowledgment success means the Relayer accepted the control message; future event delivery still depends on matching chain activity.
4

Process events

Branch on type, such as gasStats, networkStats, accountDelta, or txStatus.
5

Unsubscribe and reconnect

Unsubscribe from topics you no longer need. After reconnect, re-send subscriptions because topic state belongs to the prior connection.

​
Limits

ActionLimit
Active topics64 per connection
Message size4 MB
Gas stats debounce50 ms, with 5 s periodic fallback
Network stats intervalAdaptive, default about 6 s, clamped 500 ms to 30 s

​
Worked Example

const ws = new WebSocket("wss://relayer.xoxno.com/ws");

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    action: "subscribe",
    requestId: "gas-1",
    topic: "gasStats"
  }));
});

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  if (msg.action === "subscribe") console.log("ack", msg.status);
  if (msg.type === "gasStats") console.log("gas", msg.data);
});

​
Reconnect Rules

CaseClient action
Socket closesReconnect with exponential backoff and jitter
Reconnect succeedsRe-subscribe to required topics
Topic limit reachedUnsubscribe from inactive topics or open another connection
Duplicate event riskDe-duplicate by transaction hash, address and nonce, or event timestamp depending on topic