内部划转（永续 ↔ 现货）

将 USDT 在用户的永续保证金账户与现货钱包之间做原子划转。不涉及链上交易，两侧账本均由后台维护。

需要鉴权

仅支持 JWT。API Key 调用会返回 403 API Key permission denied。

Authorization: Bearer <JWT>

POST /spot/transfer

请求体

{
  "direction": "perp_to_spot",
  "token":     "USDT",
  "amount":    "100"
}

字段	类型	必填	说明
direction	string	是	perp_to_spot 或 spot_to_perp。
token	string	是	MVP 仅支持 USDT。
amount	string / number	是	十进制金额（如 "100" = 100 USDT），必须为正。

响应 — 200 OK

{
  "direction":           "perp_to_spot",
  "token":               "USDT",
  "amount":              "100",
  "perp_balance_after":  "4900",
  "spot_balance_after":  "5100"
}

字段	说明
perp_balance_after	划转后永续 available 余额。
spot_balance_after	划转后现货 available 余额。

原子性

划转在单个 DB 事务内完成，对两侧的余额行都加 FOR UPDATE 行锁。要么两边一起变，要么都不变；同一用户的并发划转会自动串行化。

错误响应

HTTP	error	原因
400	invalid direction: <value>	direction 不是允许的两个值之一。
400	unsupported token: <symbol>	请求了 USDT 之外的代币。
400	amount must be positive	amount ≤ 0。
400	insufficient balance	源方向 available < amount。
403	API Key permission denied: transfers not allowed	调用方使用了 API Key。
500	internal error	数据库错误，详见后端日志。

代码示例

import requests

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

resp = requests.post(
    f"{BASE}/spot/transfer",
    headers={"Authorization": f"Bearer {JWT}", "Content-Type": "application/json"},
    json={"direction": "perp_to_spot", "token": "USDT", "amount": "100"},
)
print(resp.status_code, resp.json())