eth_newFilter

The eth_newFilter method creates a filter object based on filter options to notify when the state changes (logs). This method is essential for applications that need to monitor specific events on the blockchain, such as token transfers or contract events.

The filter can be configured with specific addresses, topics, and block ranges to capture relevant log entries. Applications use this to set up event listeners, monitor contract activity in real-time, and build reactive systems that respond to blockchain events. Once created, the filter ID can be used with eth_getFilterChanges to poll for new matching logs. This is more efficient than repeatedly calling eth_getLogs for real-time event monitoring.

Filters timeout after 5 minutes of inactivity. Applications should regularly call eth_getFilterChanges to keep the filter active.

Parameters

parameter	type	description
filterObject	object (required)	Filter options including fromBlock, toBlock, address, and topics

Filter Object Properties:

property	type	description
fromBlock	string (optional)	Block number in hex format or tag (latest, earliest, pending). Starting block for the filter. Defaults to 'latest'
toBlock	string (optional)	Block number in hex format or tag (latest, earliest, pending). Ending block for the filter. Defaults to 'latest'. Use 'latest' for ongoing monitoring
address	string or array (optional)	Contract address (20-byte hex string) or array of addresses to filter logs from. Omit to match logs from all contracts
topics	array (optional)	Array of 32-byte hex strings representing topics to filter. Topics are order-dependent. Use null in a position to match any topic. Each position can also be an array to match multiple topic values

Return Object

field	type	description
result	string	A filter ID as a hexadecimal string (e.g., "0x1"). This ID is used with eth_getFilterChanges to retrieve new logs matching the filter criteria, or with eth_getFilterLogs to get all logs for the filter. The filter remains active until it times out (after 5 minutes of inactivity) or is explicitly removed with eth_uninstallFilter.

Request Example

Request

Response Example

Response