eth_newBlockFilter

eth_newBlockFilter registers a new block filter on the server and returns a hex filter ID. From then on, the server tracks the hash of every block that is added to the chain after the filter was created. You retrieve those hashes by calling eth_getFilterChanges with the ID; each poll returns the block hashes seen since your previous poll and advances the filter's cursor.

This is the HTTP-based alternative to a WebSocket subscription (eth_subscribe with newHeads): instead of the server pushing new blocks to you over a persistent connection, you create a filter once and poll it 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. It is the right choice for clients that cannot hold a WebSocket open — serverless functions, simple cron jobs, or environments behind restrictive proxies.

A filter is a stateful server-side resource. It is not tied to the lifetime of any single request, so a filter you create but never clean up lingers as an orphan and can accumulate over time. Always release a filter you are done with by calling eth_uninstallFilter. Filters also expire after a period of inactivity; once expired, polling them returns -32000 filter not found, which is your signal to recreate the filter and resume.

This method takes no parameters. Send an empty positional array.

The result is a single 0x-prefixed hex string — the filter ID. Pass it to eth_getFilterChanges to poll and to eth_uninstallFilter to release it.

See errors.md for the full error envelope and handling guidance.

JavaScript (fetch)

async function newBlockFilter() {
  const res = await fetch("https://api.triport.io/v1/polygon", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.TRIPORT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "eth_newBlockFilter",
      params: [],
    }),
  });


  const { result, error } = await res.json();
  if (error) throw new Error(error.message);
  return result; // e.g. "0x1a4b0d2e9f7c8a6b5d3e1f0c2b4a6d8e"
}


// Create a filter, poll it once per Polygon block (~2s), and clean up on exit.
const filterId = await newBlockFilter();
console.log("filter:", filterId);

TypeScript SDK (@triport/sdk)

import { Triport } from "@triport/sdk";


const client = new Triport({ apiKey: process.env.TRIPORT_API_KEY! });


// Create a block filter and poll it for new block hashes.
const filterId = await client.polygon.request<string>("eth_newBlockFilter", []);


const timer = setInterval(async () => {
  const hashes = await client.polygon.request<string[]>(
    "eth_getFilterChanges",
    [filterId],
  );
  for (const hash of hashes) console.log("new block:", hash);
}, 2000);


// When finished, stop polling and release the server-side filter.
async function stop() {
  clearInterval(timer);
  await client.polygon.request<boolean>("eth_uninstallFilter", [filterId]);
}

Python (triport-sdk)

import os
import time
from triport import Triport


client = Triport(api_key=os.environ["TRIPORT_API_KEY"])


# Create a block filter, then poll it for new block hashes.
filter_id = client.polygon.request("eth_newBlockFilter", [])
print("filter:", filter_id)


try:
    while True:
        hashes = client.polygon.request("eth_getFilterChanges", [filter_id])
        for h in hashes:
            print("new block:", h)
        time.sleep(2)  # ~one Polygon block
finally:
    # Always release the server-side filter.
    client.polygon.request("eth_uninstallFilter", [filter_id])

• Create once, poll many. A single eth_newBlockFilter call yields one filter ID; reuse it across many eth_getFilterChanges polls rather than creating a fresh filter per poll.
• Always clean up. Filters are server-side resources with no request-scoped lifetime. Release each one with eth_uninstallFilter when you are done; otherwise it lingers as an orphan until it expires through inactivity.
• Expiry is normal. If a poll returns -32000 filter not found, the filter expired or was already removed — recreate it with eth_newBlockFilter and resume polling.
• No daily cap. This method is on the free tier (polygon_read_rpc category). Rate limiting is sustained RPS per tier with a burst allowance; there is no daily quota.
• Filter the polling interval to block time. Polygon produces a block roughly every 2 seconds, so polling much faster than that wastes requests without surfacing new blocks any sooner.
• Related: eth_getFilterChanges (poll), eth_uninstallFilter (release). For lower-latency push delivery where a persistent connection is possible, prefer a WebSocket newHeads subscription instead of polling.