Etherscan 区块链分析工具
基于 Etherscan 免费 API 的命令行工具，用于查询和分析以太坊链上数据。涵盖账户余额、交易记录、合约信息、Token 转账、Gas 价格、区块奖励、事件日志等全维度链上数据查询。
When to Use
当用户需要查询或分析以太坊链上数据时使用此技能，包括但不限于：
- 查询某个地址的 ETH 余额或交易历史
- 追踪特定交易的状态、内部调用和 Token 转账
- 获取智能合约的 ABI 或源码
- 分析 ERC-20 / ERC-721 / ERC-1155 Token 转账
- 查询实时 Gas 价格
- 查询区块奖励或按时间定位区块号
- 监听合约事件日志
- 分析可疑交易或资金流向
- 查看 ETH 价格和总供应量
Quick Reference
所有命令的基本格式：etherscan [全局选项] <模块> <操作> [参数] [选项]
全局选项
| 选项 | 说明 | 默认值 |
|---|
--apikey <key> | API Key（也可设置 ETHERSCAN_API_KEY 环境变量） | - |
--network <name> | 网络：mainnet / sepolia / goerli / holesky | mainnet |
--format <type> | 输出格式：table / json | table |
Account 模块 — 账户查询
| 命令 | 说明 |
|---|
etherscan account balance --address <address> | 查询 ETH 余额 |
etherscan account balances --addresses <addr1,addr2,...> | 批量查询余额（最多 20 个） |
etherscan account txlist --address <address> | 普通交易列表 |
etherscan account txlist-internal --address <address> | 内部交易列表 |
etherscan account tokentx --address <address> | ERC-20 转账记录 |
etherscan account tokennfttx --address <address> | ERC-721 NFT 转账记录 |
etherscan account token1155tx --address <address> | ERC-1155 转账记录 |
etherscan account minedblocks --address <address> | 挖出的区块列表 |
交易列表类命令支持的通用选项：
--startblock <n> — 起始区块（默认 0）--endblock <n> — 结束区块（默认 99999999）--page <n> — 页码（默认 1）--offset <n> — 每页条数（默认 20）--sort <order> — 排序 asc/desc（默认 desc）
Token 转账类命令还支持：
--contractaddress <addr> — 指定 Token 合约地址过滤
Transaction 模块 — 交易状态
| 命令 | 说明 |
|---|
etherscan tx status --txhash <txhash> | 检查合约执行状态（是否出错） |
etherscan tx receipt --txhash <txhash> | 检查交易收据状态（成功/失败） |
Contract 模块 — 智能合约
| 命令 | 说明 |
|---|
etherscan contract abi --address <address> | 获取已验证合约的 ABI（JSON） |
etherscan contract source --address <address> | 获取已验证合约的源代码 |
Block 模块 — 区块
| 命令 | 说明 |
|---|
etherscan block reward --blockno <blockno> | 查询区块奖励详情 |
etherscan block countdown --blockno <blockno> | 查询目标区块的预计倒计时 |
etherscan block bytime --timestamp <timestamp> | 按 Unix 时间戳查询最近的区块号 |
bytime 支持 --closest before/after 选项。
Token 模块 — Token 信息
| 命令 | 说明 |
|---|
etherscan token supply --contractaddress <contractaddress> | ERC-20 Token 总供应量 |
etherscan token balance --address <address> --contractaddress <contractaddress> | 地址的 Token 余额 |
Gas 模块 — Gas 价格
| 命令 | 说明 |
|---|
etherscan gas oracle | 当前 Gas 价格（SafeGas / ProposeGas / FastGas / baseFee） |
Stats 模块 — 网络统计
| 命令 | 说明 |
|---|
etherscan stats ethsupply | ETH 总供应量 |
etherscan stats ethprice | ETH 当前价格（USD / BTC） |
Logs 模块 — 事件日志
| 命令 | 说明 |
|---|
etherscan logs get --address <address> | 查询合约事件日志 |
支持的选项：
--from-block <n> — 起始区块（默认 0）--to-block <n> — 结束区块（默认 latest）--topic0 <hash> — 事件签名哈希--topic1/2/3 <hash> — Topic 过滤--page <n> / --offset <n> — 分页
Procedure
基本用法流程
- 确认 API Key：检查是否已设置
ETHERSCAN_API_KEY 环境变量，未设置则提醒用户去 https://etherscan.io/myapikey 免费申请
- 确定查询目标：从用户请求中提取地址（address）、交易哈希（txhash）、合约地址（contractaddress）或区块号（blockno）等关键参数
- 选择合适的子命令：根据查询意图匹配最合适的命令
- 执行命令：使用
--format json 获取结构化数据以便后续分析
- 分析结果：解读返回数据，为用户提供有价值的洞察
交易分析典型流程
# 1. 查看地址交易历史
etherscan account txlist --address 0x... --format json --offset 50
# 2. 检查特定交易状态
etherscan tx status --txhash 0x... --format json
etherscan tx receipt --txhash 0x... --format json
# 3. 查看内部交易（合约调用链）
etherscan account txlist-internal --address 0x... --format json
# 4. 追踪 Token 转账
etherscan account tokentx --address 0x... --format json
合约分析典型流程
# 1. 获取合约 ABI
etherscan contract abi --address 0x... --format json
# 2. 获取合约源码
etherscan contract source --address 0x...
# 3. 查看合约事件日志
etherscan logs get --address 0x... --from-block 18000000 --to-block latest --format json
市场数据查询
# Gas 价格
etherscan gas oracle --format json
# ETH 价格
etherscan stats ethprice --format json
# ETH 供应量
etherscan stats ethsupply --format json
Common Pitfalls
- 免费版限速 5 次/秒：批量查询时注意控制频率，CLI 已内置限速器但连续大量调用仍可能触发 Etherscan 的速率限制
- 最多返回 10,000 条：交易列表类接口单次最多返回 10,000 条记录，超出需通过
--startblock / --endblock 分段查询
- 合约未验证：
contract abi 和 contract source 仅对已在 Etherscan 上验证过的合约有效
- 金额单位：Etherscan API 返回 Wei 单位（1 ETH = 10^18 Wei），CLI 已自动转换但
--format json 输出的原始值仍为 Wei
- 网络选择：默认为 mainnet，测试网查询需显式指定
--network sepolia
- 日志查询的 topic0：是事件签名的 Keccak-256 哈希，如 Transfer 事件为
0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
- Pro 接口不可用：本 CLI 仅封装免费 API，Pro 接口（如历史余额、高级 Token 分析等）不包含在内
Verification
- 执行
etherscan stats ethprice 应返回当前 ETH/USD 和 ETH/BTC 价格
- 执行
etherscan gas oracle 应返回 SafeGasPrice、ProposeGasPrice、FastGasPrice
- 执行
etherscan account balance --address 0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae 应返回以太坊基金会地址的余额
- 所有命令添加
--format json 应输出合法 JSON