基本信息

REST 基本信息

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

鉴权

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

鉴权方式	请求头	适用场景
Bearer JWT	Authorization: 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: transfers not allowed / 403 API Key permission denied: withdraws not allowed）。
Admin API Key	X-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 以毫秒为单位，必须在服务器时间 ±60000 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，或 — 仅 POST /spot/orders 与 GET /spot/depth — ENGINE_BUSY（mpsc 积压队列已满）/ ENGINE_RESTARTING（恢复中）。为暂时性错误，请使用退避策略重试。
500	服务端故障：交易类接口为 DB_ERROR，钱包侧接口为 internal error / internal。DELETE /spot/orders/:id 上的引擎队列溢出同样表现为 500 DB_ERROR。

频率限制

• 当前（MVP 阶段）未对单用户请求权重进行限制。建议每个用户在所有 /spot/* 接口上的请求频率控制在约 50 req/s。
• 撮合引擎内部有 mpsc 积压队列；若队列已满，POST /spot/orders 将返回 503 ENGINE_BUSY——请使用指数退避策略重试（200 ms → 400 ms → 800 ms，最多 5 次）。单笔撤单遇到同样的溢出会映射为 500 DB_ERROR；全部撤单则返回 200 且 canceled 数组为空（与没有挂单的情形无法区分）。

文档规范说明

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