Ethereum Balance Inquiry with Node.js: Mastering ETH and Token Balance Checks on the Blockchain

·

Blockchain technology has opened a new frontier for developers across all domains — especially for frontend engineers stepping into decentralized systems. One of the most practical and foundational skills in this space is querying blockchain data, particularly Ethereum (ETH) mainnet balance and ERC-20 token balances using Node.js. This guide walks you through the core techniques, code implementations, and best practices for retrieving wallet balances directly from the Ethereum network.

Whether you're building a crypto wallet interface, a transaction tracker, or integrating blockchain data into your app, understanding how to fetch accurate balance information is essential.

Querying Ethereum (ETH) Mainnet Balance

The Ethereum main currency, Ether (ETH), can be queried directly using a public wallet address. Thanks to Web3.js — a powerful JavaScript library for interacting with Ethereum — retrieving the native token balance is straightforward.

Start by initializing a Web3 instance connected to an Ethereum node. You can use services like Infura or Alchemy to access the network without running your own node.

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

Once connected, use the getBalance() method to retrieve the balance associated with any Ethereum address:

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

Here, address is the public wallet address (e.g., 0x...). However, there's an important detail: the returned value is in wei, the smallest denomination of ETH (1 ETH = 10¹⁸ wei).

👉 Learn how to securely connect to Ethereum and manage balances with advanced tools.

To convert this into a human-readable format in ether, use Web3’s built-in utility:

const balanceInEth = web3.utils.fromWei(baseValue, 'ether');
console.log(`Balance: ${balanceInEth} ETH`);

Now you have a clean, readable balance — perfect for display in user interfaces or logging systems.

Checking ERC-20 Token Balances

While ETH is the native currency, Ethereum hosts thousands of ERC-20 tokens — from stablecoins like USDT to governance tokens like UNI. These require a different approach because they are managed by smart contracts, not the base protocol.

Step 1: Create a Contract Instance

To query a token balance, you need two things:

The ABI defines what functions are available in the smart contract. For standard ERC-20 tokens, you can often use a minimal ABI that includes just the functions you need.

const contractABI = [
  {
    constant: true,
    inputs: [{ name: '_owner', type: 'address' }],
    name: 'balanceOf',
    outputs: [{ name: 'balance', type: 'uint256' }],
    type: 'function'
  },
  {
    constant: true,
    inputs: [],
    name: 'name',
    outputs: [{ name: '', type: 'string' }],
    type: 'function'
  },
  {
    constant: true,
    inputs: [],
    name: 'symbol',
    outputs: [{ name: '', type: 'string' }],
    type: 'function'
  },
  {
    constant: true,
    inputs: [],
    name: 'decimals',
    outputs: [{ name: '', type: 'uint8' }],
    type: 'function'
  }
];

const contractAddress = '0xTokenContractAddress'; // Replace with actual address
const tokenContract = new web3.eth.Contract(contractABI, contractAddress);

Step 2: Fetch Token Data

With the contract instance ready, call its methods to retrieve key information:

const name = await tokenContract.methods.name().call();
const symbol = await tokenContract.methods.symbol().call();
const decimals = await tokenContract.methods.decimals().call();
const rawBalance = await tokenContract.methods.balanceOf(address).call();

Just like ETH, the balance returned is in the smallest unit of the token (often called "wei" by analogy). To convert it into a readable format:

const formattedBalance = (rawBalance / Math.pow(10, decimals)).toFixed(decimals);
console.log(`Token: ${name} (${symbol})`);
console.log(`Balance: ${formattedBalance}`);

This gives you full visibility into any ERC-20 token held by a wallet.

👉 Discover how real-time blockchain data powers next-gen financial applications.

Core Keywords for SEO and Developer Search Intent

To ensure this content ranks well and meets user needs, here are the core keywords naturally integrated throughout:

These terms reflect common search queries from developers exploring blockchain development with JavaScript.

Frequently Asked Questions (FAQ)

How do I get started with Web3.js in Node.js?

Install Web3.js via npm:

npm install web3

Then import and initialize it with an Ethereum node provider URL (Infura, Alchemy, or local node).

Why is my balance returned in wei?

Ethereum uses wei as its base unit to support high precision in transactions. 1 ETH = 1,000,000,000,000,000,000 wei. Always convert to ether or other units (gwei, szabo, etc.) for readability using web3.utils.fromWei().

Can I query multiple tokens at once?

Yes! You can loop through an array of token contract addresses and ABIs, fetching balances in parallel using Promise.all() for better performance.

Do I need a private key to check balances?

No. Reading balance data is a read-only operation and only requires access to an Ethereum node. Private keys are only needed for signing transactions.

What if the token doesn't support decimals()?

Most legitimate ERC-20 tokens include the decimals() function. If missing, assume 18 decimals (standard for many tokens), but verify via block explorers like Etherscan.

Is it safe to expose my Infura key in frontend code?

While your Infura project ID isn’t a private key, it should still be protected. Exposing it could allow others to use your rate limits. For production apps, route requests through a backend proxy.

👉 Explore secure blockchain API access and scalable infrastructure solutions.

Final Thoughts

Querying Ethereum and ERC-20 token balances using Node.js is a fundamental skill for modern web developers entering the decentralized ecosystem. With Web3.js, you can build powerful tools that interact directly with the blockchain — from portfolio trackers to dApp backends.

By mastering getBalance(), balanceOf(), and proper unit conversion, you lay the groundwork for more advanced interactions like sending transactions, monitoring events, and integrating real-time blockchain data into your applications.

As blockchain continues to reshape digital finance and identity systems, developers who understand these core concepts will be at the forefront of innovation. Keep experimenting, stay secure, and keep building.