内部划转（永续 ↔ 现货）

描述

在用户的永续保证金账户与现货钱包之间原子性地移动 USDT。整个操作不涉及任何链上交易——后端在单个数据库事务中通过 FOR UPDATE 行锁同时维护两侧余额。要么两侧余额同时变动，要么均不变动；来自同一用户的并发划转会串行执行。

MVP 阶段仅支持 USDT。

HTTP 请求

POST /spot/transfer（仅 JWT）

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

权重

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

请求参数

名称	类型	必填	描述
`token`	STRING	必填	划转的代币。MVP 阶段仅支持 `USDT`。
`direction`	ENUM	必填	`perp_to_spot` 将 USDT 从永续保证金划入现货钱包；`spot_to_perp` 为反向操作。
`amount`	DECIMAL	必填	以字符串表示的十进制金额（例如 `"100"`），必须为正数。

响应示例

200 OK

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

字段	说明
`direction`	回显请求字段。
`token`	回显请求字段。
`amount`	已划转金额的十进制字符串，末尾零已去除。
`perp_balance_after`	划转后永续账户的 `available`（可用）余额（十进制字符串）。
`spot_balance_after`	划转后现货钱包的 `available`（可用）余额（十进制字符串）。

错误响应

HTTP	`error`
`400`	`INVALID_DIRECTION` — `direction` 不是 `perp_to_spot` 或 `spot_to_perp`。
`400`	`AMOUNT_NON_POSITIVE` — `amount` ≤ 0。
`400`	`INSUFFICIENT_BALANCE` — 来源方的可用余额不足 `amount`。
`400`	`UNSUPPORTED_TOKEN` — 请求了 `USDT` 以外的代币。
`403`	`API Key permission denied` — 调用方通过 API Key 认证。
`500`	`internal error` — 数据库错误，请查看服务端日志。

完整列表：错误码。

代码示例

cURL（JWT）

JWT="your_jwt_token"

curl -s -X POST "https://api-sepolia.p99.world/api/v1/spot/transfer" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "token":     "USDT",
    "direction": "perp_to_spot",
    "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/transfer",
    headers={
        "Authorization":  f"Bearer {JWT}",
        "Content-Type":   "application/json",
    },
    json={
        "token":     "USDT",
        "direction": "perp_to_spot",
        "amount":    "100",
    },
    timeout=5,
)
resp.raise_for_status()
data = resp.json()
print(
    f"transferred {data['amount']} {data['token']}  "
    f"perp_after={data['perp_balance_after']}  "
    f"spot_after={data['spot_balance_after']}"
)

描述​

HTTP 请求​

权重​

请求参数​

响应示例​

错误响应​

代码示例​

cURL（JWT）​

Python​

描述