OKX · API Orders
TP/SL in attachAlgoOrds only goes live once the parent order fills
Attaching a take-profit and a stop-loss to an order placed through the OKX API means adding an attachAlgoOrds array to the request body of the place-order endpoint, POST /api/v5/trade/order. The take-profit side takes tpTriggerPx (trigger price) and tpOrdPx (order price), the stop-loss side takes slTriggerPx and slOrdPx, and an order price of -1 makes the order execute at market once it triggers. To take profit in several portions, put one object per portion in the array, each with its own size.
TP/SL attached this way stays tied to its parent order. If you want it to stand on its own, independent of any new order, place it separately through the algo order endpoint POST /api/v5/trade/order-algo.
Trigger price and order price are filled in as a pair
The trigger price and the order price belong together: fill in tpTriggerPx and you must fill in tpOrdPx as well, and the same applies on the stop-loss side. The one exception is a limit take-profit, which takes only the order price and no trigger price. A trigger can also be given as a ratio; the table shows where that is allowed.
| Field | What it is | How to fill it in |
|---|---|---|
| attachAlgoClOrdId | Your own ID for the algo order | Case-sensitive letters and digits, up to 32 characters |
| tpTriggerPx / tpOrdPx | TP trigger price / TP order price | Conditional TP: fill in both; limit TP: tpOrdPx only; an order price of -1 means a market take-profit |
| tpTriggerRatio | TP trigger ratio | Expiry futures and perpetuals only; send this or tpTriggerPx, not both |
| slTriggerPx / slOrdPx | SL trigger price / SL order price | Fill in one and the other is required; an order price of -1 means a market stop-loss |
| slTriggerRatio | SL trigger ratio | Expiry futures and perpetuals only; send this or slTriggerPx, not both |
| tpOrdKind | TP order kind | condition (the default) or limit |
| tpTriggerPxType / slTriggerPxType | Trigger price type | One of last, index or mark |
| sz | Size of this take-profit portion | Only for TP orders in split TPs, where it is required |
| amendPxOnTriggerType | Cost-price stop-loss | Only for the SL order in split TPs; 0 off (the default), 1 on |
| callbackRatio / callbackSpread / activePx | Trailing stop | Only when ordType = move_order_stop |
Request body for a perpetual long with a take-profit and a stop-loss attached
The request below places a limit order to open a long on BTC-USDT-SWAP. Once it fills, it carries one take-profit and one stop-loss, both triggered on the mark price and executed at market. The prices and the contract count are placeholders, so put in your own.
{
"instId": "BTC-USDT-SWAP",
"tdMode": "cross",
"side": "buy",
"posSide": "long",
"ordType": "limit",
"px": "60000",
"sz": "1",
"clOrdId": "open001",
"attachAlgoOrds": [
{
"attachAlgoClOrdId": "tpsl001",
"tpTriggerPx": "66000",
"tpOrdPx": "-1",
"tpTriggerPxType": "mark",
"slTriggerPx": "57000",
"slOrdPx": "-1",
"slTriggerPxType": "mark"
}
]
}
Without split take-profits, the take-profit and the stop-loss can in principle share one object, because the one-way rule behind 51076 only applies to split TPs.
The outer fields have to match how your account is set up. With side set to buy and posSide to long, this is a buy that opens a long in long/short mode; if the account is in net mode, leave posSide out or send net. A cross-margin perpetual uses cross for tdMode. On perpetuals, sz counts contracts, so 1 means one contract.
Once the request is sent, read the response before anything else. A code of 0 only tells you the request succeeded. Whether the order itself was placed is shown by sCode inside data, which has to be 0; if it isn't, read sMsg and subCode. Catching a rejected order in your script so the loop doesn't resend it unchanged is covered in OKX API auto-trading risk control. Send this request with a demo trading key first and only then switch to your live key; setting up the demo account is explained in How to Use OKX Demo Trading.
If the parent is cancelled before it fills, the attached TP/SL is discarded too
Attached TP/SL orders are only generated and activated after the parent order fills. If the parent is cancelled before any fill, they are discarded along with it.
Match your own case against this table:
| Your case | attachAlgoOrds | order-algo |
|---|---|---|
| TP/SL should appear automatically once the opening order fills, and needn't survive if that order is cancelled | Use it | Not needed |
| TP/SL has to exist independently of the opening order | Doesn't fit | Place it here |
| Spot market buy with tgtCcy set to base_ccy | Not supported | Place it here |
| Spot market sell with tgtCcy set to quote_ccy | Not supported | Place it here |
tgtCcy decides which currency a spot market order's sz is counted in: base_ccy for the base currency, quote_ccy for the quote currency. Parameters such as order-algo's ordType aren't described under the place-order endpoint; look them up in order-algo's own section of the docs.
How do you set up split take-profits without errors like 51076 and 51083?
Split take-profits means putting several take-profit objects in attachAlgoOrds, each with its own sz, plus at most one more object for the stop-loss. Limit take-profits and trigger take-profits can both be split, and a mistake gets the matching error code straight back from the endpoint:
| Requirement | Error code if it isn't met |
|---|---|
| Each object is one-way: a take-profit pair or a stop-loss pair, never both | 51076 |
| All take-profits use the same trigger price type (tpTriggerPxType) | 51080 |
| No two take-profits have the same trigger price | 51081 |
| Every take-profit has a size | 51089 |
| The take-profit sizes add up to the parent order's size | 51083 |
| No more than 10 take-profit orders | 51079 |
| No more than 1 stop-loss order | 51084 |
| All take-profits are of the same kind | 51091 |
| No two take-profits have the same order price | 51092 |
| A limit take-profit's order price can't be -1 | 51093 |
| Limit take-profits aren't available for spot, margin or options | 51094 |
| Split take-profits with a cost-price stop-loss aren't available for spot or margin | 51077 |
| With cost-price stop-loss on (amendPxOnTriggerType = 1), at least 2 take-profits | 51085 |
A cost-price stop-loss moves the stop-loss trigger price to the average entry price when the first take-profit triggers. With it switched on, the stop-loss trigger price can't be left empty.
Take the long order from the previous section, raise it to 2 contracts, split the take-profit in two and add a cost-price stop-loss, and attachAlgoOrds looks like this:
"sz": "2",
"attachAlgoOrds": [
{ "attachAlgoClOrdId": "tp001", "tpTriggerPx": "64000", "tpOrdPx": "64000", "sz": "1" },
{ "attachAlgoClOrdId": "tp002", "tpTriggerPx": "68000", "tpOrdPx": "68000", "sz": "1" },
{ "attachAlgoClOrdId": "sl001", "slTriggerPx": "57000", "slOrdPx": "-1", "amendPxOnTriggerType": "1" }
]
Rule by rule: the two take-profit sizes are 1 + 1 = 2, equal to the parent's 2 contracts (51083); two take-profits are exactly the minimum a cost-price stop-loss needs (51085); the trigger prices 64000 and 68000 differ (51081); both take-profits leave the trigger price type at its default, so the types match (51080); and there is a single stop-loss object holding only the stop-loss pair (51084, 51076). The docs don't say whether two take-profits that both use an order price of -1 count as having the same price, so the example gives them two different prices and stays clear of 51092.
Default trigger price, ratios on spot orders and a separate ID for attached TP/SL
Do TP and SL orders trigger on the last price or the mark price by default?
If you don't send tpTriggerPxType or slTriggerPxType, they trigger on the last price (last). Both fields also accept index (index price) and mark (mark price). With split take-profits, every take-profit on the same order has to use the same trigger price type, or the request fails with 51080.
Can a spot order set take-profit and stop-loss as a percentage?
tpTriggerRatio and slTriggerRatio only apply to expiry futures and perpetual futures, so a spot order needs an actual price in tpTriggerPx or slTriggerPx. Ratios are written as decimals, where 0.3 means 30%, and you send either the ratio or the matching trigger price, not both. When the main order is a buy, tpTriggerRatio must be greater than 0 and slTriggerRatio between 0 and 1; when it is a sell, tpTriggerRatio must be between -1 and 0 and slTriggerRatio greater than 0.
Can I look up the attached TP/SL with the clOrdId I sent on the order?
No. clOrdId is not carried over to the attached TP/SL algo orders. To give them an ID of their own, fill in attachAlgoClOrdId: once the order is completely filled and the attached algo order is placed, that value is posted to algoClOrdId. When tpOrdKind is limit and there is only one TP order, attachAlgoClOrdId can also be used as clOrdId on the GET / Order details endpoint.