WebSockets

Build real-time apps on Conduit using WebSocket subscriptions.

Quick start: connect to Conduit WebSockets

Open a connection using the WSS URL from your Nodes dashboard. The URL is shown next to each API key and may include a path segment. Use that exact value.

Example using wscat:

wscat -c wss://rpc-[YOUR_NETWORK_SLUG].t.conduit.xyz/<API_KEY>

To create or manage keys, see Get an API key.

What are WebSockets?

WebSockets is a bidirectional protocol that keeps a persistent connection between a client and a server. Unlike HTTP, clients don’t need to poll for updates. With an open WebSocket connection, the server can push network updates to subscribed clients (for example, when new blocks are produced or matching logs are found).

When to use HTTP instead of WebSockets

Use HTTPS for standard JSON-RPC requests (eth_call, eth_getBlockByNumber, eth_sendRawTransaction). Reserve WebSockets for push-style subscriptions.

Why HTTP is often better for requests:

1. Reliability and error signals: HTTP provides status codes and mature retry tooling; WebSockets can fail silently without careful client handling
2. Load balancing: Each HTTP request is routed to the healthiest backend; a long-lived WebSocket stays on one node
3. Retries and backoff: HTTP clients commonly support automatic retries and backoff; WebSocket JSON-RPC requires custom id tracking and reconnect logic
4. Compression: HTTP compression can reduce bandwidth for large payloads

Subscriptions: real-time updates

After connecting, use standard Ethereum JSON-RPC methods to manage subscriptions:

• eth_subscribe
• eth_unsubscribe

Examples

Subscribe to new heads:

{ "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newHeads"] }

Subscribe to logs for an address and topic:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0x0000000000000000000000000000000000000000",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
      ]
    }
  ]
}

Unsubscribe:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "eth_unsubscribe",
  "params": ["<SUBSCRIPTION_ID>"]
}

Connection management

• Use exponential backoff with jitter when reconnecting and resubscribing
• Send application-level heartbeats if your client or environment doesn’t automatically respond to ping/pong
• Deduplicate messages by block number or transaction hash when reconnecting
• Limit the number of concurrent subscriptions per connection; scope filters narrowly

Limits and throughput

• WebSocket traffic counts toward your organization’s throughput. See Throughput
• Avoid very large subscription result sets; filter by address and topics
• If the connection is idle for an extended period, servers may close it. Reconnect with backoff

Best practices checklist

• Keep one WebSocket per service; avoid opening many connections
• Scope subscriptions narrowly (filter by address and topics)
• Reconnect with exponential backoff and jitter; resubscribe on reconnect
• Implement heartbeats or respond to ping/pong
• Fall back to HTTP for historical scans and catch-up reads