跳到主要内容

接口鉴权

ZTDX 接受两种鉴权方式，每个端点的文档会标明它需要哪一种：

方式头 / 体适用场景
HMAC SHA-256 签名X-MBX-APIKEY: <api_key> + signature/fapi/v1/* 程序化 / 做市商客户端
EIP-712 钱包签名Authorization: Bearer <JWT>（登录后）/api/v1/* 交互 / 浏览器客户端

公开接口（行情、exchangeInfo、公开排行榜等）无需任何签名。

HMAC SHA-256 签名​

这是 Binance 兼容的签名流程。任何要程序化下单的客户端都用这一套。

步骤​

  1. 创建 API Key，详见 快速入门。
  2. 构造待签名字符串 —— GET / DELETE 取 URL query string （如 symbol=BTCUSDT&side=BUY&timestamp=…）；POST / PUT 取 query string 拼接 request body。
  3. 计算 HMAC_SHA256(secret_key, payload)，将十六进制结果作为 &signature=<hex> 追加到 URL。
  4. 请求时带上 X-MBX-APIKEY: <api_key>。

必需参数​

名称说明
timestampUnix 毫秒，必须落在 [serverTime - recvWindow, serverTime + 1000ms] 区间
recvWindow可选，默认 5000（毫秒），最大 60000。用来收紧或放宽 timestamp 容差窗口。
signature十六进制 HMAC SHA-256

timestamp 越界会返回 -1021 INVALID_TIMESTAMP。

Payload 编码兼容​

部分 HTTP 库会先把 query string 里的特殊字符做 URL 编码（例如 [ → %5B，, → %2C）再签名；另一些直接对原始字节签名。 ZTDX 两种都接受：服务器先按 raw payload 验证，失败时回退到 URL-decoded 比较。客户端不必预先统一编码方式。

示例（Python）​

import time, hmac, hashlib, requests

API_KEY    = "your_api_key"
API_SECRET = "your_api_secret"
BASE_URL   = "https://api.ztdx.io"

def sign(payload: str) -> str:
    return hmac.new(API_SECRET.encode(), payload.encode(), hashlib.sha256).hexdigest()

def signed_get(path: str, params: dict):
    params["timestamp"] = int(time.time() * 1000)
    qs = "&".join(f"{k}={v}" for k, v in params.items())
    return requests.get(
        f"{BASE_URL}{path}?{qs}&signature={sign(qs)}",
        headers={"X-MBX-APIKEY": API_KEY},
    )

print(signed_get("/fapi/v1/openOrders", {"symbol": "BTCUSDT"}).json())

EIP-712 钱包签名​

供前端及任何要用钱包鉴权的客户端使用。完整登录流程（nonce → typed-data 签名 → 换 JWT）见 基本信息。

签发后 JWT 以 Authorization: Bearer <jwt> 发送。/api/v1/* 上大部分 交易动作还要求请求体内携带一个 EIP-712 签名（覆盖该动作的 typed-data 结构体）—— 各端点页会列出对应的 TypeHash。