WEEX API 指南：從 API Key 到首筆簽名訂單

WEEX API 涵蓋範圍：現貨、合約與 WebSocket

大多數 WEEX API 集成失敗並非因為策略邏輯，而是在最初的一小時內，因四個不明顯的細節導致：剛創建的 Key 尚未生效；想要交易的交易對不在 API 白名單內；因未發送 User-Agent 請求頭導致 WebSocket 連接被拒；或者因為對重序列化後的正文進行簽名，導致簽名與發送的原始字串不符，出現位元組偏差。

本指南將帶您完整了解 WEEX API：Key 創建、權限設置、簽名規則、速率限制、導致構建停滯的錯誤代碼，以及無需投入資金即可進行全方位測試的模擬交易端點。以下所有內容均已根據 2026 年 8 月 21 日的 V3 在線文檔進行了核對。

WEEX API 分為兩個獨立產品，擁有兩個獨立的 REST 域名。現貨（Spot）位於 api-spot.weex.com，路徑為 /api/v3。合約（Futures）位於 api-contract.weex.com，路徑為 /capi/v3。它們共享簽名方案和請求頭設置，但除此之外完全獨立——包括權限標誌、WebSocket 主機和訂單參數。

端點分為兩類訪問權限。公共端點（伺服器時間、訂單簿深度、K 線、資金費率、24 小時行情）無需任何身份驗證，這是在進行簽名操作前確認網路路徑是否通暢的最快方式。私有端點（餘額、持倉、訂單）則要求每個請求都包含完整的四項簽名請求頭。

對於任何 Tick 級別的數據，WEEX 建議使用 WebSocket 而非 REST 輪詢，這是明智之舉：公共頻道提供行情、深度和成交流，私有頻道則提供帳戶、持倉和訂單更新。透過 REST 輪詢深度來構建訂單簿只會無謂地消耗您的 IP 權重額度。

一個過往的參考點：截至 2026 年 8 月 21 日，BTC/USDT 永續合約在 WEEX 合約盤口上的最新成交價為 65,088.8 USDT，這與您調用 /capi/v3/market/ticker24h 返回的 Tick 數據一致。

如何創建 WEEX API Key 並設置權限

Key 可在網頁平台的「帳戶」→「API 管理」中創建。每個帳戶最多可持有 10 個 API Key 組。

創建時會返回三個值，第三個值最容易被遺忘：

• APIKey — 公共識別符，需在 ACCESS-KEY 請求頭中發送。
• SecretKey — HMAC 簽名密鑰。僅顯示一次。
• Passphrase — 用戶自定義，需在 ACCESS-PASSPHRASE 中發送。它無法更改也無法找回。一旦丟失，只能重新創建 Key。

以下三個配置細節導致的工單數量超過了其他所有問題的總和：

1. 新 Key 默認為唯讀。交易權限是單獨的複選框，且針對產品——Spot 用於現貨交易，Futures 用於合約交易。勾選一個並不會自動啟用另一個。使用唯讀 Key 下單會返回 -1052。
2. Key 全球生效約需 15 分鐘。如果一個 Key 驗證通過但在不同端點上失敗，通常是因為尚未完全生效。在調試簽名之前請稍作等待。
3. 保持 Passphrase 為字母數字組合。WEEX 明確建議不要使用特殊字元。特殊字元的編碼不匹配是一類極其難以排查的 Bug。

在創建頁面時請綁定 IP 白名單。未綁定的 Key 是可以在網際網路任何地方使用的憑證，如果持有該 Key 的機器被入侵，白名單是保護您持倉的最後一道防線。

WEEX 現貨 API 與合約 API：關鍵區別

這是您在開發時需要常備的對照表。這兩個產品看起來對稱，實則不然。

其中兩點最容易踩坑。合約要求每個訂單必須包含 newClientOrderId，因此如果從現貨遷移過來的代碼省略了該參數，在對接合約時會被拒絕。此外，POST_ONLY 僅存在於合約中——針對現貨 API 編寫的做市策略無法原生保證不跨越買賣價差。

合約的止盈止損參數值得額外關注。將 tpTriggerPrice 和 slTriggerPrice 附加到開倉訂單上，意味著您的止損從持倉建立的那一刻起就存在於交易所，而不是透過後續調用來設置，從而避免了因進程崩潰或網路分區導致止損設置失敗。您還可以透過 TpWorkingType 和 SlWorkingType 選擇觸發源——止損使用 MARK_PRICE 是更安全的選擇，因為 CONTRACT_PRICE 可能會因流動性差的交易對上的微小成交而出現異常波動。

如何正確簽署 WEEX API 請求

每個私有調用都包含四個請求頭：ACCESS-KEY、ACCESS-SIGN、ACCESS-PASSPHRASE、ACCESS-TIMESTAMP，以及 Content-Type: application/json。

簽名規則在兩個域名上完全相同。構建以下字串：

timestamp + METHOD + requestPath + "?" + queryString + body

如果沒有查詢參數，則省略 ? 和 queryString；如果沒有正文，則省略 body。使用您的 SecretKey 進行 HMAC-SHA256 運算，然後對結果進行 Base64 編碼。

import base64, hashlib, hmac, json, time, requests

API_KEY, SECRET, PASSPHRASE = "...", "...", "..."
BASE = "https://api-contract.weex.com"
path = "/capi/v3/order"
body = json.dumps({
    "symbol": "BTCUSDT", "side": "BUY", "positionSide": "LONG",
    "type": "LIMIT", "timeInForce": "GTC", "quantity": "0.01",
    "price": "60000", "newClientOrderId": "my-order-0001",
}, separators=(",", ":"))

ts = str(int(time.time() * 1000))
message = ts + "POST" + path + body
sign = base64.b64encode(
    hmac.new(SECRET.encode(), message.encode(), hashlib.sha256).digest()
).decode()

r = requests.post(BASE + path, data=body, headers={
    "ACCESS-KEY": API_KEY, "ACCESS-SIGN": sign,
    "ACCESS-PASSPHRASE": PASSPHRASE, "ACCESS-TIMESTAMP": ts,
    "Content-Type": "application/json",
})

注意使用 data=body，而非 json=payload。請對您傳輸的原始位元組進行簽名。如果您的 HTTP 客戶端重新序列化了字典（例如重新排序鍵或在分隔符後插入空格），伺服器計算出的摘要就會不同，從而導致 -1047 錯誤，且不會提示原因是空格問題。

時間戳視窗為 WEEX 伺服器時間的 30 秒內。如果您的主機時鐘漂移，請求會間歇性失敗，表現得像簽名 Bug。建議調用 GET /capi/v3/market/time 並追蹤偏移量，而不是信任本地時間。

WebSocket 私有頻道的簽名方式不同，這一點常被忽略：消息僅為 timestamp + requestPath，其中 requestPath 為 /v3/ws/private。無需方法，無需正文。

在複製貼上前值得了解的一個文檔怪癖：合約簽名頁面使用現貨路徑（/api/v3/order）來說明規則。規則是正確的，但示例路徑並非合約路徑。在合約域名上請務必使用 /capi/v3/...。

WEEX API 速率限制：兩個獨立的計數器

WEEX 運行兩個獨立的速率限制計數器，混淆它們是導致機器人意外收到 429 錯誤的原因。

關鍵細節：下單操作消耗零 IP 權重，而撤單和查詢消耗零訂單額度。它們是完全獨立的帳本。激進的做市循環在下單時會耗盡訂單額度，而其撤單流量會悄悄消耗 IP 權重——兩個計數器互不預警。

請讀取請求頭而不是在客戶端計數。X-REMAINING-WEIGHT-1M 和 X-ORDER-REMAINING-1M 會在每次調用時返回，反映伺服器的真實視圖。超過限制會返回 HTTP 429 並觸發 10 秒封禁，繼續無視 429 強行請求是導致 API 訪問權限被風控禁用的最快途徑。

如果您在一台機器上運行多個策略，請記住 IP 權重是共享的。同一伺服器上的兩個機器人會競爭相同的每 10 秒 500 權重。

導致大多數集成停滯的 WEEX API 錯誤

錯誤響應由代碼和消息組成。以下是在集成過程中最常出現的錯誤：

-1058 需要特別的工作流。並非所有 WEEX 合約都支持 API 交易，且無法從 UI 推斷。請在啟動時調用 GET /capi/v3/market/apiTradingSymbols，緩存數組，並在策略下單前驗證交易對。這一檢查可消除一整類運行時故障。

還有兩個看起來像 Bug 其實不是的問題。WebSocket 握手返回 403 通常意味著您遺漏了 User-Agent 請求頭——內容可以是任意的，但防火牆會丟棄沒有它的連接。此外，關於撤單失敗的文檔目前存在衝突：錯誤代碼參考將 -1054 映射為通用系統錯誤，將 -3200 映射為「訂單不存在」，而合約 FAQ 將「訂單不存在」歸為 -1054。建議在撤單路徑中同時處理這兩個代碼，而不是只處理其中一個。

首先在 WEEX 模擬交易端點測試

WEEX 在合約域名下增加了模擬交易端點，其鏡像了真實環境，足以進行真正的壓力測試而非玩具式測試：

• GET /capi/v3/sim/balance — 模擬餘額，以 SUSDT 計價
• GET /capi/v3/sim/position/allPosition — 持倉，包括對衝模式的多/空對
• POST /capi/v3/sim/order — 各類訂單下單
• GET /capi/v3/sim/order/history — 模擬成交歷史

相同的域名、相同的請求頭、相同的簽名規則。將 /capi/v3/order 替換為 /capi/v3/sim/order 通常是進行完整集成測試所需的唯一更改。

利用它們來驗證系統在真實條件下才可能崩潰的部分：WebSocket 斷開後的重連邏輯、訂單狀態機在成交先於 REST 確認到達時是否能恢復、持倉規模在槓桿上限時是否正確。這些是在生產環境中導致虧損的故障，且無需真實資金即可浮現。

在架構設計前值得了解：WEEX 目前既不支持 TradingView Webhook 執行，也不支持 FIX 網關。如果您的策略依賴於這兩者，請改用 REST 和 WebSocket。

結論

一旦您理解現貨和合約是兩個共享簽名方案但幾乎沒有其他共同點的產品，WEEX API 就非常直觀。確保四個請求頭正確，對發送的原始位元組進行簽名，緩存 API 交易對白名單，讀取速率限制請求頭而不是計數，並顯式處理 -1047、-1052 和 -1058——這涵蓋了絕大多數常見問題。

最節省時間的順序：創建一個唯讀權限的 Key，確認公共端點響應正常，實現一個已簽名的私有讀取調用，針對模擬交易端點運行完整策略，最後再啟用交易權限並綁定 IP 白名單。完整的端點參考位於 WEEX 合約 API 文檔和 WEEX 現貨 API 文檔，權限和速率限制詳情收集在 合約 API FAQ 中。

FAQ

1. 我需要為現貨和合約分別準備 WEEX API Key 嗎？

不需要——一個 Key 可以攜帶兩種權限。但它們是獨立的複選框，且默認均為關閉。僅勾選 Spot 的 Key 在進行合約下單時會返回 -1052，反之亦然。

2. WEEX API 的速率限制是多少？

兩個獨立計數器：通用 REST 端點為每個 IP 每 10 秒 500 權重，合約下單為每個帳戶每分鐘 300 筆。WebSocket 限制為每個 IP 20 個並發連接，每個連接 100 個頻道。超過任何限制都會返回 HTTP 429 並封禁 10 秒。

3. 為什麼我的 WEEX API Key 在創建後立即返回 -1049？

新創建或修改的 Key 在 WEEX 系統中全球生效約需 15 分鐘。如果 Key 是剛創建的，請等待後再調試。如果問題持續，請檢查密碼是否包含特殊字元——WEEX 建議僅使用字母數字。

4. 我可以透過 API 交易所有 WEEX 交易對嗎？

不能。只有在 API 交易白名單上的交易對才能透過程序化交易。調用 GET /capi/v3/market/apiTradingSymbols 獲取當前列表；任何在此之外的交易對都會返回 -1058。

5. WEEX 支持 TradingView 警報或 FIX 嗎？

截至 2026 年 4 月的文檔更新，兩者均不支持。自動化交易透過 REST 和 WebSocket API 進行。

6. 如何在不承擔資金風險的情況下測試 WEEX API 策略？

使用 /capi/v3/sim/ 下的合約模擬交易端點。它們接受與真實端點相同的身份驗證和簽名，並以模擬 SUSDT 結算。

風險提示

加密資產波動劇烈，價值可能迅速歸零；交易可能導致部分或全部資本損失。API 交易會集中而非降低這種風險。自動化系統可能在人為發現故障前下單數百次，簽名錯誤、陳舊的價格源或未處理的重連都可能導致意外持倉。合約交易增加了槓桿風險：部分 WEEX 合約槓桿高達 400 倍，不利波動可在秒內清算倉位，在流動性差的市場中使用 CONTRACT_PRICE 作為止損觸發器會使您暴露於插針導致的止損風險中。API Key 同樣存在託管風險——未綁定 IP 且擁有交易權限的 Key 是可以在網際網路任何地方使用的實時憑證。請務必綁定 IP 白名單，在集成測試透過模擬交易端點前關閉交易權限，並假設您的代碼最終會出錯來設定持倉規模。