All API calls in this section are made by the broker’s backend to the cTrader backend.
| Method | URL |
|---|---|
POST |
/webserv/managers/token |
Creates a manager token required for API authentication. This token does not have an expiration period.
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
hashedPassword |
Yes | string | The MD5 of the manager’s password. |
login |
Yes | integer | The unique ID of the manager. |
Output
| Key | Data Type | Description |
|---|---|---|
webservToken |
string | A long-term token authenticating the manager. |
Request Example
curl -X POST ‘https://HOST:PORT/v2/webserv/managers/token’ -H ‘Accept:application/json’ -H ‘Content-Type: application/json’ -d ‘{"hashedPassword": "0f94e246908667af85916300c57f74b6", "login": 2309}’
Expected Response Status Code
200
Response Example
{
"webservToken": "04d95575-c9af-42fba72e-2f0ce93f01d4"
}
| Method | URL |
|---|---|
POST |
/oauth2/ctid/create |
Creates a new user via the SSO (OAuth) flow.
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
brokerCrmName |
Yes | string | See Section 2.3. |
email |
Yes | string | The user’s email address. |
firstName |
No | string | The user’s first name. The value of this parameter can be used for sending notifications (e.g., ‘Dear {name}’). |
preferredLanguage |
No | string | The user’s preferred language. The parameter takes Alpha-2 (ISO 369-2) codes as values. |
Output
| Key | Data Type | Description |
|---|---|---|
userId |
integer | The unique ID of a specific user. |
Request Example
curl -X POST ‘https://HOST:PORT/cid/oauth2/ctid/create?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ -H ‘Content-Type: application/json’ -H ‘Accept: application/json’ -d ‘{"brokerCrmName": "BESTBROKERCRM", "email": "president!bestbroker.com", "firstName": "Trader", "preferredLanguage": "en"}’
Expected Response Status Code
201
Response Example
{
"userId": 10345533
}
| Method | URL |
|---|---|
POST |
/webserv/traders |
Creates a new trading account.
Parameters
No parameters.
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
accessRights |
Yes | enum | The access rights given to the new account. Can be limited to closing positions (CLOSE_ONLY), a total ban on trading (NO_TRADING), and removal of all login rights (NO_LOGIN). The default value is FULL_ACCESS. |
accountType |
Yes | enum | The type of the newly created account. The values include HEDGED, NETTED, and SPREAD_BETTING; HEDGED is the default value. |
balance |
Yes | integer | The balance of the new account. You can use this parameter to create demo accounts with a non-zero balance. Note that balance is specified in 10^2. A balance value of 56445 would equal to 564.45 in the account base currency units. If JPY is the account currency, the last two digits in balance must be zero. |
brokerName |
No | string | See Section 2.3. |
contactDetails |
Yes | object | A JSON object containing the trader’s address, phone number, and other details. |
contactDetails.address |
No | string | The trader’s address of residence. |
contactDetails.city |
No | string | The trader’s city of residence. |
contactDetails.countryId |
No | integer | The identifier of the trader’s country of residence. |
contactDetails.documentId |
No | string | The trader’s unique document ID. |
contactDetails.email |
No | string | The trader’s email address. |
contactDetails.phone |
No | string | The trader’s phone number. |
contactDetails.state |
No | string | The trader’s state of residence. |
contactDetails.zipCode |
No | string | The zip code of the trader’s residence. |
depositCurrency |
Yes | string | The currency that the account uses for making deposits and withdrawals. |
description |
No | string | A brief description of the account |
groupName |
Yes | string | The name of the group to which the account is assigned. |
hashedPassword |
Yes | string | The MD5 of the account password. |
isLimitedRisk |
Yes | boolean | The trader’s limited risk (LR) status. All positions of LR accounts must have guaranteed stop lossses. |
lastName |
No | string | The trader’s last name. |
leverageInCents |
Yes | integer | The default leverage available to the account. This value is specified in 10^2. The value of 12515 would signify a 1:121.15 leverage. |
limitedRiskMarginCalculationStrategy |
No | enum | The margin calculation strategy used for a limited risk account. Can be ACCORDING_TO_LEVERAGE, ACCORDING_TO_GSL, and ACCORDING_TO_GSL_AND_LEVERAGE. |
maxLeverage |
No | integer | The maximum leverage (in base currency units) available to an account. This value is specified in 10^2. |
name |
No | string | The name of the account. |
sendOwnStatement |
No | boolean | A flag determining whether a daily trading statement is sent to the trader. |
sendStatementToBroker |
No | boolean | A flag determining whether a daily account trading statement is sent to the broker. |
totalMarginCalculationType |
No | boolean | The strategy for calculating the total margin used by the account. The value can equal MAX, SUM, and NET. |
Output
Several keys from the request body are repeated in the output, namely accessRights, accountType, balance, brokerName, contactDetails, depositCurrency, description, groupName, isLimitedRisk, lastName, leverageInCents, limitedRiskMarginCalculationStrategy, maxLeverage, name, sendOwnStatement, sendStatementToBroker, and totalMarginCalculationType.
| Key | Data Type | Description |
|---|---|---|
bonus |
integer | The total amount of bonus allocated to the account. Subject to moneyDigits. |
equity |
integer | The account equity. Subject to moneyDigits. |
freeMargin |
integer | The amount of free margin available to the account. Subject to moneyDigits. |
lastUpdateTimestamp |
integer | A timestamp with the date and time of the latest account update. |
login |
integer | The number of a specific trading account. |
moneyDigits |
integer | See Section 2.1.. |
nonWithdrawableBonus |
integer | The total amount of the non-withdrawable bonus allocated to the account. Subject to moneyDigits. |
registrationTimestamp |
integer | A timestamp with the date and time of account registration. |
swapFree |
boolean | If true, rollover commissions are applied to the account instead of swaps. The reverse applies if false. Charging rollover commissions is in compliance with Sharia law. |
usedMargin |
integer | The total amount margin used by the account. Subject to moneyDigits. |
Request Example
curl -X POST ‘https://HOST:PORT/v2/webserv/traders?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ -H ‘Accept: application/json’ -H ‘Content-Type: application/json’ -d ‘{"accessRights": "FULL_ACCESS", "accountType": "HEDGED", "balance": 1000, "brokerName": "BESTBROKER", "contactDetails": {"address": "Moon", "city": "Lake", "countryId": 8, "documentId": "0123", "email": "president@bestbroker.com", "phone": "+50987654321", "state": "RE ", "zipCode": "5500"},"depositCurrency": "EUR", "description": "string", "groupName": "Default", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "isLimitedRisk": false, "lastName": "President ", "leverageInCents": 10000, "maxLeverage": 100000, "name": "Best", "sendOwnStatement": true, "sendStatementToBroker": true, "totalMarginCalculationType": "MAX"}’
Expected Response Status Code
201
Response Example
{
"accessRights": "FULL_ACCESS",
"accountType": "HEDGED",
"balance": 1000,
"brokerName": "BESTBROKER",
"contactDetails": {
"address": "Moon",
"city": "Lake",
"countryId": 8,
"documentId": "0123",
"email": "president@bestbroker.com",
"phone": "+50987654321",
"state": "RE ",
"zipCode": "5500"
},
"depositCurrency": "EUR",
"description": "string",
"groupName": "Default",
"isLimitedRisk": false,
"lastName": "President ",
"leverageInCents": 10000,
"maxLeverage": 100000,
"name": "Best",
"sendOwnStatement": true,
"sendStatementToBroker": true,
"totalMarginCalculationType": "MAX",
"bonus": 0,
"equity": 0,
"freeMargin": 1000,
"lastUpdateTimestamp": 1598862013825,
"login": 8673590,
"moneyDigits": 2,
"nonWithdrawableBonus": 0,
"registrationTimestamp": 1598862013824,
"swapFree": false,
"usedMargin": 0
}
| Method | URL |
|---|---|
POST |
/ctid/link |
Links an existing trading account to a previously created user.
Parameters
No parameters.
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
traderLogin |
Yes | integer | The number of a specific trading account. It is equivale to the login key in API call 3.3. |
traderPasswordHash |
Yes | string | The MD5 of the account password. |
userId |
Yes | integer | The unique ID of a specific user. |
brokerName |
Yes | string | See Section 2.3.. |
environmentName |
Yes | string | The name of the current server environment ("live" or "demo"). |
returnAccountDetails |
Yes | boolean | A flag determining whether the ctidTraderAccountId key is returned in the response to this request. Set it to true to ensure that the response to this API call is not empty. |
Output
| Key | Data Type | Description |
|---|---|---|
ctidTraderAccountId |
integer | The unique ID of the linkage between a specific user and one of their trading accounts. |
Request Example
curl -X POST 'https://HOST:PORT/cid/ctid/link?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"environmentName": "demo", "brokerName": "BESTBROKER", "traderLogin": 8673590, "traderPasswordHash": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "userId": 10345533, "returnAccountDetails": true}'
Expected Response Status Code
201
Response Example
{
"ctidTraderAccountId": 9017800
}
Note that the response body will be empty if
returnAccountDetailsisfalse.
| Method | URL |
|---|---|
POST |
/webserv/traders/{login}/changebalance |
Changes the balance of a given account.
Note that
preciseAmounthas to be a non-negative value. To differentiate between deposits and withdrawals, use thetypekey.
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
login |
path | Yes | integer | The number of a specific trading account. |
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
comment |
No | string | A short note that can be attached to any balance change. This note is not shown to traders. |
externalId |
No | string | A number that matches an external identifier of the broker’s choosing. For instance, externalId could be equal to the number of the bank transfer order through which the user chose to make a deposit. |
externalNote |
No | string | A brief comment attached to the deposit/withdrawal. In contrast to comment, this text is displayed to traders. |
login |
Yes | integer | The number of a specific trading account. |
preciseAmount |
Yes | number | The precise amount of withdrawn or deposited funds. Specified as a decimal number. For BTC and similar assets, the value of preciseAmount can include as many as eight digits after the decimal point. |
source |
No | string | The designated source of the deposit/withdrawal. |
type |
Yes | string | The desired type of balance change (can equal either "DEPOSIT" or "WITHDRAW"). |
Output
| Key | Data Type | Description |
|---|---|---|
balanceHistoryId |
integer | The unique number of the balance history of a specific trading account. |
Request Example
curl -X POST ‘https://HOST:PORT/v2/webserv/traders/8673590/changebalance?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ -H ‘accept: application/json’ -H ‘Content-Type: application/json’ -d ‘{"comment": "any", "externalId": "34456778", "externalNote": "example", "login": 8673590, "preciseAmount": 123.45, "source": "wire", "type": "DEPOSIT"}’
Expected Response Status Code
200
Response Example
{
"balanceHistoryId": 6340680
}
| Method | URL |
|---|---|
PUT |
/oauth2/ctid/referral |
Creates a new partner by linking a partner identifier (a string) from the broker’s backend to an existing user or an existing account on the cTrader backend.
Parameters
No parameters.
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
brokerCrmName |
Yes | string | See Section 2.3.. |
partnerId |
Yes | string | The string assigned as a partner identifier to a specific user or an account. |
userId |
No (if the chosen partner is an account) | integer | The unique ID of a specific user. |
ctidTraderAccountId |
No (if the chosen partner is a user) | integer | The unique ID of the linkage between a specific user and one of their trading accounts. |
The request body can include either a
userIdor actidTraderAccountIddepending on the entity to which the partner identifier is assigned. To elaborate,userIdis a mandatory parameter if the identifier is assigned to a user; alternatively,ctidTraderAccountIdis a mandatory parameter if the identifier is assigned to an account.
Request Example
curl -X PUT ‘https://HOST:PORT/cid/oauth2/ctid/referral?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ -H ‘Content-Type: application/json’ -H ‘Accept: application/json’ -d ‘{"brokerCrmName": "BESTBROKERCRM", "ctidTraderAccountId": 9017800, "partnerId": "somePartnerId", "userId": 10345533}’
Expected Response Status Code
200
| Method | URL |
|---|---|
GET |
oauth2/ctid/referral |
Retrieves the unique partner identifier of a specific partner entity.
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
userId |
query | No (if the partner entity is an account) | integer | The unique ID of a specific user. |
ctidTraderAccountId |
query | No (if the partner entity is a user) | integer | The unique ID of the linkage between a specific user and one of their trading accounts. |
brokerCrmName |
query | Yes | string | See Section 2.3.. |
The request body can include either a
userIdor actidTraderAccountIddepending on the entity to which the partner identifier is assigned. To elaborate,userIdis a mandatory parameter if the identifier is assigned to a user; alternatively,ctidTraderAccountIdis a mandatory parameter if the identifier is assigned to an account.
Output
| Key | Data Type | Description |
|---|---|---|
ctidTraderAccountId |
integer | The unique ID of the linkage between a specific user and one of their trading accounts. |
userId |
integer | The unique ID of a specific user. |
partnerId |
string | The string assigned as a partner identifier to a specific user or an account. |
Request Example
curl -X GET "https://HOST:PORT/cid/oauth2/ctid/referral?token=token=04d95575-c9af-42fba72e-2f0ce93f01d4?ctidTraderAccountId=9017800&brokerCrmName=BESTBROKERCRM" -H "Accept: application/json"
Expected Response Status Code
200
Response Example
{
"userId": 10345533,
"ctidTraderAccountId": 9017800,
"partnerId":"somePartnerId"
}
| Method | URL |
|---|---|
DELETE |
oauth2/ctid/referral |
Deletes the partner identifier attached to a specific partner entity.
Parameters
No parameters.
Request Body
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
userId |
query | Yes | integer | The unique ID of a specific user. |
ctidTraderAccountId |
query | No | integer | The unique ID of the linkage between a specific user and one of their trading accounts. |
brokerCrmName |
query | Yes | string | See Section 2.3.. |
If ctidTraderAccountId is unspecified, only a record with an unspecified account will be deleted.
Request Example
curl -X DELETE "https://HOST:PORT/cid/oauth2/ctid/referral?token=token=04d95575-c9af-42fba72e-2f0ce93f01d4?userId=10345533?ctidTraderAccountId=9017800&brokerCrmName=BESTBROKERCRM" -H "Accept: application/json"
Expected Response Status Code
200
| Method | URL |
|---|---|
PUT |
oauth2/ctid/inAppControls |
Sets up one or more InApp controls in the form of ribbons.
Parameters
No parameters.
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
brokerCrmName |
Yes | string | Please, see Section 2.3. |
rules |
Yes | object | An object containing the key types of the created InApp control(s). |
rules.userId |
Yes | integer | The ID of the user to whom the created InApp controls will be displayed. |
rules.ribbons |
Yes | array | An array containing the main characteristics of the created ribbons. Each ribbon constitutes a separate JSON object. |
rules.ribbons.color |
Yes | string | The six-digit HEX value of the color assigned to a specific ribbon. |
rules.ribbons.title |
Yes | string | The text displayed on the ribbon. |
rules.ribbons.enabled |
Yes | boolean | A boolean value determining whether a ribbon is active (i.e., shown to the user). |
rules.ribbons.closable |
Yes | boolean | A boolean value determining whether the ribbon is closable by the user. Upon subsequent application launches, all closed ribbons will be re-shown to the user. |
rules.ribbons.brokerName |
No | string | The name of a specific broker. The ribbon will only be shown to users whose trading account belongs to this broker. |
rules.ribbons.ctidTraderAccountId |
No | string | The unique ID of the linkage between a specific user and one of their trading accounts. |
rules.ribbons.action |
Yes | object | An object listing the InApp actions that occur when users interact with the ribbon. |
rules.ribbons.action.urlExternal |
No (but only when using in-app URLs) | string | The external URL assigned to the relevant InApp action. Upon interaction, opens a separate external browser window. |
rules.ribbons.action.urlinApp |
No (but only when using external URLs) | string | The in-app URL assigned to the relevant InApp action. Upon interaction, opens an iframe. |
As the
rules.ribbonsarray may include several JSON objects (each acting as a unique ribbon), you may combine parameters to create custom sets of InApp controls shown under different circumstances. For instance, you may create ribbons that are only shown to users logged in under a specific account; alternatively, certain ribbons may only be shown to users whose current account belongs to a certain White Label (brokerName).
There are three possible cases that may arise depending on the parameters specified in the request body.
ctidTraderAccountId is specified, the ribbon(s) will only be shown to sessions logged in under this specific account.ctidTraderAccountId is unspecified but a valid brokerName is specified, and there is no ribbon matching by account, the ribbon(s) will be shown to sessions under this specific brokerName.ctidTraderAccountId nor brokerName is specified and there is no ribbon matching by account or brokerName, the ribbons(s) will be shown to sessions under the specified brokerCrmName.You may also choose to send an empty rules object to immediately clear all ribbons already shown to the sessions specified via other parameters.
Request Example
curl -X PUT ‘https://HOST:PORT/cid/oauth2/ctid/inAppControls?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ -H ‘Content-Type: application/json’ --header ‘Accept: application/json’ -d ‘{"brokerCrmName": "BESTBROKERCRM", "userId": 10345533, "rules": {"ribbons": [{"color": "#ff33ee", "title": "MyRibbon one", "action": {"urlinApp": "https://exampleurl.com"}, "enabled": true, "closable": true, "ctidTraderAccountId": 6530877} {"color": "#33ffee", "title": "MyRibbon two", "action": {"urlExternal": "https://anotherurl.com"}, "enabled": true, "closable": true, "brokerName": "smartBroker"}]}, "userId": 10345533}’
Alternate Example (for clearing ribbons)
curl -X PUT ‘https://HOST:POST/cid/oauth2/ctid/inAppControls?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ -H ‘Content-Type: application/json’ --header ‘Accept: application/json’ -d ‘{“brokerCrmName”: “BESTBROKER”, “userId”: 10335, “rules”: {}}’
Expected Response Status Code
201
| Method | URL |
|---|---|
PUT |
/oauth2/ctid/changeEmail |
Changes a user’s email in the cTrader backend in the event of an email change in the broker’s CRM system.
Parameters
No parameters.
Request Body
| Key | Required? | Data Type | Description |
|---|---|---|---|
userId |
Yes | integer | The unique ID of a specific user. |
newEmail |
Yes | string | The user’s new email address. |
brokerCrmName |
Yes | string | See Section 2.3. |
Request Example
curl -X POST ‘https://HOST:PORT/cid/oauth2/ctid/changeEmail?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ -H ‘Accept: application/json’ -H ‘Content-Type: application/json’ -d ‘{"userId": 10345533, "newEmail": "user@gmail.com", "brokerCrmName": "BESTBROKERCRM"}’
Expected Response Status Code
204
| Method | URL |
|---|---|
GET |
oauth2/ctid/getUserId |
Gets the userId of the user with the specified email.
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
brokerCrmName |
query | Yes | string | See Section 2.3. |
email |
query | Yes | string | The email of the user for which you would like to get userId. |
Output
| Key | Data Type | Description |
|---|---|---|
userId |
integer | The unique ID of a specific user. |
Request Example
curl -X GET ‘https://HOST:PORT/cid/oauth2/ctid/getUserId?token=04d95575-c9af-42fba72e-2f0ce93f01d4&email=user@gmail.com&brokerCrmName=BESTBROKERCRM’ -H ‘Accept: application/json’ -H ‘Content-Type: application/json’
Expected Status Code
200
Response Example
{
"userId": 10345533
}
Note that if the user with the specified
brokerCrmNamedoes not exist, you will still receive code200; however, the response will be empty.