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

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

Try it live in the Ethereum playground.

Errors & troubleshooting

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

See also

• eth_unsubscribe
• eth_newFilter
• eth_getLogs
• eth_getFilterChanges

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_subscribe","params":["",null]}'