etherscan — 以太坊浏览器（Etherscan）

Etherscan 区块链分析工具 基于 Etherscan 免费 API 的命令行工具，用于查询和分析以太坊链上数据。涵盖账户余额、交易记录、合约信息、Token 转账、Gas 价格、区块奖励、事件日志等全维度链上数据查询。

何时使用 当用户需要查询或分析以太坊链上数据时使用此技能，包括但不限于： 查询某个地址的 ETH 余额或交易历史 追踪特定交易的状态、内部调用和 Token 转账 获取智能合约的 ABI 或源码 分析 ERC-20 / ERC-721 / ERC-1155 Token 转账 查询实时 Gas 价格 查询区块奖励或按时间定位区块号 监听合约事件日志 分析可疑交易或资金流向 查看 ETH 价格和总供应量

快速参考 所有命令的基本格式：etherscan [全局选项] <模块> <操作> [参数] [选项] 全局选项 选项 说明 默认值 --apikey API Key（也可设置 ETHERSCAN_API_KEY 环境变量） - --network 网络：mainnet / sepolia / goerli / holesky mainnet --format 输出格式：table / json table

Account 模块 — 账户查询 命令 说明 etherscan account balance --address

查询 ETH 余额 etherscan account balances --addresses 批量查询余额（最多 20 个） etherscan account txlist --address 普通交易列表 etherscan account txlist-internal --address 内部交易列表 etherscan account tokentx --address ERC-20 转账记录 etherscan account tokennfttx --address ERC-721 NFT 转账记录 etherscan account token1155tx --address ERC-1155 转账记录 etherscan account minedblocks --address 挖出的区块列表

交易列表类命令支持的通用选项： --startblock — 起始区块（默认 0） --endblock — 结束区块（默认 99999999） --page — 页码（默认 1） --offset — 每页条数（默认 20） --sort — 排序 asc/desc（默认 desc）

Token 转账类命令还支持： --contractaddress — 指定 Token 合约地址过滤

Transaction 模块 — 交易状态 命令 说明 etherscan tx status --txhash 检查合约执行状态（是否出错） etherscan tx receipt --txhash 检查交易收据状态（成功/失败）

Contract 模块 — 智能合约 命令 说明 etherscan contract abi --address

获取已验证合约的 ABI（JSON） etherscan contract source --address 获取已验证合约的源代码

Block 模块 — 区块 命令 说明 etherscan block reward --blockno 查询区块奖励详情 etherscan block countdown --blockno 查询目标区块的预计倒计时 etherscan block bytime --timestamp 按 Unix 时间戳查询最近的区块号 bytime 支持 --closest before/after 选项。

Token 模块 — Token 信息 命令 说明 etherscan token supply --contractaddress ERC-20 Token 总供应量 etherscan token balance --address

--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

查询合约事件日志 支持的选项： --from-block — 起始区块（默认 0） --to-block — 结束区块（默认 latest） --topic0 — 事件签名哈希 --topic1/2/3 — Topic 过滤 --page / --offset — 分页

流程 基本用法流程 确认 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

常见陷阱 免费版限速 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 分析等）不包含在内

验证 执行 etherscan stats ethprice 应返回当前 ETH/USD 和 ETH/BTC 价格 执行 etherscan gas oracle 应返回 SafeGasPrice、ProposeGasPrice、FastGasPrice 执行 etherscan account balance --address 0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae 应返回以太坊基金会地址的余额 所有命令添加 --format json 应输出合法 JSON