Subscribe to events by using either RPC Pub/Sub over WebSockets or filters over HTTP.
Use RPC Pub/Sub over WebSockets to wait for events instead of polling for them. For example, dapps subscribe to logs and receive notifications when a specific event occurs.
Methods specific to RPC Pub/Sub are:
eth_subscribe and eth_unsubscribe - create or cancel a subscription for specific events.
!!!important
Unlike other [ClishaChain API methods](../../reference/api/index.md), you cannot call
the RPC Pub/Sub methods over HTTP. Use the
[`--rpc-ws-enabled`](../../reference/cli/options.md#rpc-ws-enabled) option to enable the
WebSockets JSON-RPC service.
To create subscriptions, use eth_subscribe or priv_subscribe. Once subscribed, the API publishes notifications using eth_subscription or priv_subscription.
Subscriptions couple with connections. If a connection is closed, all subscriptions created over the connection are removed.
Subscription ID
eth_subscribe and priv_subscribe return a subscription ID for each subscription created. Notifications include the subscription ID.
!!!example
For example, to create a synchronizing subscription:
```json
{"id": 1, "method": "eth_subscribe", "params": ["syncing"]}
```
The result includes the subscription ID of `"0x1"`:
```json
{"jsonrpc":"2.0","id":1,"result":"0x1"}
```
The notifications also include the subscription ID of `"0x1"`:
```json
{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{"startingBlock":"0x0","currentBlock":"0x50","highestBlock":"0x343c19"}}}
```
Notifications when synchronizing
Subscribing to some events (for example, logs) can cause a flood of notifications while the node is synchronizing.
Subscribe
Use eth_subscribe to create subscriptions for the following event types:
To notify you about each block added to the blockchain, use the newHeads parameter with eth_subscribe.
If a chain reorganization occurs, the subscription publishes notifications for blocks in the new chain. This means the subscription can publish notifications for multiple blocks at the same height on the blockchain.
The new headers notification returns block objects. The second parameter is optional. If specified, the notifications include whole transaction objects, Otherwise, the notifications include transaction hashes.
To notify you about logs included in new blocks, use the logs parameter with eth_subscribe or priv_subscribe. Specify a filter object to receive notifications only for logs matching your filter.
Logs subscriptions have an filter object parameter with the following fields:
address - (optional) Either an address or an array of addresses. Returns only logs created from these addresses.
topics - (optional) Returns only logs that match the specified topics.
fromBlock - (optional) The earliest block from which to return logs.
toBlock - (optional) The last block from which to return logs.
For private contracts, the privacy group ID must be specified. Only members of a privacy group receive logs for a private contract subscription. If you create a subscription for a privacy group you are not a member of, you will not receive any notifications.
If a chain reorganization occurs, the subscription publishes notifications for logs from the old chain with the removed property in the log object set to true. This means the subscription can publish notifications for multiple logs for the same transaction.
To notify you about pending transactions added to the transaction pool for the node, use the newPendingTransactions parameter with eth_subscribe.
The pending transactions subscription returns the transaction hashes or transaction details of the pending transactions. If the includeTransactions parameter is not included, the default is transaction hashes only.
If a chain reorganization occurs, Clisha Chain resubmits transactions for inclusion in the new canonical chain. This means the subscription can publish notifications for the same pending transaction more than once.
!!!example "Transaction hashes"
To subscribe to pending transaction notifications and receive transaction hashes only:
```json
{"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions", {"includeTransactions":false}]}
```
Example result:
```json
{"jsonrpc":"2.0","id":1,"result":"0x1"}
```
Example notification:
```json
{
"jsonrpc":"2.0",
"method":"eth_subscription",
"params":{
"subscription":"0x1",
"result":"0x5705bc8bf875ff03e98adb98489428835892dc6ba6a6b139fee1becbc26db0b8"
}
}
```
!!!example "Transaction details"
To subscribe to pending transaction notifications and receive transaction details:
```json
{"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions", {"includeTransactions":true}]}
```
Example result:
```json
{"jsonrpc":"2.0","id":1,"result":"0x2"}
```
Example notification:
```json
{
"jsonrpc":"2.0",
"method":"eth_subscription",
"params":{
"subscription":"0x2",
"result":{
"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
"gas":"0x5208",
"gasPrice":"0x2540be400",
"hash":"0x7a4185f40ee93cb27eb132f301d0a5414c1f871051f166fc8804c376aab3ffec",
"input":"0x",
"nonce":"0x13",
"to":"0x9d8f8572f345e1ae53db1dfa4a7fce49b467bd7f",
"value":"0x8ac7230489e80000",
"v":"0xfe7",
"r":"0xdd9013c67469d2fe79afdc61777c55bdced33c90fa6f9b83d8f9b7e445085123",
"s":"0x45823a1ab22ae9c83876ea435dc5ecc4fe3a83c1bfbc340a5f57df2f5a474fa5"
}
}
}
```
Dropped transactions
To notify you about transactions dropped from the transaction pool for the node, use the droppedPendingTransactions parameter with eth_subscribe.
The dropped transactions subscription returns the transaction hashes of the dropped transactions.
Dropped transactions can be re-added to the transaction pool from a variety of sources. For example, receiving a previously dropped transaction from a peer. As a result, it's possible to receive multiple dropped transaction notifications for the same transaction.
!!!example
To subscribe to dropped transaction notifications:
```json
{"id": 1, "method": "eth_subscribe", "params": ["droppedPendingTransactions"]}
```
Example result:
```json
{"jsonrpc":"2.0","id":1,"result":"0x1"}
```
Example notification:
```json
{
"jsonrpc":"2.0",
"method":"eth_subscription",
"params":{
"subscription":"0x1",
"result":"0xf57d6a90a7fb30880cfbdf6b432b487d0e94a3b55b34dc4b45e3b0b237ecab4c"
}
}
```
Synchronizing
To notify you about synchronization progress, use the syncing parameter with eth_subscribe.
When behind the chain head, the synchronizing subscription returns an object indicating the synchronization progress. When fully synchronized, returns false.
!!!example
To subscribe to synchronizing notifications:
```json
{"id": 1, "method": "eth_subscribe", "params": ["syncing"]}
```
Example result:
```json
{"jsonrpc":"2.0","id":1,"result":"0x4"}
```
Example notification while synchronizing:
```json
{
"jsonrpc":"2.0",
"method":"eth_subscription",
"params":{
"subscription":"0x4",
"result":{
"startingBlock":"0x0",
"currentBlock":"0x3e80",
"highestBlock":"0x67b93c"
}
}
}
```
Example notification when synchronized with chain head:
```json
{
"jsonrpc":"2.0",
"method":"eth_subscription",
"params":{
"subscription":"0x4",
"result":false
}
}
```
Unsubscribe
To cancel a subscription, use the subscription ID with eth_unsubscribe. Only the connection that created a subscription can unsubscribe from it.
eth_unsubscribe and priv_unsubscribe return true if subscription successfully unsubscribed; otherwise, returns an error.
!!!example
To unsubscribe from a subsciption with subscription ID of `0x1`:
```json
{"id": 1, "method": "eth_unsubscribe", "params": ["0x1"]}
```
Example result:
```json
{"jsonrpc":"2.0","id":1,"result":true}
```
