New Order

Description

Create and submit a new order.

HTTP Request

POST /fapi/v1/order (HMAC SHA256)

Weight

0 (The order endpoint does not consume general weight, but is subject to order rate limits)

Request Parameters

Name	Type	Required	Description
symbol	STRING	YES	Trading pair
side	ENUM	YES	Order side: BUY, SELL
positionSide	ENUM	NO	Position side: BOTH, LONG, SHORT (only BOTH is currently supported — Primit is one-way mode only)
type	ENUM	YES	Order type: LIMIT, MARKET, STOP, TAKE_PROFIT, STOP_MARKET, TAKE_PROFIT_MARKET, TRAILING_STOP_MARKET. STOP_LIMIT and TAKE_PROFIT_LIMIT are accepted as aliases for STOP and TAKE_PROFIT.
reduceOnly	BOOL or STRING	NO	true / false / "true" / "false". Reduce-only orders are clamped to the opposite-side position size at admission and rejected if they would open or flip a position. reduceOnly=true orders bypass the MIN_NOTIONAL filter so a sub-10 USD residual position can still be closed; LOT_SIZE and MAX_NOTIONAL still apply.
quantity	DECIMAL	NO	Order quantity (base-asset units). Floored to the symbol's lot size; the resulting notional must satisfy the symbol's min/max bounds, otherwise -1013. The error message starts with Filter failure: <FILTER>. where <FILTER> is one of LOT_SIZE, MIN_NOTIONAL, or MAX_NOTIONAL — clients can switch on the filter type. Mutually exclusive with quoteOrderQty.
quoteOrderQty	DECIMAL	NO	Order size denominated in USDT (the quote asset). Server converts to quantity using a per-type reference price and floors to lot size; see USDT-denominated ordering below. Mutually exclusive with quantity.
price	DECIMAL	NO	Order price
newClientOrderId	STRING	NO	User-defined order ID. Persisted; round-tripped on query-order / all-orders.
stopPrice	DECIMAL	NO	Stop / trigger price. Trigger orders whose condition is already satisfied at submission are rejected with -2021.
activationPrice	DECIMAL	NO	Activation price (trailing stop orders only)
callbackRate	DECIMAL	NO	Callback rate (trailing stop orders only)
timeInForce	ENUM	NO	Time in force: GTC, IOC, FOK, GTX. GTX is post-only — a crossing GTX order is rejected with -2010. IOC / FOK semantics are strictly enforced at the engine level.
workingType	ENUM	NO	Working type: MARK_PRICE, CONTRACT_PRICE
recvWindow	LONG	NO	See Endpoint Security Type
timestamp	LONG	YES	Timestamp

USDT-denominated ordering (quoteOrderQty)

quoteOrderQty lets you size an order in USDT instead of base-asset units. Server picks a reference price by order type, divides quoteOrderQty by it, then floors to the symbol's lot_size to derive the quantity that the engine sees. Mutually exclusive with quantity — set exactly one, never both.

Order type	Reference price	Required field besides quoteOrderQty
MARKET	Current mark price (price feed)	—
LIMIT / STOP (= STOP_LIMIT) / TAKE_PROFIT (= TAKE_PROFIT_LIMIT)	price	price
STOP_MARKET / TAKE_PROFIT_MARKET	stopPrice (estimate; trigger fills at market with slippage)	stopPrice

Conversion: quantity = floor(quoteOrderQty / ref_price / lot_size) × lot_size. Because flooring rounds toward zero, the actual spend is bounded by quoteOrderQty (modulo a residual smaller than one lot × ref_price). For MARKET / trigger-MARKET orders the realised notional may differ from quoteOrderQty due to slippage at the fill — if you need a strict upper bound use quantity directly.

Errors specific to this path:

Code	Message prefix	Cause
-1106	Parameter 'quantity' and 'quoteOrderQty' are mutually exclusive.	Both set on the same request.
-1102	Mandatory parameter 'price' was not sent;	LIMIT-style + quoteOrderQty without price.
-1102	Mandatory parameter 'stopPrice' was not sent;	STOP_MARKET / TAKE_PROFIT_MARKET + quoteOrderQty without stopPrice.
-2010	Reference price unavailable for <symbol>	Mark price feed returned ≤ 0 (MARKET only — the limit and stop paths can't reach this since price / stopPrice are already validated > 0).
-1013	Filter failure: LOT_SIZE. quoteOrderQty <q> at ref price <r> converts below the minimum lot size <l>	quoteOrderQty / ref_price floors to zero.

Note: this is a Primit extension. Binance Futures (fapi) does not support quoteOrderQty; Binance Spot only supports it for MARKET. Primit accepts it for every order type listed above so desks that book in USDT don't need to convert client-side.

Deprecated

Submitting TRAILING_STOP_MARKET via POST /fapi/v1/order silently drops activationPrice and callbackRate and is not equivalent to the Binance behaviour. Use POST /fapi/v1/algoOrder for any trailing-stop / conditional order placement.

Attaching take-profit / stop-loss to a market entry

To open a position with TP and/or SL, place the market entry first, then submit one or two reduce-only trigger orders sitting on the opposite side at the desired trigger price:

Order	type	side	stopPrice	reduceOnly
Entry	MARKET	your direction (BUY / SELL)	—	false
Take-profit	TAKE_PROFIT_MARKET	opposite of entry	TP trigger price	true
Stop-loss	STOP_MARKET	opposite of entry	SL trigger price	true

The trigger orders execute as MARKET when their stopPrice is hit against the configured workingType (MARK_PRICE or CONTRACT_PRICE). Cancel them explicitly via DELETE /fapi/v1/order if you close the position by other means — they are not chained to the entry.

Response Example

{
    "clientOrderId": "testOrder1",
    "cumQty": "0",
    "cumQuote": "0",
    "executedQty": "0",
    "orderId": 2254222045,
    "avgPrice": "0.00000",
    "origQty": "10",
    "price": "0",
    "reduceOnly": false,
    "side": "SELL",
    "positionSide": "BOTH",
    "status": "NEW",
    "stopPrice": "0",
    "closePosition": false,
    "symbol": "BTCUSDT",
    "timeInForce": "GTC",
    "type": "TRAILING_STOP_MARKET",
    "origType": "TRAILING_STOP_MARKET",
    "activatePrice": "9020",
    "priceRate": "0.3",
    "updateTime": 1566818724722,
    "workingType": "CONTRACT_PRICE",
    "priceProtect": false            
}

Code Examples

cURL

API_KEY="your_api_key"
API_SECRET="your_api_secret"

# Order params go in the JSON body, not the URL.
BODY='{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"0.01","price":"60000"}'

# Auth params (timestamp, recvWindow) stay in the URL.
# `date +%s%3N` is GNU-only; this works on macOS too.
TIMESTAMP=$(python3 -c 'import time; print(int(time.time()*1000))')
QUERY="timestamp=${TIMESTAMP}&recvWindow=5000"

# Signature is HMAC-SHA256 over the query string (without `signature`)
# concatenated directly with the raw body — no separator. `sed` strips the
# `(stdin)= ` prefix that older OpenSSL emits; newer OpenSSL/LibreSSL emits
# just the hex, which sed leaves unchanged.
SIGNATURE=$(printf '%s' "${QUERY}${BODY}" \
  | openssl dgst -sha256 -hmac "${API_SECRET}" \
  | sed 's/^.*= //')

curl -s -X POST \
  -H "X-MBX-APIKEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${BODY}" \
  "https://api-sepolia.primit.io/fapi/v1/order?${QUERY}&signature=${SIGNATURE}"

Python

import time, hmac, hashlib, requests, json

API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
BASE_URL = "https://api.primit.io"

def sign(msg: str) -> str:
    return hmac.new(API_SECRET.encode(), msg.encode(), hashlib.sha256).hexdigest()

def signed_post(path, body={}):
    ts = int(time.time() * 1000)
    qs = f"timestamp={ts}"
    body_str = json.dumps(body, separators=(',', ':'))
    sig = sign(qs + body_str)
    return requests.post(
        f"{BASE_URL}{path}?timestamp={ts}&signature={sig}",
        data=body_str,
        headers={"X-MBX-APIKEY": API_KEY, "Content-Type": "application/json"},
    )

# Place a LIMIT BUY order for BTCUSDT
resp = signed_post("/fapi/v1/order", body={
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01",
    "price": "60000",
})
print(resp.json())

# Same intent but sized in USDT — server divides 500 / 60000 / lot_size,
# floors to lot, and uses the resulting quantity. The actual spend stays
# at-or-below 500 USDT modulo the lot residual.
resp = signed_post("/fapi/v1/order", body={
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quoteOrderQty": "500",
    "price": "60000",
})
print(resp.json())