eth_getFilterChanges

eth_getFilterChanges is the polling half of the stateful filter API. You first create a filter — with eth_newBlockFilter for new blocks or eth_newFilter for logs — and receive a filter ID. You then call eth_getFilterChanges with that ID, and the server returns the items that have appeared since your previous call (or since the filter was created, for the first poll). Each call advances the filter's cursor, so consecutive polls never return the same item twice.

This is the HTTP-based alternative to WebSocket subscriptions (eth_subscribe): instead of the server pushing updates to you, your client polls on an interval. On Polygon, where block time is roughly 2 seconds, a polling loop of about that interval keeps you close to the chain tip. The trade-off versus a WebSocket subscription is more requests and slightly higher latency, in exchange for working over plain request/response HTTP with no persistent connection.

The shape of the returned array depends on the type of filter the ID refers to: a block filter yields an array of 32-byte block hashes, while a log filter yields an array of log objects. A poll that finds nothing new returns an empty array — this is normal and not an error.

Filters are server-side resources with a limited lifetime. If a filter ID is unknown — never created, already removed with eth_uninstallFilter, or expired through inactivity — the call fails with -32000 filter not found. Treat that as a signal to recreate the filter and resume polling.