Users and accounts
Broker → cTrader endpoints for creating and managing users and trading accounts. Authenticated with the Manager Token (see Authentication of API calls).
Create a user
Creates a new user via the SSO (OAuth) flow.
| Method | URL |
|---|---|
POST | /oauth2/ctid/create |
Request body
| Key | Required? | Data type | Description |
|---|---|---|---|
brokerCrmName | Yes | string | See broker identification. |
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}'). |
nickName | No | string | The user's cTID name. |
preferredLanguage | No | string | The user's preferred language. The parameter takes Alpha-2 (ISO 369-2) codes as values. |
info
If the specified nickName is unique, it is set from the request. However, if the specified nickName is not unique or invalid (e.g. too long, contains forbidden characters, etc), it is inferred from the userId. If a nickName is not specified, it is inferred from the user's email. If the nickName from the user's email already exists, it is inferred from the userId.
Output
| Key | Data type | Description |
|---|---|---|
userId | integer | The unique ID of a specific user. |
Expected status code
201
Errors
See Error codes.
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", "nickname": "letstrade", "preferredLanguage": "en"}'
Response example
{
"userId": 10345533
}
Create a trader
Creates a new trader entity.
| Method | URL |
|---|---|
POST | /webserv/traders |
Request body
| Key | Required? | Data type | Description |
|---|---|---|---|
accessRights | Yes | enum | The access rights of the account. The following values are accepted:"FULL_ACCESS". The account can perform all operations with no restrictions."CLOSE_ONLY". The account can only close existing positions."NO_TRADING". The account cannot perform any trading operations."NO_LOGIN". The account cannot log into cTrader. |
accountType | Yes | enum | The type of the trading account. The following values are accepted:"HEDGED". The account can open positions in both directions for the same symbol simultaneously."NETTED". The account can only positions in one directions for a given symbol."SPREAD_BETTING". The account can perform spread betting operations. |
balance | Yes | long | The total balance of the new account. This parameter primarily exists for the creation of demo accounts with a non-zero balance. |
brokerName | Yes | string | A unique name denoting a specific broker (including White Labels). |
depositCurrency | Yes | string | The name of the currency that the account uses for making deposits and withdrawals. |
groupName | Yes | string | The name of the group to which the account is assigned. |
hashedPassword | Yes | string | The MD5 of the account password. |
leverageInCents | Yes | integer | The total amount of leverage available to the account; is specified in 10^2. E.g., the 1:1 leverage is leverageInCents=100 while the 1:100 leverage is leverageInCents=10000. |
totalMarginCalculationType | Yes | enum | The strategy via which the account margin is calculated. The following values are accepted:"MAX". The total margin requirements per symbol are equal to the maximum margin requirements for all positions opened for this symbol."SUM". The total margin requirements per symbol are equal to the sum of all margin requirements of all positions opened for this symbol."NET". The total margin requirements per symbol are equal to the difference between the margin requirements for all long positions and all short positions opened for this symbol. |
contactDetails | No | JSON object | A JSON object containing the trader's address, phone number and other details as shown below. |
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 the trader's country of residence. The full list of these identifiers can be accessed here. |
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. |
contactDetails.introducingBroker1 | No | string | A custom identifier of the first-level partner that has introduced this trader. |
contactDetails.introducingBroker2 | No | string | A custom identifier of the second level-partner that has introduced this trader. |
description | No | string | The description of the account. |
isLimitedRisk | No | boolean | The trader's limited risk (LR) status. LR means the establishment of guaranteed stop losses. If isLimitedRisk=true, LR is enabled, and vice versa. |
lastName | No | string | The last name of the account holder. |
limitedRiskMarginCalculationStrategy | No | enum | The margin calculation strategy used for the limited risk account. The following values are accepted:"ACCORDING_TO_LEVERAGE". Margin requirements have to be calculated based on the account leverage."ACCORDING_TO_GSL". Margin requirements have to be calculated based on the distance between the position open price and the guaranteed stop loss."ACCORDING_TO_GSL_AND_LEVERAGE". cServer calculates the leverage-based and GSL-based margin requirements, and chooses the larger of the two values. |
maxLeverage | No | integer | The maximum amount of leverage (in the base currency units) available to the account. Specified in 10^2. |
name | No | string | The first name of the account holder. |
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 under which the account is registered. |
swapFree | No | boolean | A flag determining whether the account is charged swaps (swapFree=true) or administrative fees (swapFree=false). |
Output
For a JSON schema of the output, click here.
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 funds allocated to the account. Subject to moneyDigits. |
equity | integer | The total amount of equity possessed by the account. Subject to moneyDigits. |
freeMargin | integer | The amount of free margin available to the account. Subject to moneyDigits. |
cashEquity | integer | The current amount of funds that the account can withdraw. It is calculated via the following formula: cashEquity = balance + unrealized P&L - management fees, where management fees are all management fees charged by the providers of strategies that the account owner has invested in. 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 | The number that determines how finance-related values are defined for the account. E.g., if moneyDigits=2 and balance=1234512, the account balance is 12345.12 in the account deposit currency.Additional details are given in General provisions. |
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 this parameter equals true, rollover commissions are applied to the account instead of swaps. The reverse applies if the parameter is false. This field is useful for ensuring compliance with Sharia law. |
usedMargin | integer | The total amount of margin in use by the account. Subject to moneyDigits. |
Expected status code
201
Errors
See Error codes.
Request example
curl -X POST 'https://HOST:PORT/v2/webserv/traders?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"accessRights": "FULL_ACCESS", "accountType": "HEDGED", "balance": 0, "brokerName": "BESTBROKER", "contactDetails": {"address": "Moon", "city": "Lake", "countryId": 8, "documentId": "0123", "email": "president@bestbroker.com", "phone": "+50987654321", "state": "RE", "zipCode": "5500", "introducingBroker1": "CoolPartner", "introducingBroker2": "AnotherCoolPartner"},"depositCurrency": "EUR", "description": "coolDescription", "groupName": "Default", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "isLimitedRisk": false, "lastName": "President", "leverageInCents": 1000, "maxLeverage": 100000, "name": "Best", "sendOwnStatement": true, "sendStatementToBroker": true, "totalMarginCalculationType": "MAX"}'
Response example
{
"accessRights": "FULL_ACCESS",
"accountType": "HEDGED",
"balance": 0,
"bonus": 0,
"cashEquity": 0,
"brokerName": "BESTBROKER",
"contactDetails": {
"address": "Moon",
"city": "Lake",
"countryId": 8,
"documentId": "0123",
"email": "president@bestbroker.com",
"phone": "+50987654321",
"state": "RE",
"zipCode": "5500",
"introducingBroker1": "CoolPartner",
"introducingBroker2": "AnotherCoolPartner"
},
"depositCurrency": "EUR",
"description": "coolDescription",
"equity": 0,
"freeMargin": 0,
"groupName": "Default",
"isLimitedRisk": false,
"lastConnectionTimestamp": 0,
"lastName": "President",
"lastUpdateTimestamp": 0,
"leverageInCents": 1000,
"limitedRiskMarginCalculationStrategy": "ACCORDING_TO_LEVERAGE",
"login": 8673590,
"maxLeverage": 100000,
"moneyDigits": 0,
"name": "Best",
"nonWithdrawableBonus": 0,
"registrationTimestamp": 0,
"sendOwnStatement": true,
"sendStatementToBroker": true,
"swapFree": true,
"totalMarginCalculationType": "MAX",
"usedMargin": 0
}
Link a trading account
Links a trader entity to a user entity.
| Method | URL |
|---|---|
POST | /ctid/link |
Request body
| Key | Required? | Data type | Description |
|---|---|---|---|
traderLogin | Yes | integer | The number of a specific trading account. |
traderPasswordHash | Yes | integer | The MD5 of the account password. |
userId | Yes | integer | The unique identifier of a user entity. |
brokerName | Yes | string | A unique name denoting a specific broker (including White Labels). |
environmentName | Yes | string | A unique name of a specific trading environment where the specified traderLogin is registered. |
returnAccountDetails | No | boolean | A flag that denotes whether the ctidTraderAccountId key is returned in the response to this API call. Set it to true to ensure that the response to this call is not empty. |
Output
| Key | Data type | Description |
|---|---|---|
ctidTraderAccountId | integer | The unique identifier of the linkage between a specific user and one of their trading accounts. |
info
Note that the response body will be empty if returnAccountDetails is false.
Expected status code
200
Errors
See Error codes.
Request example
curl -X POST 'https://HOST:PORT/cid/ctid/link?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"environmentName": "demo", "brokerName": "BESTBROKER", "traderLogin": 9017800, "traderPasswordHash": "0f94e246908667af85916300c57f74b6", "userId": 10333, "returnAccountDetails": true}'
Response example
{
"ctidTraderAccountId": 90178000
}
Confirm user agreement
Confirms user agreement by updating the user's details.
| Method | URL |
|---|---|
PUT | /oauth2/ctid/acceptAgreement |
Parameters
| Parameter | Parameter type | Required? | Data type | Description |
|---|---|---|---|---|
brokerCrmName | query | Yes | string | See broker identification. |
userId | query | Yes | integer | The unique ID of a specific user. |
Output
This call does not produce an output.
Expected status code
200
Errors
See Error codes.
Request example
curl -X PUT 'https://HOST:PORT/cid/oauth2/ctid/acceptAgreement?token=04d95575-c9af-42fba72e-2f0ce93f01d4' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{ "brokerCrmName": "BESTBROKERCRM", "userId": 10345533}'
Change a user's email
Changes a user's email in the cTrader backend in the event of an email change in the broker's CRM system.
| Method | URL |
|---|---|
PUT | /oauth2/ctid/changeEmail |
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 broker identification. |
Expected status code
204
Errors
See Error codes.
Request example
curl -X PUT '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"}'
Read a user's ID by email
Gets the userId of the user with the specified email.
| Method | URL |
|---|---|
GET | /oauth2/ctid/getUserId |
Parameters
| Parameter | Parameter type | Required? | Data type | Description |
|---|---|---|---|---|
brokerCrmName | query | Yes | string | See broker identification. |
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. |
info
Note that if the user with the specified email and brokerCrmName does not exist, you will still receive code 200; however, the response will be empty.
Expected status code
200
Errors
See Error codes.
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'
Response example
{
"userId": 10345533
}
Log out a user from cTrader
Logs out the user with the specified userId from all cTrader applications and drop all of the user's current sessions if they exist.
| Method | URL |
|---|---|
PUT | /oauth2/ctid/logout |
info
The primary purpose of this call is to log out a user from cTrader whenever they log out from inside your client area.
Parameters
| Parameter | Parameter type | Required? | Data type | Description |
|---|---|---|---|---|
brokerCrmName | query | Yes | string | See broker identification. |
userId | query | Yes | integer | The unique ID of a specific user. |
Output
This call does not produce an output.
Expected status code
200
Errors
See Error codes.
Request example
curl -X PUT 'https://HOST:PORT/cid/oauth2/ctid/logout?token=04d95575-c9af-42fba72e-2f0ce93f01d4&userId=10345533&brokerCrmName=BESTBROKERCRM' -H 'Accept: application/json' -H 'Content-Type: application/json'