充值余额

描述

直接向用户的现货余额充入代币。仅限测试网——此接口通过 TESTNET_ONLY=true 环境变量进行硬性限制。在主网（或任何 TESTNET_ONLY 不为 true 的环境）中，该路由将返回 404 DISABLED，以保持接口面一致。

仅管理员。 服务器须设置 ADMIN_API_KEY 环境变量，且请求头中须传入 X-API-Key。

成功执行的副作用：

对 spot_balances 表中的 (user_address, token) 对应的 available 字段执行余额 upsert（若记录不存在则自动创建）。
在 spot_admin_credits 表中写入一条审计记录，admin_actor 为 "admin_api_key"（共享管理员密钥不区分用户，故记录此通用标识）。
通过 WebSocket 推送余额更新，使 UI 无需轮询即可立即反映新余额。

HTTP 请求

POST /admin/spot/balances/credit (X-API-Key: ADMIN_API_KEY)

仅限测试网（服务器须设置 TESTNET_ONLY=true）。

权重

0 — 管理员接口不设权重限制。每次市场变更都会向撮合引擎发送 ReloadMarket 命令，使内存中的 MarketCache 无需重启即可获取最新配置。

请求参数

名称	类型	必填	描述
`user_address`	STRING	必填	收款方的 EVM 钱包地址（如 `"0xabc..."`）。存储和匹配时均转为小写。
`token`	STRING	必填	充值的代币符号（如 `"DF"`、`"USDT"`）。
`amount`	DECIMAL	必填	充值金额，以字符串表示。必须 `> 0`，否则返回 `400 AMOUNT_NON_POSITIVE`。
`reason`	STRING	可选	记录在审计日志中的自由文本说明。不适用时可省略。

响应示例

200 OK

{
  "ok": true
}

字段	说明
`ok`	成功时始终为 `true`。余额已更新且审计记录已提交。

错误响应

HTTP	`error`	触发条件
`400`	`AMOUNT_NON_POSITIVE`	`amount` 小于等于 `0`。
`404`	`DISABLED`	服务器的 `TESTNET_ONLY` 环境变量未设置为 `"true"`（主网防护）。
`500`	`DB_ERROR`	执行余额 upsert 或审计插入时发生意外的 Postgres 错误。请查看服务器日志。

完整列表：错误代码。

代码示例

cURL

ADMIN_API_KEY="your_admin_api_key"

curl -s -X POST "https://api-sepolia.p99.world/api/v1/admin/spot/balances/credit" \
  -H "X-API-Key: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_address": "0xabc123def456abc123def456abc123def456abc1",
    "token":        "DF",
    "amount":       "1000",
    "reason":       "testnet faucet grant"
  }'

Python

import requests

ADMIN_API_KEY = "your_admin_api_key"
BASE_URL      = "https://api-sepolia.p99.world/api/v1"

def credit_balance(user_address: str, token: str, amount: str, reason: str | None = None) -> dict:
    body = {
        "user_address": user_address,
        "token":        token,
        "amount":       amount,
    }
    if reason is not None:
        body["reason"] = reason

    r = requests.post(
        f"{BASE_URL}/admin/spot/balances/credit",
        json=body,
        headers={"X-API-Key": ADMIN_API_KEY, "Content-Type": "application/json"},
        timeout=5,
    )
    r.raise_for_status()
    return r.json()

result = credit_balance(
    user_address="0xabc123def456abc123def456abc123def456abc1",
    token="DF",
    amount="1000",
    reason="testnet faucet grant",
)
print(result["ok"])

描述​

HTTP 请求​

权重​

请求参数​

响应示例​

错误响应​

代码示例​

cURL​

Python​

描述