eth_subscribe

Creates a subscription. The first parameter selects the subscription kind and determines which optional second-parameter shape applies and what notification data is pushed to the client. Returns a subscription ID that can later be passed to `eth_unsubscribe` to cancel the subscription.

Subscription notifications are delivered as JSON-RPC notifications with method `eth_subscription` and `params` of the form `{ "subscription": <id>, "result": <data> }`, where `<data>` depends on the kind:

- `newHeads`: a block header (same shape as a Block object, without `transactions`, `withdrawals`, `uncles`, or `size`). No second parameter. - `logs`: a Log object matching the supplied Filter (same shape as the filter accepted by `eth_getLogs`). Removed logs (due to chain reorgs) are pushed with `removed: true`. - `newPendingTransactions`: a transaction hash by default, or a full transaction object if the optional boolean second parameter is `true`. - `transactionReceipts`: an array of receipt objects (same shape as `eth_getTransactionReceipt`) for transactions included in the latest imported block. If the optional `{ transactionHashes: [...] }` filter is provided, only receipts for those transactions are pushed; otherwise receipts for all transactions in the block are pushed.

This method is only available on transports that support server-initiated notifications (e.g. WebSocket and IPC).

Subscribes to events on the node.

Parameters (by position)

kind string required

---

arg unknown or unknown or object

---

Show Option 1 Logs filter (for `logs`)

Logs filter (for `logs`) fields

arg object or object

---

Show Option 1 Filter by block range object

Filter by block range fields

arg object

Filter by block range

---

Show arg object

arg fields

• address null or string or array<string>

  ---

  Show Option 1 Any Address null

  Any Address fields

  address null

  Any Address

  ---

  Show Option 2 Address string

  Address fields

  address string

  Address

  Match pattern: ^0x[0-9a-fA-F]{40}$

  ---

  Show Option 3 Addresses array

  Addresses fields

  address array<string>

  hex encoded address

  Match pattern: ^0x[0-9a-fA-F]{40}$

  ---

• fromBlock string or string

  ---

  Show Option 1 Block number string

  Block number fields

  fromBlock string

  Block number

  Match pattern: ^0x(0|[1-9a-f][0-9a-f]*)$

  ---

  Show Option 2 Block tag string

  Block tag fields

  earliest: The lowest numbered block the client has available; finalized: The most recent crypto-economically secure block, cannot be re-orged outside of manual intervention driven by community coordination; safe: The most recent block that is safe from re-orgs under honest majority and certain synchronicity assumptions; latest: The most recent block in the canonical chain observed by the client, this block may be re-orged out of the canonical chain even under healthy/normal conditions. Before the merge transition is finalized, any call querying for finalized or safe block MUST be responded to with -39001: Unknown block error

  fromBlock string

  earliest: The lowest numbered block the client has available; finalized: The most recent crypto-economically secure block, cannot be re-orged outside of manual intervention driven by community coordination; safe: The most recent block that is safe from re-orgs under honest majority and certain synchronicity assumptions; latest: The most recent block in the canonical chain observed by the client, this block may be re-orged out of the canonical chain even under healthy/normal conditions. Before the merge transition is finalized, any call querying for finalized or safe block MUST be responded to with -39001: Unknown block error

  Allowed values: earliest finalized safe latest

  ---

• toBlock string or string

  ---

  Show Option 1 Block number string

  Block number fields

  toBlock string

  Block number

  Match pattern: ^0x(0|[1-9a-f][0-9a-f]*)$

  ---

  Show Option 2 Block tag string

  Block tag fields

  earliest: The lowest numbered block the client has available; finalized: The most recent crypto-economically secure block, cannot be re-orged outside of manual intervention driven by community coordination; safe: The most recent block that is safe from re-orgs under honest majority and certain synchronicity assumptions; latest: The most recent block in the canonical chain observed by the client, this block may be re-orged out of the canonical chain even under healthy/normal conditions. Before the merge transition is finalized, any call querying for finalized or safe block MUST be responded to with -39001: Unknown block error

  toBlock string

  earliest: The lowest numbered block the client has available; finalized: The most recent crypto-economically secure block, cannot be re-orged outside of manual intervention driven by community coordination; safe: The most recent block that is safe from re-orgs under honest majority and certain synchronicity assumptions; latest: The most recent block in the canonical chain observed by the client, this block may be re-orged out of the canonical chain even under healthy/normal conditions. Before the merge transition is finalized, any call querying for finalized or safe block MUST be responded to with -39001: Unknown block error

  Allowed values: earliest finalized safe latest

  ---

• topics null or array<unknown>

  ---

  Show Option 1 Any Topic Match null

  Any Topic Match fields

  topics null

  Any Topic Match

  ---

  Show Option 2 Specified Filter Topics array

  Specified Filter Topics fields

  topics null or string or array<string>

  ---

  Show Option 1 Any Topic Match null

  Any Topic Match fields

  topics array<null>

  Any Topic Match

  ---

  Show Option 2 Single Topic Match string

  Single Topic Match fields

  topics array<string>

  Single Topic Match

  Match pattern: ^0x[0-9a-f]{64}$

  ---

  Show Option 3 Multiple Topic Match array

  Multiple Topic Match fields

  topics array<string>

  32 hex encoded bytes

  Match pattern: ^0x[0-9a-f]{64}$

  ---

• additionalProperties true

  ---

Show Option 2 Filter by block hash object

Filter by block hash fields

arg object

Filter by block hash

---

Show arg object

arg fields

• address null or string or array<string>

  ---

  Show Option 1 Any Address null

  Any Address fields

  address null

  Any Address

  ---

  Show Option 2 Address string

  Address fields

  address string

  Address

  Match pattern: ^0x[0-9a-fA-F]{40}$

  ---

  Show Option 3 Addresses array

  Addresses fields

  address array<string>

  hex encoded address

  Match pattern: ^0x[0-9a-fA-F]{40}$

  ---

• blockHash string required

  block hash

  Match pattern: ^0x[0-9a-f]{64}$

  ---

• topics null or array<unknown>

  ---

  Show Option 1 Any Topic Match null

  Any Topic Match fields

  topics null

  Any Topic Match

  ---

  Show Option 2 Specified Filter Topics array

  Specified Filter Topics fields

  topics null or string or array<string>

  ---

  Show Option 1 Any Topic Match null

  Any Topic Match fields

  topics array<null>

  Any Topic Match

  ---

  Show Option 2 Single Topic Match string

  Single Topic Match fields

  topics array<string>

  Single Topic Match

  Match pattern: ^0x[0-9a-f]{64}$

  ---

  Show Option 3 Multiple Topic Match array

  Multiple Topic Match fields

  topics array<string>

  32 hex encoded bytes

  Match pattern: ^0x[0-9a-f]{64}$

  ---

• additionalProperties true

  ---

Show Option 2 Full-transaction flag (for `newPendingTransactions`) boolean

Full-transaction flag (for `newPendingTransactions`) fields

arg boolean

Full-transaction flag (for newPendingTransactions)

---

Show Option 3 Transaction receipts filter (for `transactionReceipts`) object

Transaction receipts filter (for `transactionReceipts`) fields

arg object

Transaction receipts filter (for transactionReceipts)

---

Show arg object

arg fields

• transactionHashes array<string>

  32 byte hex value

  Match pattern: ^0x[0-9a-f]{64}$

  ---

• additionalProperties false

  ---

Result

Subscription ID string

hex encoded unsigned integer

Match pattern: ^0x(0|[1-9a-f][0-9a-f]*)$

---

Examples

eth_subscribe newHeads example

Request

{
  "params": [
    "newHeads"
  ]
}

Response

"0x9cef478923ff08bf67fde6c64013158d"

eth_subscribe logs example

Request

{
  "params": [
    "logs",
    {
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
      ]
    }
  ]
}

Response

"0x4a8a4c0517381924f9838102c5a4dcb7"

eth_subscribe newPendingTransactions example

Request

{
  "params": [
    "newPendingTransactions",
    false
  ]
}

Response

"0xc3b33aa549fb9a60e95d21862596617c"

eth_subscribe transactionReceipts example

Request

{
  "params": [
    "transactionReceipts",
    {
      "transactionHashes": [
        "0x66e7a140c8fa27fe98fde923defea7562c3ca2d6bb89798aabec65782c08f63d"
      ]
    }
  ]
}

Response

"0x1a2b3c4d5e6f70819293a4b5c6d7e8f9"

Request

Server URL:

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