JavaScript / TypeScript

There are two main library choices for building on Polygon in JavaScript and TypeScript: web3.js and ethers.js. Both are actively maintained and both work unchanged against Polygon PoS, since chain ID 137 is EVM-equivalent — you just point the library at https://polygon.therpc.io/YOUR_API_KEY. For new projects we recommend ethers.js v6: it has stronger first-class TypeScript support and a smaller bundle size, which matters most for browser dApps where load time is user-facing.

Both web3.js and ethers.js are actively maintained and fully support Polygon. For new Polygon projects, prefer ethers.js v6 — its better TypeScript support and smaller bundle size make it the more comfortable default for both backend services and browser dApps.

Web3.js

web3.js is the original and one of the most widely used JavaScript APIs for EVM chains, so it remains a solid choice for Polygon and has a large pool of existing code and examples to draw on. Install it with npm install web3, then create a client by passing the Polygon endpoint straight into the constructor: new Web3('https://polygon.therpc.io/YOUR_API_KEY'). Balances are returned in wei, so convert with web3.utils.fromWei(...) to display MATIC.

1import Web3 from 'web3';
2const web3 = new Web3('https://polygon.therpc.io/YOUR_API_KEY');
3 
4// Get balance
5const getBalance = async (address) => {
6	const balance = await web3.eth.getBalance(address);
7	const balanceInEth = web3.utils.fromWei(balance, 'ether');
8	return balanceInEth;
9};
10 
11// Send transaction
12const sendTransaction = async (from, to, value) => {
13	const tx = {
14		from,
15		to,
16		value: web3.utils.toWei(value, 'ether'),
17	};
18	return await web3.eth.sendTransaction(tx);
19};

• GitHub: https://github.com/web3/web3.js
• Docs: https://web3js.readthedocs.io/
• Key features: complete coverage of the Polygon JSON-RPC API, WebSocket subscriptions, contract interactions, ENS resolution, and a large, established community

Ethers.js

ethers.js is a modern, compact library with first-class TypeScript support, which is why it is our default recommendation for new Polygon work. Install it with npm install ethers, then connect by constructing a JsonRpcProvider with the endpoint: new ethers.JsonRpcProvider('https://polygon.therpc.io/YOUR_API_KEY'). Use ethers.formatEther(...) to turn wei balances into readable MATIC amounts.

1import { ethers } from 'ethers';
2const provider = new ethers.JsonRpcProvider('https://polygon.therpc.io/YOUR_API_KEY');
3 
4// Get balance
5const getBalance = async (address) => {
6	const balance = await provider.getBalance(address);
7	return ethers.formatEther(balance);
8};
9 
10// Send transaction
11const sendTransaction = async (wallet, to, value) => {
12	const tx = await wallet.sendTransaction({
13		to,
14		value: ethers.parseEther(value),
15	});
16	return await tx.wait();
17};

• GitHub: https://github.com/ethers-io/ethers.js/
• Docs: https://docs.ethers.org/
• Key features: first-class TypeScript support, smaller bundle size for Polygon browser dApps, careful security defaults, ENS resolution, and an extensively tested codebase

TypeScript Support

Both libraries ship their own type definitions, so there are no separate @types/* packages to install for either one when building on Polygon. That means you get IDE autocompletion across the full API surface, compile-time checking that catches mistakes before they reach the network, and types that double as inline documentation while you code.

1import { BigNumber } from 'ethers';
2 
3interface TransactionData {
4	to: string;
5	value: BigNumber;
6	gasLimit?: BigNumber;
7}
8 
9const createTransaction = async (data: TransactionData) => {
10	// Your implementation
11};

Node.js Usage

Both web3.js and ethers.js run in Node.js, which makes them a good fit for Polygon backends, indexers, and bots. They support either module style: require() if your project uses CommonJS, or import if it is set up for ES modules — the connection to the Polygon endpoint is identical in both cases.

1// Web3.js in Node.js
2const Web3 = require('web3');
3const web3 = new Web3('https://polygon.therpc.io/YOUR_API_KEY');
4 
5// Ethers.js in Node.js
6const { ethers } = require('ethers');
7const provider = new ethers.JsonRpcProvider('https://polygon.therpc.io/YOUR_API_KEY');

Browser Usage

In the browser, import either library as an ES module and let a bundler like webpack or Vite package it for the web. When your Polygon dApp needs to act on behalf of a user — sending MATIC or signing transactions — connect to their injected wallet (such as MetaMask) with new ethers.BrowserProvider(window.ethereum) instead of a read-only RPC provider, so the wallet handles signing and the user approves each action.

1// Using ES modules
2import { Web3 } from 'web3';
3// or
4import { ethers } from 'ethers';
5 
6// Using window.ethereum (MetaMask)
7const provider = new ethers.BrowserProvider(window.ethereum);