充值

DF 充值由后台监听器在 BSC 上轮询金库合约的 SpotDeposit 事件后给现货钱包入账。没有"发起充值"的接口 —— 用户直接与金库合约交互，后台异步对账。

充值流程

1. approve()        2. deposit()                3. SpotDeposit 事件
   ──────────▶         ──────────▶                    │
   DF 代币 ERC-20      金库合约                         ▼
                       (0x4Fe0...664a)        后台监听器
                                                       │
                                            ≥ 20 个区块确认（≈ 40s）
                                                       │
                                                       ▼
                                          spot_balances.available += amount
                                          INSERT spot_deposits 行

第 1 步 — 授权

用户授权金库合约从其账户拉取 amount 数量的 DF。

DF.approve(vaultAddress, amount);

第 2 步 — 调用 deposit

用户调用金库合约的 deposit 方法。

ZtdxSpotVault.deposit(address token, uint256 amount);
// token  = DF 代币地址（0x8063a4...）
// amount = wei（DF 18 位精度，1 DF = 10**18）

金库收到代币后会发出：

event SpotDeposit(address indexed account, address indexed token, uint256 amount);

第 3 步 — 后台入账

充值轮询器在事件之上等 SPOT_BSC_CONFIRMATION_DEPTH（当前 20）个区块确认后：

• 向 spot_deposits 表插入一条 status = "confirmed" 记录。
• 给该用户的 spot_balances.available 增加对应金额。

幂等性由 (chain_id, tx_hash, log_index) 唯一键保证 —— 同一事件被重放不会重复入账。

查询我的充值记录

返回当前用户最近已确认的充值。

需要鉴权

Authorization: Bearer <JWT>     # 或 X-API-Key

GET /spot/deposits

Query 参数

参数	类型	默认	说明
limit	number	50	1–200，服务端 clamp。

响应 — 200 OK

[
  {
    "id":           "5af0c1a2-...",
    "token":        "DF",
    "amount":       "100",
    "chain_id":     97,
    "tx_hash":      "0xabc...",
    "block_number": 106384180,
    "status":       "confirmed",
    "created_at":   1778315530,
    "confirmed_at": 1778315570
  }
]

字段	类型	说明
id	string	充值记录 UUID。
token	string	MVP 阶段恒为 DF。
amount	string	已入账金额（十进制）。
chain_id	number	来源链（97 = BSC Testnet）。
tx_hash	string	链上交易哈希。
block_number	number	事件所在区块号。
status	string	当前恒为 confirmed。未达确认数的充值不会出现在这里。
created_at	number	Unix 秒 — DB 插入时间。
confirmed_at	number	Unix 秒 — 监听器入账时间。

此接口只返回已确认的记录；处于待确认阶段的充值暂时不暴露。前端如需展示进度，可以拿用户钱包的 TX hash 在此接口轮询匹配。

代码示例

import requests

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

deposits = requests.get(
    f"{BASE}/spot/deposits?limit=20",
    headers={"Authorization": f"Bearer {JWT}"},
).json()
for d in deposits:
    print(f"  {d['token']:5} {d['amount']:>14}  tx={d['tx_hash'][:10]}…  block={d['block_number']}")

运维说明

• 充值轮询器每 SPOT_BSC_POLL_INTERVAL_MS（当前 2000 ms）跑一次，每次拉至多 100 个区块。
• 冷启动追块速率约 30 块/秒；稳态延迟 ≤ 40 秒（20 确认 × BSC ≈ 2 秒/块）。
• MVP 不支持原生币（BNB）充值。