Subscribe module

eth_subscribe
Starts a subscription to specific event. For every event matching subscription, JSON-RPC notification with event details and subscription ID will be sent to a client.
Subscriptions are created with a regular RPC call, with eth_subscribe as method and subscription type as first parameter. If successful, returns subscription ID.
Parameters
Parameter
Type
Description
subscriptionType
string
Type of subscription you want to subscribe to.
arguments
Filter object
Optional arguments available only for logs subscription.
Returns
Returned type
Description
string
Subscription ID, used to identify subscription and to unsubscribe.
Notifications returns
Depends on the subscription type.
Supported subscriptions
newHeads - subscribes to incoming block headers.
logs - subscribes to incoming logs, filtered by the given options.
newPendingTransactions - subscribes to incoming pending transactions.
syncing - subscribes to syncing events.
Additional informations
Subscriptions require a full duplex connections. Due to this reason, they are not available via HTTP and supported only on WebSockets.
​Learn how to install and use wscat - simple command line WebSockets client.​
Subscriptions are coupled to a connection. If the connection is closed, all subscriptions created over this connection are removed.
Subscribing to some events can cause a flood of notifications, e.g. listening for all logs/blocks when the node starts to synchronize.
newHeads
Subscribes to incoming block headers. Fires a notification each time a new header is appended to the chain, including chain reorganizations. Returns Block object.
Parameter: "newHeads"
Example
Request of newHeads
Response of newHeads
Notification of newHeads
{"method":"eth_subscribe","params":["newHeads"],"id":1,"jsonrpc":"2.0"}
{"jsonrpc":"2.0","result":"0x1a14b6bdcf4542fabf71c4abee244e47","id":1}
{
	"jsonrpc":"2.0",
	"method":"eth_subscription",
	"params":
		{
			"subscription":"0x1a14b6bdcf4542fabf71c4abee244e47",
			"result":
				{
					"author":"0x000000568b9b5a365eaa767d42e74ed88915c204",
					"difficulty":"0x1",
					"extraData":"0x4e65746865726d696e6420312e392e32322d302d6463373666616366612d32308639ad8ff3d850a261f3b26bc2a55e0f3a718de0dd040a19a4ce37e7b473f2d7481448a1e1fd8fb69260825377c0478393e6055f471a5cf839467ce919a6ad2700",
					"gasLimit":"0x7a1200",
					"gasUsed":"0x0",
					"hash":"0xa4856602944fdfd18c528ef93cc52a681b38d766a7e39c27a47488c8461adcb0",
					"logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
					"miner":"0x0000000000000000000000000000000000000000",
					"mixHash":"0x0000000000000000000000000000000000000000000000000000000000000000",
					"nonce":"0x0000000000000000",
					"number":"0x434822",
					"parentHash":"0x1a9bdc31fc785f8a95efeeb7ae58f40f6366b8e805f47447a52335c95f4ceb49",
					"receiptsRoot":"0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
					"sha3Uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
					"size":"0x261",
					"stateRoot":"0xf38c4bf2958e541ec6df148e54ce073dc6b610f8613147ede568cb7b5c2d81ee",
					"totalDifficulty":"0x633ebd",
					"timestamp":"0x604726b0",
					"transactions":[],
					"transactionsRoot":"0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
					"uncles":[]
				}
		}
}
logs
Subscribes to incoming logs, filtered by the given options. In case of a chain reorganization previous sent logs that are on the old chain will be resend with the removed property set to true.
Parameters:
"logs"
Filter object (optional)
fromBlock - "earliest", "pending" or "latest" (optional)
toBlock - "earliest", "pending" or "latest" (optional)
address - either an address or an array of addresses. Only logs that are created from these addresses are returned (optional)
topics - only logs which match the specified topics (optional)
If RPC call doesn't have second parameter, or parameters fromBlock or toBlock are not provided, subscription will use default filter: fromBlock - "latest", toBlock - "latest"
Example
Request of logs
Response of logs
Notification of logs
{
	"method":"eth_subscribe",
	"params":
		["logs",
			{
				"fromBlock":"latest",
				"toBlock":"latest",
				"address":"0xb7705ae4c6f81b66cdb323c65f4e8133690fc099",
				"topics":["0x03783fac2efed8fbc9ad443e592ee30e61d65f471140c10ca155e937b435b760"]
			}
		],
	"id":1,
	"jsonrpc":"2.0"
}
{"jsonrpc":"2.0","result":"0x0de42098e48c4ffba6d40561dc17b065","id":1}
{
	"jsonrpc":"2.0",
	"method":"eth_subscription",
	"params":
		{
			"subscription":"0x0de42098e48c4ffba6d40561dc17b065",
			"result":
				{
					"address":"0xb7705ae4c6f81b66cdb323c65f4e8133690fc099",
					"blockHash":"0x05333898e7f28f21a56370ed272b16c4b603d8a1dd26ec44f22639d8d90fe9d9",
					"blockNumber":"0x43489c",
					"data":"0x0000000000000000000000000000000000000000000000000000000000000000",
					"logIndex":"0x7",
					"removed":false,
					"topics":["0x03783fac2efed8fbc9ad443e592ee30e61d65f471140c10ca155e937b435b760","0x1f675bff07515f5df96737194ea945c36c41e7b4fcef307b7cd4d0e602a69111","0x000000000000000000000000c74f17181bf55635be65672e366b20f70662b79c"],
					"transactionHash":"0x29c551ba625bfaf58cb3d407c3e6f5c647032725c145cf55c7353cd3387cf845",
					"transactionIndex":"0xa",
					"transactionLogIndex":"0x0"
				}
		}
}
newPendingTransactions
Subscribes to incoming pending transactions. Returns transaction hash.
Parameter: "newPendingTransactions"
Example
Request of newPendingTransactions
Response of newPendingTransactions
Notification of newPendingTransactions
{"method":"eth_subscribe","params":["newPendingTransactions"],"id":1,"jsonrpc":"2.0"}
{"jsonrpc":"2.0","result":"0xfa561cbadf9b4bd79b62537661d18f27","id":1}
{
	"jsonrpc":"2.0",
	"method":"eth_subscription",
	"params":
		{
			"subscription":"0xfa561cbadf9b4bd79b62537661d18f27",
			"result":"0x6ad1058c56f71fe630053d24905f06d80677262ae2e8f42799690ab6b9fc5bd0"
		}
}
droppedPendingTransactions
Subscribes to transactions evicted from transaction pool. Returns transaction hash.
Parameter: "droppedPendingTransactions"
Example
Request of droppedPendingTransactions
Response of droppedPendingTransactions
Notification of droppedPendingTransactions
{"method":"eth_subscribe","params":["droppedPendingTransactions"],"id":1,"jsonrpc":"2.0"}
{"jsonrpc":"2.0","result":"0xfa561cbadf9b4bd79b62537661d18f27","id":1}
{
	"jsonrpc":"2.0",
	"method":"eth_subscription",
	"params":
		{
			"subscription":"0xfa561cbadf9b4bd79b62537661d18f27",
			"result":"0x6ad1058c56f71fe630053d24905f06d80677262ae2e8f42799690ab6b9fc5bd0"
		}
}
syncing
Subscribe to syncing events. Returns boolean false once if node is synced or an object with statistics once when the node starts syncing.
Parameter: "syncing"
Example
Request of syncing
Response of syncing
Notification of syncing
{"method":"eth_subscribe","params":["syncing"],"id":1,"jsonrpc":"2.0"}
{"jsonrpc":"2.0","result":"0x28d37f96bc784de4abf96ee4f8005a79","id":1}
{
	"jsonrpc":"2.0",
	"method":"eth_subscription",
	"params":
		{
			"subscription":"0x28d37f96bc784de4abf96ee4f8005a79",
			"result":false
		}
}
​
or
​
{
	"jsonrpc":"2.0",
	"method":"eth_subscription",
	"params":
		{
			"subscription":"0x28d37f96bc784de4abf96ee4f8005a79",
			"result":
				{
					"isSyncing":true,
					"startingBlock":"0x0",
					"currentBlock":"0x4346fe",
					"highestBlock":"0x434806"
				}
		}
}
eth_unsubscribe
Unsubscribes from subscription. Subscriptions are cancelled with a regular RPC call with eth_unsubscribe as method and subscription ID as a parameter. It returns a bool indicating if the subscription was cancelled successful.
Parameters
Parameter name
Type
Description
subscriptionId
string
ID of subscription you want to unsubscribe.
Returns
Returned type
Description
bool
true if subscription was cancelled successful, false if not.
Example
Request of eth:unsubscribe
Response of eth:unsubscribe
{"method":"eth_unsubscribe","params":["0x3cd2bcd1630948fe89190ca27b3b5913"],"id":1,"jsonrpc":"2.0"}
{"jsonrpc":"2.0","result":true,"id":1}
Proof module
Trace module
Last modified 1mo ago
Copy link
On this page
eth_subscribe
newHeads
logs
newPendingTransactions
droppedPendingTransactions
syncing
eth_unsubscribe