Skip to main content

Limit orders

Limit order is an order to conclude a transaction to buy/sell stated number of lots of a financial instrument at the price that the trader who placed the order considers acceptable.

General information​

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

Limit order is a direct order.

Direct orders passing to the Exchange without additional processing or waiting for specific conditions on the trading system side. Such orders are visible for all traders and affect the order book of the selected instrument. Also, the funds (money/lots) required to fulfill a direct order will be reserved at the moment of its posting.

Limit order directly forms the order book.

An order book is literally a list of limit orders waiting to be executed at a given price. When a limit order is posted, it is placed in a fulfillment queue waiting for a counter offer with the same price. Sell orders will overprice from the current best price, while buy orders will do the opposite. The closest bids to each other in terms of price determine the current market price of the lot, at which deals will be made on market orders.

Limit order may remain unfulfilled.

If a market order is executed immediately at the current best lot price, a limit order awaits execution at the price specified at the time of placing. If for the whole period of the order existence there were no counter offers matching the price of the placed order, such order will remain unexecuted and will be cancelled later.

Example

Trader posts a limit order to buy 1000 lots of the instrument at the price of RUB 300. The current best lot price is RUB 301. If the market will show a growth tendency and the best lot price will increase, the order with unattractive price for other traders will remain unexecuted and the opportunity to conclude a profitable deal will be lost. To avoid such situations, it is recommended to use conditional orders and combine them with limit orders into groups.

Exchange may limit the price of a limit order.

To control the order aggressiveness, the Exchange may impose restrictions on the minimum and maximum lot price. Such limitation is based on the best lot price at the moment of order placement and is intended to protect investors from possible mistakes when making deals. The conditions of the limitation are determined by the exchange itself and may differ for different markets.

Example

The stock market on the Moscow Exchange is subject to a price limit of 5% of the current best price of the instrument. If the current best price of an instrument is equal to RUB 300, orders with prices of 315.01 and 284.99 will be automatically rejected by the exchange as overly aggressive.

Order collateralization

Limit order must be collateralized in accordance with the client's risk level and trading method:

  • In case of non-marginal trading the collateral for the order shall be the full value of the order;

  • For margin trading, collateral depends on the client's level of risk.

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.

Limit orders should be considered as an opportunity to make a deal at a desired price (within certain limits), but with no guarantee of finding a suitable counter offer.

If this method does not match the trading strategy you use, we recommend to try market orders to increase the probability of a successful trade.

Conditions​

The main condition for order execution is the timeInForce parameter, which regulates the processing of the order balance after exhaustion of all counter offers of the market. Possible values:

Condition

Description

oneday

Order shall be valid during the trading day. The balance after withdrawal of the entire available volume of counter offers shall be placed in the queue for execution and shall be held until order fulfillment, cancellation or the end of the trading day within which the order was placed.

goodtillcancelled

Similar to oneday, but with no time limit — the balance is held in the queue until the order is complete or canceled.

immediateorcancel

Order is fulfilled for the volume available at the moment of placement, the rest is canceled.

fillorkill

Order can be fulfilled only in its entirety. If the available volume does not allow to fulfill the order, it will not be placed at all.

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 Limit order page

To create a limit order via HTTP API, use a POST request to the /commandapi/warptrans/TRADE/v2/client/orders/actions/limit endpoint with a message containing all order parameters.

Complete URL looks as follows:

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

The message body should contain basic information about the order: side, number of lots, instrument data, portfolio and condition for execution of the order. If necessary, you can add a custom comment to make it easier to identify the order by a human.

Request body example
{
  "side": "buy",
  "quantity": 100,
  "price": 301.74,
  "instrument": {
    "symbol": "SBER",
    "exchange": "MOEX",
    "instrumentGroup": "TQBR"
  },
  "comment": "Custom comment",
  "user": {
    "portfolio": "D39004"
  },
  "timeInForce": "oneday"
}
Expected result

A limit order was created to buy 100 lots of SBER on the Moscow Exchange (MOEX) in the T+2 (TQBR) mode at a price of RUB 301.74 per lot.

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 Limit order page

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

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/limit/189...559
https://apidev.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/actions/limit/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
{
  "side": "buy",
  "quantity": 10,
  "price": 301.74,
  "instrument": {
    "symbol": "SBER",
    "exchange": "MOEX",
    "instrumentGroup": "TQBR"
  },
  "comment": "Custom comment",
  "user": {
    "portfolio": "D39004"
  },
  "timeInForce": "oneday"
}
Expected result

The order with the number 189...559 has been canceled. A new limit order was created to buy 10 lots of the SBER instrument on the Moscow Exchange (MOEX) in the T+2 (TQBR) mode at a price of RUB 301.74 per lot.

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.

Cancelling 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, a DELETE request to the /commandapi/warptrans/TRADE/v2/client/orders/{orderId} endpoint is used, 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: false

So, the complete URL of the request to cancel the order looks as follows:

https://api.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/189...560?portfolio=D39004&exchange=MOEX&stop=false
https://apidev.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/189...560?portfolio=D39004&exchange=MOEX&stop=false
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

If necessary, a limit order can be grouped with other orders for cohesive execution.

What's next?​

Additionally, we recommend reading the following related articles: