Polygon

Polygon networks are routed by Chain IDs 137 and 80002

Polygon networks are separate EVM execution environments, so an RPC client must bind chain ID 137 to Polygon PoS mainnet and 80002 to Amoy. The client should query eth_chainId, compare the hexadecimal response with its expected target, and reject every read or transaction after a mismatch.

Routing a Request from Configuration to Polygon PoS

A reliable Polygon RPC flow chooses one target, probes its identity, and creates the client only after an exact match.

Set One Expected Chain

Assign one typed configuration value before constructing any provider. Production resolves to decimal chain ID 137, while testing resolves to decimal chain ID 80002. Keep the endpoint alias beside that value, but never infer identity from an alias such as “mainnet” or “testnet.” An operator can replace an endpoint without changing the expected chain, which separates transport maintenance from network selection.

Probe Before Business Calls

Send one JSON-RPC 2.0 request for eth_chainId with an empty params array. The method accepts zero parameters and returns one hexadecimal quantity in result. Parse that quantity as an integer, compare it with the configured decimal ID, and stop initialization when the values differ. Balance reads, nonce queries, simulations, and fee estimation should begin only after this gate passes.

Bind Reads and Writes Together

Create the reader, signer, event subscriber, and receipt poller from the verified chain context. A write client pointed at 137 must not borrow nonce or gas data from an 80002 reader. Include the chain ID in structured logs and deployment records, because an endpoint name alone does not prove where a transaction ran. Recheck identity whenever a backend transport reconnects or changes endpoints.

This three-stage gate turns a configuration assumption into a verified routing decision before the application touches chain-specific state.

Chain IDs 137 and 80002 Split Production from Testing

The two Polygon targets separate production state from testing state, even though both expose EVM-compatible JSON-RPC methods. Polygon PoS mainnet uses chain ID 137, while the Amoy testnet uses chain ID 80002. Mainnet connects to Ethereum as its parent chain; Amoy uses Sepolia. A wallet address keeps the same 20-byte form on both, yet its balance, nonce, contracts, and transaction history belong to the selected chain. Adding the identifier to every state key prevents test data from entering production views.

Gas Metadata Follows the Selected Chain

Polygon gas metadata follows the chain selection: both current targets use POL, while balances and transaction histories remain separate.

Production POL Pays Real Execution

For context, Polygon PoS debits production gas from the native POL balance attached to the sending address.

POL uses 18 decimal places in standard EVM tooling, so 1 POL equals 10^18 wei. Polygon PoS supports EIP-1559 type 2 transactions, which carry maxFeePerGas and maxPriorityFeePerGas; the charged amount combines the network base fee with the included priority fee. Legacy type 0 transactions instead carry one gasPrice field. Gas estimates and fee suggestions change with chain conditions, but the signer must embed chain ID 137 before broadcasting a production transaction. A correct fee quote never repairs a wrong network selection.

Amoy POL Keeps Tests Isolated

Faucet-issued test POL pays Amoy gas and has no production value. The same 18-decimal unit model and EIP-1559 fields apply, but the estimator must query chain 80002. Copying a mainnet fee response into a test flow mixes two independent states. A test runner should fund the Amoy address, read its balance through the Amoy provider, and build the transaction within the same verified context.

What Should eth_chainId Return for Each Polygon Network?

The eth_chainId method returns one 0x-prefixed hexadecimal quantity and accepts zero parameters from a properly configured Polygon endpoint.

For Polygon PoS, chain ID 137 appears as 0x89, while Amoy chain ID 80002 appears as 0x13882. Decimal and hexadecimal are two representations of the same integers. Parse the returned quantity before comparison; string comparisons become brittle when libraries normalize letter case or remove leading zeroes. EIP-695 ties this method to the identifier used for EIP-155 transaction signing, making it the correct routing check. The older net_version method reports a network identifier and should not govern transaction routing.

The JSON-RPC request id only correlates a response with its request; it is unrelated to the chain ID. Validate the result field, retain the parsed integer in the provider context, and print both forms in diagnostics. Showing 137 beside 0x89, or 80002 beside 0x13882, makes configuration reviews faster without changing the underlying value.

Wallet Switching Depends on Hexadecimal Identifiers

Wallet routing uses the same identity values, while EIP-1193 providers expose them as hexadecimal strings during selection and events.

A wallet_switchEthereumChain request carries one object parameter containing chainId. Use 0x89 for Polygon PoS or 0x13882 for Amoy. A successful switch returns null, but the request does not add missing network metadata. After the wallet confirms a switch, query eth_chainId again and rebuild chain-bound clients. MetaMask and other injected providers also emit chainChanged, so the interface must discard stale balances, fee estimates, contract instances, and pending requests.

Adding a network follows a separate EIP-3085 shape. The request needs at least 1 RPC entry, and any supplied nativeCurrency object contains 3 fields: name, symbol, and decimals. Polygon metadata uses POL with 18 decimals. A conforming wallet compares the declared chain ID with the endpoint response and rejects disagreement, which makes an obsolete or misrouted endpoint visible during setup.

Tooling Keeps Decimal IDs in Project Configuration

Development tools keep Polygon networks reproducible by storing decimal chain IDs beside separate endpoint aliases and deployment records. Hardhat network configuration accepts 137 or 80002 as chainId. Foundry RPC aliases keep mainnet and Amoy transports distinct. viem chain objects carry the numeric identifier, while ethers exposes the detected value through its network object. Remix inherits the active network from its injected wallet. Each tool still benefits from one explicit identity assertion before deployment, because a familiar alias does not override an endpoint response.

Mismatch Failures Reveal the Broken Layer

A chain mismatch identifies whether configuration, transport, wallet state, or cached application data points at the wrong Polygon target.

Endpoint Identity Differs

An expected 137 with an actual 80002 means the endpoint route is wrong, regardless of its label. Reject startup and report both decimal and hexadecimal values. An empty response, invalid hex quantity, or JSON-RPC error belongs to the transport layer; retrying a transaction does not resolve identity. Test a replacement endpoint with the same zero-parameter probe before admitting it to the pool.

Wallet State Changes

An injected provider can change chains while the page remains open. Handle chainChanged, clear chain-scoped objects, and verify the new value before enabling writes. EIP-1193 reserves error 4900 for disconnection from every chain and 4901 for disconnection from the requested chain. Those codes distinguish a dead provider from a provider that still reaches another network, giving the interface a precise recovery path.

Cache Keys Collide

Cache keys must carry the chain ID alongside every address, hash, block number, and contract record.

An EVM address contains 20 bytes and displays 40 hexadecimal digits after the 0x prefix, so identical address text appears across independent chains. A transaction hash contains 32 bytes and displays 64 hexadecimal digits after its prefix, yet its lookup still requires the correct RPC target. Use compound keys such as chain ID plus address for balances, and chain ID plus transaction hash for receipts. Indexers should partition cursors by chain as well. This prevents an Amoy deployment record from being presented as a Polygon PoS contract merely because the byte strings match.

Production Routing Needs Endpoint Isolation and Verification

Production Polygon routing stays predictable when each environment owns separate credentials, health checks, queues, and indexed state.

Keep an allowlist containing exactly the two intended identifiers, 137 and 80002, then assign only one to each running process. Probe every HTTP or WebSocket transport at startup and after reconnection. If a service uses multiple providers for resilience, require every member of the production pool to return 0x89; the Amoy pool must return 0x13882. Send reads and writes through clients created from the same verified pool. Record the chain ID with the deployment artifact, contract address, transaction hash, and block number so later automation reconstructs one coherent chain context.

Smart contracts also read the identifier through the EVM CHAINID opcode 0x46. The opcode takes 0 stack arguments and pushes one 256-bit chain ID, exposed in Solidity as block.chainid. EIP-712 domains use a uint256 chain ID when that field is present. For legacy EIP-155 signing, the protected preimage expands from 6 RLP elements to 9 by adding the chain ID and 2 zero placeholders. These mechanisms bind on-chain checks and signed data to the selected network.

Across Polygon networks, the endpoint is replaceable infrastructure, while the verified chain ID is the routing invariant. Carry that invariant through configuration, providers, wallets, databases, signatures, and receipts. Every operational record then names one unambiguous Polygon target.

Answers to common questions