Skip to main content

WebSocket Subscriptions

For applications that need real-time updates — indexers, monitoring dashboards, live UIs — WebSocket subscriptions push events as they happen rather than requiring polling.

Endpoint​

The WebSocket endpoint is served at:

wss://rpc.bout.network

Standard eth_subscribe / eth_unsubscribe methods over the JSON-RPC 2.0 protocol.

Supported subscription topics​

TopicPurpose
newHeadsFires on every new block.
logsFires for events matching a filter.
newPendingTransactionsFires for each pending transaction accepted into the mempool.

Example: subscribing to new blocks​

import { ethers } from "ethers";

const provider = new ethers.WebSocketProvider("wss://rpc.bout.network");

provider.on("block", (blockNumber) => {
  console.log("New block:", blockNumber);
});

Example: subscribing to events​

const filter = {
  address: "0xYourContractAddress",
  topics: [ethers.id("Transfer(address,address,uint256)")]
};

provider.on(filter, (log) => {
  console.log("Log:", log);
});

On OXN, event topics and data are encrypted for encrypted transactions. See Confidentiality Model for the implications — a WebSocket subscriber sees ciphertext, and only decrypts if they are the caller who emitted the events.

Connection lifecycle​

Reconnection. WebSocket connections drop periodically due to network conditions. Applications should implement reconnection with exponential backoff.

let provider;
function connect() {
  provider = new ethers.WebSocketProvider("wss://rpc.bout.network");
  provider._websocket.on("close", () => {
    console.log("Connection closed, reconnecting in 5s");
    setTimeout(connect, 5000);
  });
  provider._websocket.on("error", (err) => console.error("WS error:", err));
}
connect();

Heartbeat. Some deployments send WebSocket ping frames to keep the connection alive. If your client doesn't respond, the connection may be dropped.

Connection limits​

The public endpoint applies limits on:

  • Concurrent connections per source IP. If you need more, run a dedicated node.
  • Subscription count per connection. Distribute across multiple connections if needed.
  • Message throughput. Very chatty subscriptions (e.g. newPendingTransactions on a busy chain) may be throttled.

For heavy WebSocket usage, contact the team through Support or plan to self-host a node.

Debugging WebSocket issues​

provider._websocket.on("message", (data) => {
  console.log("Raw:", data.toString());
});
provider._websocket.on("close", (code, reason) => {
  console.log("Closed:", code, reason.toString());
});

Common failure codes:

  • 1000 — normal closure
  • 1001 — going away (server restart)
  • 1006 — abnormal closure (network issue)
  • 1008 — policy violation (usually rate limit)

Next steps​