OnFinality

Posted on Aug 24 Originally published at onfinality.io

Polygon MATIC API: RPC, SDKs, and Endpoints

#web3 #blockchain #devops #tutorial

Quick Decision Guide: Which Polygon API Do You Need?

Before diving into endpoints and SDKs, it helps to map the Polygon API landscape. The term "Polygon MATIC API" can mean several different things, and picking the wrong one wastes engineering time.

If you need to...	Use this	Example
Read balances, send transactions, call contracts	JSON-RPC endpoint	`eth_getBalance`, `eth_sendRawTransaction`
Interact with the Polygon bridge (legacy)	Matic.js SDK	`posClient.erc20(...)`
Query historical balances, token holders, or complex analytics	Indexing API (e.g., Bitquery)	GraphQL query for balances
Move stablecoins or build payment flows	Payments API (e.g., Chaingateway)	REST call to send USDC

For most dApp developers, the raw JSON-RPC endpoint is the foundation. It gives you full control and works with any Ethereum tooling (ethers, viem, web3.js). If you need indexed data or payment-specific features, you'll add a specialized API on top.

If you're building a production app, you'll want a reliable RPC provider. OnFinality offers managed Polygon RPC endpoints with HTTP and WebSocket support, and you can compare pricing to see if a dedicated node fits your workload.

What Is the Polygon MATIC API?

Polygon (formerly Matic Network) is an Ethereum-compatible proof-of-stake chain. The "Polygon MATIC API" generally refers to the interfaces for interacting with this chain. The core is the JSON-RPC API, which is identical to Ethereum's, so any Ethereum library works out of the box.

Historically, MATIC was the native token used for gas. After the POL upgrade, POL is now the native token, but many docs and tools still reference MATIC. The API itself is unchanged—you're still sending transactions and querying state.

There are also higher-level APIs:

Matic.js: a legacy SDK for interacting with the Polygon bridge contracts. It's still in the docs but is being phased out.
Indexing APIs: services like Bitquery that provide GraphQL or REST endpoints for historical data, token balances, and analytics.
Payments APIs: services like Chaingateway that abstract away node management and provide webhooks for deposits.

Polygon Chain Settings at a Glance

When configuring your app, you need the correct chain ID and RPC URL. Here are the official settings for Polygon mainnet:

Parameter	Value
Chain ID	137
Native currency	POL (formerly MATIC)
Symbol	POL
Decimals	18
Block explorer	https://polygonscan.com
Public RPC URL	`https://polygon.api.onfinality.io/public`
WebSocket support	Yes (via OnFinality)

For testnet, the Polygon Amoy testnet uses chain ID 80002 and the public RPC URL https://polygon-amoy.api.onfinality.io/public. You can find more details on the Polygon network page.

How to Connect to Polygon with JSON-RPC

You can use any Ethereum-compatible library. Here's an example using ethers.js to read a balance and send a transaction:

const { ethers } = require("ethers");

const provider = new ethers.JsonRpcProvider("https://polygon.api.onfinality.io/public");

async function getBalance(address) {
  const balance = await provider.getBalance(address);
  console.log(`Balance: ${ethers.formatEther(balance)} POL`);
}

async function sendTransaction(signer, to, amount) {
  const tx = await signer.sendTransaction({
    to,
    value: ethers.parseEther(amount),
  });
  await tx.wait();
  console.log(`Tx hash: ${tx.hash}`);
}

For raw JSON-RPC calls, you can use curl:

curl -X POST https://polygon.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

This returns the latest block number, confirming your endpoint is live.

Using Matic.js for Bridge Operations

Matic.js is the legacy SDK for interacting with the Polygon bridge. It's still documented, but Polygon Labs recommends newer alternatives for moving money. If you're maintaining existing code, here's a quick example:

const { POSClient, use } = require("@maticnetwork/maticjs");
const { Web3ClientPlugin } = require("@maticnetwork/maticjs-web3");
const HDWalletProvider = require("@truffle/hdwallet-provider");

use(Web3ClientPlugin);

const posClient = new POSClient();
await posClient.init({
  network: "mainnet",
  version: "v1",
  parent: {
    provider: new HDWalletProvider(privateKey, "https://ethereum-rpc.example.com"),
    defaultConfig: { from: userAddress },
  },
  child: {
    provider: new HDWalletProvider(privateKey, "https://polygon.api.onfinality.io/public"),
    defaultConfig: { from: userAddress },
  },
});

const erc20 = posClient.erc20("<token-address>");
const balance = await erc20.getBalance(userAddress);

Note that Matic.js is deprecated for new projects. For modern bridge interactions, consider using the official Polygon bridge UI or a payments API.

Indexing APIs for Balances and History

If you need to query historical balances or token holders, an indexing API like Bitquery can be more efficient than scanning blocks yourself. For example, to get the native POL balance of an address:

query {
  EVM(network: matic, dataset: combined) {
    Balances(
      where: {
        Balance: {
          Address: { is: "0x..." }
        }
      }
    ) {
      Currency { Symbol }
      Balance { Amount }
    }
  }
}

These APIs are useful for analytics dashboards, audit trails, and wallet apps. They typically require an API key and have usage limits.

Choosing Between Public, Managed, and Dedicated RPC

For production apps, the public endpoint is not reliable enough. You have three main options:

Option	Pros	Cons
Public RPC	Free, no signup	Rate limits, unreliable, no SLA
Managed RPC (e.g., OnFinality)	Reliable, scalable, WebSocket support, free tier	Requires API key, usage-based pricing
Dedicated node	Full control, no shared limits, archive data	Higher cost, requires maintenance

OnFinality provides managed Polygon RPC that handles infrastructure concerns like load balancing and failover. For high-throughput or archive needs, a dedicated node might be worth the cost.

Common Pitfalls and Troubleshooting

Chain ID mismatch: Ensure your wallet uses chain ID 137 for mainnet, not 80001 (old Mumbai testnet) or 80002 (Amoy).
Rate limiting: Public endpoints often throttle. If you see 429 errors, switch to a managed provider.
WebSocket disconnects: For real-time updates, use WebSocket but implement reconnection logic.
MATIC vs POL: Some tools still expect MATIC. Check your library's documentation for the correct symbol.

Key Takeaways

The Polygon MATIC API is primarily JSON-RPC, compatible with Ethereum tools.
Choose the right API layer: raw RPC for control, indexing APIs for analytics, payments APIs for stablecoin flows.
Use the correct chain ID (137) and a reliable RPC provider for production.
OnFinality offers managed Polygon RPC with HTTP and WebSocket support.

Frequently Asked Questions

What is the difference between MATIC and POL?

MATIC was the original native token. In 2024, Polygon upgraded to POL, which now serves as the gas token and staking token. The API and chain ID remain the same.

Can I use Ethereum libraries with Polygon?

Yes, Polygon is EVM-compatible, so ethers.js, viem, and web3.js work without modification. Just point them to a Polygon RPC endpoint.

Is the public Polygon RPC endpoint free?

Yes, the public endpoint https://polygon.api.onfinality.io/public is free to use, but it has rate limits. For production, consider a managed RPC plan.

How do I get testnet POL for Amoy?

You can use the Amoy faucet, which is linked from the Polygon network page.

What is Matic.js used for?

Matic.js is a legacy SDK for interacting with the Polygon bridge. It's deprecated for new projects, but existing code may still use it.

Does OnFinality support WebSocket for Polygon?

Yes, OnFinality's Polygon endpoint supports both HTTP and WebSocket. Check the network page for details.

How do I choose between a managed RPC and a dedicated node?

If you need high throughput, archive data, or custom configuration, a dedicated node may be better. For most apps, a managed RPC offers a good balance of cost and reliability. See our RPC provider selection guide for more.

What are the rate limits for the public endpoint?

Public endpoints are subject to rate limits to ensure fair usage. For higher limits, sign up for a free API key on OnFinality.

Can I use Polygon with viem?

Yes, viem supports Polygon out of the box. You can create a client with createPublicClient({ chain: polygon, transport: http("https://polygon.api.onfinality.io/public") }).

DEV Community