eth_subscribe

BNB Smart Chain runs as chain ID 56 with BNB as its gas token, and eth_subscribe is the way to follow its ~3-second PoSA blocks as a live stream instead of by repeated requests. It opens a push-based subscription over a WebSocket connection. Subscribe to a topic, whether newHeads, logs, or newPendingTransactions, and the node pushes notifications your way the instant those events occur, which removes polling entirely. Being push-based, it has to run over a WebSocket: connect to the wss:// form of https://bsc.therpc.io/YOUR_API_KEY, and the call returns a hex subscription ID that tags every notification the node sends back.

Use cases

Stream newHeads block headers to power a real-time BNB Smart Chain dashboard that updates the instant each block seals, without any polling loop.
Subscribe to logs for a contract address to receive its events, for example Venus market updates, the moment they are mined.
Track newPendingTransactions to see transactions enter the BNB Smart Chain mempool before inclusion.

Parameters

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

Response

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

Example request

1curl https://bsc.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 BNB Smart Chain playground.

Errors & troubleshooting

Code	Meldung	Ursache
`-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 only works over a WebSocket; calling it on an HTTP transport returns a notifications not supported error, so always connect via wss://.
Anything emitted while your socket is down is gone for good, so add reconnect logic and backfill the gap with eth_getLogs once you are back online.
During a tip reorg the node may send logs notifications carrying removed: true; handle those explicitly so you roll back state for events that were un-mined.

Supported networks

Mainnet — Chain ID: 56
Testnet — Chain ID: 97

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

Typ

Beschreibung

string

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

Example request

1curl https://bsc.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  }'

Code

Meldung

Ursache

-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 only works over a WebSocket; calling it on an HTTP transport returns a notifications not supported error, so always connect via wss://.

Anything emitted while your socket is down is gone for good, so add reconnect logic and backfill the gap with eth_getLogs once you are back online.

During a tip reorg the node may send logs notifications carrying removed: true; handle those explicitly so you roll back state for events that were un-mined.

eth_subscribe

Use cases

Parameters

Response

Example request

Errors & troubleshooting

Common pitfalls

Supported networks

See also

Bereit, das in der Produktion aufzurufen?

eth_subscribe

Use cases

Parameters

Response

Example request

Errors & troubleshooting

Common pitfalls

Supported networks

See also