Appearance
Place conditional order
POST
/v1/orders/conditionals
For users wishing to manage futures exposure, VALR offers conditional orders that can be added to an existing position as a Take Profit and Stop Loss (TPSL).
| Parameter | Description |
|---|---|
| quantity (required) | The value in base amount (truncated to baseDecimalPlaces of the currency pair). 0 closes the entire open position. > 0 places a reduce-only order. -1 closes only the quantity added by the new order. |
| triggerType (required) | Can either be LAST_TRADED or MARK_PRICE |
| pair (required) | A valid currency pair (e.g., BTCUSDTPERP for futures, BTCZAR for spot) |
| takeProfitTriggerPrice (required for TP) | The mark price or last traded price to trigger the conditional order. |
| takeProfitOrderPrice (required for TP) | The price at which the conditional order will be placed. Use -1 for a market order. |
| stopLossTriggerPrice (required for SL) | The mark price or last traded price to trigger the conditional order. |
| stopLossOrderPrice (required for SL) | The price at which the conditional order will be placed. Use -1 for a market order. |
| customerOrderId (optional) | Alphanumeric value. Must be unique across all open orders. |
If both TP and SL are specified, the order is handled as OCO (One-Cancels-the-Other). Once one side triggers, the other is cancelled.
Note: The response uses takeProfitPlacePrice for the value submitted as takeProfitOrderPrice, and stopLossPlacePrice for the value submitted as stopLossOrderPrice.
When you receive a response with an id, it does not always mean that the order has been placed. When the response is 202 Accepted, you can use the Order Status REST API or WebSocket API to receive the status of this order.
On spot, it can be used to construct a take profit, stop loss as well as ordinary conditional orders. It can also be used with margin.
On futures, a conditional order can be used to specify Take Profit and Stop Loss (TPSL) together in one request. When one of the TPSL orders is triggered, the other is automatically cancelled. A full list of conditional order request formats is available in the Postman collection.
Authorizations
apiKey
Your API key
Type
API Key (header: X-VALR-API-KEY)
apiSignature
HMAC SHA512 signature of the request (see Authentication section)
Type
API Key (header: X-VALR-SIGNATURE)
apiTimestamp
Request timestamp in milliseconds
Type
API Key (header: X-VALR-TIMESTAMP)
Request Body
application/json
JSON
{
"quantity": "0.0001",
"triggerType": "LAST_TRADED",
"pair": "BTCUSDTPERP",
"stopLossTriggerPrice": "97400",
"stopLossOrderPrice": "97000",
"takeProfitTriggerPrice": "97600",
"takeProfitOrderPrice": "98000",
"customerOrderId": "Atest"
}
Responses
Conditional order accepted
application/json
JSON
{
"id": "7a19f5a1-afad-4138-bb9a-65a136e6c507"
}