This section describes the most common use cases for the Web Services API. It also lists the API calls needed to perform specific actions as well as the corresponding request/response examples.
Note that all examples below assume that
moneyDigits=2.
All examples below are made to a ‘sandbox’ allowing you to quickly test them provided you append a valid manager’s token.
To create a new trader with the minimum possible number of parameters in the request body, perform the following request (API call 4.1).
curl -X POST ‘https://demo-chsandbox2.webapi.ctrader.com:8443/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": "00", "brokerName": "BESTBROKER", "depositCurrency": "EUR", "groupName": "Default", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "leverageInCents": 10000}’
You will receive the following response.
{
"login": 8035344,
"groupName": "Default",
"depositCurrency": "EUR",
"accessRights": "FULL_ACCESS",
"brokerName": "BESTBROKER",
"balance": 0,
"bonus": 0,
"nonWithdrawableBonus": 0,
"leverageInCents": 10000,
"contactDetails": {},
"registrationTimestamp": 1680163530801,
"lastUpdateTimestamp": 1680163530802,
"equity": 0,
"usedMargin": 0,
"freeMargin": 0,
"accountType": "HEDGED",
"limitedRisk": false,
"sendOwnStatement": false,
"swapFree": false,
"totalMarginCalculationType": "MAX",
"isLimitedRisk": false,
"moneyDigits": 2,
}
Send the following request to create another trader (API call 4.1).
curl -X POST ‘https://demo-chsandbox2.webapi.ctrader.com:8443/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": "00", "brokerName": "BESTBROKER", "depositCurrency": "EUR", "groupName": "Default", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "leverageInCents": 10000}’
You will receive the following response.
{
"login": 8035345,
"groupName": "Default",
"depositCurrency": "EUR",
"accessRights": "FULL_ACCESS",
"balance": 0,
"bonus": 0,
"nonWithdrawableBonus": 0,
"leverageInCents": 10000,
"contactDetails": {},
"registrationTimestamp": 1680163530801,
"lastUpdateTimestamp": 1680163530802,
"equity": 0,
"usedMargin": 0,
"freeMargin": 0,
"accountType": "HEDGED",
"limitedRisk": false,
"sendOwnStatement": false,
"swapFree": false,
"totalMarginCalculationType": "MAX",
"isLimitedRisk": false,
"moneyDigits": 2,
}
Note that groupName is "Default".
Now, send the request to update the trader you have just created (API call 4.5.1).
curl -X POST ‘https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc’ -H ‘Accept: application/json’ -H ‘Content-Type: application/json’ -d ‘{"accessRights": "FULL_ACCESS", "accountType": "HEDGED", "balance": "00", "brokerName": "BESTBROKER", "depositCurrency": "EUR", "groupName": "DX_452", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "leverageInCents": 10000}’
In the request body, we have changed groupName to "DX_452" while leaving all other parameters unchanged.
After receiving code 204, send the below request to check whether the trader’s group has changed as requested (API call 4.2).
curl -X GET "https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345?token=8fe4a3a3-1fa6-c4cf-da0f-9c04ee0307b1" -H "accept: */*"
In the response you receive, groupName should be equal to "DX_452".
You may want to prevent new traders from performing any trading operations inside the platform until they pass a KYC check.
To create a new trader, send the request below (API call 4.1).
curl -X POST ‘https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc’ -H ‘Accept: application/json’ -H ‘Content-Type: application/json’ -d ‘{"accessRights": "NO_TRADING", "accountType": "HEDGED", "balance": "00", "brokerName": "BESTBROKER", "depositCurrency": "EUR", "groupName": "Default", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "leverageInCents": 10000}’
Note that accessRights is "NO_TRADING" in the request body.
You will receive a response containing the following parameters.
{
"accessRights": "NO_TRADING",
"login": 8035346,
...
}
After you see that the trader has passed their KYC check in your client area, send the following request (API call 4.5.1).
curl -X POST ‘https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035346?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc’ -H ‘Accept: application/json’ -H ‘Content-Type: application/json’ -d ‘{"accessRights": "FULL_ACCESS", "accountType": "HEDGED", "balance": "00", "brokerName": "BESTBROKER", "depositCurrency": "EUR", "groupName": "DX_452", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "leverageInCents": 10000}’
If you send the request to read the trader’s details (API call 4.2), you should see that the accessRights parameter has switched to "FULL_ACCESS".
curl -X GET "https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035346?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: application/json"
The response to this call should be as follows.
{
"accessRights": "FULL_ACCESS",
"login": 8035346,
...
}
To deposit funds to a trader, send the following request (API call 4.7).
curl -X POST 'https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345/changebalance?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"login": 8035345, "preciseAmount": 123.45, "type": "DEPOSIT"}'
You will receive the following example response.
{
"balanceHistoryId": 74217197
}
To see the trader’s current balance, perform the below request (API call 4.2).
curl -X GET "https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: Application/json"
You will receive a response containing the following parameter.
{
"balance": 12345,
...
}
To perform a withdrawal, send the following request (API call 4.7).
curl -X POST 'https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345/changebalance?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"login": 8035345, "preciseAmount": 111.11, "type": "WITHDRAWAL"}'
Note that the value of the
preciseAmountparameter is still positive even though we are performing a withdrawal.
The response should be as follows.
{
"balanceHistoryId": 74217198
}
The trader’s current balance should now accurately represent both the previous deposit and the withdrawal. Again, perform API call 4.2).
curl -X GET "https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: Application/json"
The response should account for your latest withdrawal.
{
"balance": 1234,
...
}
To deposit bonus to a trader, send the following request (API call 4.10).
curl -X POST 'https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345/changebonus?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"login": 8035345, "preciseAmount": 123.45, "type": "DEPOSIT"}'
You should receive the following response.
{
"bonusHistoryId": 11691
}
If you then check the trader’s details (API call 4.2), you should see your allocated bonus being added to the value of the bonus parameter.
curl -X GET "https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345/?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: Application/json"
The response to the call should reflect the trader’s increased bonus.
{
"bonus": 12345,
...
}
To withdraw bonus, perform API call 4.10 with type=WITHDRAW.
curl -X POST 'https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345/changebonus?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"login": 8035345, "preciseAmount": 123.45, "type": "WITHDRAW" }
Note that the value of the
preciseAmountparameter is still positive even though we are performing a withdrawal.
The response should be as follows.
{
"bonusHistoryId": 11692
}
To see the current amount of bonus allocated to the trader, perform the below request (API call 4.2).
curl -X GET "https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035345?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: Application/json"
The response should account for the recent withdrawal of bonus.
{
"bonus": 1234
}
To attribute a new trader to a partner, simply specify the values of the contactDetails.introducingBroker1 and/or contactDetails.introducingBroker2 keys when creating a new trader (API call 4.1).
curl -X POST ‘https://demo-chsandbox2.webapi.ctrader.com:8443/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": "00", "brokerName": "BESTBROKER", "contactDetails": {"introducingBroker1": "GreatPartner", "introducingBroker2": "BestPartner"} "depositCurrency": "EUR", "groupName": "Default", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "leverageInCents": 10000}’
Assuming that login=8035581 in the response, afterward, you can send API call 4.2 to see that the trader contains information about the specified partners.
curl -X GET "https://HOST:PORT/v2/webserv/traders/8035581/?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: application/json"
In the response, you should see the following information.
{
...
"contactDetails": {
"introducingBroker1": "GreatPartner",
"introducingBroker2": "BestPartner"
},
...
}
To attribute an existing trader to a partner, send specify the values of the contactDetails.introducingBroker1 and/or contactDetails.introducingBroker2 keys when updating a trader (API call 4.5.1).
curl -X POST ‘https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035581?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc’ -H ‘Accept: application/json’ -H ‘Content-Type: application/json’ -d ‘{"accessRights": "FULL_ACCESS", "accountType": "HEDGED", "balance": "00", "brokerName": "BESTBROKER", "contactDetails": {"introducingBroker1": "GreatestPartner", "introducingBroker2": "SuperPartner"} "depositCurrency": "EUR", "groupName": "DX_452", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "leverageInCents": 10000}’
Send API call 4.1 again, and you should see the new partners in the response.
{
...
"contactDetails": {
"introducingBroker1": "GreatestPartner",
"introducingBroker2": "SuperPartner"
},
...
}
To quickly create a new user with minimal parameters, perform the following request (API call 5.1).
curl -X POST 'https://https://demo-chsandbox2.webapi.ctrader.com:8443/v2/cid/ctid/create?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: Application/json' -H 'Accept: Application/json' -d '{"email": "test@emailone.com"}'
You should receive the following response.
{
"userId": 18615,
"nickname": "ctid18615",
"email": "test@emailone.com",
"utcCreateTimestamp": 1680266904176,
"status": "CTID_NEW"
}
In many cases, your clients could request the creation of additional accounts the deposit currency and/or the White Label of which differs from their original account.
Consider an example of a trader with the following parameters.
{
"login": 8035346,
"depositCurrency": "EUR",
"brokerName": "BESTBROKER",
...
}
The userId of the user to which this account is linked is 18615.
To create a new account with different parameters, perform the following request (API call 4.1).
curl -X POST ‘https://demo-chsandbox2.webapi.ctrader.com:8443/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": "00", "brokerName": "BESTBROKER_UK", "depositCurrency": "USD", "groupName": "Default", "hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "leverageInCents": 10000}’
You should receive the following response.
{
"login": 8035344,
"groupName": "Default",
"depositCurrency": "USD",
"accessRights": "FULL_ACCESS",
"balance": 0,
"bonus": 0,
"brokerName": "BESTBROKER_UK",
"nonWithdrawableBonus": 0,
"leverageInCents": 10000,
"contactDetails": {},
"registrationTimestamp": 1680163530801,
"lastUpdateTimestamp": 1680163530802,
"equity": 0,
"usedMargin": 0,
"freeMargin": 0,
"accountType": "HEDGED",
"limitedRisk": false,
"sendOwnStatement": false,
"swapFree": false,
"totalMarginCalculationType": "MAX",
"isLimitedRisk": false,
"moneyDigits": 2,
}
To link the new trader with a specific cTID, make API call 5.2.
curl -X POST 'https://demo-chsandbox2.webapi.ctrader.com:8443/v2/cid/ctid/link?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -Р 'Content-Type: application/json' -H 'Accept: application/json' -d '{"traderLogin": 8035344, "traderPasswordHash": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "userId": 18615, "returnAccountDetails": true}'
You will receive the following response.
{
"ctidTraderAccountId": 61641
}
There may also be cases when you change the structure of one or more existing White Labels (e.g., when rebranding different White Labels that you own). In this situation, you would need to change the White Label(s) of already existing accounts.
To do so for one trader, send the following request API call 5.3. In the example below, we are assuming that the trader with login=8035372 is attributed to any White Label the brokerName of which is different from "BESTBROKER_UK".
curl -X POST 'https://demo-chsandbox2.webapi.ctrader.com:8443/v2/cid/ctid/changeCtidTraderAccount?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{ "environmentName": "live", "brokerName": "BESTBROKER_UK", "traderLogin": 8035372}'
Note that this API call does not produce any output. To double-check whether the trader has been transferred to another White Label, send the following request (API call 4.2).
curl -X GET "https://demo-chsandbox2.webapi.ctrader.com:8443/v2/webserv/traders/8035372?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: application/json"
In the response body, you should see the updated brokerName key.
{
"brokerName": "BESTBROKER_UK",
...
}