Etherscan API从零开始：新手友好的链上数据接入指南

你刚接触链上数据查询，可能听过Etherscan的名字。这家以太坊浏览器除了提供网页查询，还开放了完善的REST API。本文从零开始，带新手一步步完成第一个API调用，并实现几个常见功能，适用于面向Binance生态的应用接入。

一、API的基本概念

API即应用程序接口，是Etherscan提供给开发者通过HTTP请求获取链上数据的通道。你的应用发送请求，Etherscan返回JSON响应，整个过程不需要自建以太坊节点，极大降低了入门门槛。

对于刚开始做钱包或资产查询应用的团队，使用Etherscan API是最快上线的路径。这一路径在必安生态许多DApp中已被广泛验证。

二、申请API Key

第一步是申请API Key：

1. 注册Etherscan账户
2. 登录后进入 my account 页面
3. 选择API Keys菜单
4. 点击 Add 按钮创建新Key
5. 给Key起个名字，例如 dev、prod

创建成功后会显示Key字符串，立即复制保存。后续所有API请求都需带上这个Key。

三、第一个API请求

打开命令行或浏览器，访问：

https://api.etherscan.io/api?module=account&action=balance&address=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2&apikey=YOUR_KEY

这一请求查询WETH合约地址的余额。响应JSON包含status、message、result三个字段。result是以wei为单位的余额，需要除以1e18得到ETH数。

四、常用接口浏览

几个新手最常用的接口：

• account/balance：查询单地址余额
• account/balancemulti：批量查询多个地址
• account/txlist：查询交易历史
• contract/getabi：获取合约ABI
• gastracker/gasoracle：查询Gas价格

这些接口足以支撑大多数链上数据查询需求。

五、解析响应

Etherscan响应均为JSON，常见字段：

• status：1表示成功，0表示失败
• message：状态描述
• result：结果数据，可能是字符串、对象或数组

建议封装一层客户端，统一处理状态判断与错误抛出。对接BN交易所内部对账系统时，这层封装能让上层业务代码更清晰。

六、Gas与单位换算

以太坊使用wei作为最小单位，1 ETH = 1e18 wei。常用换算：

• 1 ETH = 1000000000 Gwei
• 1 Gwei = 1000000000 wei

显示给用户时，建议保留4到6位小数，避免精度问题。整数运算使用BigInt或BigNumber，不要用普通number类型。

七、错误处理

新手最容易在错误处理上偷懒。建议至少处理以下情况：

• HTTP 429：触发限流，需退避
• status=0且message为NOTOK：检查参数
• status=0且message为max rate limit reached：调用过快
• HTTP 5xx：服务异常，自动重试

八、速率限制

免费账户每秒5次调用、每天100000次。超出后会限流。新手最容易踩坑的就是循环查询无退避。建议：

• 引入指数退避重试
• 高频接口用本地缓存
• 分散请求时间避免集中突发

对于面向币岸社区做钱包查询的应用，缓存层是必备组件。

九、第一个完整例子

用Node.js写一个查询余额的小程序：

const fetch = require(`node-fetch`);
async function getBalance(address) {
  const url = `https://api.etherscan.io/api?module=account&action=balance&address=` + address + `&apikey=` + process.env.ETHERSCAN_KEY;
  const r = await fetch(url).then(r => r.json());
  if (r.status !== `1`) throw new Error(r.message);
  return BigInt(r.result);
}

这段代码已经具备生产代码的雏形：环境变量管理Key、错误处理、BigInt精度。

十、后续学习路径

新手完成本教程后，建议继续学习：

• 多链V2统一端点
• Webhook实时推送
• 合约事件日志解析
• 与节点RPC的差异与互补

这些进阶能力能让你的应用在bn量级业务场景下游刃有余。从零开始的每一步积累，都将变成日后构建可靠链上数据系统的基础。