ClawHub

etherscan

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

Audits

Pass
ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install rockylong526-etherscan

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 / holeskymainnet
--format <type>输出格式：table / jsontable

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 ethsupplyETH 总供应量
etherscan stats ethpriceETH 当前价格（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