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

#	Name	Type	Required	Description
1	`subscriptionId`	string	Yes	The hex subscription ID returned by eth_subscribe.

Response

Type	Description
boolean	`true` if the subscription was found and cancelled. `false` if it did not exist.

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

Code	Message	Cause
`-32602`	`invalid subscription id`	The subscription ID is malformed or belongs to a different connection.
`-32000`	`subscription not found`	The subscription was already cancelled or never existed.

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