> ## 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.
# Collateral bulk limit order
> Place multiple collateral limit orders in a single request via the WhiteBIT V4 API.
* [Collateral limit order](/api-reference/collateral-trading/collateral-limit-order) — Place a single collateral limit order
* [Collateral market order](/api-reference/collateral-trading/collateral-market-order) — Place a collateral market order
* [Cancel conditional order](/api-reference/collateral-trading/cancel-conditional-order) — Cancel an active conditional order
* [Open positions](/api-reference/collateral-trading/open-positions) — List current open positions
## OpenAPI
````yaml /openapi/private/http-trade-v4.yaml POST /api/v4/order/collateral/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/collateral/bulk:
post:
tags:
- Collateral Trading
summary: Collateral bulk limit order
description: >
The endpoint creates multiple collateral [limit
orders](/glossary#limit-order) in a single request. Each order in the
`orders` array is validated and processed individually. The `stopOnFail`
parameter controls whether processing stops at the first failure or
continues through all orders. The response array contains a result or
error object for each submitted order, in the same order as the request.
Rate limit: 10000 requests/10 sec.
- `30` - default validation error code (per-order). Also returned when `reduceOnly=true` is combined with `stopLoss` or `takeProfit`
- `31` - market validation failed
- `32` - amount validation failed
- `33` - price validation failed
- `36` - clientOrderId validation failed
- `37` - `ioc=true` cannot be used with `postOnly=true` or `rpi=true`
- `10` - insufficient balance to place the order
- `111` - resulting position would exceed the market maximum
- `112` - pending orders value would exceed the allowed maximum
- `113` - position side cannot be changed while open positions or orders exist
- `114` - hedge mode position side does not match (per-order; sent `BOTH` or omitted `positionSide` in hedge mode, or sent `LONG`/`SHORT` in one-way mode)
- `115` - order would open a position in the opposite direction (one-way mode)
- `116` - reduce-only validation failed (no position exists or order side matches position direction). For bulk orders, this error appears per-order inside the response array.
operationId: createCollateralBulkOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
orders:
type: array
items:
type: object
properties:
market:
type: string
description: >-
Available margin [market](/glossary#market). Example:
BTC_USDT
example: BTC_PERP
side:
type: string
enum:
- buy
- sell
description: 'Order type. Variables: ''buy'' / ''sell''.'
example: buy
amount:
type: string
description: >-
Amount of [stock](/glossary#stock) currency to buy or
sell. Minimum and step values are market-dependent —
query the [market
info](/api-reference/market-data/market-info) endpoint
for constraints.
example: '0.02'
price:
type: string
description: >-
Limit order price in [money](/glossary#money)
currency. Minimum price step is market-dependent.
example: '40000'
clientOrderId:
type: string
description: >-
Identifier must be unique and contain letters,
numbers, dashes, dots, or underscores.
example: ''
stopLoss:
type: string
description: >
Stop loss price.
When provided, the system creates an
[OTO](/glossary#one-triggers-the-other-oto) order with
a stop loss condition.
example: '50000'
takeProfit:
type: string
description: >
Take profit price.
When provided, the system creates an
[OTO](/glossary#one-triggers-the-other-oto) order with
a take profit condition.
example: '30000'
postOnly:
type: boolean
default: false
description: >-
Ensures the order adds liquidity and executes as
maker. 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
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
positionSide:
type: string
enum:
- LONG
- SHORT
- BOTH
description: >
Position direction. Optional at the request layer but
functionally required when hedge mode is enabled. See
[positionSide](/glossary#position-side).
- **One-way mode** (default account mode): the field
is ignored. Orders always use `BOTH`, and the response
returns `positionSide: "BOTH"` whether the field is
sent or omitted.
- **Hedge mode**: the field MUST be `LONG` or `SHORT`.
Sending `BOTH`, omitting the field, or sending a value
that does not match the account's mode causes the
trade service to reject the per-order item with error
code `114` (`Hedge mode position side does not
match`).
example: LONG
reduceOnly:
type: boolean
default: false
description: >-
When `true`, the order can only reduce or close an
existing position — the order cannot increase the
position or open a new one. If the order amount
exceeds the current position size, the system reduces
the order to match — the response returns the adjusted
amount. Cannot be combined with `stopLoss` or
`takeProfit`. The API returns error code `116` if no
open position exists or the order side matches the
position direction. See
[reduce-only](/glossary#reduce-only).
example: false
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_PERP
postOnly: false
ioc: false
clientOrderId: ''
positionSide: LONG
rpi: true
reduceOnly: false
- side: sell
amount: '0.0001'
price: '41000'
market: BTC_USDT
postOnly: false
ioc: false
clientOrderId: ''
positionSide: LONG
rpi: true
reduceOnly: true
- side: sell
amount: '0.02'
price: '0.030'
market: ETH_BTC
postOnly: false
ioc: false
clientOrderId: ''
positionSide: LONG
rpi: true
reduceOnly: false
stopOnFail: true
request: '{{request}}'
nonce: 1594297865000
responses:
'200':
description: Successful response - returns array of order results
content:
application/json:
schema:
type: array
description: >-
Array of order creation results. Each item contains either a
successful result or an error.
items:
type: object
properties:
result:
type: object
nullable: true
description: Order data when successful, null when failed
properties:
orderId:
type: integer
description: Unique order identifier
example: 4326248250
clientOrderId:
type: string
description: >-
Custom client order identifier. Empty string if not
specified
example: ''
market:
type: string
description: Market name
example: BTC_USDT
side:
type: string
description: Order side
enum:
- buy
- sell
example: buy
type:
type: string
description: Order type
example: limit
timestamp:
type: number
description: >-
Unix timestamp in seconds (UTC) of order creation,
with microsecond precision.
example: 1684916268.825564
dealMoney:
type: string
description: Amount in money currency that is finished
example: '641.988'
dealStock:
type: string
description: Amount in stock currency that is finished
example: '0.02'
amount:
type: string
description: Order amount
example: '0.02'
left:
type: string
description: Remaining amount that must be finished
example: '0'
dealFee:
type: string
description: Fee in money that is paid when order is finished
example: '1.283976'
price:
type: string
description: Order price
example: '40000'
postOnly:
type: boolean
description: Post-only flag
example: false
ioc:
type: boolean
description: Immediate or cancel flag
example: false
status:
$ref: '#/components/schemas/ActiveOrderStatus'
type: string
stp:
type: string
description: Self trade prevention mode
example: 'no'
positionSide:
type: string
description: Position side
enum:
- LONG
- SHORT
- BOTH
example: LONG
rpi:
type: boolean
description: Retail Price Improvement flag
example: true
reduceOnly:
type: boolean
description: Reduce-only flag
example: false
error:
type: object
nullable: true
description: >-
Error details when order creation failed, null when
successful
properties:
code:
type: integer
description: Error code
example: 32
message:
type: string
description: Error message
example: Validation failed
errors:
type: object
description: Detailed validation errors
additionalProperties:
type: array
items:
type: string
example:
amount:
- Given amount is less than min amount 0.001.
example:
- result:
orderId: 4326248250
clientOrderId: ''
market: BTC_USDT
side: buy
type: limit
timestamp: 1684916268.825564
dealMoney: '641.988'
dealStock: '0.02'
amount: '0.02'
left: '0'
dealFee: '1.283976'
ioc: false
postOnly: false
price: '40000'
status: FILLED
stp: 'no'
positionSide: LONG
rpi: true
reduceOnly: false
error: null
- result: null
error:
code: 32
message: Validation failed
errors:
amount:
- Given amount is less than min amount 0.001.
- result:
orderId: 4326248250
clientOrderId: ''
market: BTC_USDT
side: sell
type: limit
timestamp: 1684916268.825564
dealMoney: '641.988'
dealStock: '0.02'
amount: '0.02'
left: '0'
dealFee: '1.283976'
ioc: false
postOnly: false
price: '41000'
status: FILLED
stp: 'no'
positionSide: LONG
rpi: true
reduceOnly: false
error: null
'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:
ActiveOrderStatus:
type: string
description: >-
Order status. `NEW` — accepted, not yet matched. `FILLED` — fully
executed. `PARTIALLY_FILLED` — partially executed, remainder still
active. `CANCELLED` — canceled before full execution.
enum:
- NEW
- FILLED
- PARTIALLY_FILLED
- CANCELLED
example: FILLED
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
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)).
````