跳到主要内容

接口鉴权类型

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 − 60000ms, serverTime + 60000ms] 区间（固定 ±60s 窗口，两个方向都强制校验）
recvWindow为兼容 Binance 而接受，但会被忽略 —— 窗口固定为 ±60000ms，无法收紧或放宽。
signature十六进制 HMAC SHA-256

timestamp 落在窗口之外的请求会返回 HTTP 401，响应体为标准错误信封：

{
  "success": false,
  "data": null,
  "error": {
    "code": "SIGNATURE_INVALID",
    "message": "Timestamp outside recv window"
  },
  "timestamp": 1778716800
}

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.prex.world"

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）​

  1. 获取 nonce：GET /api/v1/auth/nonce/:address 返回用户当前的 nonce，以及一个可直接签名的 EIP-712 typed_data 对象（类型为 Login(address wallet,uint256 nonce,uint256 timestamp)）。 首次调用时会自动创建用户记录。
  2. 签名：用钱包对 typed data 签名（如 eth_signTypedData_v4）。
  3. 换取 JWT：POST /api/v1/auth/login，请求体为 { "address", "signature", "timestamp" }。timestamp（Unix 秒） 必须在服务器时间 ±300 秒以内，否则请求以 400 TIMESTAMP_EXPIRED 失败。成功后 nonce 自增（每个签名仅可 使用一次），响应为 { "token", "expires_at" }。
  4. JWT 默认有效期为 86400 秒（24 小时）。

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

两种机制分别在哪些路由上生效​

两种鉴权机制由同一个中间件处理，该中间件同时挂载在两套接口面 （/api/v1/* 与 /fapi/*）的受保护路由上。实际效果：

凭证/api/v1/*/fapi/v1/*
API Key + HMAC（X-MBX-APIKEY）可用 —— 且 API-key 调用方免除逐请求的 EIP-712 请求体签名可用（文档化的主要用法）
JWT（Authorization: Bearer）可用（文档化的主要用法）；交易动作仍需请求体内的 EIP-712 签名可用

中间件先检查 X-MBX-APIKEY；该头缺失时回退到 Bearer-JWT 校验。 本页顶部的表格描述的是预期搭配，并非硬性限制。