跳到主要内容

现货钱包说明

ZTDX Spot 是与永续合约系统并行、且代码层面完全隔离的多代币钱包。MVP 阶段支持 DF（BSC 上的治理代币），并提供永续保证金 ↔ 现货钱包之间的 USDT 内部划转。

核心概念​

概念含义
现货余额按 (用户, 代币) 维度记录 available + frozen。frozen 表示已为某笔在途提现冻结的金额。
内部划转永续保证金与现货钱包之间的原子划转（MVP 仅支持 USDT），不涉及链上交易。
充值用户向 BSC 上的金库合约转入 ERC-20，后台监听器在达到 confirmation_depth 个区块确认后给现货余额入账。
提现两步：(1) 后台签发 EIP-712 释放授权；(2) 用户拿这个签名调用金库合约把代币提走。

服务地址​

环境REST
测试网https://api-sepolia.p99.world/api/v1
主网（暂未部署）

鉴权​

所有 /spot/* 接口走项目通用鉴权中间件，支持两种方式：

方式请求头适用范围
Bearer JWTAuthorization: Bearer <JWT>所有现货接口
API KeyX-API-Key: <key>仅只读接口。POST /spot/transfer 与 POST /spot/withdraw/request 拒绝 API Key 调用，返回 403 API Key permission denied。

GET /wallet/tokens 是公开接口，无需鉴权。

响应封装​

GET /wallet/tokens 使用项目统一封装：

{ "success": true, "data": [...], "error": null, "timestamp": 1778312000 }

其他现货接口当前直接返回 裸数据（对象 / 数组），错误形如 {"error": "..."} 并搭配相应 HTTP 状态码。

链上组件​

项网络地址 / 值
BSC 链 IDBSC Testnet97
金库合约（ZtdxSpotVault）BSC Testnet0x4Fe0b354c5865ee9deb979a99030d757ae47664a
DF 代币（ERC-20）BSC Testnet0x8063a43ed88397c1B10DA23dcC60ba1E7A0Bf555
DF 精度—18
永续保证金代币（USDT）Arbitrum Sepolia (421614)0xfA70c5A9221d239Cd51DBf48967ABc79d7B9D61d
USDT 精度—6

EIP-712 域（提现签名）​

提现签名是 EIP-712 类型化数据，由金库合约链上验签。

Domain

字段值
nameZTDX Spot Vault
version1
chainId97（BSC Testnet）
verifyingContract金库地址（见上）

主类型 — SpotReleaseFunds

SpotReleaseFunds(
    address account,
    address token,
    uint256 value,
    uint256 nonce,
    uint256 deadline
)

签名最终被金库合约的 withdraw(token, amount, deadline, signature) 函数消费。

业务流程​

充值​

用户钱包 ──approve──▶ DF 代币
用户钱包 ──deposit(token, amount)──▶ 金库合约
                                              │
                                              ▼ SpotDeposit 事件
                                       后台监听器
                                              │
                              confirmation_depth 个区块（当前 20）
                                              │
                                              ▼
                                  spot_balances.available += amount

提现​

1. POST /spot/withdraw/request                     2. 链上提交
   ─────────────────────────────────▶  后台         ─────────────────▶ 金库合约
                                          │                                  │
                                          ▼                                  ▼
                              status = "signed"                       SpotWithdrawal 事件
                              available -= amount                            │
                              frozen    += amount                            ▼
                                                                   后台监听器
                                                                            │
                                                                            ▼
                                                            status = "confirmed"
                                                            frozen -= amount

如果某笔 signed 状态的提现在 SPOT_WITHDRAW_NONCE_TTL_SECS（当前 86400 = 24 小时）内未上链，回收任务会把它标记为 expired，并把冻结的金额退回到 available。

提现状态​

状态含义
signed后台已签发释放授权；用户尚未上链。资金处于冻结。
confirmed已观察到链上 SpotWithdrawal 事件。资金已离开金库。
expired签名 deadline 已过仍未使用。资金退回 available。

接口索引​

公开（无鉴权）​

MethodPath说明
GET/wallet/tokens充值/提现 UI 用的代币元数据列表
GET/spot/markets列出交易对 + 配置（tick / lot / fee / status）
GET/spot/depth订单簿快照（按价格聚合）
GET/spot/trades最近公共成交
GET/spot/klinesK 线（1m / 5m / 15m / 1h / 4h / 1d）
GET/spot/ticker/24hr24h 滚动 ticker（单个或全部）
GET/spot/healthengine 健康探针

钱包（JWT 或 API Key）​

MethodPath说明
GET/spot/balances列出当前用户的现货余额
POST/spot/transfer永续保证金 ↔ 现货钱包之间的 USDT 划转（仅 JWT）
GET/spot/deposits列出当前用户已确认的充值记录
POST/spot/withdraw/request申请提现签名（仅 JWT）
GET/spot/withdrawals列出当前用户的提现记录
GET/spot/withdrawals/:id按 id 查询单笔提现

交易（JWT 或 API Key）​

MethodPath说明
POST/spot/orders下新单（限价 / 市价）
DELETE/spot/orders/:id按 id 撤一单
DELETE/spot/orders撤所有（可选 ?symbol=）
GET/spot/orders/:id按 id 查单笔订单
GET/spot/orders列订单（filters：symbol / status / start / end / limit）
GET/spot/trades/me列调用者参与的成交（maker + taker）

Admin（X-API-Key 匹配 ADMIN_API_KEY）​

MethodPath说明
POST/admin/spot/markets创建交易对
PATCH/admin/spot/markets/:id更新 tick / lot / min_notional / fee
PATCH/admin/spot/markets/:id/statuslisted ↔ halted ↔ delisted（delisted 会清空盘口）
POST/admin/spot/balances/credit直接 off-chain 加余额（受 TESTNET_ONLY=true gate）

交易子系统​

订单簿交易场所（CLOB）由 SPOT_TRADING_ENABLED=true 在 SPOT_ENABLED 之上额外 gate。当交易关闭时，/spot/orders*、/spot/trades*、/admin/spot/* 路由仍然挂载（下单/撤单返回 503 spot trading disabled）；/spot/markets、/spot/health、公开行情路由也照常工作但反映空状态。

Engine 是单 Tokio task，每个市场拥有一个 in-memory order book（MVP 只有 DFUSDT）。每笔成交在自己的 DB 事务里 commit。重启时从 spot_orders 重建 GTC 限价单；正在执行的 IOC 和市价单会被撤销并退还冻结金额。

备注​

  • 现货子系统由 SPOT_ENABLED=true 开启。当其关闭时，/spot/* 路由不挂载（404），/wallet/tokens 仅返回永续保证金条目。
  • BSC 监听器冷启动追块速率约 30 块/秒。追上之后，充值入账延迟通常 ≤ 40 秒（20 个确认 × BSC 约 2 秒/块）。
  • WebSocket 推送（depth diff / trades / klines / ticker / 私有订单 + 余额变更）在路线图中；MVP 阶段客户端轮询上面的 REST 接口即可。