etherscan-api

Etherscan API V2

概览

使用 Etherscan 统一 API V2 查询区块链数据。本技能涵盖：

• 原生 ETH 余额查询
• ERC-20 代币余额查询（单个合约；查询全部持仓需要 PRO 计划）
• 交易历史查询（普通交易、内部交易、ERC-20/ERC-721/ERC-1155 转账）
• 通过 chainid 参数支持多条链

范围： 本技能侧重于免费账户的只读账户查询。有关 Etherscan API 的其他功能，请参阅备用文档。

前提条件

API 密钥验证

进行任何 API 调用之前，请确认已设置 ETHERSCAN_API_KEY 环境变量：

if [ -z "$ETHERSCAN_API_KEY" ]; then
  echo "Error: ETHERSCAN_API_KEY environment variable is not set."
  echo "Get a free API key at: https://etherscan.io/myapikey"
  exit 1
fi

如果缺少该环境变量，请告知用户并停止执行。

链推断

不要默认使用 Ethereum Mainnet。进行任何 API 调用之前，始终根据用户的提示推断链。

推断规则

1. 明确提及链 — 如果用户提到了链名（例如，“在 Polygon 上”、“Arbitrum 余额”、“Base 链”），请使用该链。
2. 特定链上的代币 — 某些代币主要存在于特定链上：
   • POL → Polygon (137)
   • ARB → Arbitrum One (42161)
   • OP → OP Mainnet (10)
   • AVAX → Avalanche C-Chain (43114)
   • BNB → BNB Smart Chain (56)
   • SONIC → Sonic (146)
   • SEI → Sei (1329)
   • MON → Monad (143)
3. 合约地址模式 — 如果用户提供了合约地址，请考虑询问该合约部署在哪条链上（许多合约存在于多条链上）。
4. 测试网关键词 — “testnet”、“Sepolia”、“Hoodi”、“Amoy”等词表示测试网。
5. 不明确的情况 — 如果无法推断链，请先询问用户，再继续操作。不要假定使用 Ethereum Mainnet。

不支持的链

如果用户提到 Etherscan 不支持的链（例如 Solana、Bitcoin），请告知用户：

The chain "[chain name]" is not supported by Etherscan API V2.

Etherscan supports EVM-compatible chains only. For the full list, see:
https://docs.etherscan.io/supported-chains

完整的受支持链及其 ID 列表请参阅 ./references/chains.md。

API 基础 URL

所有请求均使用统一的 V2 端点：

https://api.etherscan.io/v2/api

chainid 参数决定要查询的区块链。

ETH 余额查询

查询地址的原生 ETH（或原生代币）余额。

端点参数

参数	必填	默认值	描述
chainid	否	1	链 ID（参见 chains.md）
module	是	-	设置为 account
action	是	-	设置为 balance
address	是	-	钱包地址（最多支持 20 个逗号分隔的地址）
tag	否	latest	latest 或十六进制区块编号（仅限最近 128 个区块 — 更早的历史记录需要使用 balancehistory PRO 端点）
apikey	是	-	来自 $ETHERSCAN_API_KEY 的 API 密钥

查询单个地址

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balance&address=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe&tag=latest&apikey=$ETHERSCAN_API_KEY"

查询多个地址（最多 20 个）

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balancemulti&address=0xaddress1,0xaddress2,0xaddress3&tag=latest&apikey=$ETHERSCAN_API_KEY"

响应格式

单个地址：

{
  "status": "1",
  "message": "OK",
  "result": "172774397764084972158218"
}

多个地址：

{
  "status": "1",
  "message": "OK",
  "result": [
    {"account": "0xaddress1", "balance": "1000000000000000000"},
    {"account": "0xaddress2", "balance": "2500000000000000000"}
  ]
}

ERC-20 代币余额查询

查询地址的 ERC-20 代币余额。

端点参数

参数	必填	默认值	描述
chainid	否	1	链 ID（参见 chains.md）
module	是	-	设置为 account
action	是	-	设置为 tokenbalance
contractaddress	是	-	ERC-20 代币合约地址
address	是	-	要查询的钱包地址
tag	否	latest	区块标签
apikey	是	-	来自 $ETHERSCAN_API_KEY 的 API 密钥

查询示例

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokenbalance&contractaddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&address=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe&tag=latest&apikey=$ETHERSCAN_API_KEY"

响应格式

{
  "status": "1",
  "message": "OK",
  "result": "135499000000"
}

完整持仓（仅限 PRO）

tokenbalance 一次只返回一个 ERC-20 合约的余额。要列出某个地址持有的所有代币，请使用 PRO 端点：

操作	返回内容
addresstokenbalance	所有 ERC-20 持仓（代币、数量、小数位数、USD 价格）
addresstokennftbalance	所有 ERC-721 收藏品持仓及数量

这两种操作都要求使用 Standard 计划或更高级别，并且无论所属层级如何，调用频率均限制为每秒 2 次。免费层级的替代方案是针对每个已知代币合约分别调用一次 tokenbalance。

交易历史查询

查询某个地址的交易历史。module=account 下提供五种操作：

操作	返回内容
txlist	普通（外部）交易
txlistinternal	内部交易（由合约发起）
tokentx	ERC-20 代币转账事件
tokennfttx	ERC-721（NFT）代币转账事件
token1155tx	ERC-1155 代币转账事件

端点参数

参数	必需	默认值	说明
chainid	否	1	链 ID（参见 chains.md）
module	是	-	设为 account
action	是	-	上述操作之一
address	是	-	钱包地址
contractaddress	否	-	代币合约筛选条件（tokentx/tokennfttx/token1155tx）
startblock	否	0	起始区块编号
endblock	否	999999999	结束区块编号
page	否	1	分页页码
offset	否	100	每页结果数（参见下方免费层级限制说明）
sort	否	asc	按区块编号升序或降序（asc 或 desc）
apikey	是	-	来自 $ETHERSCAN_API_KEY 的 API 密钥

自 2026 年 7 月 1 日起生效的免费层级限制变更： 对免费层级账户，txlist、txlistinternal、tokentx、tokennfttx、token1155tx 以及其他几个列表端点的 offset 最大值将从 10000 降至 1000。请按每批 1,000 条或更少的结果进行分页，以确保兼容未来版本。付费层级仍保留 10,000 的上限。

查询示例

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=txlist&address=0x8877bcb2223682048baDD5b09b7eE5a8FA2F3424&startblock=0&endblock=999999999&page=1&offset=100&sort=desc&apikey=$ETHERSCAN_API_KEY"

响应格式

result 是一个交易对象数组。每个对象都包含 Unix 格式的 timeStamp（秒，以字符串形式表示）以及特定于链的字段（hash、from、to、value、gasUsed 等）。

{
  "status": "1",
  "message": "OK",
  "result": [
    {
      "blockNumber": "18000000",
      "timeStamp": "1693526400",
      "hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "gasUsed": "21000"
    }
  ]
}

时间戳转换

timeStamp 是以秒为单位的 Unix 纪元时间。请始终生成包含时区信息的 UTC 日期时间。

from datetime import datetime, timezone

dt = datetime.fromtimestamp(int(tx["timeStamp"]), tz=timezone.utc)

不要使用 datetime.utcfromtimestamp()——它会返回不包含时区信息的日期时间，并且在 Python 3.12+ 中已弃用。

# Shell equivalent (GNU date)
date -u -d "@1693526400" --iso-8601=seconds
# macOS / BSD date
date -u -r 1693526400 +"%Y-%m-%dT%H:%M:%SZ"

多链用法

指定 chainid 参数以查询不同的区块链。

常见链 ID（免费层级）

链	链 ID
Ethereum	1
Polygon	137
Arbitrum One	42161
Linea	59144
Blast	81457
Unichain	130
Mantle	5000

示例：Polygon 查询

curl -s "https://api.etherscan.io/v2/api?chainid=137&module=account&action=balance&address=0x...&tag=latest&apikey=$ETHERSCAN_API_KEY"

如需查看支持的链的完整列表，请参阅 ./references/chains.md。

Wei 转换为便于阅读的格式

API 响应会以最小单位返回余额（ETH 使用 wei，代币使用最小单位）。

ETH 转换

除以 10^18：

# Using bc for precision
echo "scale=18; 172774397764084972158218 / 1000000000000000000" | bc
# Result: 172774.397764084972158218

ERC-20 转换

除以 10^decimals（通常为 18，但因代币而异）：

代币	小数位数
大多数代币	18
USDC、USDT	6
WBTC	8

# USDC example (6 decimals)
echo "scale=6; 135499000000 / 1000000" | bc
# Result: 135499.000000

输出格式

默认行为： 以 Markdown 表格呈现结果：

| Address | Balance (ETH) | Chain |
|---------|---------------|-------|
| 0xde0B...7BAe | 172,774.40 | Ethereum |
| 0xabc1...2def | 50.25 | Polygon |

用户偏好： 如果用户要求特定格式（JSON、CSV、纯文本等），请改用该格式。用户指定其他输出格式时，不要生成 Markdown 表格。

免费套餐限制

以下链需要付费的 Etherscan 套餐，免费套餐不支持：

• Base（8453）
• OP Mainnet（10）
• Avalanche C-Chain（43114）
• BNB Smart Chain（56）

如果用户请求查询这些链，请告知他们需要付费套餐。

错误处理

常见错误响应

状态	消息	原因
0	NOTOK	API 密钥无效或请求频率受限
0	Invalid address format	地址格式错误
0	No transactions found	地址没有活动记录

速率限制（免费套餐）

• 每秒 3 次调用
• 每天 100,000 次调用

Lite 套餐将限制提高到每秒 5 次调用；更高等级的套餐限制更高。完整限制表请参阅 https://docs.etherscan.io/resources/rate-limits。

如果受到速率限制，请稍等片刻后重试。

参考文件

• ./references/chains.md - 支持的链及其 chain ID 完整列表

备用文档

对于此技能未涵盖的用例（交易历史、合约验证、Gas 估算等），请获取 AI 友好的文档：

https://docs.etherscan.io/llms.txt

使用 WebFetch 获取此文档，以了解扩展的 API 功能。