新建订单

描述

下一笔新的现货订单。请求响应内联 fills 数组，报告本次请求中发生的所有撮合（Binance 风格）。

HTTP 请求

POST /spot/orders（JWT 或 API Key）

权重

0——订单接口不受按 IP 权重限制约束。撮合引擎内部设有 mpsc 积压队列；若队列溢出，响应为 503 ENGINE_BUSY。

请求参数

名称	类型	必填	描述
symbol	STRING	是	市场 id，来自 GET /spot/markets（例如 DFUSDT）。区分大小写。
side	ENUM	是	buy 或 sell（小写）。参见枚举定义。
type	ENUM	是	limit 或 market（小写）。
tif	ENUM	可选	gtc / ioc / post_only。默认值：limit 订单为 gtc，market 订单为 ioc。
price	DECIMAL	仅限价单必填	限价，以字符串形式传入。必须为正数且是市场 tick_size 的整数倍。
quantity	DECIMAL	限价单及市价卖单必填	基础资产数量，以字符串形式传入。必须为正数且是市场 lot_size 的整数倍。
quote_quantity	DECIMAL	仅市价买单必填	愿意花费的报价资产（USDT）金额。市价买单请使用此参数代替 quantity。

市价买单规则（quote_quantity）

市价买单预先锁定报价资产（USDT）。您指定愿意花费的金额（quote_quantity）；撮合引擎按卖方报价从低到高依次撮合，以 lot_size 为单位买入基础资产，直至锁定金额耗尽。撮合完成后，任何剩余的报价资产将被退还。

市价卖单使用 quantity（基础资产 / DF 数量），与限价卖单一致。

自成交防护

若您的新订单将与自身挂单发生撮合，该新订单将被拒绝，并返回 SELF_TRADE（DECLINE_TAKER 策略）。已有挂单保持不变。

过滤规则

• price 必须 > 0 且为 tick_size 的整数倍，否则返回 INVALID_TICK。
• quantity 必须 > 0 且为 lot_size 的整数倍，否则返回 INVALID_LOT。
• price * quantity >= min_notional，否则返回 BELOW_MIN_NOTIONAL。
• 所需锁定金额（卖单锁定 quantity 基础资产；限价买单锁定 price * quantity 报价资产；市价买单锁定 quote_quantity）必须 <= 调用方的可用余额，否则返回 INSUFFICIENT_BALANCE。

响应示例

200 OK

{
  "id":             "9f2a1c4e-5b67-4d8a-bf93-2e1f4a6c8d10",
  "symbol":         "DFUSDT",
  "side":           "buy",
  "type":           "limit",
  "tif":            "gtc",
  "price":          "0.5000",
  "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":  "3e761331-0cec-481c-81be-f62ab572757b",
      "price":     "0.499",
      "quantity":  "30",
      "fee":       "0",
      "fee_token": "DF"
    }
  ]
}

字段	说明
id	服务器生成的订单 UUID。用于撤单 / 查询。
status	参见订单状态。终态：filled / canceled / rejected。
filled_qty, avg_fill_price	反映本次请求中已发生的成交情况。
quote_quantity	仅市价买单时有值（与请求一致）；其他情况为 null。
fills[].fee_token	调用方收到的代币（买入 → 基础资产，卖出 → 报价资产）。MVP 阶段手续费为 0；该字段为兼容未来版本而保留。
created_at, updated_at	UNIX 秒。

错误响应

HTTP	error
400	MARKET_NOT_FOUND, INVALID_TICK, INVALID_LOT, BELOW_MIN_NOTIONAL, INSUFFICIENT_BALANCE, POST_ONLY_REJECT, SELF_TRADE, invalid side / invalid type / invalid tif, quantity required for limit, quantity required for market sell, quote_quantity required for market buy
404	MARKET_NOT_FOUND
409	MARKET_HALTED
410	MARKET_DELISTED
503	spot trading disabled, ENGINE_BUSY, ENGINE_RESTARTING

完整列表：错误码。

代码示例

cURL（JWT）

JWT="your_jwt_token"

curl -s -X POST "https://api-sepolia.p99.world/api/v1/spot/orders" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol":   "DFUSDT",
    "side":     "buy",
    "type":     "limit",
    "tif":      "gtc",
    "price":    "0.5",
    "quantity": "100"
  }'

cURL（HMAC API Key）

API_KEY="your_api_key"
API_SECRET="your_api_secret"
TIMESTAMP=$(date +%s%3N)
BODY='{"symbol":"DFUSDT","side":"buy","type":"limit","tif":"gtc","price":"0.5","quantity":"100"}'
PAYLOAD="timestamp=${TIMESTAMP}${BODY}"
SIGNATURE=$(echo -n "${PAYLOAD}" | openssl dgst -sha256 -hmac "${API_SECRET}" | awk '{print $2}')

curl -s -X POST \
  -H "X-MBX-APIKEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${BODY}" \
  "https://api-sepolia.p99.world/api/v1/spot/orders?timestamp=${TIMESTAMP}&signature=${SIGNATURE}"

Python

import time, hmac, hashlib, json, requests

API_KEY    = "your_api_key"
API_SECRET = "your_api_secret"
BASE_URL   = "https://api-sepolia.p99.world/api/v1"

def signed_post(path: str, body: dict) -> dict:
    ts = int(time.time() * 1000)
    body_str = json.dumps(body, separators=(",", ":"))
    payload  = f"timestamp={ts}{body_str}"
    sig      = hmac.new(API_SECRET.encode(), payload.encode(), hashlib.sha256).hexdigest()
    r = requests.post(
        f"{BASE_URL}{path}?timestamp={ts}&signature={sig}",
        data=body_str,
        headers={"X-MBX-APIKEY": API_KEY, "Content-Type": "application/json"},
        timeout=5,
    )
    r.raise_for_status()
    return r.json()

order = signed_post("/spot/orders", {
    "symbol":   "DFUSDT",
    "side":     "buy",
    "type":     "limit",
    "tif":      "gtc",
    "price":    "0.5",
    "quantity": "100",
})
print(order["id"], order["status"], order["filled_qty"], "/", order["quantity"])