How to Get the Balance of an ERC-20 Token

·

Understanding how to retrieve the balance of an ERC-20 token is a foundational skill for developers building on the Ethereum blockchain. The ERC-20 standard defines a common set of rules that all Ethereum-based tokens must follow, enabling seamless interaction across wallets, exchanges, and decentralized applications. In this guide, you’ll learn how to programmatically check the token balance of any Ethereum wallet using Web3.js, a powerful JavaScript library for blockchain interaction.

Whether you're building a portfolio tracker, a DeFi dashboard, or integrating token balances into your dApp, this tutorial provides a clear, step-by-step approach to fetching real-time token data.

Prerequisites

Before diving into the code, ensure your development environment is ready:

With these tools in place, you’re ready to begin.

Setting Up Your Project

Start by creating a dedicated project folder. Open your terminal and run:

mkdir ERC20Balance
cd ERC20Balance

This creates a new directory and navigates into it. Next, initialize a new Node.js project:

npm init -y

Then install the web3.js library, which enables communication with the Ethereum blockchain:

npm install web3

This command generates package.json, package-lock.json, and the node_modules folder—essential components for your project.

Now, create a file named index.js in your project root. This will house the logic for retrieving ERC-20 token balances.

👉 Discover how to connect to Ethereum and fetch real-time token data with ease.

Understanding the ERC-20 Standard

The ERC-20 specification outlines a standardized interface for fungible tokens on Ethereum. It includes methods like transfer, approve, and crucially, balanceOf, which allows you to query the token balance of any wallet address.

To interact with an ERC-20 contract, you need two things:

You don’t need the full ABI—just the balanceOf function is sufficient for this task.

Writing the Minimal ABI

The ABI tells your script which function to call and how to interpret the response. Here’s a minimal ABI containing only the balanceOf method:

const minABI = [
  {
    constant: true,
    inputs: [{ name: "_owner", type: "address" }],
    name: "balanceOf",
    outputs: [{ name: "balance", type: "uint256" }],
    type: "function",
  },
];

This compact definition is all you need to query a wallet’s token balance.

Finding the Token Contract Address

To get a token’s balance, you must know its smart contract address. For example, USDC, one of the most widely used stablecoins, has the following address on Ethereum:

0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

You can find any ERC-20 token’s contract address on Etherscan by searching for the token name. Always verify the contract is official and audited.

Selecting a Wallet Address

Next, choose the wallet whose balance you want to check. For demonstration, we’ll use this randomly selected address:

0x2e91728aF3a54aCDCeD7938fE9016aE2cc5948C9

You can replace this with any valid Ethereum address—your own, a friend’s, or a DeFi protocol’s treasury.

Connecting to an Ethereum Node

To interact with the blockchain, your script needs to connect to an Ethereum node. You can run your own node, but it’s more efficient to use a reliable API provider.

Use the following code in your index.js file to initialize Web3 with an HTTP provider:

const Web3 = require('web3');
const provider = 'https://ethereum.api.watchdata.io/node/jsonrpc?api_key=YOUR_API_KEY';
const web3 = new Web3(new Web3.providers.HttpProvider(provider));

Replace YOUR_API_KEY with a valid key from your chosen service. This connection allows you to make read requests to the Ethereum network.

Putting It All Together: The Complete Code

Here’s the full script that retrieves an ERC-20 token balance:

const Web3 = require('web3');
const provider = 'https://ethereum.api.watchdata.io/node/jsonrpc?api_key=YOUR_API_KEY';
const web3 = new Web3(new Web3.providers.HttpProvider(provider));

const token = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; // USDC
const wallet = '0x2e91728aF3a54aCDCeD7938fE9016aE2cc5948C9';

const minABI = [
  {
    constant: true,
    inputs: [{ name: "_owner", type: "address" }],
    name: "balanceOf",
    outputs: [{ name: "balance", type: "uint256" }],
    type: "function",
  },
];

const contract = new web3.eth.Contract(minABI, token);

const getBalance = async () => {
  try {
    const res = await contract.methods.balanceOf(wallet).call();
    const format = web3.utils.fromWei(res, 'mwei'); // USDC uses 6 decimals
    console.log(`Balance: ${format} USDC`);
  } catch (err) {
    console.error("Error fetching balance:", err);
  }
};

getBalance();
Note: Token balances are returned in wei, the smallest unit of Ether. Use web3.utils.fromWei() to convert to human-readable units. For USDC, which has 6 decimal places, use 'mwei' as the unit.

Run the script with:

node index.js

You should see output like: Balance: 1500.25 USDC.

👉 Learn how to scale your blockchain projects with real-time data access.

Frequently Asked Questions

How do I find the decimal places of an ERC-20 token?

Check the token’s contract on Etherscan and look for the decimals() function. Most stablecoins like USDC and DAI use 6 decimals, while others like UNI use 18.

Why is my balance showing as a very large number?

The raw balance is returned in the smallest unit (e.g., wei for Ether). Always use web3.utils.fromWei(value, 'unit') with the correct decimal unit—like 'ether', 'mwei', or 'gwei'—to format it properly.

Can I check balances for multiple tokens at once?

Yes. You can loop through an array of token addresses and contract ABIs, calling balanceOf for each. Just ensure your API provider supports high request volumes.

Do I need to pay gas to check a balance?

No. Reading data from the blockchain via call() is free. Gas fees only apply when writing data (e.g., sending tokens).

What if the contract doesn’t support ERC-20?

If a token isn’t ERC-20 compliant, it may not have a balanceOf function. Always verify the token standard before querying.

Can I use this method for other blockchains?

Yes—similar approaches work on Binance Smart Chain, Polygon, and other EVM-compatible networks. Just switch the node URL and use the correct chain’s token address.

Core Keywords

With this knowledge, you can now integrate real-time token balance checks into your applications. Whether you're monitoring investments or building a crypto dashboard, understanding how to query blockchain data is essential.

👉 Start building with powerful blockchain tools today.