eth_subscribe

eth_subscribe opens a push-based stream over a WebSocket connection to an Ethereum node. Instead of polling on a timer, you subscribe once and the node sends eth_subscription notifications as events happen. Four subscription types are supported: newHeads for each new block header (about one per 12-second slot under PoS), logs for event logs matching an address-and-topics filter, newPendingTransactions for mempool hashes, and syncing for changes in the node's sync state. Because this is a stateful streaming method, it requires the WebSocket endpoint wss://ethereum.therpc.io/YOUR_API_KEY on chain ID 1, not the plain HTTP path. The call returns a hex subscription ID, and you tear the stream down with eth_unsubscribe.

Use cases

Subscribe to newHeads to drive a live dashboard or block-explorer view, reacting the instant each Ethereum block header arrives instead of polling for the chain head.
Use a logs subscription with a contract address and topic set to receive smart-contract events, such as Aave borrows or an ERC-721 mint, the moment the blocks carrying them are gossiped.
Watch newPendingTransactions to observe transactions entering the mempool, feeding a fee tracker or front-running-aware order flow.

Parameters

#	Name	Type	Required	Description
1	`subscriptionType`	string	Yes	Subscription type: `newHeads` — new block headers; `logs` — matching event logs; `newPendingTransactions` — pending tx hashes; `syncing` — node sync status changes.
2	`filter`	object	No	Required only for `logs` subscriptions. Same filter shape as eth_newFilter: `address` and/or `topics`.

Response

Type	Description
string	Hex subscription ID. Subsequent notifications arrive as `eth_subscription` messages with `params.subscription` matching this ID.

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_subscribe",
7    "params": [
8        "newHeads",
9        {}
10      ],
11    "id": 1
12  }'

Try it live in the Ethereum playground.

Errors & troubleshooting

Code	Message	Cause
`-32602`	`invalid argument`	Unknown subscription type or malformed filter for a logs subscription.
`-32000`	`notifications not supported`	Method called over an HTTP connection instead of WebSocket.

Common pitfalls

This method is WebSocket-only. Call it over an HTTP transport and the node returns a notifications-not-supported error, so connect to wss://ethereum.therpc.io/YOUR_API_KEY.
A dropped WebSocket loses every event that fired while you were disconnected. Add reconnect logic, and after reconnecting backfill the gap with eth_getLogs over the missed block range so you do not silently skip events.
During a reorg at the chain head, logs notifications can arrive with removed: true to retract a previously delivered log. Handle these explicitly, since an event you acted on may end up off the canonical chain before it reaches the finalized tag.

Supported networks

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