Scan to Download ios&Android APP

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);
       }
      }

      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==";
    • Go to the POST ​​/session endpoint, set true value for the encryptionKey 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

Status code Meaning
200 The request is successful.
HTTP/1.1 200 OK
400 There is a mistake in the request itself, i.e. wrong parameter value, the required parameter/header is not mentioned.
HTTP/1.1 400 Bad Request
{
 "errorCode": "error.invalid.from"
}
401 An authorisation mistake, i.e. the session has expired, the token is incorrect, etc.
HTTP/1.1 401 Unauthorized
{
 "errorCode": "error.security.token-invalid"
}
404 The requested value is not found, i.e. epic, watchlist id, etc.
HTTP/1.1 404 Not Found
{
 "errorCode": "error.epic.not-found"
}

Still looking for a broker you can trust?


Join the 400.000+ traders worldwide that chose to trade with Capital.com

1. Create & verify your account

2. Make your first deposit

3. You’re all set. Start trading