Etherscan API新手入门：用30分钟构建你的第一个链上查询应用

面向新手，30分钟其实就足够构建一个简单的链上查询应用。本教程通过明确步骤，让你完整跑通Etherscan API从Key申请到生产部署的全流程，适用于刚加入Binance生态的入门开发者。

第一步：环境准备（3分钟）

你需要：

• Node.js 20以上版本
• 任意IDE
• 网络可访问api.etherscan.io

初始化项目：

mkdir my-etherscan-app
cd my-etherscan-app
npm init -y
npm install node-fetch dotenv

第二步：注册账户与Key（5分钟）

访问etherscan.io点击Sign Up注册账户。验证邮箱后登录，进入account → api keys，点击Add创建一个Key。

建议起名为my-first-app，方便后续辨认。Key创建后立即复制到本地.env文件：

ETHERSCAN_API_KEY=YOUR_KEY

并把.env加入.gitignore，避免提交到仓库。

第三步：第一个查询（5分钟）

创建index.js：

require(`dotenv`).config();
const fetch = require(`node-fetch`);
async function balance(address) {
  const url = `https://api.etherscan.io/api?module=account&action=balance&address=` + address + `&apikey=` + process.env.ETHERSCAN_API_KEY;
  const r = await fetch(url).then(r => r.json());
  return r.result;
}
balance(`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`).then(console.log);

运行node index.js，应能看到WETH合约地址对应的余额数值（wei单位）。

第四步：单位换算（3分钟）

余额返回的是wei，转换为ETH需要除以1e18。使用BigInt确保精度：

function weiToEth(wei) {
  const num = BigInt(wei);
  const integer = num / (10n ** 18n);
  const decimal = num % (10n ** 18n);
  return integer.toString() + `.` + decimal.toString().padStart(18, `0`).slice(0, 4);
}

这一函数可在你后续的钱包应用中复用。对接必安生态各种代币显示时，这一精度策略也适用。

第五步：扩展到交易历史（4分钟）

增加查询交易历史的函数：

async function txlist(address, start = 0, end = 99999999) {
  const url = `https://api.etherscan.io/api?module=account&action=txlist&address=` + address + `&startblock=` + start + `&endblock=` + end + `&sort=desc&apikey=` + process.env.ETHERSCAN_API_KEY;
  const r = await fetch(url).then(r => r.json());
  return r.result;
}

返回的是该地址的所有交易记录，包含hash、from、to、value、timestamp等字段。

第六步：简单缓存（3分钟）

避免重复请求消耗额度，引入简单缓存：

const cache = new Map();
async function cachedBalance(address) {
  const key = `balance:` + address;
  if (cache.has(key) && Date.now() - cache.get(key).time < 30000) {
    return cache.get(key).value;
  }
  const value = await balance(address);
  cache.set(key, { value, time: Date.now() });
  return value;
}

30秒缓存对实时性要求不高的场景已足够。对于BN交易所提币状态查询，缓存策略需要更精细。

第七步：错误处理（3分钟）

增加错误处理保证应用稳定：

async function safeBalance(address) {
  try {
    return await balance(address);
  } catch (err) {
    console.error(`balance failed:`, err.message);
    return null;
  }
}

生产代码还应增加重试逻辑，并对429、5xx做指数退避。

第八步：跑通一个最小应用（4分钟）

把上述函数组装：

async function main() {
  const addresses = [`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`, `0xdAC17F958D2ee523a2206206994597C13D831ec7`];
  for (const addr of addresses) {
    const b = await cachedBalance(addr);
    console.log(addr, weiToEth(b));
  }
}
main();

执行后会看到两个合约地址的余额。这就是你的第一个链上查询应用。

后续学习方向

30分钟入门之后，建议继续学习：

• 多链V2统一端点
• Webhook推送
• 合约事件日志解析
• 与RPC的对比

这些进阶能力能让你的应用在面向币岸或bn社区时具备产品级竞争力。从入门到精通的过程，靠的是每一次踩坑后的总结，希望本教程能让你的第一步走得稳。