shield_lock
JinDaGe
← Back to skills
extension
Category: OtherAPI key required

etherscan

当用户需要查询或分析以太坊链上数据时触发，包括：查询地址 ETH 余额、普通/内部交易记录、ERC-20/ERC-721/ERC-1155 Token 转账、智能合约 ABI 和源码、Gas 价格、区块奖励、事件日志、ETH 价格和供应量等。使用 etherscan-cli 命令行工具调用 Etherscan 免...

personAuthor: pflonghubclawhub
open_in_newRepositorydownloadDownload package

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

基本用法流程

  1. 确认 API Key：检查是否已设置 ETHERSCAN_API_KEY 环境变量，未设置则提醒用户去 https://etherscan.io/myapikey 免费申请
  2. 确定查询目标：从用户请求中提取地址（address）、交易哈希（txhash）、合约地址（contractaddress）或区块号（blockno）等关键参数
  3. 选择合适的子命令：根据查询意图匹配最合适的命令
  4. 执行命令：使用 --format json 获取结构化数据以便后续分析
  5. 分析结果：解读返回数据，为用户提供有价值的洞察

交易分析典型流程

# 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

  1. 免费版限速 5 次/秒：批量查询时注意控制频率，CLI 已内置限速器但连续大量调用仍可能触发 Etherscan 的速率限制
  2. 最多返回 10,000 条：交易列表类接口单次最多返回 10,000 条记录，超出需通过 --startblock / --endblock 分段查询
  3. 合约未验证：contract abi 和 contract source 仅对已在 Etherscan 上验证过的合约有效
  4. 金额单位：Etherscan API 返回 Wei 单位（1 ETH = 10^18 Wei），CLI 已自动转换但 --format json 输出的原始值仍为 Wei
  5. 网络选择：默认为 mainnet，测试网查询需显式指定 --network sepolia
  6. 日志查询的 topic0：是事件签名的 Keccak-256 哈希，如 Transfer 事件为 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
  7. 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