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，并在生产环境前进行充分的小额测试。本文仅为技术集成指南，不构成投资建议。