eth_getBalance

eth_getBalance returns the native-token balance of an account at a chosen block — on Polygon PoS that is the account's MATIC balance, the token used to pay gas. You can read the current balance with latest or look back at any historical block, which is handy for accounting and audits. The value comes back as hex wei (18 decimals). Query https://polygon.therpc.io/YOUR_API_KEY (chain ID 137, 0x89) with an address and a block tag to get it.

Use cases

• Display a wallet's MATIC balance in a Polygon dApp or portfolio UI.
• Verify an account holds enough MATIC to cover gas before estimating or submitting a transaction.
• Poll the balance on a short interval — at ~2s blocks, incoming MATIC payments show up almost immediately.
• Audit the balance at a specific historical block on polygonscan.com for accounting or forensic reconciliation.

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_getBalance",
7    "params": [
8        "0x0000000000000000000000000000000000000000",
9        "latest"
10      ],
11    "id": 1
12  }'

Try it live in the Polygon playground.

Errors & troubleshooting

Common pitfalls

• Never run Number() on the raw hex — a MATIC balance in wei easily exceeds 2^53 and loses precision. Use BigInt(value) and divide by 10n**18n for whole MATIC.
• A balance at latest can still be reorged on Polygon before its Heimdall checkpoint lands on Ethereum; for a system of record read finalized instead.
• This returns only the native MATIC balance. For an ERC-20 such as USDT (0xc2132D05D31c914a87C6611C10748AEb04B58e8F) you must eth_call balanceOf on the token contract.

Supported networks

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

See also

• eth_getTransactionCount
• eth_call
• eth_getProof

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_getBalance","params":["0x0000000000000000000000000000000000000000","latest"]}'