Etherscan API V2

概述

使用此技能通过统一的 V2 API 从兼容 Etherscan 的区块浏览器获取链上数据。

核心设计：

• 统一基础地址：https://api.etherscan.io/v2/api
• 一个 API 密钥
• 通过 chainid 切换网络

本工作区相关的区块浏览器地址：

• Ethereum 主网：https://etherscan.io/
• Ethereum hoodi：https://hoodi.etherscan.io/
• Taiko 主网：https://taikoscan.io/
• Taiko hoodi：https://hoodi.taikoscan.io/

阅读前必读：

• references/network-map.md
• references/endpoint-cheatsheet.md
• references/rate-limits.md
• references/explorer-url-patterns.md

必需输入

查询前请收集以下信息：

• ETHERSCAN_API_KEY
• 目标 chainid
• 地址 / 交易哈希 / 区块范围
• 接口用途（活动、日志、源码、ABI、状态）

确定性工作流程

1. 从 references/network-map.md 中选择 chainid。
2. 根据用途从 references/endpoint-cheatsheet.md 中选择对应接口。
3. 在 https://api.etherscan.io/v2/api 上构建请求，附带必要参数。
4. 解析 status、message、result。
5. 若合约接口返回代理元数据（Proxy == "1"），则遵循 Implementation 字段。
6. 对于大量历史数据，使用分页（page、offset）或缩小区块范围。

方法选择

快速命令

设置一次密钥：

export ETHERSCAN_API_KEY="<your_key>"

获取 ABI（Taiko 主网示例）：

curl -s "https://api.etherscan.io/v2/api?chainid=167000&module=contract&action=getabi&address=<contract>&apikey=$ETHERSCAN_API_KEY"

获取源码及代理元数据（Taiko hoodi 示例）：

curl -s "https://api.etherscan.io/v2/api?chainid=167013&module=contract&action=getsourcecode&address=<contract>&apikey=$ETHERSCAN_API_KEY"

获取指定区块窗口内的地址活动记录：

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

获取指定区块窗口内合约的日志：

curl -s "https://api.etherscan.io/v2/api?chainid=560048&module=logs&action=getLogs&address=<contract>&fromBlock=<from>&toBlock=<to>&page=1&offset=1000&apikey=$ETHERSCAN_API_KEY"

代理感知的合约处理

当 getsourcecode 返回：

• Proxy: "1"
• Implementation 字段非空

则执行以下步骤：

1. 保持运行时调用目标为代理地址。
2. 从实现地址获取 ABI 或源码。
3. 使用实现地址的 ABI 解码函数选择器。
4. 在进行特权写入分析前，重新验证实现地址。

安全约束

请始终遵守以下检查：

• 始终设置正确的 chainid；错误的链会静默返回错误上下文。
• 遵守套餐限制，并添加客户端侧的节流或重试机制。
• 即使 HTTP 状态码为 200，也应将 status: "0" 视为失败。
• 在分析时间窗口时，显式锁定 startblock/endblock。
• 查询日志时，注意 offset 最大值为 1000，需分页处理。
• 重试操作应具备幂等性，并从存储的游标或区块检查点处恢复扫描。

预期输出

返回以下内容：

• 使用的精确 URL/查询（不暴露密钥）
• 网络信息（chainid + 区块浏览器）
• 接口信息（module/action）
• 解析后的状态与结果摘要
• 合约相关时的代理跟进决策（Proxy、Implementation）