API Documentation

Development guide

Authentication

There are 2 ways to start the session:

• Using your API key, login and password details.
• Using your API key, login and encrypted password details.

1. API key, login and password details. The value of the encryptionKey parameter in the POST/session endpoint = false

   • Here you should simply use the POST​​/session endpoint and mention the received in the platform’s Settings API key in the X-CAP-API-KEY header, login and password info in the identifier and password parameters.

2. API key, login and encrypted password details. The value of the encryptionKey parameter in the POST/session endpoint = true

   • First of all you should use the GET ​/session​/encryptionKey and mention the generated in the platform’s Settings API key in the X-CAP-API-KEY header. As a response you will receive the encryptionKey and timestamp parameters;

   • Using the received encryptionKey and timestamp parameters you should encrypt your password using the AES encryption method.

     Encryption request example:

     public static String encryptPassword(String encryptionKey, 
     Long timestamp, String password) {
     try {
      byte[] input = stringToBytes(password + "|" + timestamp);
      input = Base64.encodeBase64(input);
      KeyFactory keyFactory = KeyFactory.getInstance(RSA_ALGORITHM);
      PublicKey publicKey = keyFactory.generatePublic(new 
      X509EncodedKeySpec 
      (Base64.decodeBase64 (stringToBytes(encryptionKey))));
      Cipher cipher = Cipher.getInstance(PKCS1_PADDING_TRANSFORMATION);
      cipher.init(Cipher.ENCRYPT_MODE, publicKey);
      byte[] output = cipher.doFinal(input);
      output = Base64.encodeBase64(output);
      return bytesToString(output);
      } catch (Exception e) {
      throw new RuntimeException(e);
      }
     }

     Copy code

     Encrypted password example:

     encryptionKey = 
     "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBC
     gKCAQEA1dOujgcFh/9n4JLJMY4VMWZ7aRrynwKXUC9
     RuoC8Qu5UOeskxgZ1q5DmAXjkes77KrLfFZYEKtrp2g1TB
     0MBkSALiyrG+Fl52vhET9/AWRhvHuFyskWI7tEtcGIaOB1FwR0
     EDO9bnylTaZ+Y9sPbLVA7loAtfaX3HW/TI9JDpdmgz
     XZ0KrwIxdMRzPxVqQXcA8yJL1m33pvo9mOJ0AsQ8FFuy+
     ctjI8l/8xUhe2Hk01rpMBXDwI1lSjnvuUUDvAta
     cxyYVlNsnRvbrMZYp7hyimm27RtvCUXhTX2A94t
     DB0MFLApURrki+tvTvw5ImDPN8qOdTUzbs8hNtV
     wTpSxPwIDAQAB";
     timestamp = 1647440528194;
     password = "1111qqqq";
     // Result of password encryption with the encryptionKey
     encryptedPassword = "hUxWlqKRhH6thdjJnR7DvdlGE
     7ABkcKHrzKDGeE7kQ7nKg91sw7BpYsLDqtxihnlHN2IEmF
     PZ/ZmOKBAwEAw9/vjELmAZDeKsu3Q6s+Koj4wt8giE1Sxv
     76JjjOB/667dEeL22IFO1rwTMZ1NS5DrfeYbTfOdQgA0v5
     eIOS3fH8Pp/mFHodibY28X+zIaNwk6Rcb49l6aiXwM1CAt
     Dl359qK633a+sEB9TR0/C3EaRkuGg8wAQyQ0JERaSYOZ58
     Dx7pw//cmvk/U5dkQlgli2l6Ts2cMhqYXCD1ZlTDA/rLfl
     52lgnarfari3n0uh6LicmNeWXJBF5oxj3LCruVwMA==";

     Copy code

   • Go to the POST ​​/session endpoint, set true value for the encryptedPassword parameter and mention the received in the platform’s Settings API key in the X-CAP-API-KEY header, login and prior encrypted password info in the identifier and password parameters.

On starting the session you will receive the CST and X-SECURITY-TOKEN parameters in the response headers. CST is an authorization token, X-SECURITY-TOKEN shows which financial account is used for the trades. Both of these tokens are to be used in the headers of every request sent.

Symbology

• Financial accounts
  accountId is the ID of your financial account. Each financial account has its unique ID. To view the full list of the available financial accounts, use the GET ​​/accounts endpoint. To find out which financial account is used for trading operations in the API please go to the GET​/session endpoint. To change the financial account use: PUT ​/session
• Epic
  Epic is the name of the market pair. You can use the GET /markets{?searchTerm} endpoint to find the market pairs you are interested in. A simple market name like ‘Bitcoin’ or ‘BTC’ can be requested with the searchTerm parameter and you will receive the full list of the market pairs associated with it. The GET ​/marketnavigation endpoint can be used to obtain asset group names. These names can be used with the GET ​​/marketnavigation​/{nodeId} endpoint to view the list of assets under the corresponding group.
• Watchlists
  The Watchlist is the list of assets which can be seen and created on the platform. The GET /watchlists end point returns the existing watchlists on your account. Each watchlist has an id parameter which can be used to obtain the corresponding list of assets: GET ​/watchlists​/{watchlistId}

Notes on orders and positions

• When opening a position using the POST /positions endpoint a dealReference parameter is included in the response. However, a successful response does not always mean that the position has been successfully opened. The status of the position can be confirmed using GET ​/confirms​/{dealReference}. This will produce the status of the position together with the affectedDeals array. Note that several positions can be opened at a time: this info will be shown in the affectedDeals array.
• It is important to ensure that the correct trading mode is in use with the API. To find out which trading mode is set on your financial account use the GET ​/accounts​/preferences method. The hedgingMode parameter value shows whether the hedging mode is engaged. This value can be altered using endpoint: PUT ​/accounts​/preferences
• The leverages set for trades can be obtained using the GET ​​/accounts​/preferences endpoint. To change leverages, use PUT ​​/accounts​/preferences
• Note: Stop loss and take profit values cannot be set when conducting trades with real stocks.

Status codes