eth_getFilterChanges | Ethereum

Ethereum API polling method used to retrieve updates from a filter. A filter is an object used to track changes to the state of the blockchain.

👍

Get you own node endpoint today

Start for free and get your app to production levels immediately. No credit card required.

You can sign up with your GitHub, X, Google, or Microsoft account.

Filters can be created using one of the following methods:

• eth_newFilter
• eth_newPendingTransactionFilter
• eth_newBlockFilter

After creating a filter using one of the available methods, the resulting filter ID can be used to fetch changes by calling the eth_getFilterChanges method.

🚧

Disclaimer

Note that the default interactive example in this page will not work as the filter will be expired.

To test eth_getFilterChanges in this page, first create a new filter using one of the following:

• eth_newFilter
• eth_newPendingTransactionFilter
• eth_newBlockFilter

Then use the fresh filter ID as the parameter for eth_getFilterChanges.

Parameters

• string — the filter ID of the filter for which you want to retrieve the changes

Response

• array — an array that represents the changes that have occurred on the blockchain since the last time the filter was polled:
  • For filters created with eth_newBlockFilter:
    • blockHash — the hashes of the new blocks since the last time the filter was polled.
  • For filters created with eth_newPendingTransactionFilter:
    • transactionHash — the hashes identifying new pending transactions since the last time the filter was polled.
  • For filters created with eth_newFilter, the following event logs:
    • address — the contract address from which the event originated.
    • topics — an array of 32-byte data fields containing indexed event parameters.
    • data — the non-indexed data that was emitted along with the event.
    • blocknumber — the block number in which the event was included. null if it is pending.
    • transactionhash — the hash of the transaction that triggered the event. null if pending.
    • transactionindex — the integer index of the transaction within the block's list of transactions. null if it is pending.
    • blockhash — the hash of the block in which the event was included. null if it is pending.
    • logindex — the integer identifying the index of the event within the block's list of events. null if pending.
    • removed — the boolean value indicating if the event was removed from the blockchain due to a chain reorganization. True if the log was removed. False if it is a valid log.

eth_getFilterChanges code examples

📘

Note that the web3.eth.filter methods have been deprecated and replaced with the web3.eth.subscribe in web3.js. See web3.js subscriptions.

const ethers = require("ethers");

// Create a ChainstackProvider instance for Ethereum mainnet
const chainstack = new ethers.ChainstackProvider("mainnet");

async function getFilterChanges(filter) {
  try {
    const changes = await chainstack.send("eth_getFilterChanges", [filter]);
    console.log(changes); // Log the with the new data
  } catch (err) {
    console.error(err); // Handle errors that may occur
  }
}

const filterId = "0x4e7ef166cd43f188b0f8f9e218966a8f"; //'YOUR_FILTER_iD'
getFilterChanges(filterId);

from web3 import Web3  
node_url = "CHAINSTACK_NODE_URL" 
web3 = Web3(Web3.HTTPProvider(node_url))

def get_filtered_events(filter_id):
    try:
        filter_changes = web3.eth.get_filter_changes(filter_id)
        print(filter_changes) # the array of events that match the filter
    except Exception as e:
        print(e)

filter_id = '0x0'
get_filtered_events(filter_id)       

📘

Learn more about the ChainstackProvider in ethers.js: ethers ChainstackProvider Documentation.

Use case

The eth_getFilterChanges method can be used to periodically poll a filter to retrieve new data. In the following Python program, using the web3.py library creates a filter using eth_newBlockFilter to poll for new blocks, and uses eth_getFilterChanges to poll the filter and retrieve new blocks.

Here is the implementation in Python:

from web3 import Web3  
node_url = "CHAINSTACK_NODE_URL" 
web3 = Web3(Web3.HTTPProvider(node_url))

def get_new_blocks():
    try:
        blocks_filter = web3.eth.filter('latest')
        return blocks_filter
    except Exception as e:
        print(e)

def get_filtered_events(filter_id):
    try:
        filter_changes = web3.eth.get_filter_changes(filter_id)
        return filter_changes # the array of events that match the filter
    except Exception as e:
        print(f'Error getting filter changes: {e}')

def main():
    # Create a block filter
    blocks = get_new_blocks()
    block_filter_id = blocks.filter_id
    
    if block_filter_id is not None:
        print(f'New block filter ID: {block_filter_id}')
    else:
        print('Error creating block filter')
        return

    # Loop forever and poll the filter every 10 seconds
    while True:
        print('Polling for new blocks...')
        new_blocks = get_filtered_events(block_filter_id)
        if new_blocks is not None:
            print(new_blocks)
        else:
            print('Error getting filter changes')
        time.sleep(5)

if __name__ == '__main__':
    main()

Here is the explanation of the code:

The create_block_filter function creates a new block filter with the web3.eth.filter('latest') method, which matches against the latest block. The resulting filter object is converted to a string, split into parts using the split method and the filter ID is extracted from the second part using array indexing. The filter ID is then returned by the function.

The get_filtered_events function uses the eth_getFilterChanges method to retrieve the new blocks. The function takes a single parameter, filter_id, which is a string that represents the ID of the filter to be polled, the filter created by the create_block_filter function in this case.

If the filter ID is valid, get_filtered_events calls web3.eth.getFilterChanges(filter_id) to retrieve the array of events that match the filter criteria. This array is then returned by the function, which is then printed to the console in the main function.

The main function encapsulates the program logic, calling create_block_filter to create a new block filter and print the resulting filter ID to the console. The function then enters an infinite loop, calling get_filtered_events every 10 seconds to retrieve the changes to the blockchain that match the filter criteria. If the changes are not None, they are printed to the console. An error message is printed to the console if an error occurs while creating the block filter or retrieving the filter changes.

Try the eth_getFilterChanges RPC method yourself