Subscriptions

eth_subscribe works as it does on any WebSocket endpoint. A WebSocket to the local gateway stays with one provider, and carries the subscription for as long as it is open.

ws://127.0.0.1:1337/service/ethereum

The WebSocket accepts ordinary JSON-RPC requests as well as subscription messages. It uses the same chain path as HTTP, with ws:// for the local gateway. For managed access, use the supplied WebSocket URL where available.

New heads

With wscat:

wscat -c ws://127.0.0.1:1337/service/ethereum
> { "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newHeads"] }
< { "jsonrpc": "2.0", "id": 1, "result": "0x9ce59a13056e85ae" }
< { "jsonrpc": "2.0", "method": "eth_subscription", "params": { "subscription": "0x9ce59a13056e85ae", "result": { "number": "0x16b3e4b", … } } }

With viem:

import { createPublicClient, webSocket } from "viem"
import { mainnet } from "viem/chains"

const client = createPublicClient({
  chain: mainnet,
  transport: webSocket("ws://127.0.0.1:1337/service/ethereum"),
})

const unwatch = client.watchBlockNumber({
  onBlockNumber: (n) => console.log("block", n),
})

With ethers:

import { WebSocketProvider } from "ethers"

const provider = new WebSocketProvider("ws://127.0.0.1:1337/service/ethereum")
provider.on("block", (n) => console.log("block", n))

Logs

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

Every notification arrives on the same WebSocket, tagged with the subscription id, exactly as the node sends it.

Unsubscribing

Send eth_unsubscribe with the subscription id, and the node stops sending notifications for it. The WebSocket stays open for other subscriptions and requests.

{ "jsonrpc": "2.0", "id": 3, "method": "eth_unsubscribe", "params": ["0x9ce59a13056e85ae"] }

Closing the WebSocket ends every subscription on it. Unsubscribe from what you no longer need: every notification counts as a request.

How a subscription is paid

The subscribe call and each notification are billed at the selected provider's request price. A busy logs subscription can therefore cost substantially more than a block-header subscription. Unsubscribe when the stream is no longer needed, and account for notification volume when estimating costs. See Pricing.