> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bulk limit order
> Place multiple spot limit orders in a single request via the WhiteBIT V4 API.
* [Create limit order](/api-reference/spot-trading/create-limit-order) — place a single limit order
* [Cancel bulk orders](/api-reference/spot-trading/cancel-bulk-order) — sibling bulk endpoint for cancelling up to 100 orders
* [Query unexecuted orders](/api-reference/spot-trading/query-unexecuted-orders) — list open orders
* [Cancel all orders](/api-reference/spot-trading/cancel-all-orders) — cancel all open orders
## OpenAPI
````yaml /openapi/private/http-trade-v4.yaml POST /api/v4/order/bulk
openapi: 3.0.3
info:
title: Private HTTP API V4 - Collateral Trading
description: |
WhiteBIT Private HTTP API V4 for collateral/margin trading operations.
Base URL: https://whitebit.com
All endpoints return time in Unix-time format.
All endpoints return either a JSON object or array.
For receiving responses from API calls please use http method POST.
Authentication required for all endpoints.
version: 4.0.0
license:
name: WhiteBIT Terms of Service
url: https://whitebit.com/terms
servers:
- url: https://whitebit.com
description: WhiteBIT Global Server
- url: https://whitebit.eu
description: WhiteBIT EU Server
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
tags:
- name: Collateral Trading
description: Endpoints for collateral/margin trading operations
- name: Spot Trading
description: Endpoints for spot trading operations
- name: Market Fee
description: Endpoints for querying trading fees
paths:
/api/v4/order/bulk:
post:
tags:
- Spot Trading
summary: Bulk limit order
description: >
The endpoint creates bulk [limit trading orders](/glossary#limit-order).
Each order in the batch follows the same validation rules as a single
limit order. The `stopOnFail` parameter controls whether processing
stops at the first failure or continues through all orders. The response
contains a result-or-error pair for each submitted order.
Limit: From 1 to 20 orders per request.
- 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 orders are post-only by design and cannot be used with the IOC flag. The API returns error code `40` when both `rpi=true` and `ioc=true` are used.
- `retail=true` marks the order as a retail-source taker eligible to match RPI-maker liquidity. The Retail flag must be enabled on the account; contact the account manager to enable it.
- `retail=true` and `rpi=true` cannot be combined. The API returns error code `41` when both flags are set on an item.
- `retail=true` has no effect on a `postOnly=true` item. Post-only orders are makers and cannot be retail takers.
- `30` - default validation error code
- `31` - market validation failed
- `32` - amount validation failed
- `33` - price validation failed
- `36` - clientOrderId validation failed
- `37` - `ioc=true` cannot be combined with `postOnly=true`
- `40` - `ioc=true` cannot be combined with `rpi=true`
- `41` - `retail=true` cannot be combined with `rpi=true`
- `42` - `retail=true` is not allowed for the account
- `43` - `rpi=true` is not allowed for the account
```json
{
"code": 30,
"message": "Validation failed",
"errors": {
"orders": ["The orders must be an array."]
}
}
```
Individual order errors (in multiply response):
```json
{
"code": 30,
"message": "Validation failed",
"errors": {
"amount": ["Amount field is required."],
"market": ["Market field is required."],
"price": ["Price field is required."],
"side": ["Side field is required."]
}
}
```
```json
{
"code": 30,
"message": "Validation failed",
"errors": {
"side": ["Side field should contain only 'buy' or 'sell' values."]
}
}
```
```json
{
"code": 32,
"message": "Validation failed",
"errors": {
"amount": ["Amount field should be numeric string or number."]
}
}
```
```json
{
"code": 33,
"message": "Validation failed",
"errors": {
"price": ["Price field should be numeric string or number."]
}
}
```
```json
{
"code": 41,
"message": "Validation failed",
"errors": {
"retail": ["api.tradeErrors.flagsCantBeCombined.rpiRetail"]
}
}
```
```json
{
"code": 42,
"message": "Validation failed",
"errors": {
"retail": ["api.validation.retail.not_allowed"]
}
}
```
operationId: createBulkLimitOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
orders:
type: array
description: Array of limit orders
items:
$ref: '#/components/schemas/BulkOrderItem'
stopOnFail:
type: boolean
default: false
description: >
Controls how the bulk order processor handles failures.
When true: Processing stops at the first order that fails
validation or execution. Only orders up to (but not
including) the failed order are processed.
When false (default): All orders in the bulk request are
processed regardless of individual failures. Each order
result is returned in the response array.
example: true
request:
type: string
example: '{{request}}'
nonce:
type: integer
example: 1594297865000
example:
orders:
- side: buy
amount: '0.02'
price: '40000'
market: BTC_USDT
postOnly: false
ioc: false
clientOrderId: ''
rpi: true
retail: false
- side: sell
amount: '0.0001'
price: '41000'
market: BTC_USDT
postOnly: false
ioc: false
clientOrderId: ''
rpi: false
retail: true
- side: sell
amount: '0.02'
price: '41000'
market: BTC_USDT
postOnly: false
ioc: false
clientOrderId: ''
rpi: false
retail: false
responses:
'200':
$ref: '#/components/responses/BulkLimitOrderResponse'
'400':
description: Inner validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service temporarily unavailable
security:
- ApiKeyAuth: []
PayloadAuth: []
SignatureAuth: []
components:
schemas:
BulkOrderItem:
type: object
properties:
side:
type: string
enum:
- buy
- sell
description: 'Order side. Allowed values: `buy`, `sell`.'
example: buy
amount:
type: string
description: >-
Order quantity in base (stock) currency. Minimum and maximum values
are market-dependent. Query `GET /api/v4/public/markets` for
`minAmount` and precision (`stockPrec`).
example: '0.001'
price:
type: string
description: >-
Limit price per unit in quote (money) currency. Minimum and maximum
values are market-dependent. Query `GET /api/v4/public/markets` for
precision (`moneyPrec`).
example: '40000'
market:
type: string
description: 'Trading pair for the order. Format: `BASE_QUOTE` (e.g., `BTC_USDT`).'
example: BTC_USDT
postOnly:
type: boolean
default: false
description: >-
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:
type: boolean
default: false
description: >
Immediate-or-cancel (IOC) executes all or part of an 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 `40` when an order item sets both
`ioc=true` and `rpi=true`.
example: false
clientOrderId:
type: string
description: >-
Custom client order identifier. Uniqueness is enforced only among
the account's open (pending) orders on the same market — once a
previous order is filled or canceled, the same identifier can be
reused, including on the same market. Contains only letters,
numbers, dashes, dots, or underscores.
example: ''
rpi:
type: boolean
default: false
description: >
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 `40` when an order item sets both
`rpi=true` and `ioc=true`.
example: true
retail:
type: boolean
default: false
description: >
Retail-source taker flag for the bulk-order item. When `true`, the
item is eligible to match against orders submitted by RPI makers and
may receive price improvement at execution. Default: `false`.
The Retail flag must be enabled on the account before a private-API
request can set `retail=true`. Contact the account manager to enable
the Retail flag.
The Retail flag cannot be combined with `rpi`. The API returns error
code `41` when an item sets both `retail=true` and `rpi=true`.
The flag has no effect on a `postOnly=true` item. Post-only orders
are [makers](/glossary#maker); only takers carry the retail
designation.
Refer to [Retail flag](/glossary#retail-flag) and [Order Parameter
Rules](/guides/order-parameter-rules) for unsupported parameter
combinations.
example: false
ErrorResponse:
type: object
properties:
code:
type: integer
description: Error code
example: 30
message:
type: string
description: Error message
example: Validation failed
errors:
type: object
additionalProperties:
type: array
items:
type: string
description: Detailed error information
BulkLimitOrderResponse:
type: array
items:
type: object
properties:
result:
type: object
allOf:
- $ref: '#/components/schemas/OrderResponse'
nullable: true
error:
type: object
allOf:
- $ref: '#/components/schemas/ErrorResponse'
nullable: true
OrderResponse:
type: object
properties:
orderId:
type: integer
description: Unique identifier assigned to the order by the matching engine.
example: 4180284841
clientOrderId:
type: string
description: >-
Custom client order identifier supplied in the request. Returns an
empty string when not specified.
example: order1987111
market:
type: string
description: 'Trading pair for the order. Format: `BASE_QUOTE` (e.g., `BTC_USDT`).'
example: BTC_USDT
side:
type: string
description: 'Order side. Possible values: `buy`, `sell`.'
example: buy
type:
type: string
description: >-
Order type. Possible values: `limit`, `market`, `stock market`,
`stop limit`, `stop market`.
example: limit
timestamp:
type: number
description: >-
Unix timestamp in seconds (UTC) of order creation, with microsecond
precision.
example: 1595792396.165973
dealMoney:
type: string
description: >-
Filled amount in quote currency. Returns `"0"` while the order
remains unfilled.
example: '0'
dealStock:
type: string
description: >-
Filled amount in base currency. Returns `"0"` while the order
remains unfilled.
example: '0'
amount:
type: string
description: >-
Order quantity in base currency for limit and stop-limit orders, or
in quote currency for buy market orders.
example: '0.01'
left:
type: string
description: >-
Remaining unfilled quantity. Equals `amount` for new orders and
`"0"` for fully filled orders.
example: '0.001'
dealFee:
type: string
description: >-
Cumulative trading fee charged for filled portions, denominated in
the fee asset.
example: '0'
price:
type: string
description: >-
Limit price per unit in quote currency. Returns `"0"` for market
orders.
example: '40000'
postOnly:
type: boolean
description: >-
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:
type: boolean
description: >-
Immediate-or-cancel flag. When `true`, the order executes available
quantity immediately and cancels the unfilled remainder. Default:
`false`.
example: false
status:
$ref: '#/components/schemas/OrderStatus'
stp:
type: string
description: >-
Self-trade prevention mode. Possible values: `no`, `cancel_both`,
`cancel_new`, `cancel_old`. Default: `no`.
example: 'no'
positionSide:
type: string
description: Position side (for collateral orders)
example: LONG
rpi:
type: boolean
description: Indicates Retail Price Improvement (RPI) mode for the order.
example: true
retail:
type: boolean
description: >-
Retail-source taker flag. The field is present only when the order
was placed with `retail=true`. See [Retail
flag](/glossary#retail-flag).
example: true
reduceOnly:
type: boolean
description: >-
Reduce-only flag. When `true`, the order can only reduce or close an
existing position. See [reduce-only](/glossary#reduce-only).
example: false
activated:
type: integer
description: >-
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:
type: string
enum:
- lte
- gte
description: >
Trigger condition for the stop order. Response-only — not accepted
in the request body, and cannot be overridden. Derived from `side`:
- `side = buy` → `gte`. The order activates when the market price
rises to or above `activation_price`.
- `side = sell` → `lte`. The order activates when the market price
falls to or below `activation_price`.
example: lte
activation_price:
type: string
description: >-
The trigger price for the stop order. Always equals the
activation_price value submitted in the request.
example: '40000'
OrderStatus:
type: string
description: >-
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. `AUTO_CANCELED_LIQUIDATION` — pending order auto-canceled
because the associated position was force-liquidated. `CANCELED_STP` —
order canceled by [Self-Trade
Prevention](/platform/self-trade-prevention).
example: FILLED
responses:
BulkLimitOrderResponse:
description: Orders created
content:
application/json:
schema:
$ref: '#/components/schemas/BulkLimitOrderResponse'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-TXC-APIKEY
description: The public WhiteBIT API key.
PayloadAuth:
type: apiKey
in: header
name: X-TXC-PAYLOAD
description: Base64-encoded JSON request body.
SignatureAuth:
type: apiKey
in: header
name: X-TXC-SIGNATURE
description: >-
HMAC-SHA512 signature of the payload, hex-encoded. Computed as
hex(HMAC-SHA512(payload, api_secret)).
````