WEEX API Python SDK：如何端到端簽名並調用

在編寫代碼前，首先要明確一點：截至2026年7月，WEEX並未發布名為「weex-python-sdk」的官方獨立包。您實際上擁有兩種可行的路徑——使用requests庫配合WEEX的簽名規則直接調用REST接口，或者使用已集成WEEX的開源多交易所庫ccxt。本指南將完整演示這兩種路徑，並重點講解集成中最容易出錯的兩個環節：如何對請求進行簽名，以及如何保障密鑰安全。

這是一份可直接複製到項目中的構建筆記，而非接口字典。WEEX現貨和合約API目前處於V3（BETA）版本，合約仍提供V2版本；下文代碼均基於現貨V3版本。

「WEEX API Python SDK」的實際含義

嚴格來說，它並非一個官方認證的軟件包，而是指「一個與WEEX接口通信的Python客戶端」。WEEX提供涵蓋現貨、合約、跟單和經紀商產品的REST和WebSocket接口。任何能夠發送HTTP請求並計算HMAC簽名的語言都可以進行集成。

在實踐中，「Python SDK」通常有三種形式：

• 輕量級手寫封裝 — requests加上hmac，僅需幾十行代碼，依賴項最少，控制力最強。
• ccxt統一庫 — pip install ccxt，將WEEX視為ccxt支持的100多家交易所之一，跨平台共享方法名稱。
• WebSocket客戶端 — 使用websocket-client訂閱實時行情或私有頻道。

API簡介本身建議開發者遵循文檔中的架構並維護版本化的客戶端——換句話說，SDK需要您自行組裝，無需等待官方版本。

準備工作：創建API Key並設置權限

在調用前，請先在帳戶中創建API Key。根據集成準備文檔，一個帳戶最多可持有10組Key。每組Key包含三個憑證，缺一不可：

權限設置至關重要：新創建的Key默認為唯讀——您必須手動啟用現貨交易權限才能下單。創建時請綁定IP白名單；文檔明確指出，未綁定IP的無限制Key存在安全風險。

如何調用：在Python中對請求進行簽名

根據簽名文檔，WEEX的簽名規則為：拼接時間戳 + 方法（大寫） + 請求路徑（含查詢參數） + 請求體，使用SecretKey進行HMAC SHA256計算，最後進行Base64編碼。時間戳單位為毫秒，任何與服務器時鐘偏差超過30秒的請求都將被拒絕。

以下代碼可直接運行（使用文檔中的深度接口示例）：

import time, hmac, hashlib, base64, requests

API_KEY    = "your-APIKey"
SECRET_KEY = "your-SecretKey"
PASSPHRASE = "your-Passphrase"
BASE = "https://api-spot.weex.com"  # 請根據官方StandardSpecifications文檔確認主機地址

def sign(ts, method, path, body=""):
    prehash = f"{ts}{method.upper()}{path}{body}"
    mac = hmac.new(SECRET_KEY.encode(), prehash.encode(), hashlib.sha256)
    return base64.b64encode(mac.digest()).decode()

def request(method, path, body=""):
    ts = str(int(time.time() * 1000))
    headers = {
        "ACCESS-KEY": API_KEY,
        "ACCESS-SIGN": sign(ts, method, path, body),
        "ACCESS-TIMESTAMP": ts,
        "ACCESS-PASSPHRASE": PASSPHRASE,
        "Content-Type": "application/json",
    }
    url = BASE + path
    if method == "GET":
        return requests.get(url, headers=headers).json()
    return requests.post(url, headers=headers, data=body).json()

# 公共行情數據無需簽名；此處展示簽名請求頭模式
print(request("GET", "/api/v3/market/depth?symbol=BTCUSDT&limit=20"))

陷阱：GET參數包含在path的查詢字符串中，POST使用JSON請求體，且您簽名的請求體必須與發送的請求體字節完全一致。鍵值順序不同或多出一個空格都會導致簽名失效——這是手寫客戶端中最常見的401錯誤來源。

使用ccxt快速入門（大多數人的首選）

如果您不想手動處理簽名，ccxt已經封裝了WEEX的現貨、合約（永續）和WebSocket，涵蓋80多種方法。只需幾行代碼即可獲取行情和訂單：

import ccxt   # pip install ccxt

ex = ccxt.weex({
    "apiKey": "your-APIKey",
    "secret": "your-SecretKey",
    "password": "your-Passphrase",   # WEEX的Passphrase對應ccxt的"password"
})

print(ex.fetch_ticker("BTC/USDT"))            # 行情數據
# print(ex.fetch_balance())                    # 需要交易權限
# ex.create_order("BTC/USDT", "limit", "buy", 0.001, 30000)

優勢：今天調用WEEX的代碼，明天只需修改一行類名即可切換到其他平台。代價是ccxt是一個社區維護的抽象層——對全新WEEX接口的覆蓋可能會滯後，因此在追逐新功能時，請務必對照官方文檔核對字段。

實時數據：從Python連接WebSocket

輪詢REST接口很快會觸及頻率限制。對於實時數據，請使用WebSocket——公共頻道為wss://ws-spot.weex.com/v3/ws/public，私有頻道為.../private，後者使用相同的四個ACCESS-KEY / ACCESS-SIGN / ACCESS-TIMESTAMP / ACCESS-PASSPHRASE字段進行身份驗證（簽名字符串為時間戳 + /v3/ws/private）。

import json, websocket   # pip install websocket-client

ws = websocket.create_connection("wss://ws-spot.weex.com/v3/ws/public")
ws.send(json.dumps({"method": "SUBSCRIBE", "params": ["BTCUSDT@ticker"], "id": 1}))
print(ws.recv())

服務器會定期發送ping消息；客戶端必須回覆{"method":"PONG","id":1}，否則連接會斷開。字段詳情請參考WebSocket文檔。

安全嗎？權限與密鑰管理的實踐

API交易的安全性取決於您的密鑰管理，而非接口本身。幾乎所有的損失都源於密鑰處理不當，而非接口被攻破。實用清單如下：

• 最小權限原則 — 僅啟用當前策略所需的權限。唯讀Key永遠無法獲得交易權限；WEEX Key默認不具備提幣權限，這限制了密鑰洩漏後的風險。
• 綁定IP白名單 — 將Key鎖定在服務器的外網IP上，使洩漏的Key在其他地方無法使用。
• 密鑰不入代碼庫 — 使用環境變量或密鑰管理工具；嚴禁硬編碼、提交到Git或在客戶端代碼中發布。
• 開發與生產分離 — 兩套Key，互不干擾，便於事故排查。
• 定期輪換 — 週期性更換Key，並對簽名失敗和429錯誤進行報警。

預先設計好頻率限制：公共行情接口每2秒允許約20次請求，超過則返回HTTP 429；私有接口遵循每個Key的規則。在客戶端中構建重試和退避機制遠比事後救火有效。

快速參考

總結

目前沒有官方的獨立WEEX API Python SDK，這並非障礙：簽名邏輯清晰（HMAC SHA256 + Base64），且ccxt為您提供了現成的統一入口。決定成敗的關鍵在於權限和密鑰管理——默認唯讀、綁定IP、密鑰不入庫——做好這些，WEEX API Python集成既快速又穩定。準備好後，請從集成準備文檔創建您的第一個Key。

延伸閱讀：ccxt的WEEX覆蓋情況記錄在其官方維基中。

常見問題解答

1. WEEX有官方Python SDK嗎？

截至2026年7月沒有。WEEX提供REST和WebSocket接口；在Python端，您可以編寫requests封裝或使用已集成WEEX的ccxt。

2. 我的調用一直返回簽名錯誤（401）——如何調試？

通常是以下三個原因之一：時間戳不是毫秒級或偏差超過30秒；簽名字符串順序錯誤（必須是時間戳+方法+路徑+請求體）；或者POST請求中簽名的請求體與實際發送的請求體不一致。請逐一檢查。

3. WEEX的Passphrase在ccxt中填在哪裡？

填在password字段中。ccxt使用apiKey、secret和password來映射WEEX的APIKey、SecretKey和Passphrase。

4. 公共行情接口需要簽名嗎？

公共接口（如行情數據）通常不需要簽名；只有涉及帳戶或訂單的私有接口才需要完整的四個認證請求頭。公共接口仍受頻率限制。

5. 為什麼我的新API Key無法下單？

因為新Key默認為唯讀。創建或編輯Key時，請手動啟用現貨交易權限，並同時綁定IP白名單。

風險提示

數字資產波動劇烈，自動化交易可能因策略缺陷、市場劇變或系統故障導致部分或全部本金損失。API交易增加了特定風險：未綁定IP的洩漏Key可能讓攻擊者操作您的帳戶；高槓桿合約會放大損失；頻率限制（429）或網絡中斷可能導致訂單未成交或撤單失敗。請應用最小權限原則，綁定IP白名單，妥善保管SecretKey和Passphrase，並在生產環境前進行充分的小額測試。本文僅為技術集成指南，不構成投資建議。