Orders

Interaction with the trading system within the trading directly consists of three main actions:

Creating the order — for placing an offer to buy or sell a financial asset
Modifying the order — for changing the conditions of the placed offer
Canceling the order — to withdraw a previously placed offer if it was not satisfied in time

Commands to perform these actions can be transferred both within multiple separate connections established when sending requests to the HTTP API and within a single WebSocket connection to the order management interface.

The following describes the main features of WebSocket API orders management.

Interfaces

To manage orders within a single connection, the ALOR Broker trading system provides a WebSocket interface /cws. Full path to the interface will differ depending on the used system environment:

Address	Environment
`wss://api.alor.ru/cws`	Production environment. Requires a real trading account
`wss://apidev.alor.ru/cws`	Test environment. Uses a test trading account

caution

he server accepts requests only via the WebSocket Secure (wss) protocol due to the data security policy. An attempt to connect using the insecure WebSocket (ws) protocol will be rejected by the server with a 406 Not Acceptable response.

Creating a request

Regardless of the order type being handled and the action being performed, the request must always meet the following requirements:

Executed by an authorized user
Refers to a specific type of transaction
Has a unique identifier to distinguish it from other requests

To fulfill these requirements, the message body for each supported request must contain the required token, opcode, and guid parameters filled in.

The details of how these parameters should be applied are described below.

Authorization

All operations performed using WebSocket API require authorization to confirm the identity of API users and their rights to perform the requested actions. To confirm these rights, the Access Token of the API user passed to the server as the value of the token parameter is used.

Unlike subscription management commands, Access Token must be provided to the /cws interface as a part of a standalone command for authorization of the entire connection.

To authorize a WebSocket connection, send a request with the authorize operation code in the opcode parameter and your Access Token in the token parameter.

Example of authorization request body

{
  "opcode": "authorize",
  "guid": "c328fcf1-e495-408a-a0ed-e20f95d6b813",
  "token": "eyJhbGciOiJ..."
}

In case of success, the server will respond with a single 200 code message confirming that the connection has been authorized.

Example of response body confirming authorization of connection

200. Request handled successfully
{
  "requestGuid": "c328fcf1-e495-408a-a0ed-e20f95d6b813",
  "httpCode": 200,
  "message": "The connection has been initialized."
}

After that, all following messages sent within the same WebSocket connection will be considered authorized until the connection is closed or the Access Token expires.

caution

The system performs token validation only when receiving client messages. Token validation without messages is not supported. It means that the system does not inform about expiration of the token used for connection authorization, and users should control it themselves.

The expiration date of Access token is 30 minutes from the moment of creation. It is recommended to refresh the connection authorization from time to time by resending the request for authorization containing a new token. It is recommended to set the refresh period a few minutes shorter than the token validity period.

note

WebSocket connections are isolated from each other, so authorization applies only to the connection within which the request was made.

If authorization fails (For example, the provided Access Token is invalid), the server will return a response with the code 401 and immediately terminate the connection.

Example of a message body containing a subscription creation rejection

401. Failed to authorize the request
{
  "requestGuid": "c328fcf1-e495-408a-a0ed-e20f95d6b813",
  "httpCode": 401,
  "message": "Invalid JWT token!"
}

Summary

Request execution requires user authorization
Authorization applies to the WebSocket connection, spreading to all requests executed within it
Authorization of each WebSocket connection should be done separately
Authorization uses a standalone request with the authorize operation code and a valid Access Token in the token parameter.
The Access Token used must be valid for both the selected system environment and the moment the request is executed.
The WebSocket connection remains authorized until terminated or the used Access Token expires
Failed authorization attempt or execution of other requests without authorization terminates the WebSocket connection

Identification

Within a single authorized WebSocket connection API user can send an unlimited number of requests for order creation, modification and deletion. To avoid duplication of requested actions, each request must contain a unique operation identifier passed to the server in the guid parameter.

tip

The guid parameter should be assigned to the subscription by the API user, not by the server. Ensure that the software you are using provides a mechanism for generating such values.

As the value of the guid parameter, the server accepts any custom string value unique to the established WebSocket connection. The following combinations of characters will be equal as a valid value:

123456
abcdefABCDEF
!@№;%:?*()-_=+/|"'
c328fcf1-e495-408a-a0ed-e20f95d6b813
Client-31075-Delete-StopLimit-185117

So, depending on the task, the guid can contain either a randomly generated or a personalized value.

Escaping wildcard characters

When using wildcard characters as part of the identifier, make sure to preserve the integrity of the JSON object being sent. Symbols breaking the syntax should be excluded or escaped with the \ symbol. The escape character is not counted as part of the identifier, so, for example, the value /|\" will be interpreted by the system as /|".

WebSocket connections are isolated from each other, so the same value of the guid parameter can be used in multiple requests if they are created in different connections.

Each request within a WebSocket connection must have a unique guid value regardless of the type of operation performed. For example, requests for authorization, creation of a market order and its withdrawal, performed within one connection, will require three different guid values. If a message with a non-unique value is received, the server will reject the request with the response code 400 and the message Request with such Guid has already been handled and then terminate the connection. This is one of the differences between the subscription management and the order management interfaces.

Summary

A single WebSocket connection supports the ability to process multiple requests simultaneously
Each request must contain filled in guid parameter
Response messages returned by the server within a subscription contain the same guid value that was passed to the server in the initial message
The guid parameter must be filled in by the API user
The value of the parameter can be random
Wildcard characters breaking JSON object integrity must be escaped or excluded from the value of the parameter
The parameter value must be unique for the WebSocket connection used. Only the value that has not been used in requests since the connection was established is considered unique
The same value of the guid parameter can be used without any consequences in other WebSocket connections
Using a non-unique value when managing orders will cause request processing error with the subsequent connection termination

Operation code

When working with HTTP API, all user actions are determined by the resource URL specified as a path and HTTP verb specifying the interaction method (GET, PUT, POST, DELETE). In case of WebSocket API, the interaction method is determined by the operation code passed within the client message sent to the WebSocket connection.

As with HTTP verbs, the operation codes are strictly defined and do not allow for changes in spelling. The difference is that HTTP verbs are defined by the generally accepted standard RFC 9110, whereas for the WebSocket API the operation codes are defined by the system creators.

The exact code value for each operation is provided on the description page of the corresponding request.

Example

To create a market order, use the create:market operation code. This code must be passed to the system as-is to successfully execute the request.

Such options as Create:Market, createmarket, market:create or create:marketorder will be rejected by the system as unknown operations.

Sending request

To manage orders, send to the established WebSocket connection a command containing in its body an executable operation code (opcode), a unique identifier (guid) and additional parameters defining the details of the order.

Example body of a request to create limit order:

{
  "opcode": "create:limit",
  "guid": "c328fcf1-e495-408a-a0ed-e20f95d6b813",
  "side": "buy",
  "quantity": 1,
  "price": 142.52,
  "instrument": {
    "symbol": "SBER",
    "exchange": "MOEX"
  },
  "comment": "First order",
  "board": "TQBR",
  "user": {
    "portfolio": "D39004"
  },
  "timeInForce": "OneDay",
  "icebergFixed": 100,
  "icebergVariance": 2,
  "checkDuplicates": true
}

Where:

opcode is the code of requested operation
guid is the unique user identifier
side is the trade side (buy or sell)
quantity is the number of financial asset lots
price is the desired lot price
symbol is the security code (ticker)
exchange is the exchange code
comment is a custom comment
board is the trading mode code (Board)
portfolio is the client portfolio ID
timeInForce is the order type
icebergFixed is visible constant part of iceberg order in lots
icebergVariance is the deviation amplitude (% of icebergFixed) of the random increment to the visible part of the iceberg order
checkDuplicates is the flag for checking the uniqueness of commands

note

The value for the guid field should be provided by the user. Ensure that the software you are using provides a mechanism for generating unique identifiers for the messages you send.

Limitations and recommendations

When using the WebSocket API, keep in mind the following limitations and conditions applied by the system.

Limitation	Recommendation
A large number of active WebSocket connections negatively affects system stability. Actions that harm the system may lead to temporary blocking of the user who committed such behavior	Use a single connection to send all commands related to order management or use HTTP API resources if the intensity of trading allows to do so

Interfaces​

Creating a request​

Authorization​

Identification​

Operation code​

Sending request​

Limitations and recommendations​