从签名到入账，
每一步都有明确答案。

01 · QUICKSTART

快速开始

管理员先在后台创建接入平台并配置 HTTPS 回调地址。系统会一次性返回App ID、API Secret 和Webhook Secret。

02 · AUTHENTICATION

请求鉴权

所有 /v1/* 请求必须携带以下四个请求头：

待签名字符串

{timestamp}\n{nonce}\n{HTTP_METHOD}\n{path_with_query}\n{sha256(raw_body)}

最终签名为 hex(HMAC-SHA256(api_secret, canonical_request))。 GET 请求体是空字节；存在查询参数时必须按实际发送顺序签入。

Python 示例

import hashlib, hmac, json, secrets, time

method = "POST"
path = "/v1/deposit-addresses"
body = json.dumps(
    {"external_user_id": "user-10001"},
    separators=(",", ":"),
).encode()
timestamp = str(int(time.time()))
nonce = secrets.token_hex(16)

canonical = "\n".join([
    timestamp,
    nonce,
    method,
    path,
    hashlib.sha256(body).hexdigest(),
])
signature = hmac.new(
    API_SECRET.encode(),
    canonical.encode(),
    hashlib.sha256,
).hexdigest()

03 · DEPOSITS

充值接口

为平台用户获取固定充值地址。同一平台、同一用户重复请求会返回同一地址。

POST /v1/deposit-addresses
Content-Type: application/json
X-App-Id: app_xxx
X-Timestamp: 1785388800
X-Nonce: 9f21e8...
X-Signature: 6dc70e...

{
  "external_user_id": "user-10001"
}

{
  "external_user_id": "user-10001",
  "network": "TRON",
  "asset": "USDT",
  "address": "T..."
}

04 · WITHDRAWALS

提现接口

创建待审核提现。金额必须是十进制字符串，最多 6 位小数，禁止使用浮点数计算。

POST /v1/withdrawals
Content-Type: application/json
X-App-Id: app_xxx
X-Timestamp: 1785388800
X-Nonce: 504ceb...
X-Signature: dcd085...

{
  "platform_order_id": "wd-20260730-00001",
  "external_user_id": "user-10001",
  "to_address": "T...",
  "amount": "12.500000"
}

platform_order_id 是幂等键。相同订单号和参数会返回原订单； 同订单号但参数不同返回 409。

提现状态

05 · WEBHOOKS

Webhook 验签

网关向平台配置的回调地址发送 JSON，并携带：

const expected = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(timestamp + "." + rawBody)
  .digest("hex");

if (!crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(signature)
)) throw new Error("invalid webhook signature");

签名消息为 timestamp + "." + 原始请求体。 业务事务提交成功后返回任意 2xx，否则网关会指数退避重试。

06 · ERRORS

错误处理

07 · GO-LIVE

上线检查