eth_subscribe

eth_subscribe opens a push-based subscription over a WebSocket connection to a Polygon PoS node. Instead of repeatedly polling for changes, your client registers interest in an event stream — new block headers, matching logs, pending transaction hashes, or sync status — and the node pushes eth_subscription notifications the moment events occur. On Polygon's fast ~2-second Bor block cadence this is the difference between catching every block and falling behind a busy poller. Point a WebSocket client at the Polygon mainnet endpoint behind https://polygon.therpc.io/YOUR_API_KEY (chain ID 137, 0x89) and the gas-cheap, MATIC-fee network will deliver updates with minimal latency.

Use cases

• Stream newHeads to drive a real-time dashboard or block explorer that reacts to each Polygon block as it is produced, without burning request quota on polling.
• Receive live logs from a specific contract — for example Transfer events from the USDT contract at 0xc2132D05D31c914a87C6611C10748AEb04B58e8F or swap events from QuickSwap pools — as they are mined.
• Monitor newPendingTransactions to watch the Polygon mempool and react to transactions before they are confirmed, useful for trading bots and Polymarket order-flow tooling.

Parameters

Response

Example request

1curl https://polygon.therpc.io/YOUR_API_KEY \
2  -X POST \
3  -H "Content-Type: application/json" \
4  -d '{
5    "jsonrpc": "2.0",
6    "method": "eth_subscribe",
7    "params": [
8        "newHeads",
9        {}
10      ],
11    "id": 1
12  }'

Try it live in the Polygon playground.

Errors & troubleshooting

Common pitfalls

• eth_subscribe only works over a WebSocket connection. Calling it over plain HTTP against the Polygon endpoint returns a "notifications not supported" error.
• Any events emitted while your WebSocket is dropped are lost — the node does not replay them. Build reconnect logic and backfill the gap with eth_getLogs over the missed block range.
• During short Polygon reorgs (Bor produces blocks every ~2 seconds before Heimdall checkpoints them to Ethereum L1), logs notifications can arrive with removed: true. Handle these explicitly so your application rolls back state that referenced an orphaned block.

Supported networks

• Mainnet — Chain ID: 137
• Amoy — Chain ID: 80002

See also

• eth_unsubscribe
• eth_newFilter
• eth_getLogs
• eth_getFilterChanges

1curl https://polygon.therpc.io/YOUR_API_KEY \
2  -X POST \
3  -H 'Content-Type: application/json' \
4  -d '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["",null]}'