How to Query Ethereum Mainnet and ERC-20 Token Balances Using Node.js

·

Blockchain development has opened new frontiers for developers across all domains — especially for frontend engineers stepping into Web3. One of the most fundamental tasks in interacting with the Ethereum network is retrieving balance information, whether it's for ETH (Ethereum’s native cryptocurrency) or ERC-20 tokens. This guide walks you through how to query both ETH balances and ERC-20 token balances using Node.js and the Web3.js library, with clear code examples and best practices.

Whether you're building a wallet interface, a decentralized exchange dashboard, or simply exploring blockchain data, understanding how to retrieve and format balance data correctly is essential.

Querying Ethereum (ETH) Balance

The first step in reading blockchain data is connecting to an Ethereum node. With Web3.js, you can easily interact with the Ethereum blockchain by calling built-in methods.

To get the ETH balance of any public address, use the getBalance() method provided by the web3.eth module.

const balanceWei = await web3.eth.getBalance(address);

Here, address is the Ethereum public key (e.g., 0x...) whose balance you want to check.

⚠️ Important: The returned value is in wei, the smallest denomination of ether (1 ETH = 10^18 wei). You cannot display raw wei values directly to users — they must be converted into a human-readable format.

Converting Wei to Ether

Use the fromWei() utility function to convert the balance from wei to ether:

const balanceEther = web3.utils.fromWei(balanceWei, 'ether');

Now balanceEther represents the account balance in ETH (e.g., 1.5, 0.0023) — perfect for display in user interfaces.

👉 Learn how to connect your app to real-time blockchain data with ease.

This simple two-step process — fetching the balance and converting units — forms the foundation of most Ethereum-based balance displays.

Querying ERC-20 Token Balances

While ETH is the native currency of Ethereum, most applications also need to support ERC-20 tokens, such as USDT, DAI, or custom project tokens. Unlike ETH, token balances are not stored directly on addresses but within smart contracts.

To retrieve a user’s token balance, you need:

  1. The token contract address
  2. The contract ABI (Application Binary Interface)
  3. The user’s public wallet address

Step 1: Create a Contract Instance

Use web3.eth.Contract to instantiate the token contract:

const tokenContract = new web3.eth.Contract(contractAbi, contractAddress);

Once instantiated, you can call read-only methods on this contract.

Step 2: Retrieve Token Metadata

ERC-20 contracts typically expose standard methods to fetch basic token details:

const name = await tokenContract.methods.name().call();       // e.g., "Tether USD"
const symbol = await tokenContract.methods.symbol().call();   // e.g., "USDT"
const decimals = await tokenContract.methods.decimals().call(); // e.g., 6

These values provide context for displaying token information accurately.

Step 3: Get User Balance

Use the balanceOf() method to retrieve the token balance for a specific address:

const balanceRaw = await tokenContract.methods.balanceOf(address).call();

Like ETH balances, this value is returned as an integer in the smallest unit of the token — not in its full decimal form.

For example, USDT has 6 decimal places. So if balanceRaw returns 1500000, the actual balance is 1.5 USDT.

Step 4: Format Balance Using Decimals

To convert the raw balance into a readable number:

const balanceFormatted = balanceRaw / Math.pow(10, decimals);

Alternatively, use Web3’s utility (if decimals are known):

const balanceFormatted = web3.utils.fromWei(balanceRaw, 'mwei'); // For 6 decimals
💡 Tip: Always fetch decimals() dynamically rather than hardcoding it — different tokens have different precision levels (e.g., 6 for USDC, 18 for DAI).

Core Keywords for SEO Optimization

To ensure visibility and relevance in search results, here are the core keywords naturally integrated throughout this article:

These terms reflect common developer search queries related to Ethereum development and are strategically included without keyword stuffing.

Frequently Asked Questions (FAQ)

Q: Can I query Ethereum balances without running my own node?

Yes. You don’t need to run a full Ethereum node. Services like Infura, Alchemy, or OKX Web3SDK allow you to connect to Ethereum nodes via HTTPS/WSS endpoints using API keys. Just configure your Web3 provider like this:

const web3 = new Web3('https://mainnet.infura.io/v3/YOUR_PROJECT_ID');

👉 Access scalable blockchain infrastructure without managing nodes yourself.

Q: What is the difference between wei and ether?

Wei is the smallest unit of ether — 1 ether equals 1,000,000,000,000,000,000 (10^18) wei. All calculations on-chain happen in wei because integers are safer than floating-point numbers. Always convert to ether (or gwei) only when displaying values to users.

Q: Where do I get a contract ABI?

You can find verified ABIs on block explorers like Etherscan. Navigate to the token’s contract page → "Contract" tab → "ABI" section → copy as JSON. Make sure you're using the correct ABI version matching the deployed contract.

Q: Why does my token balance show up as a huge number?

Because it's returned in raw units (without decimal formatting). For example, 1 DAI with 18 decimals becomes 1000000000000000000 in raw form. Always divide by 10^decimals to get the human-readable amount.

Q: Can I query multiple tokens at once?

Yes. You can loop through multiple contract addresses and create individual instances to fetch balances in parallel using Promise.all() for better performance:

const promises = tokens.map(token => 
  new web3.eth.Contract(token.abi, token.address)
    .methods.balanceOf(userAddress).call()
);

const balances = await Promise.all(promises);

Final Thoughts and Next Steps

Understanding how to query both ETH and ERC-20 balances is foundational for any Web3 application. From wallets to DeFi dashboards, accurate balance display enhances user trust and experience.

As you advance, consider integrating features like:

With solid fundamentals in place, scaling your blockchain application becomes much more manageable.

👉 Start building powerful blockchain tools with reliable API access today.

Remember: always validate inputs, handle errors gracefully (try/catch), and never expose sensitive keys in client-side code.

By mastering these core interactions — reading balances, formatting values, and working with smart contracts — you're well on your way to becoming proficient in modern blockchain development using Node.js and Web3.js.