WebSockets

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. An API key is required — append it to the WSS URL as shown below.

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:

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

Subscribe to logs for an address and topic:

1
{
2
  "jsonrpc": "2.0",
3
  "id": 2,
4
  "method": "eth_subscribe",
5
  "params": [
6
    "logs",
7
    {
8
      "address": "0x0000000000000000000000000000000000000000",
9
      "topics": [
10
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
11
      ]
12
    }
13
  ]
14
}

Unsubscribe:

1
{
2
  "jsonrpc": "2.0",
3
  "id": 3,
4
  "method": "eth_unsubscribe",
5
  "params": ["<SUBSCRIPTION_ID>"]
6
}

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

Connection and subscription limits

Per-plan WebSocket session limits take effect later this quarter:

These limits are set well above what most customers use today. If you already connect with an API key, your existing traffic patterns are unlikely to be affected.

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