跳到主要内容

基本信息

REST 基本信息​

  • 本文档中引用的 REST Base URL：https://api-sepolia.p99.world/api/v1（测试网）。
  • 所有接口响应均为 JSON 格式。
  • 所有时间与时间戳均为 UNIX 时间。现货接口使用秒为单位，除非明确标注为毫秒（公开成交 WebSocket 推送及 GET /spot/trades 的 ts 字段为毫秒级精度——这是现货 API 中仅有的毫秒级时间戳）。
  • 所有数值类型的金额（价格、余额、数量）均以字符串形式返回，以保留精度。

鉴权​

/spot/* 和 /admin/spot/* 接口均受项目统一鉴权中间件保护，支持以下三种鉴权方式：

鉴权方式请求头适用场景
Bearer JWTAuthorization: Bearer <JWT>所有 /spot/* 接口（读写均可）。
API Key (HMAC-SHA256)X-MBX-APIKEY: <api_key> + ?timestamp=<ms>&signature=<hex>所有 /spot/* 接口，除 POST /spot/transfer 和 POST /spot/withdraw/request（这两个接口拒绝 API Key 调用，返回 403 API Key permission denied）。
Admin API KeyX-API-Key: <ADMIN_API_KEY>所有 /admin/spot/* 接口。

GET /wallet/tokens 为公开接口（无需鉴权）。所有 GET /spot/* 行情接口（/spot/markets、/spot/depth、/spot/trades、/spot/klines、/spot/ticker/24hr、/spot/health）同样为公开接口。

HMAC 签名​

HMAC 鉴权方案与 Binance 兼容：

payload    = query_string_without_signature + body_string
signature  = hex( HMAC_SHA256(secret_key, payload) )
final_url  = ${BASE}${PATH}?<query>&timestamp=<ms>&signature=<hex>
  • timestamp 以毫秒为单位，必须在服务器时间 ±5000 ms 范围内。
  • 对于 GET / DELETE：参数放在 query string 中，body 为空。
  • 对于 POST：timestamp 放在 query string 中，参数放在 JSON body 中。签名的 payload 为 timestamp=<ms> 与原始 JSON body 字节的拼接。

关于如何申请用户 API Key，请参见 POST /api-keys（使用永续合约侧接口；返回的 Key 同样适用于现货）。

接口规范​

  • GET / DELETE 接口的参数必须通过 query string 传递。
  • POST 接口的参数通过 JSON body 传递。对于 HMAC 鉴权，timestamp query 参数是唯一放在 query string 中的内容。
  • 对参数顺序无要求。
  • 交易对匹配区分大小写——请使用 DFUSDT，而非 dfusdt。

响应结构​

GET /wallet/tokens 使用项目标准响应结构：

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

其他现货接口成功时直接返回数据（裸对象或数组）。错误响应格式为 {"error": "<STRING_CODE>"} 并附带相应 HTTP 状态码。

HTTP 返回码​

状态码含义
200成功。
400请求校验或撮合引擎预检失败。响应体包含 error 字段，值为字符串错误码（参见错误码）。
401鉴权失败：JWT 缺失 / 无效、HMAC 签名缺失 / 错误，或 timestamp 已过期。
403禁止操作：API Key 调用了仅限 JWT 的接口，或访问了其他用户的资源。
404资源不存在（或因属于其他用户而被隐藏）。
409冲突：市场处于 halted 状态。
410已下架：市场处于 delisted 状态。
503撮合引擎不可用：spot trading disabled、ENGINE_BUSY（mpsc 积压队列已满）或 ENGINE_RESTARTING（恢复中）。为暂时性错误，请使用退避策略重试。
500服务端故障：通常为 DB_ERROR。

频率限制​

  • 当前（MVP 阶段）未对单用户请求权重进行限制。建议每个用户在所有 /spot/* 接口上的请求频率控制在约 50 req/s。
  • 撮合引擎内部有 mpsc 积压队列；若队列已满，下单 / 撤单 / 状态查询将返回 503 ENGINE_BUSY。请使用指数退避策略重试（200 ms → 400 ms → 800 ms，最多 5 次）。

文档规范说明​

  • 每个接口页面均列出：HTTP 方法 + 路径、鉴权方式、请求参数（含类型及是否必填）、响应示例以及 cURL + Python 代码片段。
  • 参数类型：STRING、NUMBER、DECIMAL（以字符串编码以保留精度）、BOOL、LONG（UNIX 时间戳）。
  • 示例中的订单金额基于测试网 DFUSDT 市场（tick_size=0.0001、lot_size=0.01、min_notional=1）。