Skip to main content

Conditional orders

Conditional order is an order to a broker to place a market or limit order on an exchange only when certain conditions are met.

General information​

Conditional orders have a few features that must be noted when trading using them. In particular, keep in mind that:

Conditional orders are NOT direct orders

Conditional orders should be considered as a preparatory step for placing direct orders.

Such orders exist only on the Broker's servers and their purpose is to pass a market or limit order with specified parameters to the Exchange only when certain price conditions are reached.

Until the moment of triggering, conditional orders are not visible to other traders and do not require collateral, as they are only required to wait for an opportunity to create a direct order.

Orders following conditional orders must meet all requirements for direct orders.

When a conditional order is triggered, a direct order will be sent to the exchange, by which the transaction must be concluded. And this order, whether it is a market, limit or iceberg order, will be subject to all requirements and features corresponding its type.

In addition, it is necessary to make a difference between collateralization of conditional and direct orders. A conditional order does not require collateral, but a direct order must have it in accordance with the trading account rate. If at the moment when the conditional order is triggered and an attempt to place a direct order is made, it is impossible to collateralize the transaction, such an order will be rejected by the Exchange just like an attempt to create an uncollateralized order manually.

Nesting of conditional orders is limited.

Each conditional order can create only one direct order when triggered. Direct orders include market, limit and iceberg orders. You cannot create scenarios like "Stop order creates a stop order that creates a stop order" or "One stop order creates several direct orders".

Group of orders

This limitation can be partially bypassed by combining multiple orders into groups.

Price limits work both ways.

When placing a conditional order, it is required to specify the price at which the order should be triggered. Depending on how the triggering price is set, conditional orders can be categorized into two types:

  • Take profit: the price in the order is more profitable than the current market price. Such an order allows a trader to make a deal on terms more favorable than currently available. For example, to post a market order to sell an instrument when the price reaches the desired value on market growth.

  • Stop loss: the price in the order is less profitable than the current market price. Such an order allows a trader to make a deal with the losses he is agreed with. For example, to place a market order to sell an instrument when the market is falling at the price at which losses will be minimal.

Features

Other trading system APIs may use requests to different resources to create take profit and stop loss orders. ALOR Broker API creates both types of orders with the same command, while the order type is determined by the trade direction and triggering condition.

Other traders can "take out" conditional orders.

Most traders rely on the current trading dynamics to set the trigger price, so the deviation of the trigger price from the current market price usually is quite small. This can be used by market makers to provoke a false "breakout" of a price level, when the market price makes a short-term, but still painful jump. This will trigger all stop orders within the price range of the price bounce. False "breakout" has a short-term nature and the price quickly returns to its previous position, but the consequences of such jump can be quite serious, depending on the type of exchange order selected for placing. If limit orders with proper skill and prompt detection of a breakout can be canceled before execution, market orders will be immediately executed at an unfavorable price, usually exceeding the losses for which the trader was ready.

It should be noted that there is no universal way of extremely profitable trading with conditional orders: by placing stop orders only for market orders, a trader faces the risk of making a deal at an unfavorable price in case of a false "breakdown" without the possibility to immediately compensate losses at the same price, while by placing only limit orders - not to make a deal at all, when the "breakdown" will be in his favor.

Group of orders

You can reduce losses from triggering conditional orders at false breakouts by uniting orders into a group for chain triggering.

Order collateralization

Conditional orders do not require collateral, whereas market and limit orders placed must be collateralized. Thus, at the moment of triggering a conditional order there must be enough funds in the portfolio to fulfill the contract, otherwise the exchange order will be rejected by the trading system.

You can check the sufficiency of funds by the order evaluation request. To find out the terms and conditions of the order collateral depending on the risk level, click here.

Conditional orders should be considered as a way to automate the trading process, allowing to set in advance the upper and lower price limits of the instrument, at which the deal should be concluded.

Conditions​

Validity period

Due to the fact that conditional orders exist only on the Broker's servers, their validity period is not limited by the Exchange and can be equal to several hours, days, weeks, months or years. ALOR Broker trading system uses the stopEndUnixTime parameter passed in the request body to set the validity period. The value is the date of order completion in the Unix-time format, data type int64.

Example
{
  "stopEndUnixTime": 1735689599 // 31.12.2024 23:59:59 UTC
}

Trigger price

For a conditional order to be triggered, the instrument price must reach a certain value. ALOR Broker trading system uses the triggerPrice parameter passed in the request body to set the price value. The desired price per lot in the settlement currency, data type decimal is specified as the value. If the value is fractional, a dot (".") must be used as a divisor.

Thus, if a conditional order is to be triggered when the lot price reaches the value of RUB 350.86, the value of the parameter must be as follows:

Example
{
  "triggerPrice": 350.86
}

Trigger condition

To specify the order type (take profit or stop loss), in addition to the triggering price, the triggering condition relative to this price must also be specified. ALOR Broker trading system uses the condition parameter passed in the request body for this purpose. One of four string variants supported by the system must be stated as a value:

  • More — Strictly higher than the specified price
  • MoreOrEqual — Higher or equal to the specified price
  • LessOrEqual — Lower or equal to the specified price
  • Less — Strictly lower than the specified price.

Thus, if the conditional order should be triggered when the price falls to the value of RUB 350.86 or lower, the value of the parameter should be as follows:

Example
{
  "triggerPrice": 350.86,
  "condition": "LessOrEqual"
}

Request examples​

Common requirements​

An order through the API can be posted, changed and canceled if it has not been executed before. In this case, regardless of the selected action and interaction protocol, all requests must:

  • be authorized
  • be identifiable
  • contain a message with all order parameters

How these conditions should be met, however, depends on the interaction protocol.

Authorization

Authorization is necessary to confirm that the sender has the rights to use the requested resource. Request authorization uses a JWT token, which acts as an Access token. A full description of available authorization methods is available in the Authorization section.

HTTP API uses the Authorization header parameter to pass the token. The header must be passed with each executed request.

This token should be passed as a Bearer token, so the header must contain the Bearer prefix before the passed value. A correctly filled Authorization header looks as follows:

Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6IkpXVCJ9.eyJzdWIiOiJMb2dpblNhbXBsZSIsImVudCI6ImNsaWVudCIsImVpbiI6IjAxMjM0IiwiY2xpZW50aWQiOiIwMTIzNDU2IiwiYXpwIjoiMDEyMzQ1Njc4OWFiY2RlZjAxMjMiLCJhZ3JlZW1lbnRzIjoiQWdyZWVtZW50U2FtcGxlMSBBZ3JlZW1lbnRTYW1wbGUyIEFncmVlbWVudFNhbXBsZTMiLCJwb3J0Zm9saW9zIjoiUG9ydGZvbGlvU2FtcGxlMSBQb3J0Zm9saW9TYW1wbGUyIFBvcnRmb2xpb1NhbXBsZTMiLCJzY29wZSI6Ik9yZGVyc1JlYWQgT3JkZXJzQ3JlYXRlIFRyYWRlcyBQZXJzb25hbCBTdGF0cyIsImV4cCI6Mjg3MTc2MzE5OSwiaWF0IjowLCJpc3MiOiJBbG9yLklkZW50aXR5IiwiYXVkIjoiQ2xpZW50IFdBUlAgV2FycEFUQ29ubmVjdG9yIHN1YnNjcmlwdGlvbnNBcGkgQ29tbWFuZEFwaSBJbnN0cnVtZW50QXBpIFRyYWRpbmdWaWV3UGxhdGZvcm0ifQ.QOQVMIAoZ6SnF5urnIzJ0EvtQd9P5Sx355069kXoID207wHOTW0wkKNMcrIKXmENEQQ_0yDjqH_kjeqWLBJuqA

Identification

Request identification is needed to sort out a dozen of similar requests into unique ones. The identifier must be provided by the user and passed as a value of the X-REQID header parameter, so the API client used must be able to generate it.

Any character combination can be used as a request identifier, including the wildcard characters !@##;%:?*()-_=+/|''. Identifier has two restrictions:

  • The identifier value must be unique for the trading system. If the value has been previously used for another request, a copy of the response to the first request with this identifier will be returned instead of execution of the new request

  • Wildcard characters that violate the integrity of a JSON object must be escaped

Thus, the system will accept both Dxxxxx-Order-Market-No-812643-@-MOEX and d3c886f1-ea1e-4634-aff4-119c902ad926 as the request identifier, provided that these values have not been previously passed to the system by any API user.

A properly filled X-REQID parameter does not require any additional prefixes and looks as follows:

X-REQID: d3c886f1-ea1e-4634-aff4-119c902ad926

Order management​

Interchangeability

Order management options are interchangeable. For example, an order placed via HTTP API can be changed or canceled via WebSocket API, and vice versa.

Creating order

Interactive description

Interactive description of this request is available at the Create Stop order page

To create a stop order with subsequent market order posting to the exchange via HTTP API, use POST request to the /commandapi/warptrans/TRADE/v2/client/orders/actions/stop endpoint.

Complete URL looks as follows:

https://api.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/actions/stop
https://apidev.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/actions/stop

The message body should contain parameters of both the stop order and the market order:

Request body example
{
// Stop order parameters:
  "condition": "MoreOrEqual",
  "triggerPrice": 350.86,
  "stopEndUnixTime": 1735678799,
  "activate": true,
// Market order parameters:
  "side": "sell",
  "quantity": 100,
  "instrument": {
    "symbol": "SBER",
    "exchange": "MOEX",
    "instrumentGroup": "TQBR"
  },
  "user": {
    "portfolio": "D39004"
  }
}
Expected result

A stop order was created, which when triggered will post a market order to sell 100 lots of SBER on Moscow Exchange (MOEX) in T+2 mode (TQBR) at the price that is the best price of the lot at the moment of execution.

The stop order will be triggered if the market price of the lot equals or exceeds the value of RUB 350.86, or canceled if the condition is not met by December 31, 2024 23:59:59 UTC.

If the request is successful, the API will return a message with response code 200 containing the exchange order number:

Response body example
{
  "message": "success",
  "orderNumber": "189...559"
}

If the request processing ended with an error, the API will return information about the cause of this error.

Request parameters

A complete list of all parameters and possible responses is available on the request description page.

Changing order

Interactive description

Interactive description of this request is available at the Update Stop order page

To change a previously placed market stop order via HTTP API, use a PUT request to the same endpoint with the addition of the Path parameter {stopOrderId}, replacing it with the order number when the request is executed.

How the order will be changed?

Modification of the order is made by canceling the previously placed order and publishing a new one. It is not possible to change fulfilled or canceled orders.

Complete URL looks as follows:

https://api.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/actions/stop/189...559
https://apidev.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/actions/stop/189...559

Where 189...559 is the actual value of the {orderId} parameter.

When changing an existing order, a message identical to the order posting request is used. The difference is in other parameter values.

Request body example
{
// Stop order parameters:
  "condition": "MoreOrEqual",
  "triggerPrice": 330.15,
  "stopEndUnixTime": 1719781199,
  "activate": true,
// Market order parameters:
  "side": "sell",
  "quantity": 50,
  "instrument": {
    "symbol": "SBER",
    "exchange": "MOEX",
    "instrumentGroup": "TQBR"
  },
  "user": {
    "portfolio": "D39004"
  }
}
Expected result

The order with the number 189...559 has been canceled. A new stop order has been created, which when triggered will post a market order to sell 50 lots of SBER on Moscow Exchange (MOEX) in T+2 mode (TQBR) at the price, which is the best price of the lot at the moment of execution.

The modified stop order will be triggered if the market price of the lot equals or exceeds the value of RUB 330.15, or canceled if the condition is not met by June 30, 2024 23:59:59 UTC.

If the request is successful, the previous order will be canceled and the API will return a message with response code 200 containing the exchange number of the new order:

Response body example
{
  "message": "success",
  "orderNumber": "189...560"
}

If the request processing ended with an error, the API will return information about the cause of this error.

Request parameters

A complete list of all parameters and possible responses is available on the request description page.

Canceling order

Interactive description

Interactive description of this request is available at the Cancel one order page

What orders can be canceled?

Only pending orders can be canceled. It is impossible to cancel fulfilled orders.

To cancel a previously posted order via HTTP API, use a DELETE request to the /commandapi/warptrans/TRADE/v2/client/orders/{orderId} endpoint, where {orderId} is a Path parameter that passes the order number.

In addition to the order number, the following attributes of the order are also required:

Query parameters

    portfolio stringrequired

    Client portfolio Id

    Example: D39004
    exchange stringrequired

    Possible values: [MOEX]

    Exchange code

    stop booleanrequired

    Is it a stop order?

    Example: true
Attention to detail

The same request is used both for canceling stop and exchange orders. The difference is in the value of the stop parameter: for exchange orders the value should be false, whereas for stop orders it should be true.

Complete URL looks as follows:

https://api.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/189...560?portfolio=D39004&exchange=MOEX&stop=true
https://apidev.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/189...560?portfolio=D39004&exchange=MOEX&stop=true
Expected result

Order with number 189...560 has been canceled.

If the request is successful, the previous order will be canceled and the API will return a message with response code 200:

success

If the request processing ended with an error, the API will return information about the cause of this error.

Request parameters

A complete list of all parameters and possible responses is available on the request description page.

Group of orders

Stop orders are recommended to group with other orders for cohesive execution.

What's next?​

Additionally, we recommend reading the following related articles: