eth_subscribe

The eth_subscribe method creates a subscription to specific events on the Ethereum blockchain. It requires a WebSocket connection and allows clients to receive real-time notifications about new blocks, pending transactions, logs, and synchronization status.

Use Cases

• Building real-time blockchain explorers and dashboards
• Monitoring smart contract events without constant polling
• Creating responsive dApps that update instantly when state changes
• Tracking pending transactions to detect when they're mined
• Receiving immediate notification when a payment arrives
• Implementing efficient event-driven architecture for blockchain applications
• Monitoring smart contract activity with minimal server load
• Building high-performance trading systems requiring real-time data
• Tracking node synchronization in real-time
• Implementing webhooks for blockchain events

Method Details

Subscription Types

newHeads

Subscribe to receive information about new blocks added to the blockchain. This is useful for applications that need to react to new blocks or monitor chain progress.

Request

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": ["newHeads"]
}

Response

Initial response with subscription ID:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": "0x9cef478923ff08bf67fde6c64013158d"
}

Subsequent notifications when new blocks are added:

{
	"jsonrpc": "2.0",
	"method": "eth_subscription",
	"params": {
		"subscription": "0x9cef478923ff08bf67fde6c64013158d",
		"result": {
      "difficulty": "0x0",
      "extraData": "0xd883010b05846765746888676f312e32302e35856c696e7578",
			"gasLimit": "0x1c9c380",
      "gasUsed": "0xe8c35a",
      "logsBloom": "0x24a0a00e2800a84002408401021c8200410a40340440800900000820804830202d00004204204804800900110314a0088ac11a0a402809a044404a943d0812ce408101342401004a6080490900245000240140901901124288a20d840008200014150600a2080832000220250912a0400124009c00202430c00298b0a8d0822d1a10188080000c0124203a041100601880308406a2600d0420a140801000a4c80a2a0080a5108042302008080a0050a000a44214011610400002090000170003800020d0c1840022008408a4810401d881002202a2100a00204244120200000000810600da940000a0018a40406100006100c044a0202400200420000200211000880",
      "miner": "0x86c501ed1cb7123feb9db41f10eca511fb3e1416",
      "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "nonce": "0x0000000000000000",
      "number": "0x1b4",
      "parentHash": "0x3863a513b3d30160cf76cefee31652f188ddd2e2c9b169bc7d35e324f99cd24e",
      "receiptsRoot": "0x28d996993bebb61fb8056d9938f148c3c683e772ae5d53b63ef9bcc601072a66",
      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "size": "0x973",
      "stateRoot": "0xb9c737605971351a00b9a978b72271874ef3cf0a2dc87a7c4325993ddf84e83f",
      "timestamp": "0x64",
      "transactionsRoot": "0xf25ff1909e48c93a122b52d9c576b62c141a2f51f3d9b7c53afa7cdb2eec62b2",
      "baseFeePerGas": "0x42214d6b"
		}
	}
}

Key Block Header Fields

The notification includes a complete block header with the following key fields:

• number: The block height (hexadecimal)
• hash: The block hash (may be null if still pending)
• parentHash: Hash of the parent block
• timestamp: Unix timestamp when block was mined
• gasUsed: Total gas used by all transactions in the block
• gasLimit: Maximum gas allowed in the block
• baseFeePerGas: Base fee per gas (post-EIP-1559)
• miner: Address of the miner/validator who produced the block
• difficulty: Block difficulty (will be 0 after The Merge)
• size: Size of the block in bytes

logs

Subscribe to receive logs that match specific filter criteria. This is particularly useful for tracking events emitted by smart contracts.

Request with Filter Options

{
  "id": 1,
	"jsonrpc": "2.0",
	"method": "eth_subscribe",
	"params": [
		"logs",
		{
      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
      "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]
    }
  ]
}

Filter Options Explained

The second parameter is a filter object that can include:

• address (optional): String or array of strings with addresses to filter logs
• topics (optional): Array of topic filters, supports null for wildcard
• fromBlock (optional): Block height from which to start getting logs (hexadecimal)
• toBlock (optional): Block height to which to get logs (hexadecimal)

Topics Array Format

Topics are ordered and correspond to the event signature and indexed parameters:

1. First topic: keccak256 hash of the event signature (e.g., Transfer(address,address,uint256))
2. Second topic: First indexed parameter
3. Third topic: Second indexed parameter (if present)
4. Fourth topic: Third indexed parameter (if present)

Topics can be:

• A single topic: exact match required
• Null: any value accepted (wildcard)
• Array of topics: any of the topics in the array will match (OR condition)

Response

Initial response with subscription ID:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x4a8a4c0517381924f9838102c5a4dcb7"
}

Subsequent notifications when matching logs are emitted:

{
	"jsonrpc": "2.0",
	"method": "eth_subscription",
	"params": {
    "subscription": "0x4a8a4c0517381924f9838102c5a4dcb7",
		"result": {
      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
      "blockHash": "0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
      "blockNumber": "0x29e87",
      "data": "0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
      "logIndex": "0x0",
      "removed": false,
      "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],
      "transactionHash": "0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
      "transactionIndex": "0x0"
		}
	}
}

Log Object Fields

Every log notification contains:

• address: The address of the contract that emitted the log
• topics: Array of 0-4 32-byte topics, indexed parameters from the event
• data: Contains the non-indexed parameters of the log
• blockNumber: Block in which the transaction was included
• transactionHash: Hash of the transaction
• transactionIndex: Integer of the transaction's position in the block
• blockHash: Hash of the block
• logIndex: Integer of the log index position in the block
• removed: true when the log was removed due to a chain reorganization, false if it's a valid log

newPendingTransactions

Subscribe to receive notification of new pending transactions as they're added to the transaction pool.

Request

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": ["newPendingTransactions"]
}

Response

Initial response with subscription ID:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xc3b33aa549fb9a60e95d21862596617c"
}

Subsequent notifications when new pending transactions are added:

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0xc3b33aa549fb9a60e95d21862596617c",
    "result": "0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc8f1c857"
  }
}

Important Notes

1. WebSocket Required: eth_subscribe is only available over WebSocket connections, not HTTP
2. Subscription Limits: Many providers limit the number of active subscriptions per connection
3. Missed Events: If connection drops, events occurring during disconnection are missed
4. Chain Reorganizations: Events may be marked as removed during chain reorganizations
5. Client Support: Not all Ethereum clients support all subscription types
6. Public Node Restrictions: Public nodes like Infura may have throttling for subscriptions
7. Filter Precision: More specific filters improve performance and reduce data volume
8. Security Considerations: WebSockets have different security requirements than HTTP
9. Guaranteed Delivery: Unlike message queues, WebSocket does not guarantee delivery
10. Connection Stability: Long-running subscriptions should implement reconnection logic

See also

• eth_unsubscribe - Cancels an active subscription
• eth_newFilter - HTTP-based alternative for log filtering
• eth_getLogs - Query historical events
• eth_getFilterChanges - Poll-based alternative for logs
• eth_newBlockFilter - HTTP-based alternative for new blocks
• eth_newPendingTransactionFilter - HTTP-based alternative for pending transactions
• WebSockets Guide - Comprehensive guide to WebSocket connections
• Event Logging Guide - Guide to contract events and logs