简介

ViaBTC 矿池 API 返回的身份验证失败，本身并不能证明某个 API 密钥已被吊销或遭到泄露。ViaBTC 的 API 文档将一次已认证请求失败的几种不同原因进行了区分——无效的 API 密钥、签名错误、无效的时间戳参数，以及未列入账户白名单的 IP 地址。这些情况都有各自对应的错误代码。无效的 API 密钥与签名错误需要进行不同的排查，但不正确或不匹配的密钥（secret key）也可能导致签名失败。在尚未确认具体属于哪种情况之前就重置或删除凭证，可能会中断一个原本正常运行的集成，却并未解决其背后真正的配置问题。

请先从返回的错误代码入手：针对 12001 检查 API 密钥，针对 12002 检查签名与密钥（secret key）的配对关系，针对 12003 检查时间戳，针对 12004 检查 IP 白名单。如果怀疑凭证已经泄露，应立即轮换或删除受影响的凭证，而不要等到完成常规排查之后再处理。

本文将说明这些身份验证要求，提供一套实用的排查顺序，并说明在何种情况下才适合更换密钥对。

API 凭证不是挖矿工作者（Worker）凭证

在排查身份验证错误之前，有必要先区分两类彼此无关、但在支持请求中常被混淆的凭证类型。

ViaBTC 的 API 密钥及其配对的密钥（secret key）由外部应用程序——例如监控脚本、看板或记账工具——使用，用于向矿池 API 请求账户级别的数据，例如余额或算力统计信息。这些凭证应当填写在相应应用程序的配置中，而不是填写到挖矿硬件里。

与之不同，ASIC 矿机与挖矿软件是通过 Stratum URL 和 Worker 名称连接到矿池的，遵循标准的挖矿协议流程，即矿工向矿池提交工作量证明（proof-of-work）份额（share）。这一连接过程完全不使用 API 密钥或密钥（secret key）。如果某台矿机停止提交份额，或某个看板显示的算力数据已经过期，首先需要厘清的问题是：到底是这两套系统中的哪一套出现了故障，因为二者的排查步骤互不相干。

ViaBTC 如何验证一次 API 请求

根据 ViaBTC 公布的 API 身份验证要求，一次请求可能因以下四种不同原因之一被拒绝，并且并非每个接口都会以相同方式检查全部四项。

账户必须配置 IP 白名单，且请求的来源地址必须出现在该白名单中；无论该接口是否需要签名，此项检查均适用。X-API-KEY 请求头中必须包含属于被查询账户或子账户的值。对于文档中标明需要签名的接口，请求必须包含 X-SIGNATURE 请求头，该值使用与该 API 密钥配对的密钥（secret key），通过 HMAC-SHA256 计算得出——对于 GET 和 DELETE 请求，基于查询字符串计算；对于 POST 和 PUT 请求，基于 JSON 请求体计算。已签名的请求必须包含 tonce 参数，其定义为以毫秒为单位的当前时间戳，并须在生成签名之前立即生成该参数。

每个账户和每个子账户都拥有各自独立的 API 密钥与密钥（secret key）。ViaBTC 的文档同时指出，子账户仅在其自身未配置白名单的情况下，才会使用主账户的 IP 白名单——文档并未说明这种继承关系是无条件适用的，因此在管理多个子账户的运营场景中，应确认对于出现错误的那个具体子账户，实际生效的是哪一份白名单。

在采取行动之前，先读懂错误代码

ViaBTC 的 API 响应以 JSON 格式返回，其中包含一个表示成功或失败的 code 字段，以及一个描述结果的 message 字段。值为 0 表示成功；其他任何值都对应于一种已记录的错误。ViaBTC API 错误代码参考文档列出了四个与身份验证相关的代码：

应利用错误代码来确定下一步应检查的内容，而不是用它来排除其他一切可能的问题。对于 12001，应核实实际发送的 API 密钥，并确认该集成使用的是目标账户的凭证。对于 12002，应同时检查配对的密钥（secret key）以及签名的构造方式。对于时间戳或白名单错误，通常没有必要更换凭证，因为更换凭证并不能修正这些设置。

重置凭证之前的排查清单

以下是一套建议的排查顺序。它并不代表服务器端存在某种已记录的验证顺序；应依据返回的错误代码来确定应优先检查哪些内容。

1. 记录返回的确切 code 和 message。 请保存 JSON 响应正文（在分享之前务必先将密钥（secret key）进行脱敏处理），而不要仅仅依赖应用层给出的笼统的"身份验证失败"提示，因为这类提示可能概括了多种不同的可能原因。

2. 确认该接口是否需要签名。 ViaBTC 的 API 参考文档会标明每个接口是否需要签名。例如，account-hashrate 接口被记录为一个 GET 请求，仅需要 coin 参数和 X-API-KEY，不需要签名。如果此请求成功，而使用相同 API 密钥和出站 IP 的签名请求却返回 12002 或 12003，应优先排查密钥对配对、签名构造和时间戳生成问题。该成功请求只能证明该请求本身的鉴权条件是满足的。对于其他失败代码，应按照返回的错误信息排查，而不要想当然地认定是签名或时间戳问题。

3. 将请求的来源 IP 与白名单进行比对。 服务器迁移、更换云区域或新增 NAT 网关后仍能正常运行的脚本，如果其出站 IP 地址发生了变化而白名单未同步更新，仍可能返回 12004。这是一个常见但容易被忽视的原因，因为此类基础设施变更并不会影响 API 密钥和密钥本身。

4. 核实 API 密钥和密钥是否属于同一个账户或子账户。 由于每个账户和子账户都有各自独立的密钥对，一个监控多个子账户的集成系统可能会将某个账户的 API 密钥与另一个账户的密钥配对使用，尤其是在此前进行过密钥重置之后。即使两个值本身都是有效凭证，这种情况仍会产生签名错误。

5. 根据实际传输的数据重新构建签名。 HMAC-SHA256 签名必须根据实际在网络上发送的查询字符串或 JSON 请求体来计算。如果请求中间件、序列化库或代理在签名生成后对参数重新排序、更改编码或添加字段，服务器计算出的签名将与客户端不同，从而返回 12002。此时应核查的是请求构造流程，而不是想当然地认定密钥有误。

6. 检查系统时钟同步情况和时间戳单位。 tonce 必须是以毫秒表示的当前时间戳。十位数的秒级时间戳、在请求实际发送之前很久就生成的时间戳，或者出现漂移的系统时钟，都可能导致 12003。这些问题都无法通过更换密钥对来解决。

如果没有怀疑凭证泄露的情况，应先完成与所报错误相关的排查工作，再考虑更换凭证。如果在核实提交的密钥无误后 12001 仍然持续出现，或者无法找回用于签名请求的正确密钥，那么更换凭证可能是合适的做法。如果怀疑凭证已经泄露，则应及时轮换或删除，而无需等待完成此排查清单。

何时更换密钥对才是恰当的应对措施

ViaBTC 的 API 设置指南记录了重置 API 密钥对或将其删除的选项；删除操作需要进行邮箱验证和 Google Authenticator 验证码确认。在以下几种特定情况下，重置或删除凭证是合理的应对方式：

• 在确认请求为对应账户或子账户发送了正确的密钥之后，错误仍持续以 12001 返回。
• 密钥丢失或从未被记录下来，导致无法恢复用于签名的集成。
• 某个集成或第三方应用已经下线，不再需要访问权限。
• 有任何理由怀疑密钥或密钥本身已经泄露——例如被粘贴到公开代码仓库、截图、聊天记录或工单中。

尤其是在泄露这种情况下，应及时进行轮换或删除，而无需进行长时间的排查，因为继续使用所带来的风险要大于查明原始错误原因的价值。ViaBTC 建议对 API 密钥和密钥均严格保密，这一原则适用于整个排查过程——在任何支持请求、论坛帖子或日志文件中都不应泄露这两个值。每个账户白名单最多可配置 20 个 IP 地址，每行一个，这通常足以覆盖少量应用服务器，而无需通过放宽白名单来作为权宜之计。

常见问题

我的 ASIC 配置中需要填写 API 密钥吗？

不需要。API 密钥和密钥用于验证外部应用程序向 ViaBTC 矿池 API 发出的请求。ASIC 矿机和挖矿软件是通过 Stratum URL 和矿工名称连接矿池的，这是一套独立的凭证体系。

我的 API 密钥是正确的，为什么请求仍返回“IP not allowed”错误？

ViaBTC 的 API 会独立于 API 密钥本身是否有效，将请求的来源 IP 地址与账户配置的白名单进行比对。即使密钥正确，只要发送请求的地址不在白名单中，仍会返回错误 12004。

为什么使用同一个密钥时，某个接口返回签名错误，而另一个接口却能正常工作？

并非所有 ViaBTC 接口都需要签名。一个无需签名的接口，只要满足其他条件，即可在不提供 X-SIGNATURE 的情况下成功调用。如果使用相同 API 密钥和出站 IP 的某个需要签名的接口返回 12002，请检查该密钥是否与对应的 API 密钥正确配对，以及签名是否是根据实际传输的请求数据计算得出的。

收到无效 tonce 错误后，我应该重置我的 API 密钥吗？

不应作为第一步操作。错误 12003 指向的是时间戳参数，而非密钥本身。在考虑更改任何凭证之前，应先检查系统时钟是否同步，以及 tonce 是否以毫秒而非秒为单位发送为当前时间戳。

参考资料

• ViaBTC Pool API，《API 认证》，GitHub wiki。
• ViaBTC Pool API，《错误代码》，GitHub wiki。
• ViaBTC Pool API，《获取账户算力》，GitHub wiki。
• ViaBTC 帮助中心，《什么是 API 以及如何设置》。