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.
API key, login and password details. The value of the
encryptionKey
parameter in thePOST/session
endpoint =false
- Here you should simply use the
POST/session
endpoint and mention the received in the platform’s Settings API key in theX-CAP-API-KEY
header, login and password info in theidentifier
andpassword
parameters.
- Here you should simply use the
-
API key, login and encrypted password details. The value of the
encryptionKey
parameter in thePOST/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 theX-CAP-API-KEY
header. As a response you will receive theencryptionKey
andtimestamp
parameters;-
Using the received
encryptionKey
andtimestamp
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, settrue
value for theencryptedPassword
parameter and mention the received in the platform’s Settings API key in theX-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 theGET /accounts
endpoint. To find out which financial account is used for trading operations in the API please go to theGET/session
endpoint. To change the financial account use:PUT /session
- Epic
Epic is the name of the market pair. You can use theGET /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. TheGET /marketnavigation
endpoint can be used to obtain asset group names. These names can be used with theGET /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. TheGET /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 adealReference
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 usingGET /confirms/{dealReference}
. This will produce the status of the position together with theaffectedDeals
array. Note that several positions can be opened at a time: this info will be shown in theaffectedDeals
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. ThehedgingMode
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, usePUT /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.
|
401 | An authorisation mistake, i.e. the session has expired, the token is incorrect, etc.
|
404 | The requested value is not found, i.e. epic, watchlist id, etc.
|