申请提现签名

描述

预留请求数量的 DF，签署 EIP-712 类型化数据 SpotReleaseFunds 释放授权，并返回调用方向链上金库合约提交所需的全部数据。

这是两步提现流程的第一步。收到签名后，调用方需在 BSC 上向 ZtdxSpotVault.withdraw() 提交该签名。关于包含金库调用和状态轮询的完整流程，请参阅提现流程。

原子性： 在单个数据库事务中，available（可用）余额减少 amount，frozen（冻结）余额增加 amount。若在 deadline (保留) 前未完成链上调用，回收任务将把该记录标记为 expired（已过期）并将资金返还至 available。详见提现流程 → 过期回收任务。

MVP 阶段仅支持 DF。

HTTP 请求

POST /spot/withdraw/request（仅 JWT）

使用 API Key 认证的调用方将收到 403 API Key permission denied。详见通用信息 → 认证。

权重

0 — 当前 MVP 阶段不设每 IP 频率限制。

请求参数

名称	类型	必填	描述
`token`	STRING	必填	提现的代币。MVP 阶段仅支持 `DF`。
`amount`	DECIMAL	必填	以字符串表示的十进制金额（例如 `"100"`），必须 ≥ `1`（服务端强制执行最小值）。
`recipient`	STRING	可选	链上收款地址，默认为已认证用户的地址。EIP-712 类型化数据的 `account` 字段始终设置为调用方地址——第三方无法将该签名重放到不同的收款人。

响应示例

200 OK

{
  "id":            "9f2a1c4e-5b67-4d8a-bf93-2e1f4a6c8d10",
  "token":         "DF",
  "amount":        "100",
  "nonce":         42,
  "signature":     "0x...65-byte hex...",
  "deadline":      1778402000,
  "vault_address": "0x4Fe0b354c5865ee9deb979a99030d757ae47664a",
  "chain_id":      97,
  "status":        "signed"
}

字段	说明
`id`	提现记录的 UUID。可配合 `GET /spot/withdrawals/:id` 轮询状态。
`token`	回显请求字段。
`amount`	已预留金额的十进制字符串。
`nonce`	每（用户、链）单调递增的 nonce (保留)，防止链上重放攻击。
`signature`	65 字节、0x 前缀的 EIP-712 类型化数据签名。直接传入 `vault.withdraw()` 即可。
`deadline`	Unix 秒时间戳。链上 `withdraw()` 调用必须在此时间戳之前执行。
`vault_address`	需要调用 `withdraw()` 的金库合约 `ZtdxSpotVault` 地址。
`chain_id`	签名所针对的 EVM 网络的链 id — `97`（BSC 测试网）。
`status`	成功响应时始终为 `signed`（已签名）。

错误响应

HTTP	`error`
`400`	`AMOUNT_NON_POSITIVE` — `amount` ≤ 0。
`400`	`amount below minimum 1` — `amount` 低于服务端配置的最小值。
`400`	`INSUFFICIENT_BALANCE` — 现货 `available` 余额不足 `amount`。
`400`	`UNSUPPORTED_TOKEN` — 请求了 `DF` 以外的代币。
`403`	`API Key permission denied` — 调用方通过 API Key 认证。
`503`	`SIGNER_UNAVAILABLE` — 后端签名服务或其 KMS 不可达，为暂时性错误，请使用退避策略重试。
`503`	`spot subsystem disabled` — 服务端 `SPOT_ENABLED=false`。
`500`	`internal` / `sign failed` — 服务端错误，请查看日志。

完整列表：错误码。

代码示例

cURL（JWT）

JWT="your_jwt_token"

curl -s -X POST "https://api-sepolia.p99.world/api/v1/spot/withdraw/request" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "token":  "DF",
    "amount": "100"
  }'

Python

import requests

BASE_URL = "https://api-sepolia.p99.world/api/v1"
JWT      = "your_jwt_token"

resp = requests.post(
    f"{BASE_URL}/spot/withdraw/request",
    headers={
        "Authorization": f"Bearer {JWT}",
        "Content-Type":  "application/json",
    },
    json={"token": "DF", "amount": "100"},
    timeout=5,
)
resp.raise_for_status()
sig = resp.json()

print(f"withdrawal id : {sig['id']}")
print(f"nonce         : {sig['nonce']}")
print(f"deadline      : {sig['deadline']}")
print(f"signature     : {sig['signature'][:20]}...")
# 下一步：调用 vault.withdraw(DF_TOKEN, amount_in_wei, deadline, signature)
# 完整的端到端代码示例请参阅 withdraw-flow.md。

描述​

HTTP 请求​

权重​

请求参数​

响应示例​

错误响应​

代码示例​

cURL（JWT）​

Python​

描述