Docs
Supported ChainsMantleJSON-RPC APISmart Contract Methods

eth_newBlockFilter - Mantle RPC Method

Create a filter for new block notifications on Mantle. Essential for block monitoring, chain progression tracking, and reorg detection for liquid staking (mETH $1.87B TVL), institutional DeFi via Bybit, and yield optimization strategies.

Creates a filter on Mantle that notifies when new blocks arrive. Once created, poll the filter with eth_getFilterChanges to receive an array of block hashes for each new block added to the chain since your last poll.

Why Mantle? Build on the world's largest ZK rollup by TVL with $2.5B+ secured and deep Bybit integration with near-instant ZK finality via OP Succinct, $6.2B treasury backing, mETH liquid staking, and 25% Bybit trading fee discounts.

When to Use This Method

eth_newBlockFilter is essential for DeFi developers, liquid staking builders, and teams seeking institutional exchange integration:

  • Block Monitoring — Detect new blocks on Mantle as they are mined or finalized, without repeatedly calling eth_blockNumber
  • Chain Progression Tracking — Build dashboards or alerting systems that track block production rate and timing
  • Reorg Detection — Identify chain reorganizations by monitoring for blocks that are replaced or missing
  • Event-Driven Architectures — Trigger downstream processing (indexing, notifications, settlement) whenever a new block appears

Request Parameters

Request

This method accepts no parameters.

Response Body

Response
resultQUANTITY

A hex-encoded filter ID used to poll for new blocks via eth_getFilterChanges

resultArray<DATA>

Array of 32-byte block hashes for each new block since the last poll

Error Responses

Errors
Error Response-32603

Code Examples

Bash
# Create the block filter
FILTER_ID=$(curl -s -X POST https://api-mantle-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_newBlockFilter",
    "params": [],
    "id": 1
  }' | jq -r '.result')

echo "Filter ID: $FILTER_ID"

# Poll for new blocks
curl -X POST https://api-mantle-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d "{
    \"jsonrpc\": \"2.0\",
    \"method\": \"eth_getFilterChanges\",
    \"params\": [\"$FILTER_ID\"],
    \"id\": 2
  }"

Common Use Cases

1. Block Production Rate Monitor

Track block times and detect slowdowns on Mantle:

JavaScript
async function monitorBlockRate(provider) {
  const filterId = await provider.send('eth_newBlockFilter', []);
  let lastBlockTime = null;
  const blockTimes = [];

  setInterval(async () => {
    const blockHashes = await provider.send('eth_getFilterChanges', [filterId]);

    for (const hash of blockHashes) {
      const block = await provider.getBlock(hash);
      const blockTime = block.timestamp;

      if (lastBlockTime) {
        const interval = blockTime - lastBlockTime;
        blockTimes.push(interval);

        // Keep last 100 block times
        if (blockTimes.length > 100) blockTimes.shift();

        const avgBlockTime = blockTimes.reduce((a, b) => a + b, 0) / blockTimes.length;
        console.log(`Block #${block.number} | interval: ${interval}s | avg: ${avgBlockTime.toFixed(1)}s`);

        if (interval > avgBlockTime * 3) {
          console.warn(`Slow block detected — ${interval}s vs ${avgBlockTime.toFixed(1)}s average`);
        }
      }
      lastBlockTime = blockTime;
    }
  }, 2000);
}

2. Reorg-Aware Block Tracker

Detect chain reorganizations by tracking block hashes:

JavaScript
async function trackBlocksWithReorgDetection(provider) {
  const filterId = await provider.send('eth_newBlockFilter', []);
  const blockHistory = new Map(); // blockNumber -> blockHash

  setInterval(async () => {
    const newBlockHashes = await provider.send('eth_getFilterChanges', [filterId]);

    for (const hash of newBlockHashes) {
      const block = await provider.getBlock(hash);
      const existingHash = blockHistory.get(block.number);

      if (existingHash && existingHash !== hash) {
        console.warn(`Reorg detected at block #${block.number}!`);
        console.warn(`  Old hash: ${existingHash}`);
        console.warn(`  New hash: ${hash}`);
        // Trigger reorg handling logic
      }

      blockHistory.set(block.number, hash);

      // Prune old entries
      if (blockHistory.size > 1000) {
        const minBlock = block.number - 500;
        for (const [num] of blockHistory) {
          if (num < minBlock) blockHistory.delete(num);
        }
      }
    }
  }, 2000);
}

3. Block-Triggered Task Scheduler

Execute tasks whenever a new block is produced:

JavaScript
async function onNewBlock(provider, callback) {
  const filterId = await provider.send('eth_newBlockFilter', []);

  const poll = async () => {
    try {
      const hashes = await provider.send('eth_getFilterChanges', [filterId]);
      for (const hash of hashes) {
        await callback(hash);
      }
    } catch (error) {
      if (error.message.includes('filter not found')) {
        return provider.send('eth_newBlockFilter', []).then(newId => {
          console.log('Block filter recreated');
          return newId;
        });
      }
      throw error;
    }
    return filterId;
  };

  let currentFilterId = filterId;
  setInterval(async () => {
    currentFilterId = await poll() || currentFilterId;
  }, 2000);
}

// Usage
onNewBlock(provider, async (blockHash) => {
  console.log(`Processing block: ${blockHash}`);
  // Run indexer, check conditions, send notifications, etc.
});

Error Handling

Common errors and solutions:

Error CodeDescriptionSolution
-32603Internal errorNode may not support filters — verify node capabilities
-32000Filter not foundFilter expired (~5 min inactivity) — recreate with eth_newBlockFilter
-32005Rate limit exceededReduce polling frequency or implement client-side rate limiting
-32601Method not foundNode does not support filter methods — use eth_blockNumber polling instead
JavaScript
async function createBlockFilterWithFallback(provider) {
  try {
    const filterId = await provider.send('eth_newBlockFilter', []);
    return { type: 'filter', id: filterId };
  } catch (error) {
    console.warn('Block filter not supported — falling back to polling');
    return { type: 'polling', lastBlock: await provider.getBlockNumber() };
  }
}

eth_uninstallFilter

Remove a filter on Mantle created by eth_newFilter, eth_newBlockFilter, or eth_newPendingTransactionFilter. Essential for resource cleanup after event monitoring.

eth_newPendingTransactionFilter

Create a filter for pending transaction notifications on Mantle. Essential for mempool monitoring, transaction tracking, and MEV opportunity detection for liquid staking (mETH $1.87B TVL), institutional DeFi via Bybit, and yield optimization strategies.

On this page

When to Use This Method
Code Examples
Common Use Cases
1. Block Production Rate Monitor
2. Reorg-Aware Block Tracker
3. Block-Triggered Task Scheduler
Error Handling
Related Methods