Etherscan API迁移指南

随着 Etherscan API V2 的全面上线，对接旧版本的项目都面临一次集中升级。对接 币安 生态、跨链桥以及链上风控的团队来说，这次迁移既是清理技术债的好机会，也是回归测试覆盖能力的一次大考。本文按真实工程经验给出一份可落地的迁移指南。

一、迁移前的盘点

开始动手前，先做以下几项准备：

• 列出所有调用 Etherscan/BscScan/Polygonscan 的代码位置。
• 标注每个调用使用的接口、参数、字段。
• 评估 key 的使用方式与配额情况。
• 准备灰度环境，避免一次性切换造成线上事故。

类似 B安 服务上线流程，先在测试链试点，再扩展到主网。

二、路径与参数变化

V2 把所有链统一到 api.etherscan.io/v2/api，必须显式传入 chainid。对于 BSC 是 56，对于 Polygon 是 137。注意：链 ID 错误会返回 400 而不是数据为空，避免误判。

三、字段差异

• 旧版的 confirmations 字段在 V2 中保留但语义略有变化，需要重新校验。
• 内部交易的 traceId 改为 traceAddress，格式是层级数组。
• 合约调用接口增加了 accessList 字段以支持 EIP-2930。
• 代币转账接口将 value 改为字符串避免精度问题。

必安 类账户体系若依赖这些字段做对账，需要同步修改 ORM 模型。

四、签名与认证迁移

V2 不再支持把 API key 拼接到 URL path，必须放在 query 或 header。第三方 SDK 务必升级到对应新版本。如果使用代理转发，确认代理服务也透传 header。

五、回归测试方案

推荐使用以下三层测试：

1. 单元测试：针对每个 V2 接口的 schema 校验。
2. 集成测试：用历史区块数据回放，对比 V1/V2 字段一致性。
3. 端到端测试：模拟 BN 量化场景的全链路调用。

六、回滚预案

虽然 V2 已稳定上线，仍建议保留 V1 兼容层至少 4 周。具体做法是把客户端封装成 strategy 模式，能通过配置项即时切换。一旦发现 V2 接口异常，可以一键回滚保护业务。

七、写在最后

迁移本身不是目的，目的是让基础设施更稳、更便宜、更可扩展。把流程做扎实，等 比安 生态再迎来新一轮链上活动时，团队能够从容应对增长压力。