eth_newFilter

Install a log filter in the server, allowing for later polling. Registers client interest in logs matching the filter, and returns an identifier.

Parameters (by position)

Filter object or object required

---

Show Option 1 Filter by block range object

Filter by block range fields

Filter object required

Filter by block range

---

Show Filter object

Filter 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 string or array<string>

  ---

  Show Option 1 Single Topic Match string

  Single Topic Match fields

  topics array<string>

  Single Topic Match

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

  ---

  Show Option 2 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

Filter object required

Filter by block hash

---

Show Filter object

Filter 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 string or array<string>

  ---

  Show Option 1 Single Topic Match string

  Single Topic Match fields

  topics array<string>

  Single Topic Match

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

  ---

  Show Option 2 Multiple Topic Match array

  Multiple Topic Match fields

  topics array<string>

  32 hex encoded bytes

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

  ---

• additionalProperties true

  ---

Result

Filter identifier string

hex encoded unsigned integer

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

---

Examples

eth_newFilter example

Request

{
  "params": [
    {
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "fromBlock": "0x137d3c2",
      "toBlock": "0x137d3c3",
      "topics": []
    }
  ]
}

Response

"0x01"

Request

Server URL:

{ "jsonrpc": "2.0", "method": "eth_newFilter", "params": [ { "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "fromBlock": "0x137d3c2", "toBlock": "0x137d3c3", "topics": [] } ], "id": 1 }