簡介

ViaBTC Pool API 的身份驗證失敗，本身並不代表 API 密鑰已遭撤銷或洩露。ViaBTC 的 API 文件將驗證請求失敗的幾種不同原因區分開來——無效的 API 密鑰、簽名錯誤、無效的時間戳參數，以及不在帳戶白名單中的 IP 位址。這些情況各自對應有文件記載的錯誤代碼。無效 API 密鑰與簽名錯誤需要不同的檢查方式，但不正確或不匹配的密鑰（secret key）同樣也可能導致簽名失敗。在確定具體屬於哪種情況之前就重設或刪除憑證，可能會中斷原本正常運作的整合，卻無法解決根本的配置問題。

請先從返回的錯誤代碼入手：若為 12001，檢查 API 密鑰；若為 12002，檢查簽名與密鑰的配對；若為 12003，檢查時間戳；若為 12004，檢查 IP 白名單。若你懷疑憑證已經外洩，應立即輪換或刪除受影響的憑證，而不是等到完成常規故障排查後才處理。

本文將說明這些身份驗證要求，提出一套實用的故障排查流程，並說明在何種情況下更換密鑰對才是合適的做法。

API 憑證並非挖礦礦工憑證

在排查身份驗證錯誤之前，有必要先區分兩種在支援請求中經常被混淆、但彼此無關的憑證類型。

ViaBTC 的 API 密鑰及其配對的密鑰（secret key）是供外部應用程式使用的——例如監控腳本、儀表板或記帳工具——用以向礦池 API 請求帳戶層級的數據，例如餘額或算力統計資料。這些憑證應輸入到該應用程式的配置中，而非輸入到挖礦硬件中。

ASIC 礦機和挖礦軟件則是透過 Stratum URL 和礦工名稱連接到礦池，遵循標準挖礦協議流程，即由礦機向礦池提交工作量證明（proof-of-work）份額。此連接完全不使用 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 會獨立檢查請求來源 IP 位址是否在帳戶設定的白名單內，而不論 API 金鑰本身是否有效。即使金鑰正確，若從不在白名單內的位址發送請求，仍會回傳錯誤 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 以及如何設定」。