eth_unsubscribe

eth_unsubscribe is the off-switch for the live event streams you open with eth_subscribe over a WebSocket connection to Ethereum mainnet (chain ID 1). When you subscribe to something like newHeads, logs, or newPendingTransactions, the node starts pushing a notification every time a new block is sealed (one per 12-second slot) or a matching event lands. To stop that flow, send eth_unsubscribe with the subscription ID you were handed at subscribe time. Note the transport: these methods only exist over WebSocket, so you call them against wss://ethereum.therpc.io/YOUR_API_KEY rather than the HTTPS endpoint used for one-shot ETH queries. The return is true when the subscription was found and cancelled, false when nothing matched the ID.

Use cases

• Shut off a newHeads stream the moment a user leaves a live block explorer view, so you stop paying for and processing one push every 12 seconds.
• Swap filters cleanly: when a user changes which contract addresses or topics they watch, unsubscribe the old logs subscription first, then open a fresh one with the new params.

Parameters

Response

Example request

1curl https://ethereum.therpc.io/YOUR_API_KEY \
2  -X POST \
3  -H "Content-Type: application/json" \
4  -d '{
5    "jsonrpc": "2.0",
6    "method": "eth_unsubscribe",
7    "params": ["0x1"],
8    "id": 1
9  }'

Try it live in the Ethereum playground.

Errors & troubleshooting

Common pitfalls

• A subscription is bound to the socket that created it. You have to call eth_unsubscribe on that same WebSocket connection; the ID is meaningless on any other one, which is why a stale ID returns the invalid subscription id error.
• Dropping the WebSocket cancels everything tied to it automatically, so explicit unsubscribe is technically optional. It is still worth doing on long-lived connections that stay open across many block heads, where leaked subscriptions would otherwise keep streaming data you no longer read.

Supported networks

• Mainnet — Chain ID: 1
• Sepolia — Chain ID: 11155111

See also

• eth_subscribe
• eth_uninstallFilter
• eth_getLogs

1curl https://ethereum.therpc.io/YOUR_API_KEY \
2  -X POST \
3  -H 'Content-Type: application/json' \
4  -d '{"jsonrpc":"2.0","id":1,"method":"eth_unsubscribe","params":[""]}'