WEEX API 整合指南：身份驗證、限制與 403 陷阱

大多數加密貨幣交易所的 API 指南止步於「建立一個金鑰並將其指向您的機器人」。這只會帶您遇到第一個 -1052 錯誤，而不是一個可用的整合。WEEX API 是一個雙棧系統——現貨和合約運行在不同的網域上，具有不同的訂單模式——而最浪費開發者時間的故障並非概念性的。它們是缺失的 User-Agent 標頭、漂移了 31 秒的時鐘，以及一個在交易所存在但未開啟程式化存取的交易對。

本指南從頭到尾介紹了 WEEX API 的整合：API 的涵蓋範圍、如何配置不會將您鎖定的金鑰、簽章的實際建構方式、您在生產環境中會遇到的速率限制，以及導致大多數首次嘗試失敗的具體錯誤。此處的所有數據均來自截至 2026 年 8 月的 WEEX V3 文件。

WEEX API 的涵蓋範圍 — 以及尚不支援的內容

WEEX API 提供了兩個獨立的 REST 介面外加一個 WebSocket 層。它們不可互換，這是整合時必須做出的第一個結構性決定。

覆蓋範圍是真實的但有限制。WEEX OpenAPI 測試版公告列出了 140 多個支援的交易對——但分佈不均：合約表中有大約 130 個永續合約，而現貨列表只有約 25 個交易對。如果您的策略交易的是中等市值的現貨對，請在編寫程式碼前檢查該列表，因為一個交易對在網頁介面上線並不意味著它接受 API 訂單。

對於從其他平台遷移的使用者來說，有兩個缺失點很重要。WEEX 現貨 API 常見問題解答（最後更新於 2026 年 4 月 14 日）明確指出，目前不支援 FIX API 或 TradingView 整合。如果您的執行棧依賴於 FIX 會話或來自 TradingView 的 Webhook 警報，您需要針對 REST 和 WebSocket 重建該層。

同樣值得注意的是：V1 和 V2 端點正在被棄用，WEEX 建議新建構使用 V3。您在第三方機器人平台上找到的範例程式碼可能仍指向 V2 路徑。

如何建立 WEEX API 金鑰而不鎖定自己

金鑰建立在「帳戶」下的 WEEX API 管理頁面進行。操作過程只需兩分鐘。配置決策需要更長時間，其中三個是不可逆的。

1. 建立金鑰。 每個帳戶支援最多 10 個 API 金鑰組。新金鑰預設為 唯讀。
2. 明確選擇權限。 唯讀、現貨 和 合約 是獨立的。勾選現貨並不授予合約存取權限，在僅限現貨的金鑰上發送合約訂單會返回 -1052 INSUFFICIENT_PERMISSIONS，而不是更具描述性的資訊。
3. 謹慎設定密碼。 WEEX 自身的安全指南建議僅使用字母數字字元——密碼中的特殊字元是記錄在案的身份驗證失敗來源。密碼無法修改或找回。遺失後只能建立新金鑰。
4. 綁定 IP 白名單。 最多 10 個 IP，以逗號分隔。不受限制的金鑰是 API 設定中最大的託管風險，WEEX 將其標記為高風險。
5. 等待。 新建立或修改的金鑰大約需要 15 分鐘才能在 WEEX 的系統中傳播。開發者經常將此視窗期誤解為簽章錯誤並開始重寫正常工作的程式碼。

在建立時儲存 APIKey、SecretKey 和 Passphrase。之後只有 APIKey 可以找回。

從第一天起就值得養成一個習慣：永遠不要在執行交易流程的金鑰上啟用提現相關權限。將用於監控的唯讀金鑰與用於執行的交易權限金鑰分開，並為每個金鑰綁定各自的 IP。營運成本只需十分鐘；它所防止的故障模式是毀滅性的。

簽署 WEEX API 請求：30 秒視窗

每個私有 WEEX API 呼叫都包含四個標頭加上一個內容類型：

您簽署的訊息是一個拼接字串，拼接規則取決於是否存在查詢字串：

# 存在 queryString
timestamp + METHOD + requestPath + "?" + queryString + body

# 不存在 queryString
timestamp + METHOD + requestPath + body

METHOD 為大寫。body 是原始 JSON 字串，與您傳輸的內容逐位元組相同——序列化一次，簽署該字串，發送該字串。在簽章和發送之間重新序列化是導致簽章失敗的最常見原因，因為鍵的順序或空格會發生變化，導致雜湊值不再匹配。

來自 WEEX 簽章規範的範例，獲取深度：

1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20

以及一個訂單：

1561022985382POST/api/v3/order{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}

然後使用您的金鑰進行 HMAC-SHA256，再進行 Base64 編碼。

在生產環境中困擾人們的約束是時鐘。如果 ACCESS-TIMESTAMP 與 WEEX 伺服器時間偏差超過 30 秒，請求將被拒絕，並返回 -1046 ACCESS_TIMESTAMP_EXPIRED。時鐘漂移的容器、無伺服器冷啟動以及沒有 NTP 的虛擬機器都會間歇性地失敗——這比持續失敗更糟糕，因為它看起來像網路問題。在啟動時查詢伺服器時間端點，儲存偏移量，並將其應用於每個時間戳。

WebSocket 私有頻道使用更短的訊息：timestamp + "/v3/ws/private"，以相同方式簽章——相同的標頭，相同的 HMAC-SHA256 和 Base64 步驟，只是字串不同。

您實際上會遇到的 WEEX API 速率限制

超過限制會返回 HTTP 429 和 10 秒封禁。WEEX 將限制分為兩個獨立的預算，這是大多數整合建模不正確的部分。

速率限制來自 WEEX 現貨 API 文件和常見問題解答，截至 2026 年 4 月 14 日。

重要的區別在於：下單限制按帳戶計算，其他限制按 IP 計算。下單端點消耗零 IP 權重——其回應標頭中的 IP 計數器顯示為 0。因此，在同一個 IP 後運行三個策略並不會使您的訂單預算增加三倍（它是按帳戶計算的），但確實會使您對市場數據和查詢的 500 權重 IP 池的消耗量增加三倍。

讀取標頭而不是猜測。每個回應都帶有 X-USED-WEIGHT-1M 和 X-REMAINING-WEIGHT-1M；訂單端點帶有 X-ORDER-COUNT-10S 和 X-ORDER-REMAINING-10S。由剩餘權重標頭驅動的退避機制將優於您硬編碼的任何固定睡眠間隔。

現貨和合約訂單不共享模式

這是破壞共享抽象層的分歧，文件中沒有顯著標出——您可透過對比兩個訂單頁面發現這一點。

最後一行值得強調。合約端點可以返回 HTTP 200 和 {"success": false, "errorCode": "...", "errorMessage": "..."}。僅檢查 HTTP 狀態的程式碼會將拒絕的訂單註冊為已成交，並愉快地繼續建立實際上並不存在的持倉。在每個合約訂單回應中顯式檢查 success。

文件本身也存在即時不一致。現貨 API 公共參數頁面仍列出小寫列舉（buy, sell, limit, market）以及 force 欄位，而 交易 下的 V3 訂單端點使用大寫的 BUY, SELL, LIMIT 和 timeInForce。端點頁面反映了 V3；參數頁面帶有 V2 時代的值。當它們不一致時，請信任端點頁面——並將 -1116 INVALID_ORDER_TYPE 發送到您的日誌，作為您複製錯誤來源的訊號。

交易對名稱區分大小寫且必須大寫。btcusdt 會返回 -1121。

導致大多數 WEEX API 整合失敗的五個錯誤

WebSocket 403 是值得內化的一個。它與您的憑據無關——WEEX 的邊緣伺服器直接拒絕無標頭的握手，因此完美簽章的私有訂閱與未簽章的訂閱失敗方式相同。開發者在找到它之前會除錯簽章一個小時。WEEX 在現貨 API 常見問題解答中記錄了這一點，修復只需一行程式碼。

也要妥善保持連線活躍。伺服器發送定期 ping——公共頻道上的 {"event":"ping","time":"..."}，私有頻道上的 {"type":"ping","time":"..."}——並期望返回 {"method":"PONG","id":1}。錯過 10 次以上，伺服器將關閉連線。 波動會話期間的靜默斷開是機器人最終在陳舊帳本上交易的原因。

完整的錯誤分類位於 WEEX 現貨 API 常見問題解答和錯誤代碼參考。

在冒真實保證金風險前進行模擬測試

WEEX 提供了一個模擬合約環境，可透過相同的身份驗證模式在 /capi/v3/sim/ 下存取。模擬餘額端點返回以 SUSDT（模擬 USDT）計價的持倉，以及 availableBalance、frozen 和 unrealizePnl。模擬 PlaceOrder、GetAllPositions 和 GetOrderHistory 均已開放。

將其用於它真正擅長的事情：驗證您的簽章建構、錯誤處理和重連邏輯。不要用它來驗證策略經濟學。模擬場所沒有佇列位置，沒有壓力下的部分成交行為，也沒有滑點——這三件事將回測與盈虧區分開來。

關於真實環境的校準：截至 2026 年 8 月 21 日，WEEX 在其 BTC/USDT 合約市場上報價 BTC 永續合約為 65,088.80 USDT，槓桿最高可達 400 倍。該槓桿上限是自動化系統應保守的原因，而不是可以依賴的功能。觸發重複訂單的簽章錯誤在 3 倍槓桿下尚可存活。但在 400 倍槓桿下則不然。

簡短版本

一旦滿足三件事，WEEX API 就非常簡單：您的時鐘在 30 秒視窗內同步，您的 WebSocket 發送了 User-Agent，並且您的合約程式碼檢查了 success 欄位而不是 HTTP 狀態。其他一切——權限、IP 白名單、速率限制退避——都是標準的交易所整合工作。

唯一不標準且值得花時間預算的事情是現貨/合約模式的分歧。跨兩個表面的共享訂單抽象在審查時看起來正確，但在生產中會失敗。將它們建構為兩個轉接器。

準備開始了嗎？在 WEEX 的「帳戶 → API 管理」下建立一個金鑰，先指向模擬模式，只有在您的重連和錯誤路徑被證明有效後，才擴大權限。

常見問題解答

1. WEEX API 可以免費使用嗎？

是的。API 存取不收取額外費用。您支付成交訂單的標準現貨或合約交易手續費，與手動交易相同。

2. 我可以在 WEEX 上建立多少個 API 金鑰？

每個帳戶最多 10 個 API 金鑰組。每個金鑰都可以獨立配置唯讀、現貨或合約權限，並擁有最多 10 個位址的 IP 白名單。

3. 為什麼我的 WEEX API 金鑰在 Postman 中有效，但從我的伺服器卻不行？

幾乎總是 IP 白名單 (-1056) 或時鐘漂移 (-1046) 的問題。雲環境經常從不在您白名單上的輪換 NAT IP 出口，而沒有 NTP 的容器會漂移超過 30 秒的簽章視窗。

4. WEEX API 支援 FIX 或 TradingView Webhook 嗎？

不支援。截至 2026 年 4 月的文件更新，不支援 FIX API 或 TradingView 整合。REST 和 WebSocket 是可用的傳輸方式。

5. 新的 WEEX API 金鑰需要多久才能開始工作？

新金鑰或修改後的金鑰大約需要 15 分鐘才能傳播。在此視窗內的身份驗證失敗是預期的，並非簽章問題。

6. 我可以在沒有真實資金的情況下測試 WEEX API 策略嗎？

可以，針對合約。/capi/v3/sim/ 下的模擬端點接受相同的身份驗證請求並返回以 SUSDT 計價的餘額。將它們視為整合測試工具，而不是策略回測。

風險警告

加密資產具有波動性，交易它們可能導致部分或全部資本損失。API 交易軟體：先檢查交易所限制集中了這種風險而不是減少它：邏輯錯誤、未處理的拒絕或陳舊的 WebSocket 資料流可以在人類注意到之前執行數十個意外訂單。WEEX 在某些永續合約上提供最高 400 倍的槓桿，這放大了正確和錯誤的訊號——以高槓桿運行的自動化系統可能會在一次不利的波動中被清算。

API 部署中需要考慮的具體風險：來自不受限制或洩漏金鑰的託管風險，這些金鑰授予帳戶的完全交易控制權；來自WEEX API 速率限制詳解：新手易忽略的關鍵數字、速率限制封禁和斷開連線的營運風險，這些會導致持倉無人管理；在交易稀薄的交易對上的流動性風險，市價單會使帳本對您不利；以及對手方和監管風險，因為 API 交易和特定交易對的可用性可能會在不通知的情況下發生變化。綁定 IP 白名單，不要在交易金鑰上開啟提現權限，在程式碼中限制持倉規模而不是僅在意圖中，並在部署資金前在模擬模式下測試錯誤路徑。此處內容不構成投資建議。