eth_newFilter: Poll for Logs Without WebSockets

What eth_newFilter does

The filter object is the same one eth_getLogs takes: fromBlock, toBlock, address and topics, minus blockHash. The node stores it, remembers where you last read, and advances that cursor every time you poll. On Geth a filter created with a fromBlock in the past returns that backlog on the first poll and only new logs afterwards, which makes "backfill then follow" a single object rather than two code paths.

Three companions complete the API. eth_getFilterChanges returns what is new since the last poll and moves the cursor. eth_getFilterLogs returns everything matching the filter regardless of the cursor, and only works for filters created with eth_newFilter. eth_uninstallFilter deletes the filter, which is worth doing explicitly rather than waiting for the timeout. Two sibling constructors, eth_newBlockFilter and eth_newPendingTransactionFilter, produce id-based streams of block hashes and pending transaction hashes with the same polling model.

The critical thing to understand is that a filter is state living on one specific node. It is not part of the chain, it cannot be recreated from its id, and it disappears when the node forgets it. Everything that goes wrong with filters in production follows from that one fact.

Parameters

Omitting fromBlock and toBlock gives you a filter that starts at the current head and follows it. Setting toBlock to a fixed block gives a filter that stops producing once the chain passes it, which is a quiet way to build a poller that mysteriously goes silent.

What it returns

A hex filter id such as 0x6c4e010000000000d4d17d7505f071cf. The id is opaque, node-local and only meaningful to the node that issued it.

Polling it with eth_getFilterChanges returns an array of log objects in the same shape eth_getLogs produces, including removed: true entries for logs from blocks that were reorged out. An empty array means nothing matched since the last poll, which is the normal answer most of the time.

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

The filter id. Poll it with eth_getFilterChanges using the same endpoint: {"jsonrpc":"2.0","id":1,"method":"eth_getFilterChanges","params":["0x6c4e010000000000d4d17d7505f071cf"]}. Ids from a run of the example above are yours alone and expire quickly.

import { JsonRpcProvider, id } from "ethers";

const provider = new JsonRpcProvider("https://ethereum-rpc.publicnode.com");

const filterId = await provider.send("eth_newFilter", [
  {
    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    topics: [id("Transfer(address,address,uint256)")],
  },
]);

// poll well inside the node's idle timeout, and expect it to vanish anyway
setInterval(async () => {
  try {
    const logs = await provider.send("eth_getFilterChanges", [filterId]);
    for (const log of logs) console.log(log.blockNumber, log.transactionHash);
  } catch (err) {
    console.error("filter gone, recreate it:", err.shortMessage ?? err);
  }
}, 6_000);

// when you are done
// await provider.send("eth_uninstallFilter", [filterId]);

Gotchas and common errors

What eth_newFilter costs on BLAZED.sh

eth_newFilter costs 1 credit on BLAZED.sh, and so does each eth_getFilterChanges poll, which is where the real spend sits: the cost of this pattern is the polling loop, not the filter. One poll per block is the natural cadence, since logs cannot appear between blocks. Where a persistent connection is possible, a WebSocket subscription replaces the whole loop with pushes; inside a BLAZED.sh container that connection is a local socket to the node on the same host, so there is rarely a reason to poll at all.

eth_newFilter: frequently asked questions