eth_subscribe

Creates a real-time WebSocket subscription to on-chain events.

Creates a real-time subscription to on-chain events. The node pushes event notifications to the client as JSON-RPC messages whenever a matching event occurs, without the client needing to poll.

Parameters

subscriptionType · string · required

The event type to subscribe to. See subscription types below.

filterOptions · object

Optional filter options. Only applicable for the logs subscription type.

Show Filter options (logs only)

address · string | array

A single contract address or array of addresses to filter logs by. Optional.

topics · array

Array of topic filters in the same format as eth_getLogs. Optional.

Subscription Types

Type	Description	Notification payload
newHeads	Fires for each new block header appended to the chain	Block header object
logs	Fires for each new log matching the filter criteria	Log object
newPendingTransactions	Fires for each new pending transaction hash added to the mempool	Transaction hash string

Returns

result · string

A hex-encoded subscription ID. All subsequent event notifications from this subscription include this ID in params.subscription.

Event notifications arrive as unsolicited JSON-RPC messages with method: "eth_subscription":

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x1887ec8b9589ccad00000000000532da",
    "result": { ... }
  }
}

Example

Subscribe to new block headers:

Request

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

Subscribe to contract logs:

Request

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