CFDs are complex instruments and come with a high risk of losing money rapidly due to leverage. 76% of retail investor accounts lose money when trading CFDs with this provider. You should consider whether you understand how CFDs work and whether you can afford to take the high risk of losing your money.
US English

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 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

Status codeMeaning
200The request is successful.
HTTP/1.1 200 OK
400There 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" }

401An authorisation mistake, i.e. the session has expired, the token is incorrect, etc.

HTTP/1.1 401 Unauthorized { "errorCode": "error.security.token-invalid" }

404The 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 640,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