Create limit order

Place a spot limit order to buy or sell at a specified price via the WhiteBIT V4 API.

POST /api/v4/order/new

Create Limit Order

cURL

curl --request POST \
  --url https://whitebit.com/api/v4/order/new \
  --header 'Content-Type: application/json' \
  --header 'X-TXC-APIKEY: <api-key>' \
  --header 'X-TXC-PAYLOAD: <api-key>' \
  --header 'X-TXC-SIGNATURE: <api-key>' \
  --data '
{
  "market": "BTC_USDT",
  "side": "buy",
  "amount": "0.001",
  "price": "9800",
  "request": "{{request}}",
  "nonce": "{{nonce}}",
  "client_order_id": "order1987111",
  "postOnly": false,
  "ioc": false,
  "bboRole": 1,
  "stp": "no",
  "rpi": true
}
'

200

{
  "order_id": 4180284841,
  "client_order_id": "order1987111",
  "market": "BTC_USDT",
  "side": "buy",
  "type": "limit",
  "timestamp": 1595792396.165973,
  "deal_money": "0",
  "deal_stock": "0",
  "amount": "0.01",
  "left": "0.001",
  "deal_fee": "0",
  "price": "40000",
  "postOnly": false,
  "ioc": false,
  "status": "FILLED",
  "stp": "no",
  "positionSide": "LONG",
  "rpi": true,
  "reduceOnly": false,
  "activated": 0,
  "activationCondition": "lte",
  "activation_price": "40000"
}

Authorizations

X-TXC-APIKEY · string · header · required

The public WhiteBIT API key.

X-TXC-PAYLOAD · string · header · required

Base64-encoded JSON request body.

X-TXC-SIGNATURE · string · header · required

HMAC-SHA512 signature of the payload, hex-encoded. Computed as hex(HMAC-SHA512(payload, api_secret)).

Body

application/json

market · string · required

Trading pair. Format: BASE_QUOTE (e.g., BTC_USDT). Query GET /api/v4/public/markets for available markets.

Example:

"BTC_USDT"

side · enum<string> · required

Order side. Allowed values: buy, sell.

Available options: buy, sell

Example:

"buy"

amount · string · required

Order quantity in base (stock) currency. Minimum and maximum values are market-dependent. Query GET /api/v4/public/markets for minAmount, minTotal, maxTotal. Precision: stockPrec.

Example:

"0.001"

price · string · required

Limit price per unit in quote (money) currency. Minimum and maximum values are market-dependent. Precision: moneyPrec.

Example:

"9800"

request · string · required

Example:

"{{request}}"

nonce · string · required

Example:

"{{nonce}}"

client_order_id · string

Custom client order identifier. The identifier must be unique per account and contain only letters, numbers, dashes, dots, or underscores.

Example:

"order1987111"

postOnly · boolean · default: false

Post-only flag. When true, the order executes only as a maker order and the system rejects the order if it would match immediately. Default: false.

Example:

false

ioc · boolean · default: false

Immediate-or-cancel (IOC) flag. When true, the matching engine executes all or part of the order immediately and cancels any unfilled portion. Default: false.

IOC does not support rpi=true because RPI uses post-only behavior by design. The API returns error code 37 when a request sets both ioc=true and rpi=true.

Refer to Order Parameter Rules for unsupported parameter combinations.

Example:

false

bboRole · enum<integer>

Best Bid/Offer (BBO) execution method. The system selects the best market price for execution. 1 = Queue method, 2 = Counterparty method. Use method 2 with the ioc flag.

Available options: 1, 2

stp · enum<string> · default: no

Self-trade prevention mode. Allowed values: no, cancel_both, cancel_new, cancel_old. Default: no.

Available options: no, cancel_both, cancel_new, cancel_old

Example:

"no"

rpi · boolean · default: false

Enables Retail Price Improvement (RPI) mode. Default: false.

RPI orders use post-only behavior by design. An RPI order does not support ioc=true. The API returns error code 37 when a request sets both rpi=true and ioc=true. RPI orders do not appear in public order book feeds (depth, bookTicker). RPI orders are visible only in private active orders and in the exchange UI order book (web/mobile). RPI executions may apply custom fees or rebates, especially when trading via sub-accounts. Use Query Market Fee / Query All Market Fees to verify effective fees.

Refer to Order Parameter Rules for unsupported parameter combinations.

Example:

true

Response

200

application/json

Order created successfully

order_id · integer

Unique identifier assigned to the order by the matching engine.

Example:

4180284841

client_order_id · string

Custom client order identifier supplied in the request. Returns an empty string when not specified.

Example:

"order1987111"

market · string

Trading pair for the order. Format: BASE_QUOTE (e.g., BTC_USDT).

Example:

"BTC_USDT"

side · string

Order side. Possible values: buy, sell.

Example:

"buy"

type · string

Order type. Possible values: limit, market, stock market, stop limit, stop market.

Example:

"limit"

timestamp · number

Unix timestamp in seconds (UTC) of order creation, with microsecond precision.

Example:

1595792396.165973

deal_money · string

Filled amount in quote currency. Returns "0" while the order remains unfilled.

Example:

"0"

deal_stock · string

Filled amount in base currency. Returns "0" while the order remains unfilled.

Example:

"0"

amount · string

Order quantity in base currency for limit and stop-limit orders, or in quote currency for buy market orders.

Example:

"0.01"

left · string

Remaining unfilled quantity. Equals amount for new orders and "0" for fully filled orders.

Example:

"0.001"

deal_fee · string

Cumulative trading fee charged for filled portions, denominated in the fee asset.

Example:

"0"

price · string

Limit price per unit in quote currency. Returns "0" for market orders.

Example:

"40000"

postOnly · boolean

Post-only flag. When true, the order executes only as a maker order and is rejected if it would match immediately. Default: false.

Example:

false

ioc · boolean

Immediate-or-cancel flag. When true, the order executes available quantity immediately and cancels the unfilled remainder. Default: false.

Example:

false

status · string

Order lifecycle status. NEW — accepted, not yet matched. FILLED — fully executed. CANCELED — canceled before execution. PARTIAL_FILLED — partially executed, remainder still active. PARTIAL_CANCELED — partially filled, remainder canceled. CANCELED_TAKER_BAND — partially filled up to the taker band limit, remainder canceled to protect against excessive order book slippage. AUTO_CANCELED_REDUCE_ONLY — pending reduce-only order auto-canceled because the associated position was closed.

Example:

"FILLED"

stp · string

Self-trade prevention mode. Possible values: no, cancel_both, cancel_new, cancel_old. Default: no.

Example:

"no"

positionSide · string

Position side (for collateral orders)

Example:

"LONG"

rpi · boolean

Indicates Retail Price Improvement (RPI) mode for the order.

Example:

true

reduceOnly · boolean

Reduce-only flag. When true, the order can only reduce or close an existing position. See reduce-only.

Example:

false

activated · integer

Activation status of the stop order. 0 = not yet triggered (waiting for the activation_price condition to be met). 1 = triggered (the stop condition has been met and the order is now active).

Example:

0

activationCondition · enum<string>

Condition that triggers the stop order. "lte" = activate when the market price falls to or below activation_price. "gte" = activate when the market price rises to or above activation_price.

Available options: lte, gte

Example:

"lte"

activation_price · string

The trigger price for the stop order. Always equals the activation_price value submitted in the request.

Example:

"40000"