Sign in

v1

latestOpenAPI 3.0.32026-07-2613529376.3 KB
Collateral Trading

Collateral Trigger Market Order

The endpoint creates a collateral trigger market order using collateral balance. The order remains inactive until the market price reaches activation_price, then executes immediately at the best available market price. Optionally attach stopLoss and takeProfit prices to create an OTO order that activates after the trigger market order fills.

<Warning> Rate limit: 10000 requests/10 sec. </Warning> <Accordion title="Error Codes"> - `30` - default validation error code. Also returned when `reduceOnly=true` is combined with `stopLoss` or `takeProfit` - `31` - market validation failed - `32` - amount 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) </Accordion>
post/api/v4/order/collateral/trigger-market

Request body

marketstring required

Available margin market. Example: BTC_USDT

side'buy' | 'sell' required

Order direction. Use buy to open or increase a long position and sell to open or increase a short position.

amountstring required

Amount of stock currency to buy or sell. Minimum and step values are market-dependent — query the market info endpoint for constraints.

activation_pricestring required

Trigger price in money currency. The trigger market order activates when the market price reaches the specified value.

clientOrderIdstring

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.

stopLossstring

Stop loss price.

When provided, the system creates an OTO order with a stop loss condition.

takeProfitstring

Take profit price.

When provided, the system creates an OTO order with a take profit condition.

positionSide'LONG' | 'SHORT' | 'BOTH'

Position direction. Optional at the request layer but functionally required when hedge mode is enabled. See positionSide.

  • 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 order with error code 114 (Hedge mode position side does not match).
reduceOnlyboolean

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.

stp'no' | 'cb' | 'cn' | 'co'

Self-trade prevention mode. Allowed values: no (self-trades allowed), cb (cancel both the new and the existing order), cn (cancel the new order, keep the existing), co (cancel the existing order, place the new one). Default: no.

Legacy values cancel_both, cancel_new, cancel_old are deprecated: the API accepts the legacy values with identical behavior until a deprecation deadline is announced, then rejects the legacy values. Responses always return the abbreviated form, regardless of which variant the request used.

See Self-Trade Prevention.

requeststring required
nonceinteger required

Example request

{
  "market": "BTC_USDT",
  "side": "buy",
  "amount": "0.01",
  "activation_price": "40000",
  "clientOrderId": "order1987111",
  "stopLoss": "50000",
  "takeProfit": "30000",
  "positionSide": "LONG",
  "stp": "no",
  "request": "{{request}}",
  "nonce": 1594297865000
}

Response

Successful response - trigger market order created

orderIdinteger

Unique order identifier

clientOrderIdstring

Custom client order identifier. Empty string if not specified

marketstring

Market name

side'buy' | 'sell'

Order side

typestring

Order type

timestampnumber

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

dealMoneystring

Amount in money currency that is finished

dealStockstring

Amount in stock currency that is finished

amountstring

Order amount

leftstring

Remaining amount that must be finished

dealFeestring

Fee in money that is paid when order is finished

activation_pricestring

Price at which the stop market order activates

status'NEW' | 'FILLED' | 'PARTIALLY_FILLED' | 'CANCELLED'

Order status. NEW — accepted, not yet matched. FILLED — fully executed. PARTIALLY_FILLED — partially executed, remainder still active. CANCELLED — canceled before full execution.

stpstring

Self-trade prevention mode. Possible values: no, cb, cn, co. Always returned in abbreviated form, even when the request used a legacy value.

positionSide'LONG' | 'SHORT' | 'BOTH'

Position side

reduceOnlyboolean

Reduce-only flag

Example response

{
  "orderId": 4180284841,
  "clientOrderId": "order1987111",
  "market": "BTC_USDT",
  "side": "sell",
  "type": "stop market",
  "timestamp": 1595792396.165973,
  "dealMoney": "0",
  "dealStock": "0",
  "amount": "0.001",
  "left": "0.001",
  "dealFee": "0",
  "activation_price": "40000",
  "status": "FILLED",
  "stp": "no",
  "oto": {
    "otoId": 29457221,
    "stopLoss": "50000",
    "takeProfit": "30000"
  },
  "positionSide": "LONG"
}