Polygon Websocket (JSON-RPC PubSub)

Stream real-time Polygon blockchain data using WebSocket subscriptions. Get instant notifications for new blocks, pending transactions, and smart contract events without polling.

🚀
Quick Start
Ready to start streaming Polygon data? Our WebSocket endpoint provides real-time access to on-chain events with minimal setup.
👉 Check Polygon WebSocket Reference

What is Polygon WebSocket?

Polygon WebSocket interface implements the JSON-RPC 2.0 PubSub specification, enabling your application to receive real-time notifications over a persistent bidirectional connection. Instead of repeatedly polling RPC endpoints for updates, the server pushes events to your client the moment they occur on-chain.

Key features:

Low latency: Block header notifications arrive within seconds of chain confirmation
Server-side filtering: Subscribe to specific event types blocks, pending transactions, or contract logs with topic filters
Full JSON-RPC over WebSocket: Execute any standard eth_* RPC method over the same connection used for subscriptions
Auto-cleanup: Subscriptions close when the connection drops

Best for:

Block explorers and real-time dashboards
Mempool monitoring and gas price tracking
Smart contract event streaming (ERC-20 transfers, DEX swaps, NFT mints)
Transaction confirmation tracking
MEV and gas optimization strategies
Wallet notifications and balance updates

Supported Subscription Methods

Tatum's Polygon WebSocket endpoint supports the full eth_subscribe / eth_unsubscribe specification with 3 subscription types plus full JSON-RPC access over the same connection:

Subscription Types

Subscription	Description	Use Case
`newHeads`	New block headers as they are mined	Block explorers, gas tracking, chain monitoring
`newPendingTransactions`	Transaction hashes entering the mempool	Mempool dashboards, MEV monitoring, gas estimation
`logs`	Filtered event logs from smart contracts	Token transfers, DEX swaps, NFT activity, protocol events

JSON-RPC Methods Over WebSocket

In addition to subscriptions, you can call any standard Polygon JSON-RPC method over the same WebSocket connection. This eliminates the need for a separate HTTP connection:

Method	Description
`eth_getBlockByNumber`	Fetch full block data with transactions
`eth_getTransactionByHash`	Look up transaction details by hash
`eth_getTransactionReceipt`	Get transaction receipt with logs and status
`eth_getBalance`	Query account balance
`eth_call`	Execute a read-only smart contract call
`eth_getCode`	Get contract bytecode
`eth_getLogs`	Query historical event logs
`eth_gasPrice`	Get current gas price estimate
`eth_blockNumber`	Get latest block number
`net_version`	Get network ID
...and most other standard `eth_` methods*	See unsupported methods for exceptions

ℹ️
WebSocket + RPC on One Connection
Polygon's WebSocket endpoint supports both subscriptions and standard RPC calls on the same connection. This means you can subscribe to newHeads, then immediately call eth_getBlockByNumber to fetch full block details all over a single WebSocket.

Not Supported

Method	Status	Why
`syncing` subscription	❌ Not supported	Not available on Tatum's infrastructure. The `eth_syncing` RPC call is also not supported.
`eth_syncing` RPC call	❌ Not supported	Returns `Method not found`. Tatum nodes are fully synced; sync status is not exposed.
`eth_newFilter` / `eth_getFilterChanges`	❌ Not supported	Stateful filter methods. Use `eth_subscribe` with `logs` for real-time events, or `eth_getLogs` for historical queries. See why Tatum does not support eth_newFilter.

ℹ️
Workaround for Unsupported Methods
For syncing: Tatum nodes are fully synced and maintained sync status monitoring is not needed. If your application requires a health check, use eth_blockNumber to verify the node is returning current blocks.
For eth_newFilter: Use eth_subscribe with logs for real-time event streaming, or eth_getLogs for historical log queries. Both are more scalable and better suited for production workloads.

Connection

Connect to the Polygon WebSocket endpoint with your API key:

Supported networks:

Mainnet: wss://polygon-mainnet.gateway.tatum.io/{API_KEY}

ℹ️
Testnet WebSocket Availability
WebSocket connections are currently available for Polygon Mainnet only. Testnet support HTTP RPC but do not expose WebSocket endpoints at this time. Use HTTP RPC for testnet development and WebSocket for mainnet production workloads.

WebSocket vs. HTTP Polling

Feature	WebSocket	HTTP Polling
Protocol	Persistent WS connection	Repeated HTTP requests
Latency	Real-time push (~0ms after node processes)	Poll interval dependent (1s–15s typical)
Bandwidth	Efficient (events only)	Wasteful (many empty responses)
Complexity	Moderate (connection management)	Simple (stateless requests)
Mempool access	✅ `newPendingTransactions`	❌ Not available
Event streaming	✅ `logs` subscription with filters	❌ Must poll `eth_getLogs`
Best for	Dashboards, real-time UIs, event-driven backends	Simple scripts, serverless functions, one-off queries

Recommendation:

Use WebSocket for: real-time dashboards, block explorers, mempool monitoring, event-driven architectures.
Use HTTP RPC for: serverless functions, one-off queries, simple scripts, environments where persistent connections aren't possible.

Updated 32 minutes ago

Did this page help you?