订单

下单、撤单、查询、列表。看自己的成交。

鉴权

本页所有接口都要求 JWT 或 API Key：

Authorization: Bearer <JWT>

或

X-API-Key: <key>

下单

POST /spot/orders

请求体

{
  "symbol":         "DFUSDT",
  "side":           "buy",
  "type":           "limit",
  "tif":            "gtc",
  "price":          "0.5000",
  "quantity":       "100",
  "quote_quantity": null
}

字段	类型	必填	备注
`symbol`	string	是	`GET /spot/markets` 里的 market id
`side`	string	是	`buy` 或 `sell`
`type`	string	是	`limit` 或 `market`
`tif`	string	否	`gtc`（限价默认）/ `ioc` / `post_only`。市价单总是 IOC
`price`	string / number	仅限价	必须是 `tick_size` 的倍数
`quantity`	string / number	限价 + 市价卖	base 数量，必须是 `lot_size` 的倍数
`quote_quantity`	string / number	仅市价买	要花的 quote 数量（USDT）。市价买用这个代替 `quantity`

TIF 语义

`tif`	行为
`gtc`	Good-Til-Canceled。剩余部分留在盘口，直到撤销或全成
`ioc`	Immediate-Or-Cancel。立刻成交能成的部分，剩余撤销。任何剩余意味着 status 变 `canceled`（`filled_qty > 0` 表示部分成交）
`post_only`	仅限价。下单时如果会与对手盘交叉，直接拒绝 `POST_ONLY_REJECT`，不发生任何成交。否则像 GTC 一样挂上

市价 BUY 约定（`quote_quantity`）

市价买预先冻结 quote token（USDT）。你指定愿意花多少（quote_quantity），engine 沿着 ask 升序撮合，每档按 lot_size 取整。锁完后剩余的 quote 退还。

市价卖用 quantity（base / DF），跟限价卖一致。

自成交保护

如果你的新单会跟自己挂着的订单交叉，新单被拒 SELF_TRADE（DECLINE_TAKER 策略）。已挂的订单不动。

响应 — `200 OK`

fills 数组同步返回本次请求中触发的成交（Binance 风格）：

{
  "id":             "9f2a-...-uuid",
  "symbol":         "DFUSDT",
  "side":           "buy",
  "type":           "limit",
  "tif":            "gtc",
  "price":          "0.5",
  "quantity":       "100",
  "quote_quantity": null,
  "filled_qty":     "30",
  "avg_fill_price": "0.499",
  "status":         "partially_filled",
  "reject_reason":  null,
  "created_at":     1778400000,
  "updated_at":     1778400000,
  "fills": [
    { "trade_id": "...", "price": "0.499", "quantity": "30", "fee": "0", "fee_token": "DF" }
  ]
}

fee_token 是调用者收到的 token（BUY → base，SELL → quote）。MVP fee=0，字段保留是为后续兼容。

状态

`status`	含义
`open`	挂在盘口（无成交）
`partially_filled`	挂在盘口且 `filled_qty > 0`
`filled`	完全成交 —— 终态
`canceled`	用户撤单 / IOC 残量 / 市价残量 / 市场 delist —— 终态
`rejected`	engine 接受前校验失败（如自成交）—— 终态
`expired`	（现货 MVP 暂不用此状态）

错误响应

HTTP	`error`	何时
`400`	`MARKET_NOT_FOUND`、`INVALID_TICK`、`INVALID_LOT`、`BELOW_MIN_NOTIONAL`、`INSUFFICIENT_BALANCE`、`POST_ONLY_REJECT`、`SELF_TRADE`、`invalid side/type/tif`、`quote_quantity required for market buy`、`quantity required for limit`/`market sell`	请求校验 / engine 预检
`404`	`MARKET_NOT_FOUND`	symbol 不在 spot_markets
`409`	`MARKET_HALTED`	市场处于 halted
`410`	`MARKET_DELISTED`	市场终态
`503`	`spot trading disabled`（engine 未启动）/ `ENGINE_BUSY`（mpsc 满）/ `ENGINE_RESTARTING`（恢复中）	临时
`500`	`DB_ERROR`	服务端故障

撤一单

DELETE /spot/orders/:id

:id 为订单 UUID。仅当订单 open / partially_filled 且属于调用者时撤销。返回被撤的订单。

响应 — 200 OK

字段同 GET /spot/orders/:id，status = "canceled"。

错误

HTTP	`error`
`400`	`invalid id`（UUID 解析失败）
`403`	`FORBIDDEN`（订单属于其他用户）
`404`	`ORDER_NOT_FOUND`（已终态或不存在）

撤所有

DELETE /spot/orders?symbol=DFUSDT

撤销调用者所有 open / partially_filled 的订单，可选用 symbol 过滤到一个市场。已终态的静默跳过。

响应 — 200 OK

{ "canceled": [ { ...订单... }, { ...订单... } ] }

查单笔

GET /spot/orders/:id

返回调用者拥有的某个订单。不存在或属于他人 → 404 ORDER_NOT_FOUND。

{
  "id": "9f2a-...", "symbol": "DFUSDT", "side": "buy", "type": "limit", "tif": "gtc",
  "price": "0.5", "quantity": "100", "quote_quantity": null,
  "filled_qty": "100", "avg_fill_price": "0.499",
  "status": "filled", "reject_reason": null,
  "created_at": 1778400000, "updated_at": 1778400090
}

列订单

GET /spot/orders

Query 参数

参数	类型	默认	备注
`symbol`	string	(任意)	过滤到某个市场
`status`	string	(任意)	`open` / `partially_filled` / `filled` / `canceled` / `rejected` / `expired`
`start`	number（unix 秒）	(任意)	`created_at >= start`
`end`	number（unix 秒）	(任意)	`created_at <= end`
`limit`	number	`50`	1–200，服务端 clamp

响应 — 200 OK：订单数组，最新优先。

Tip：要看当前还在挂的单，用 GET /spot/orders?status=open（也可叠加 partially_filled）；都是非终态。

我的成交（Fills）

调用者参与过的所有成交（无论 maker 还是 taker）。

GET /spot/trades/me

Query 参数

参数	类型	默认	备注
`symbol`	string	(任意)
`start` / `end`	number（unix 秒）	(任意)
`limit`	number	`50`	1–200

响应 — 200 OK

[
  {
    "trade_id":  "...",
    "symbol":    "DFUSDT",
    "side":      "buy",
    "price":     "0.499",
    "quantity":  "30",
    "fee":       "0",
    "fee_token": "DF",
    "role":      "taker",
    "order_id":  "9f2a-...",
    "ts":        1778400090
  }
]

字段	备注
`side`	调用者在该笔成交里的 side（BUY/SELL），不是全局 taker side
`fee` / `fee_token`	调用者支付的手续费，以收到的 token 计
`role`	`maker` 或 `taker`
`order_id`	调用者参与该笔成交的订单 id
`ts`	Unix 秒

代码示例

端到端：下单 → 等成交 → 列出对应成交。

import requests, time

BASE = "https://api-sepolia.p99.world/api/v1"
JWT  = "your_jwt_token"
H    = {"Authorization": f"Bearer {JWT}", "Content-Type": "application/json"}

# 限价 GTC 买单
order = requests.post(f"{BASE}/spot/orders", headers=H, json={
    "symbol": "DFUSDT", "side": "buy", "type": "limit", "tif": "gtc",
    "price": "0.5", "quantity": "100"
}).json()
print(order["status"], order["filled_qty"], "/", order["quantity"])

# 轮询到终态
oid = order["id"]
while True:
    o = requests.get(f"{BASE}/spot/orders/{oid}", headers=H).json()
    if o["status"] in ("filled", "canceled", "rejected"):
        break
    time.sleep(1)

# 看自己的成交
fills = requests.get(f"{BASE}/spot/trades/me?symbol=DFUSDT&limit=10", headers=H).json()
for f in fills:
    print(f"  {f['role']:5} {f['side']:4} {f['quantity']:>8} @ {f['price']}")

鉴权​

下单​

TIF 语义​

市价 BUY 约定（quote_quantity）​

自成交保护​

响应 — 200 OK​

状态​

错误响应​

撤一单​

撤所有​

查单笔​

列订单​

我的成交（Fills）​

代码示例​

鉴权

下单

TIF 语义

市价 BUY 约定（`quote_quantity`）

自成交保护

响应 — `200 OK`

状态

错误响应

撤一单

撤所有

查单笔

列订单

我的成交（Fills）

代码示例