使用 Web3.js 获取 ERC-20 代币余额的完整指南

在以太坊生态系统中，ERC-20 是最常见的代币标准之一，它定义了一套统一的接口规则，使得智能合约能够以标准化方式实现代币功能。本文将详细介绍如何利用 Web3.js 库查询任意以太坊钱包地址的 ERC-20 代币余额。

重要提示：Web3.js 已不再积极维护，建议新项目选用 Ethers.js 或 Viem 等现代库进行开发。本文内容仍适用于现有 Web3.js 项目的维护参考。

准备工作

在开始操作前，请确保您的系统已满足以下基础要求：

安装 Node.js（推荐 18.x 或更高版本）
具备代码编辑器（如 VS Code）
熟悉终端/命令行操作

核心依赖项

依赖项	推荐版本
Node.js	18.16.0
Web3.js	4.1.1

配置以太坊节点连接

要与以太坊网络交互，首先需要接入一个节点服务提供商。您可以使用公共节点，但为了获得更稳定的性能，建议使用专业服务。

注册并登录节点服务平台
创建以太坊主网端点（Endpoint）
复制提供的 HTTP 提供商 URL

初始化项目结构

创建项目目录并初始化 Node.js 环境：

mkdir ERC20Balance
cd ERC20Balance
npm init --yes
npm install web3

随后在项目根目录中创建 index.js 文件作为主脚本文件。

获取代币余额的完整流程

获取 ERC-20 代币余额需经历以下几个关键步骤：

建立节点连接

在 index.js 中导入 Web3 库并配置提供商：

const { Web3 } = require("web3");
const endpointUrl = "您的节点URL";
const httpProvider = new Web3.providers.HttpProvider(endpointUrl);
const web3Client = new Web3(httpProvider);

定义合约ABI接口

ABI（应用程序二进制接口）是智能合约与外部世界通信的桥梁。对于余额查询，我们只需包含 balanceOf 方法的最小ABI：

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

确定代币与钱包地址

以 Basic Attention Token (BAT) 为例：

代币合约地址：0x0D8775F648430679A709E98d2b0Cb6250d2887EF
查询目标钱包地址：可通过 Etherscan 的代币持有人列表获取

整合代码实现查询

将以上元素组合成完整查询脚本：

const tokenAddress = "0x0d8775f648430679a709e98d2b0cb6250d2887ef";
const walletAddress = "0xfd821d8cea64feacb6ec86d979e37bc64c64a00b";

const contract = new web3Client.eth.Contract(minABI, tokenAddress);

async function getBalance() {
  const result = await contract.methods.balanceOf(walletAddress).call();
  const resultInEther = web3Client.utils.fromWei(result, "ether");
  
  console.log(`Wei单位余额: ${result}`);
  console.log(`Ether单位余额: ${resultInEther}`);
}

getBalance();

运行脚本后将输出指定钱包的 BAT 余额（分别以 wei 和 ether 为单位显示）。

👉 查看实时余额查询工具

替代方案：使用专业Token API

除直接与合约交互外，还可通过专业API服务获取代币数据。这类API通常提供更简洁的调用方式和更丰富的返回值，包括代币元数据和交易历史等信息。

以下示例展示了如何通过API查询钱包的所有代币余额：

(async () => {
  const heads = await web3Client.requestManager.send({
    method: "qn_getWalletTokenBalance",
    params: [{ wallet: "0xfd821d8cea64feacb6ec86d979e37bc64c64a00b" }]
  });
  console.log(heads);
})();

常见问题

ERC-20标准是什么？

ERC-20是以太坊网络上智能合约遵循的技术标准，规定了代币合约必须实现的基本功能和事件。它包括余额查询、转账授权等核心方法，确保了不同代币之间的互操作性。

为什么查询到的余额显示为极大数值？

以太坊网络中代币余额默认以最小单位（wei）记录，1个代币通常等于10^18 wei。直接查询原始数据会得到极大整数，需要经过单位转换才能获得可读余额。

如何选择以太坊节点服务提供商？

选择节点服务时应考虑可靠性、响应速度和成本因素。专业服务提供商通常能提供更稳定的连接质量和更高的请求速率限制，适合商业级应用。

Web3.js与其他库相比有何优势？

Web3.js是以太坊最早的JavaScript库之一，具有广泛的社区支持和丰富的文档资源。然而新库如Ethers.js和Viem提供了更现代的API设计和更好的性能表现，建议新项目优先考虑。

如何处理交易失败的情况？

智能合约调用可能因Gas不足或合约限制而失败。在实际应用中应当添加错误处理逻辑，包括重试机制和详细的错误日志记录，确保系统的稳定性。

能否同时查询多个代币余额？

可以并行发起多个查询请求，但需注意速率限制问题。对于大规模查询需求，建议使用批量请求功能或专门的余额查询API以提高效率。

通过本文介绍的方法，您已经掌握了使用Web3.js查询ERC-20代币余额的核心技术。无论您是开发者还是区块链爱好者，这项技能都将帮助您更好地理解和交互以太坊生态系统中的各种代币资产。