Skip to main content

Test environment

tip

This guide describes interaction with the Test environment of the system, designed to test requests and the code based on them without using the resources of a real trading account. The guide for the Production environment providing access to real trades is described here.

Step 1: Registering a developer account​

Developer account is required to get access to the request authorization mechanisms of the trading system.

Already done?

If the developer account has been registered earlier, go to next step.

Follow the steps below to create a developer account:

  1. Go to Developer Portal and click the Authorize button in the upper right corner
  2. Click the Register link below the authorization form
  3. Fill in the required fields and click `Register' button
  4. Confirm the e-mail address used for registration by clicking on the link from the automatically sent e-mail.
  5. Go to authorization page and log in to the created developer account with the data specified during registration

Registration of a developer account is a one-time process and will not be needed to be repeated each API request.

Details

More information about the developer account is provided in related article.

Step 2: Getting a trading account​

Most API requests require execution using a specific trading account for authorization purposes. Test Environment interacts with the simulation environment of the exchange and uses simulated data in its operation, because of which the trading account must also be a test account.

To get a test trading account or change the list of portfolios belonging to it, leave a request at support@alor.ru or contact us in telegram.

Test account cannot be bind to the developer account as it happens with real trading account. Keep the login and password from the provided account for the entire testing period.

Step 3: Getting Refresh token​

The only option to confirm the right to send requests to Test environment is to use JWT token.

This option allows to authorize requests with the short-term Access token created with the Refresh token.

Test trading account is designed to test requests and therefore allows you to get only one Refresh token at a time without providing information about creation and expiration date.

Already done?

If Refresh Token has been created earlier and not expired yet, go to next step.

Do the following steps to get a Refresh token for Test environment:

  1. Go to the API Access Tokens page
  2. Click the Tokens for trading in Test environment can be obtained here. link in the “Test environment” section at the bottom of the page
  3. Click the `Begin OAuth authorization flow' link on the next page
  4. Enter the credentials of the test trading account received from technical support in the fields and click Login
  5. Check the list of access rights granted for the test trading account and click Allow
  6. Save the displayed Access and Refresh tokens to a safe place

Once the last action is done, close the tab or go to documentation describing supported requests.

Details

More information about Refresh tokens is available in related article.

Step 4: Getting Access token​

Most of the private system resources require the user to have respective access rights. When proving permissions with JWT, each request must contain an Access token created with the Refresh token received earlier.

Already done?

The first Access Token for a test trading account will be created automatically when you receive a Refresh Token. This token is valid for 30 minutes from the moment of creation. If it has not expired yet, go to next step.

To get an Access token, send a POST request to the /refresh endpoint of the authorization server. In the Test environment, this server is accessible at https://oauthdev.alor.ru.

Submitted request must contain a valid Refresh token.

Example
https://oauthdev.alor.ru/refresh?token=12b...cac

Where 12b...cac is Refresh Token.

In response, the authorization server will return a JSON object containing the Access Token:

{
  "AccessToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6IkpXVCJ9.eyJzdWIiOiJMb2dpblNhbXBsZSIsImVudCI6ImNsaWVudCIsImVpbiI6IjAxMjM0IiwiY2xpZW50aWQiOiIwMTIzNDU2IiwiYXpwIjoiMDEyMzQ1Njc4OWFiY2RlZjAxMjMiLCJhZ3JlZW1lbnRzIjoiQWdyZWVtZW50U2FtcGxlMSBBZ3JlZW1lbnRTYW1wbGUyIEFncmVlbWVudFNhbXBsZTMiLCJwb3J0Zm9saW9zIjoiUG9ydGZvbGlvU2FtcGxlMSBQb3J0Zm9saW9TYW1wbGUyIFBvcnRmb2xpb1NhbXBsZTMiLCJzY29wZSI6Ik9yZGVyc1JlYWQgT3JkZXJzQ3JlYXRlIFRyYWRlcyBQZXJzb25hbCBTdGF0cyIsImV4cCI6Mjg3MTc2MzE5OSwiaWF0IjowLCJpc3MiOiJBbG9yLklkZW50aXR5IiwiYXVkIjoiQ2xpZW50IFdBUlAgV2FycEFUQ29ubmVjdG9yIHN1YnNjcmlwdGlvbnNBcGkgQ29tbWFuZEFwaSBJbnN0cnVtZW50QXBpIFRyYWRpbmdWaWV3UGxhdGZvcm0ifQ.QOQVMIAoZ6SnF5urnIzJ0EvtQd9P5Sx355069kXoID207wHOTW0wkKNMcrIKXmENEQQ_0yDjqH_kjeqWLBJuqA"
}

The received token is valid for 30 minutes from the moment of creation. If the token expires, repeat the action described above to create a new token.

Interactive description

The request to update Access Token has an interactive description on the JWT Token.

Details

More information about Access Tokens is available in related article.

Step 5: Sending requests​

Interaction with ALOR Broker API is possible both via HTTP API and WebSocket API. Some operations supported by the trading system are available in both options of interaction.

Getting order book​

The HTTP API gives the ability to interact with the system within a short-term connection designed for one-time messaging — one response per request. The response returned by the server contains information that is up to date for the moment the request is submitted. To update the received data after a while, you will need to repeat the same request on your own.

To get information about the order book of the requested instrument on the desired exchange via HTTP API, send a GET request to the /md/v2/orderbooks/{exchange}/{symbol} endpoint of the API server. Note that:

  • Test environment API server is available at https://apidev.alor.ru;
  • {exchange} must contain the actual code of the exchange;
  • {symbol} must contain the actual code (ticker) of the instrument.
Request parameters

Make sure that all necessary path-, query-, and header-parameters are filled in before executing the query.

Example of URL
https://apidev.alor.ru/md/v2/orderbooks/MOEX/SBER

If required, add supported query-parameters to the URL:

  • depth is the desired data depth. Standard value is 20 (20x20), maximum — 50 (50x50).
  • format is the format of the JSON object returned by the server: Simple, Slim, Heavy. Standard value: Simple.
Example URL with query parameters
https://apidev.alor.ru/md/v2/orderbooks/MOEX/SBER?depth=1&format=Simple

The /md/v2/orderbooks/ endpoint is a protected resource and requires authorization to execute requests. Add the Authorization parameter to the request header with the value Bearer <Token>, where <Token> is the previously obtained Access token.

If all parameters are correct, the server will return a JSON object with the requested information.

{
  "snapshot": true,
  "bids": [
    {
      "price": 281.98,
      "volume": 36
    }
  ],
  "asks": [
    {
      "price": 281.99,
      "volume": 11
    }
  ],
  "timestamp": 1701105939,
  "ms_timestamp": 1701105939395,
  "existing": true
}

If the request syntax is invalid or incorrect values are specified, the server will return a JSON object corresponding to the error.

Details

More information about the order book request is available on the interactive request description page.

Creating a market order​

Request parameters

Make sure that all necessary path-, query-, and header-parameters are filled in before executing the query.

To create a market order to buy a security on the selected exchange via HTTP API, send a POST request to the /commandapi/warptrans/TRADE/v2/client/orders/actions/market endpoint of the API server. Note that:

  • Test environment API server is available at https://apidev.alor.ru;
  • All order parameters must be passed in the request body.
Example of URL
https://apidev.alor.ru/commandapi/warptrans/TRADE/v2/client/orders/actions/market

The /commandapi endpoints are private resources and require authorization to execute requests. Add the Authorization parameter to the request header with the value Bearer <Token>, where <Token> is the previously obtained access-token.

Example of HEAD parameter
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6IkpXVCJ9.eyJzdWIiOiJMb2dpblNhbXBsZSIsImVudCI6ImNsaWVudCIsImVpbiI6IjAxMjM0IiwiY2xpZW50aWQiOiIwMTIzNDU2IiwiYXpwIjoiMDEyMzQ1Njc4OWFiY2RlZjAxMjMiLCJhZ3JlZW1lbnRzIjoiQWdyZWVtZW50U2FtcGxlMSBBZ3JlZW1lbnRTYW1wbGUyIEFncmVlbWVudFNhbXBsZTMiLCJwb3J0Zm9saW9zIjoiUG9ydGZvbGlvU2FtcGxlMSBQb3J0Zm9saW9TYW1wbGUyIFBvcnRmb2xpb1NhbXBsZTMiLCJzY29wZSI6Ik9yZGVyc1JlYWQgT3JkZXJzQ3JlYXRlIFRyYWRlcyBQZXJzb25hbCBTdGF0cyIsImV4cCI6Mjg3MTc2MzE5OSwiaWF0IjowLCJpc3MiOiJBbG9yLklkZW50aXR5IiwiYXVkIjoiQ2xpZW50IFdBUlAgV2FycEFUQ29ubmVjdG9yIHN1YnNjcmlwdGlvbnNBcGkgQ29tbWFuZEFwaSBJbnN0cnVtZW50QXBpIFRyYWRpbmdWaWV3UGxhdGZvcm0ifQ.QOQVMIAoZ6SnF5urnIzJ0EvtQd9P5Sx355069kXoID207wHOTW0wkKNMcrIKXmENEQQ_0yDjqH_kjeqWLBJuqA

Additionally, all requests related to orders must contain a unique request identifier created by the sender. The X-REQID header parameter is used to pass the identifier.

Example of HEAD parameter
X-REQID: d3c886f1-ea1e-4634-aff4-119c902ad926

The value of the X-REQID parameter can be any as long as the following requirements are met:

  • The value must be unique. If a previously used value is sent, the server will reject the request
  • The value must not break the JSON schema. For example, escape special characters (if used) when generating values

Order conditions are passed as a JSON object in the request body:

{
  "side": "buy",
  "type": "market",
  "quantity": 1,
  "instrument": {
    "symbol": "SBER",
    "exchange": "MOEX"
  },
  "comment": "Note no.451",
  "user": {
    "portfolio": "D39004"
  }
}

If the URL, body and header of the request are filled in correctly, the server will return a JSON object with the number of the created order.

Example of response body
{
  "message": "success",
  "orderNumber": "409...153"
}

If the request syntax is invalid or incorrect values are specified, the server will return a JSON object corresponding to the error.

The created order can then be viewed, modified or canceled using the corresponding requests.

Details

More information about the market order request is available on the interactive request description page.

What's next?​

Additionally, we recommend reading the following related articles: