eth_newFilter | BNB Chain

BNB API method that generates a filter object based on the filter parameters. It returns a filter ID, which can be used to retrieve the filter results using the eth_getFilterChanges method. By creating a filter for specific events, developers can receive notifications when those events occur and use them to trigger actions in their applications.


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.


  • object โ€” the filter parameters:
    • fromBlock โ€” (optional, default: latest) integer that specifies the starting block number from which the logs should be fetched.
    • toBlock โ€” (optional, default: latest) integer that specifies the ending block number until which the logs should be fetched.
    • address โ€” (optional) the contract address from which the logs should be fetched. It can be a single address or an array of addresses.
    • topics โ€” (optional) an array of DATA topics. The event topics for which the logs should be fetched. It can be a single topic or an array of topics.
    • blockhash โ€” (optional) the hash of the specific block. Limits logs to a specific block with a 32-byte hash value. It takes precedence over fromBlock and toBlock.


Possible tags for fromBlock and toBlock

  • latest โ€” the most recent block in the blockchain and the current state of the blockchain at the most recent block.
  • safe โ€” the block that received justification from the beacon chain. Although this block could be involved in a chain reorganization, it would necessitate either a coordinated attack by the majority of validators or an instance of severe propagation latency.
  • finalized โ€” the block accepted as canonical by more than 2/3 of the validators. A chain reorganization is extremely unlikely, and it would require at least 1/3 of the staked ETH to be burned.
  • earliest โ€” the earliest available or genesis block.
  • pending โ€” the pending state and transactions block. The current state of transactions that have been broadcast to the network but have not yet been included in a block.

See the default block parameter and How The Merge Impacts Ethereumโ€™s Application Layer.


  • result โ€” a hexadecimal string representing the ID of the newly created filter


The filters created are stored on the blockchain client instance. The filter is automatically deleted if not polled within a certain time (5 minutes by default).

Use the following methods with the filter ID:

eth_newFilter 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');
const provider = new ethers.JsonRpcProvider(NODE_URL);

const filter = {
  toBlock: 'latest',
  address: '0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82',
  topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']

const createFilter = async () => {
  try {
    const filterId = await provider.send('eth_newFilter', [filter]);
    console.log(filterId); // the filter ID returned by eth_newFilter
    return filterId
  } catch (error) {

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

filter = {
    'toBlock': 'latest',
    'address': '0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82',
    'topics': ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']

def create_logs_filter(filter_object):
        logs_filter = web3.eth.filter(filter_object)
        return logs_filter
    except Exception as e:

logs_filter = create_logs_filter(filter)
filter_id = logs_filter.filter_id
print(f'New filter ID: {filter_id}')

Use case

You can use eth_newFilter to create a filter for a specific action on a smart contract, for example, to monitor the transfer transactions from the Wrapped BNB token.

The idea is to create a filter using the eth_newFilter method to monitor an ERC-20 smart contract, WBNB in this case.

Try the eth_newFilter RPC method yourself

Click Try It! to start a request and see the response here!