Place TP/SL Conditional Orders (TRADE)

POST /capi/v3/placeTpSlOrder

Request Weight

1 on 10s order rate limit(X-ORDER-COUNT-10S); 1 on 1min order rate limit(X-ORDER-COUNT-1M); 0 on IP rate limit(X-USED-WEIGHT-1M);

Request Body

Parameter	Type	Required?	Description
symbol	String	Yes	Trading pair.
clientAlgoId	String	Yes	Client-defined identifier (1-36 characters, pattern `^[\\.A-Z\:/a-z0-9_-]{1,36}$`).
planType	String	Yes	Plan type. Values: `TAKE_PROFIT`, `STOP_LOSS`.
triggerPrice	String	Yes	Trigger price (> 0).
executePrice	String	No	Execution price. Use 0 or omit for market execution; a positive value selects limit execution. Full-position TP/SL (quantity is 0, null, or omitted) only supports market execution; a nonzero execution price is rejected. Copy-trading API keys only support market execution.
quantity	String	No	Execution quantity; must not be negative. Use 0, null, or omit for the full position; a positive value specifies a partial quantity. When closePosition=true, only 0, null, or omission is allowed. Copy-trading API keys only support full-position TP/SL.
positionSide	String	Yes	Position side (`LONG`, `SHORT`).
triggerPriceType	String	No	Trigger source. `CONTRACT_PRICE` or `MARK_PRICE`. Default `CONTRACT_PRICE`.
reduceOnly	Boolean	No	Compatibility parameter. This endpoint always closes positions; the server always uses true, even if false is supplied or this field is omitted.
closePosition	Boolean	No	Whether to set TP/SL for the full position. Boolean values true or false; omission is treated as false. When true, quantity must be 0, null, or omitted, and executePrice must be 0 or omitted. When false or omitted, quantity still determines whether the order covers the full position.

Request example

Code
curl -X POST "https://api-contract.weex.com/capi/v3/placeTpSlOrder" \
   -H "ACCESS-KEY:*******" \
   -H "ACCESS-SIGN:*******" \
   -H "ACCESS-PASSPHRASE:*****" \
   -H "ACCESS-TIMESTAMP:1659076670000" \
   -H "Content-Type: application/json" \
   -d '{
     "symbol": "BTCUSDT",
     "clientAlgoId": "tp-20240201-1",
     "planType": "TAKE_PROFIT",
     "triggerPrice": "70500",
     "executePrice": "70500",
     "quantity": "0.01",
     "positionSide": "LONG",
     "triggerPriceType": "MARK_PRICE",
     "reduceOnly": true
   }'

Parameter relationships

When closePosition=true, a nonzero quantity is rejected. A quantity of 0, null, or omission selects the full position.
Regardless of closePosition, a quantity of 0, null, or omission selects full-position TP/SL. executePrice must be 0 or omitted; a nonzero execution price is rejected.
When closePosition=false or omitted and quantity>0, both market execution (executePrice=0 or omitted) and limit execution (executePrice>0) are supported.
All TP/SL orders close positions only. The server always uses reduceOnly=true, regardless of the supplied value.
The server sets timeInForce; do not supply it. Market execution uses IMMEDIATE_OR_CANCEL (IOC), and limit execution uses GOOD_TIL_CANCEL (GTC). Full-position TP/SL always uses market execution and IOC.
Both planType values, TAKE_PROFIT and STOP_LOSS, follow these rules.

Full-position market stop-loss example (quantity may be omitted or set to 0):

Code
{
  "symbol": "ETHUSDT",
  "clientAlgoId": "full-position-sl-1",
  "planType": "STOP_LOSS",
  "triggerPrice": "2000",
  "executePrice": "0",
  "positionSide": "LONG",
  "triggerPriceType": "CONTRACT_PRICE",
  "closePosition": true
}

Response parameters

Returns an array of objects with the following fields:

Field	Type	Description
success	Boolean	Whether the plan order was accepted.
orderId	Long	Plan order ID when successful.
errorCode	String	Error code when `success = false`.
errorMessage	String	Error description when `success = false`.

Response example

Code
[
  {
    "success": true,
    "orderId": 812345678901234900,
    "errorCode": "",
    "errorMessage": ""
  }
]