Polygon Blockchain API: JSON-RPC Methods, WebSocket & Examples

What Is the Polygon Blockchain API?

The Polygon blockchain API refers to the Ethereum-compatible JSON-RPC interface exposed by Polygon PoS nodes. Polygon PoS uses a two-layer architecture: Bor produces blocks and executes transactions at the execution layer, while Heimdall handles validator coordination and checkpointing. For most developers, the only layer that matters is the execution layer, which speaks the same JSON-RPC protocol as Ethereum.

Every request is a JSON object with jsonrpc, method, params, and id fields. Responses return either a result or an error object. This makes Polygon directly compatible with Ethereum tooling such as ethers.js, web3.js, Hardhat, and Foundry.

• Mainnet chain ID: 137
• Amoy testnet chain ID: 80002
• Common EVM methods: eth_call, eth_getLogs, eth_blockNumber, eth_sendRawTransaction, and more.

Core JSON-RPC Methods: eth_call, eth_getLogs, Transactions, Receipts, and Gas Estimation

Choose the method based on whether you are reading state, searching logs, or writing to the chain. The table below summarizes the most important methods for day-to-day development.

• For write operations, always use eth_estimateGas before sending and poll eth_getTransactionReceipt until the receipt appears.
• Receipts contain status (1 for success), logs, gas used, and effective gas price.

Transaction Submission and Receipt Polling

Submitting a transaction involves signing with a private key, broadcasting via eth_sendRawTransaction, and waiting for inclusion. Do not hardcode private keys; use environment variables or a wallet provider.

• Use eth_getTransactionCount to retrieve the correct nonce for the from address.
• Sign the transaction with an EIP-1559 or legacy gas model.
• Broadcast the raw signed transaction with eth_sendRawTransaction.
• Poll eth_getTransactionReceipt every few seconds until the receipt is available; a null result means the transaction is not yet included.
• Check receipt.status to distinguish success from revert.

HTTP vs. WebSocket and Subscription Workflows

HTTP JSON-RPC is stateless and ideal for one-off calls like eth_call, eth_getLogs, or broadcasting transactions. WebSocket connections stay open and support push-based subscriptions such as eth_subscribe. Use WebSocket when your application must react to new blocks, pending transactions, or specific log events in near real time.

• WebSocket subscriptions require a provider endpoint that supports ws:// or wss://; verify availability for your plan.
• For log subscriptions, use eth_subscribe with logs and filter by address and topics.

Archive and Trace Data References

Archive nodes store historical state, enabling calls like eth_call at past block numbers and eth_getBalance for older blocks. Trace methods such as debug_traceTransaction or trace_transaction expose execution-level details useful for debugging and analysis. Availability depends on the RPC plan and node type; always verify current archive and trace support on the Polygon network page or with your provider.

• For historical eth_call or eth_getBalance at old blocks, use an archive-enabled endpoint.
• Trace methods may be namespaced under debug_ or trace_ depending on the client; check the provider documentation.
• Do not assume archive/trace are included by default on public endpoints.

Minimal curl and JavaScript Examples

The following curl request fetches the latest block number from any Polygon JSON-RPC endpoint. Replace the URL with your provider endpoint. ``bash curl -X POST https://rpc-assistant/polygon-rpc-guide.com \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' ``

This ethers.js example reads the balance of an address using eth_call under the hood, then subscribes to new block headers over WebSocket. ``javascript const { ethers } = require("ethers"); const provider = new ethers.JsonRpcProvider("https://your-rpc-endpoint"); const balance = await provider.getBalance("0x..."); console.log(balance.toString()); const wsProvider = new ethers.WebSocketProvider("wss://your-ws-endpoint"); wsProvider.on("block", (blockNumber) => console.log("New block:", blockNumber)); ``

For current mainnet and Amoy endpoints, see /networks/polygon and /rpc-assistant/polygon-amoy-guide.

Integration Checklist

Next steps: Dedicated Polygon Node.

• Set chain ID 137 for mainnet or 80002 for Amoy testnet in wallet and contract configurations.
• Use environment variables for private keys and provider URLs; never commit secrets.
• Call eth_estimateGas before submitting transactions to reduce out-of-gas failures.
• Handle nonce management with eth_getTransactionCount and increment on retries.
• For WebSocket use, implement reconnect with exponential backoff and resubscribe after a disconnect.
• Test all read, write, and subscription flows on Amoy before deploying to mainnet.
• Verify archive and trace availability on your plan before building features that depend on them.

Frequently Asked Questions