> ## 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 collateral OCO order
> Create a collateral OCO (one-cancels-the-other) order combining limit and stop-limit via the V4 API.
export const RelatedResources = ({children}) => {
const ref = useRef(null);
const [visible, setVisible] = useState(false);
useEffect(() => {
if (!ref.current) return;
const el = ref.current;
if (el.parentElement) {
el.parentElement.appendChild(el);
}
setVisible(true);
}, []);
return
Related resources
{children}
;
};
* [Query unexecuted OCO orders](/api-reference/collateral-trading/query-unexecuted-oco-orders) — List active OCO orders
* [Collateral limit order](/api-reference/collateral-trading/collateral-limit-order) — Place a single collateral limit order
* [Collateral stop-limit order](/api-reference/collateral-trading/collateral-stop-limit-order) — Place a collateral stop-limit order
* [Cancel conditional order](/api-reference/collateral-trading/cancel-conditional-order) — Cancel an active conditional order
## OpenAPI
````yaml /openapi/private/http-trade-v4.yaml POST /api/v4/order/collateral/oco
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/oco:
post:
tags:
- Collateral Trading
summary: Create collateral OCO order
description: >
The endpoint creates a collateral
[OCO](/glossary#one-cancels-the-other-oco) (one-cancels-the-other) order
using [collateral balance](/glossary#balance-collateral). An OCO order
combines a limit order (take-profit leg) and a stop-limit order
(stop-loss leg) into a single conditional group. When one leg executes,
the system cancels the other automatically.
Rate limit: 10000 requests/10 sec.
- `30` - default validation error code. 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
- `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 (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)
operationId: createCollateralOcoOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- market
- side
- amount
- price
- activation_price
- stop_limit_price
- request
- nonce
properties:
market:
type: string
description: >-
Available margin [market](/glossary#market). Example:
BTC_USDT
example: BTC_USDT
side:
type: string
enum:
- buy
- sell
description: >-
Order direction. Use `buy` to open or increase a long
position and `sell` to open or increase a short position.
example: buy
amount:
type: string
description: >-
Amount of [stock](/glossary#stock) currency for both legs of
the OCO order. Minimum and step values are market-dependent
— query the [market
info](/api-reference/market-data/market-info) endpoint for
constraints.
example: '0.001'
price:
type: string
description: >-
Limit order price in [money](/glossary#money) currency for
the take-profit leg.
example: '40000'
activation_price:
type: string
description: >-
Trigger price in [money](/glossary#money) currency for the
stop-loss leg. The stop-limit order activates when the
market price reaches the specified value.
example: '41000'
stop_limit_price:
type: string
description: >-
Execution price in [money](/glossary#money) currency for the
stop-loss leg. After activation, the stop-loss leg places a
limit order at the specified price.
example: '42000'
clientOrderId:
type: string
description: >-
Custom order identifier. Must be unique and contain only
letters, numbers, dashes, dots, or underscores.
example: order1987111
reduceOnly:
type: boolean
default: false
description: >-
When `true`, both legs of the OCO order can only reduce or
close an existing position — neither leg can 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. 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
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). Both legs of the
OCO inherit the value.
- **One-way mode** (default account mode): the field is
ignored. Orders always use `BOTH`, and the response returns
`positionSide: "BOTH"` on each leg 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 order with error code `114` (`Hedge mode
position side does not match`).
example: LONG
request:
type: string
example: '{{request}}'
nonce:
type: string
example: '{{nonce}}'
example:
market: BTC_USDT
side: buy
amount: '0.001'
price: '40000'
activation_price: '41000'
stop_limit_price: '42000'
clientOrderId: order1987111
reduceOnly: false
positionSide: LONG
request: '{{request}}'
nonce: '{{nonce}}'
responses:
'200':
description: Successful response - OCO order created
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: OCO order identifier
example: 117703764513
reduceOnly:
type: boolean
description: Reduce-only flag
example: false
stop_loss:
type: object
description: Stop loss order details
properties:
orderId:
type: integer
description: Order identifier
example: 117703764514
clientOrderId:
type: string
description: Custom 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: stop limit
timestamp:
type: number
description: >-
Unix timestamp in seconds (UTC) of order creation,
with microsecond precision.
example: 1594605801.49815
dealMoney:
type: string
description: Executed amount in money
example: '0'
dealStock:
type: string
description: Executed amount in stock
example: '0'
amount:
type: string
description: Order amount
example: '2.241379'
takerFee:
type: string
description: Taker fee ratio
example: '0.001'
makerFee:
type: string
description: Maker fee ratio
example: '0.001'
left:
type: string
description: Unexecuted amount in stock
example: '2.241379'
dealFee:
type: string
description: Executed fee by deal
example: '0'
post_only:
type: boolean
description: Post-only flag
example: false
mtime:
type: number
description: Timestamp of order modification
example: 1662478154.941582
price:
type: string
description: Order price
example: '19928.79'
activation_price:
type: string
description: Activation price
example: '29928.79'
activation_condition:
type: string
description: >
Trigger condition derived from `side` (response-only,
cannot be overridden): `buy` → `gte`, `sell` → `lte`.
enum:
- gte
- lte
example: gte
activated:
type: integer
description: Activation status (0 - not activated, 1 - activated)
example: 0
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
take_profit:
type: object
description: Take profit order details
properties:
orderId:
type: integer
description: Order identifier
example: 117703764515
clientOrderId:
type: string
description: Custom 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: 1662478154.941582
dealMoney:
type: string
description: Executed amount in money
example: '0'
dealStock:
type: string
description: Executed amount in stock
example: '0'
amount:
type: string
description: Order amount
example: '0.635709'
takerFee:
type: string
description: Taker fee ratio
example: '0.001'
makerFee:
type: string
description: Maker fee ratio
example: '0.001'
left:
type: string
description: Unexecuted amount in stock
example: '0.635709'
dealFee:
type: string
description: Executed fee by deal
example: '0'
post_only:
type: boolean
description: Post-only flag
example: false
mtime:
type: number
description: Timestamp of order modification
example: 1662478154.941582
price:
type: string
description: Order price
example: '9928.79'
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
example:
id: 117703764513
reduceOnly: false
stop_loss:
orderId: 117703764514
clientOrderId: ''
market: BTC_USDT
side: buy
type: stop limit
timestamp: 1594605801.49815
dealMoney: '0'
dealStock: '0'
amount: '2.241379'
takerFee: '0.001'
makerFee: '0.001'
left: '2.241379'
dealFee: '0'
post_only: false
mtime: 1662478154.941582
price: '19928.79'
activation_price: '29928.79'
activation_condition: gte
activated: 0
status: FILLED
stp: 'no'
positionSide: LONG
take_profit:
orderId: 117703764515
clientOrderId: ''
market: BTC_USDT
side: buy
type: limit
timestamp: 1662478154.941582
dealMoney: '0'
dealStock: '0'
amount: '0.635709'
takerFee: '0.001'
makerFee: '0.001'
left: '0.635709'
dealFee: '0'
post_only: false
mtime: 1662478154.941582
price: '9928.79'
status: FILLED
stp: 'no'
positionSide: LONG
'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)).
````