> ## 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.
# Create stop-limit order
> Place a spot stop-limit order; a limit order activates when the trigger price is reached.
* [Create stop-market order](/api-reference/spot-trading/create-stop-market-order) — place a stop-market order
* [Query unexecuted orders](/api-reference/spot-trading/query-unexecuted-orders) — list open orders
* [Cancel order](/api-reference/spot-trading/cancel-order) — cancel an open order
## OpenAPI
````yaml /openapi/private/http-trade-v4.yaml POST /api/v4/order/stop_limit
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/stop_limit:
post:
tags:
- Spot Trading
summary: Create stop-limit order
description: >
The endpoint creates a [stop-limit trading
order](/glossary#stop-limit-order). The order remains inactive until the
market price reaches the `activation_price`, at which point the system
places a limit order at the specified `price`. For buy orders,
activation triggers when the market price rises to or above
`activation_price`. For sell orders, activation triggers when the market
price falls to or below `activation_price`. Minimum and maximum values
for `amount`, `price`, and `activation_price` are market-dependent.
Query `GET /api/v4/public/markets` for `minAmount`, `minTotal`,
`maxTotal`, `stockPrec` (amount precision), and `moneyPrec` (price
precision).
Rate limit: 10000 requests/10 sec.
- `30` - default validation error code
- `31` - market validation failed
- `32` - amount validation failed
- `33` - price validation failed
- `36` - clientOrderId validation failed
```json
{
"code": 30,
"message": "Validation failed",
"errors": {
"activation_price": ["Activation price field is required."],
"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": 31,
"message": "Validation failed",
"errors": {
"market": ["Market is not available."]
}
}
```
```json
{
"code": 31,
"message": "Validation failed",
"errors": {
"market": ["Market field should not be empty string."]
}
}
```
```json
{
"code": 32,
"message": "Validation failed",
"errors": {
"amount": ["Not enough balance."]
}
}
```
```json
{
"code": 32,
"message": "Validation failed",
"errors": {
"amount": [
"Given amount is less than min amount 0.001",
"Min amount step = 0.000001"
]
}
}
```
```json
{
"code": 30,
"message": "Validation failed",
"errors": {
"total": ["Total (amount * price) is less than 5.05"]
}
}
```
```json
{
"code": 36,
"message": "Validation failed",
"errors": {
"clientOrderId": ["ClientOrderId field should be a string."]
}
}
```
```json
{
"code": 36,
"message": "Validation failed",
"errors": {
"clientOrderId": [
"ClientOrderId field should contain only latin letters, numbers and dashes."
]
}
}
```
operationId: createStopLimitOrder
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StopLimitOrderRequest'
responses:
'200':
description: Order created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'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:
StopLimitOrderRequest:
type: object
required:
- market
- side
- amount
- price
- activation_price
- request
- nonce
properties:
market:
type: string
description: >-
Trading pair. Format: `BASE_QUOTE` (e.g., `BTC_USDT`). Query `GET
/api/v4/public/markets` for available markets.
example: BTC_USDT
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`, `minTotal`, `maxTotal`. Precision: `stockPrec`.
example: '0.001'
price:
type: string
description: >-
Limit price per unit in quote (money) currency applied after the
stop triggers. Minimum and maximum values are market-dependent.
Precision: `moneyPrec`.
example: '9800'
activation_price:
type: string
description: >-
Trigger price in quote (money) currency. For buy orders, the stop
triggers when the market price rises to or above the specified
price. For sell orders, the stop triggers when the market price
falls to or below the specified price. Precision: `moneyPrec`.
example: '10000'
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: order1987111
bboRole:
type: integer
enum:
- 1
- 2
description: >-
Best Bid/Offer ([BBO](/glossary#bbo)) execution method. The system
selects the best market price for execution after the stop triggers.
`1` = Queue method, `2` = Counterparty method.
stp:
type: string
enum:
- 'no'
- cancel_both
- cancel_new
- cancel_old
default: 'no'
description: >-
Self-trade prevention mode. Allowed values: `no`, `cancel_both`,
`cancel_new`, `cancel_old`. Default: `no`.
example: 'no'
request:
type: string
example: '{{request}}'
nonce:
type: integer
example: 1594297865000
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'
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
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
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)).
````