New Order

Description

Place a new spot order. Inline fills array reports any matches that occurred during this request (Binance-style).

HTTP Request

POST /spot/orders (JWT or API Key)

Weight

0 — order endpoints are not subject to per-IP weight limits. A per-engine mpsc backlog is enforced; on overflow the response is 503 ENGINE_BUSY.

Request Parameters

Name	Type	Required	Description
symbol	STRING	YES	Market id from GET /spot/markets (e.g. DFUSDT). Case-sensitive.
side	ENUM	YES	buy or sell (lowercase). See Enums.
type	ENUM	YES	limit or market (lowercase).
tif	ENUM	NO	gtc / ioc / post_only. Defaults: gtc for limit, ioc for market.
price	DECIMAL	limit only	Limit price as a string. Must be a positive multiple of the market's tick_size.
quantity	DECIMAL	limit + market sell	Base amount as a string. Must be a positive multiple of the market's lot_size.
quote_quantity	DECIMAL	market buy only	Quote (USDT) amount to spend. Use this instead of quantity for market buys.

Market BUY contract (quote_quantity)

Market buys lock the quote token (USDT) up front. You specify how much you're willing to spend (quote_quantity); the engine walks asks ascending, filling base in lot_size increments until the lock is exhausted. Any unspent quote is refunded after matching.

Market sells use quantity (base / DF) — same as limit sell.

Self-trade prevention

If your incoming order would cross your own resting order, the new order is rejected with SELF_TRADE (DECLINE_TAKER policy). Existing resting orders are untouched.

Filter rules

• price must be > 0 and a multiple of tick_size → otherwise INVALID_TICK.
• quantity must be > 0 and a multiple of lot_size → otherwise INVALID_LOT.
• price * quantity >= min_notional → otherwise BELOW_MIN_NOTIONAL.
• The required lock (quantity of base for SELL; price * quantity of quote for limit BUY; quote_quantity for market BUY) must be <= caller's available balance → otherwise INSUFFICIENT_BALANCE.

Response Example

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"
    }
  ]
}

Field	Notes
id	Server-generated UUID for this order. Use it for cancel / query.
status	See Order Status. Terminal states: filled / canceled / rejected.
filled_qty, avg_fill_price	Reflect any fills that happened in this request.
quote_quantity	Set only for market BUY (mirrors the request); null otherwise.
fills[].fee_token	The token the caller received (BUY → base, SELL → quote). MVP fees are 0; field populated for forward compatibility.
created_at, updated_at	Unix seconds.

Error Responses

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

Full list: Error Codes.

Code Examples

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"])