Skip to main content

eth_newFilter

Creates a filter object based on the given filter options, to notify when the state changes (logs). To check if the state has changed, call eth_getFilterChanges.

Valid for fifteen minutes

Filter IDs will be valid for up to fifteen minutes, and can polled by any connection using the same <YOUR-API-KEY>.

Parameters​

A filter object with the following keys and their values:

  • address: [optional] A contract address or a list of addresses from which logs should originate.
  • fromBlock: [optional, default is latest] A hexadecimal block number, or one of the string tags latest, earliest, pending, safe, or finalized. See the default block parameter.
  • toBlock: [optional, default is latest] A hexadecimal block number, or one of the string tags latest, earliest, pending, safe, or finalized. See the default block parameter.
  • topics: [optional] An array of 32 bytes DATA topics. Topics are order-dependent.

Specifying topic filters​

Topics are order-dependent. A transaction with a log with topics [A, B] will be matched by the following topic filters:

  • []: Anything.
  • [A]: A in the first position, and anything after.
  • [null, B]: Anything in first position AND B in second position, and anything after.
  • [A, B]: A in the first position AND B in second position, and anything after.
  • [[A, B], [A, B]]: (A OR B) in first position AND (A OR B) in second position, and anything after.

Returns​

filter ID: A hexadecimal denoting the newly created filter ID.

Example​

Replace <YOUR-API-KEY> with an API key from your MetaMask Developer dashboard.

Request​

curl https://mainnet.infura.io/v3/<YOUR-API-KEY> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "eth_newFilter", "params": [{"topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}], "id": 1}'

Response​

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