All API calls in this section concern operations with account entities (‘traders’) and related entities (e.g., orders).
All URLs for the API calls described on this page are relative to https://HOST:PORT/v2. The value of HOST:PORT is provided during the onboarding process by Spotware’s service assurance team.
| HTTP Method | URL |
|---|---|
POST |
/webserv/traders |
Creates a new trader entity.
Parameters
No parameters.
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 Section 3. |
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. |
minEquityDaily |
integer | The minimum daily equity for the account. The day starts at 00:00 UTC. |
maxEquityDaily |
integer | The maximum daily equity for the account. The day starts at 00:00 UTC. |
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": 9017800,
"maxLeverage": 100000,
"moneyDigits": 0,
"name": "Best",
"nonWithdrawableBonus": 0,
"registrationTimestamp": 0,
"sendOwnStatement": true,
"sendStatementToBroker": true,
"swapFree": true,
"totalMarginCalculationType": "MAX",
"usedMargin": 0
}
Expected Status Code
201
| HTTP Method | URL |
|---|---|
GET |
/webserv/traders/{login} |
Reads the details of an existing trader entity.
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
login |
path | Yes | integer | The number of a specific trading account. |
Request Body
No request body.
Output
For a JSON schema of the output, click here; also see the output for API call 4.1.
Request Example
curl -X GET "https://HOST:PORT/v2/webserv/traders/9017800?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: application/json"
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": 9017800,
"maxLeverage": 1000,
"moneyDigits": 0,
"name": "Best",
"nonWithdrawableBonus": 0,
"registrationTimestamp": 0,
"sendOwnStatement": true,
"sendStatementToBroker": true,
"swapFree": true,
"totalMarginCalculationType": "MAX",
"usedMargin": 0
}
Expected Status Code
200
| HTTP Method | URL |
|---|---|
GET |
/webserv/traders/ |
Reads the details of multiple trader entities.
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
from |
query | Yes | string | The account registration timestamp. Only accounts registered at or after the specified timestamp are shown in the results. This value is formatted as yyyy-MM-ddTHH:mm:ss.SSS in UTC (e.g., 2018-01-01T12:12:12.000). |
to |
query | Yes | string | The account registration timestamp. Only accounts registered before the specified timestamp are shown in the results. This value is formatted as yyyy-MM-ddTHH:mm:ss.SSS in UTC (e.g., 2018-03-01T12:12:12.000). |
fromLastDealTimestamp |
query | No | string | The start time for deals. Only accounts whose last deals occurred at this start time or after are shown in the results. This value is formatted as yyyy-MM-ddTHH:mm:ss.SSS in UTC (e.g., 2018-01-01T12:12:12.000). |
toLastDealTimestamp |
query | No | string | The end time for deals. Only accounts whose last deals occurred before this end time are shown in the results. This value is formatted as yyyy-MM-ddTHH:mm:ss.SSS in UTC (e.g., 2018-03-01T12:12:12.000). |
fields |
query | No | string | The account details included in the response. The value is formatted as an array of strings (e.g., fields=login,brokerName,balance).If fields is specified, the trader entity is returned only with the specified fields. Otherwise, it is returned with all fields. |
hasOpenPositions |
query | No | boolean | If true, the response will include only accounts that have open positions. If false, the response will include only accounts that do not have open positions.If this parameter is not specified, the response will include accounts regardless of open positions. |
groupId |
query | No | integer | The identifier of an account group. Only accounts assigned to the group are shown in the results. |
The
fromLastDealTimestampandtoLastDealTimestampparameters must be both specified or unspecified.
If both parameters are not specified, the response will include accounts regardless of the timestamps of their last deals.
Request Body
No request body.
Output
An array of JSON objects with each object having the structure of the output of API call 4.1; for a JSON schema of the output, click here.
Request Example
curl -X GET "https://HOST:PORT/v2/webserv/traders/?from=2018-01-01T12:12:12.000&to=2018-03-01T12:12:12.000&groupId=15&token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: application/json"
Response Example
{
"trader": [
{
"login": 8044900,
"balance": 0,
"minEquityDaily": 0,
"maxEquityDaily": 0
},
{
"login": 8044899,
"balance": 0,
"minEquityDaily": 0,
"maxEquityDaily": 0
},
{
"login": 8044898,
"balance": 0,
"minEquityDaily": 0,
"maxEquityDaily": 0
}
],
"hasMore": false
}
The data chunk size in a response is limited to 100,000 by default. A response always includes the
hasMoreparameter.
WhenhasMoreistruein a response, then thetoparameter in the next request should be changed to the earliest receivedregistrationTimestamp+1so that the new response provides the next chunk of data. The accounts included in any response are filtered based onfrom<=registrationTimestamp<to.
Expected Status Code
200
| HTTP Method | URL |
|---|---|
GET |
/webserv/{login}/subaccounts |
Reads the details of all sub-accounts (special account entities for strategy following in cTrader Copy) belonging to a trader entity.
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
login |
path | Yes | integer | The number of a specific trading account. |
Request Body
No request body.
Output
| Key | Data Type | Description |
|---|---|---|
subAccountLogins |
object | The object containing an array of logins of the sub-accounts belonging to the specified trader. |
subAccountLogins.login |
array | The array of logins of the sub-accounts belonging to the specified trader. |
totalSubAccountsBalance |
integer | The total balance of all sub-accounts belonging to the specified trader. Subject to moneyDigits of the trader with the specified login. |
totalSubAccountsEquity |
integer | The total equity of all sub-accounts belonging to the specified trader. Subject to moneyDigits of the trader with the specified login. |
Request Example
curl -X GET "https://HOST:PORT/v2/webserv/traders/9017800/subaccounts?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: application/json"
Response Example
{
"subAccountLogins":
{
"login":
[
9006731,
9006762,
9006765
]
},
"totalSubAccountsBalance":46016,
"totalSubAccountsEquity":47324
}
| HTTP Method | URL |
|---|---|
PUT |
/webserv/traders/{login} |
Updates a trader entity.
When making this API call, all parameters of the trader entity become mandatory in the request body. If you do not specify their values, these parameters will be set to
nullor their respective default values.
Note that this call cannot be used to change a trader’s balance. Instead, use API call 4.7.
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
login |
path | Yes | integer | The number of a specific trading account. |
Request Body
This API call has the same request body as API call 4.1.
Output
No output.
Request Example
curl -X PUT 'https://HOST:PORT/v2/webserv/traders/9017800?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"accessRights": "FULL_ACCESS", "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"}, "description": "coolDescription", "groupName": "Default", "isLimitedRisk": false, "lastName": "President ", "leverageInCents": 10000, "maxLeverage": 100000, "name": "Best", "sendOwnStatement": true, "sendStatementToBroker": true, "totalMarginCalculationType": "MAX"}'
Response Example
This API call does not produce an output.
Expected Status Code
204
| HTTP Method | URL |
|---|---|
PATCH |
/webserv/traders/{login} |
Updates a trader entity.
In contrast to API call 4.5.1., you do not have to specify all parameters of the trader entity when performing this call.
Note that this call cannot be used to change a trader’s balance. Instead, use API call 4.7.
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 |
|---|---|---|---|
accessRights |
No | 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. |
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. |
groupname |
No | string | The name of the group to which the account is assigned. |
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. |
leverageInCents |
No | 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. |
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
No output.
Request Example
curl -X PATCH 'https://HOST:PORT/v2/webserv/traders/9017800?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"description": "updatedDescription", "groupName": "newGroup", "maxLeverage": 50000}'
Response Example
This API call does not produce an output.
Expected Status Code
200
| HTTP Method | URL |
|---|---|
DELETE |
/webserv/traders/{login} |
Deletes a trader entity.
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
login |
path | Yes | integer | The number of a specific trading account. |
Request Body
No request body.
Output
No output.
Request Example
curl -X DELETE "https://HOST:PORT/v2/webserv/traders/9017800?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc"
Response Example
This API call does not produce an output.
Expected Status Code
204
| HTTP Method | URL |
|---|---|
POST |
/webserv/traders/{login}/changebalance |
Changes the balance of a trader entity (including allocating/removing credit).
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 retail clients. |
externalId |
No | string | A number that matches an external identifier of the broker’s choosing. For instance, the value of 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 that can supplement a deposit or a withdrawal. In contrast to comment, this text is displayed to retail clients. |
login |
Yes | integer | The number of a specific trading account. |
preciseAmount |
Yes | double | The precise amount of withdrawn or deposited funds/credit. 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. The following values are accepted."DEPOSIT". Deposit funds to the trader."WITHDRAW". Withdraw funds from the trader. "DEPOSIT_NONWITHDRAWABLE_BONUS". Deposit credit to the trader."WITHDRAW_NONWITHDRAWABLE_BONUS". Withdraw credit from the trader. |
Note that only positive values are accepted when specifying the
preciseAmountparameter. The direction of the balance change is regulated entirely by thetypeparameter.
Output
| Key | Data Type | Description |
|---|---|---|
balanceHistoryId |
integer | The identifier of a balance history entity containing all balance-related transactions for the specified trader. Note that bonus and credit are not included in balanceHistoryId. |
Request Example
curl -X POST 'https://HOST:PORT/v2/webserv/traders/9017800/changebalance?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"comment": "Test deposit", "externalId": "082123301", "externalNote": "New deposit!", "login": 9017800, "preciseAmount": 123.45, "source": "Source One", "type": "DEPOSIT"}'
Output Example
{
"balanceHistoryId": 6340680
}
Expected Status Code
200
| HTTP Method | URL |
|---|---|
POST |
/webserv/traders/{login}/changepassword |
Changes the password for authenticating a trader entity.
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 |
|---|---|---|---|
hashedPassword |
Yes | string | The MD5 of the new password of the account |
login |
Yes | integer | The number of a specific trading account. |
Output
No output.
Request Example
curl -X POST 'https://HOST:PORT/v2/webserv/traders/9017800/changepassword?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "login": 9017800}'
Output Example
This API call does not produce an output.
Expected Status Code
204
| HTTP Method | URL |
|---|---|
POST |
/webserv/traders/{login}/checkpassword |
Checks the password for authenticating a trader entity.
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 |
|---|---|---|---|
hashedPassword |
Yes | string | The MD5 of the account password. |
login |
Yes | integer | The number of a specific trading account. |
Output
No output.
Request Example
curl -X POST 'https://HOST:PORT/v2/webserv/traders/9017800/checkpassword?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"hashedPassword": "c5678ghf94578ce06iqrs5ag76a62c5ca4", "login": 9017800}'
Output Example
This API call does not produce an output.
Expected Status Code
204
| HTTP Method | URL |
|---|---|
POST |
/webserv/traders/{login}/changebonus |
Changes the amount of bonus allocated to a given trader.
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 the bonus change. This note is not shown to retail clients. |
externalId |
No | string | A number that matches an external identifier of the broker’s choosing. For instance, the value of 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 that described the change. In contrast to comment, this text is displayed to retail clients. |
login |
Yes | integer | The number of a specific trading account. |
preciseAmount |
Yes | double | The precise amount of withdrawn or deposited bonus. 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. |
type |
Yes | string | The desired type of change. The following values are accepted."DEPOSIT". Allocate bonus to the trader."WITHDRAW". Withdraw bonus from the trader. |
Output
| Key | Data Type | Description |
|---|---|---|
bonusHistoryId |
integer | The identifier of a bonus history entity containing all bonus-related transactions for the specified trader. |
Request Example
curl -X POST 'https://HOST:PORT/v2/webserv/traders/9017800/changebonus?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"comment": "string", "externalId": "string", "externalNote": "string", "login": 9017800, "preciseAmount": 123.45, "type": "DEPOSIT"}'
Output Example
{
"bonusHistoryId": 2825
}
Expected Status Code
200
| HTTP Method | URL |
|---|---|
GET |
/webserv/tradergroups |
Gets a list of all trader groups.
Parameters
No parameters.
Request Body
No request body.
Output
| Key | Data Type | Description |
|---|---|---|
traderGroup |
array | An array containing JSON or XML objects representing account groups. |
traderGroup.id |
integer | The identifier of an account group. |
traderGroup.name |
string | The name of an account group. |
traderGroup.description |
string | The description of an account group. |
For a JSON schema of the output, click here.
Response Example
curl -X GET "https://HOST:PORT/v2/webserv/tradergroups?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: application/json"
Output Example
{
"traderGroup":
[
{
"id": 51350,
"name": "Default Group",
"description":""
},
{
"id": 51351,
"name": "Custom Group",
"description":"demo group"
},
{
"id": 51352,
"name":"UK Traders",
"description":""
},
{
...
},
...
]
}"
Expected Status Code
200
| HTTP Method | URL |
|---|---|
GET |
/webserv/openPositions |
Gets either a list of all open positions or a list of open positions originated by a specific trader entity (if the login parameter is specified).
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
login |
query | No | integer | The number of a specific trading account. |
Request Body
No request body.
Output
This API call returns a comma-separated ‘grid’ containing information about position entities and their details.
| Column | Data Type | Description |
|---|---|---|
login |
integer | The number of a specific trading account. |
positionId |
integer | The unique identifier of a position entity. |
openTimestamp |
string | The timestamp of the moment when the position was opened. This value is formatted as yyyy-MM-ddTHH:mm:ss.SSS in UTC (e.g., 2018-01-01T12:12:12.000). |
entryPrice |
decimal | The entry price for the position. |
direction |
string | The position direction. The following values are permitted."BUY". Denotes a long position."SELL". Denotes a short position. |
volume |
double | The traded volume denoted in units of the base asset. |
symbol |
string | The symbol for which the position is opened. Permitted values include all valid symbol names that exist on the server. |
commission |
double | The commission paid for opening the position; denoted in USD. |
swap |
double | The SWAPs charged for holding the position open overnight; denoted in USD. |
bookType |
string | The order execution book that was used for opening the position. The following values are permitted."BOOK_A". Denotes Book A execution."BOOK_B". Denotes Book B execution. |
stake |
double | The spread betting stake of the position; denoted in the account deposit currency. |
spreadBetting |
boolean | A flag that determines whether the position is of the spread betting type. |
usedMargin |
double | The margin used by the position denoted in the account deposit currency. |
Request Example
curl -X GET "https://HOST:PORT/v2/webserv/openPositions?login=9017800&token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc"
Output Examples
The following output is produced if the login parameter is omitted.
login,positionId,openTimestamp,entryPrice,direction,volume,symbol,commission,swap,bookType,stake,spreadBetting,usedMargin
9013206,4325443,2020-08-28T05:35:37.682,1.18657,BUY,1000.00,EURUSD,1.69,2.54,BOOK_B,0.00,false,0.01
9013197,4325446,2020-08-28T05:35:38.015,1.18656,BUY,1000.00,EURUSD,1.69,2.54,BOOK_B,0.00,false,0.01
...
The following output is produced if the login parameter is specified.
login,positionId,openTimestamp,entryPrice,direction,volume,symbol,commission,swap,bookType,stake,spreadBetting,usedMargin
9017800,4435112,2020-08-28T05:35:37.682,1.18657,BUY,1000.00,EURUSD,1.69,2.54,BOOK_B,0.00,false,0.01
9017800,4435113,2020-08-28T05:35:38.015,1.18656,BUY,1000.00,EURUSD,1.69,2.54,BOOK_B,0.00,false,0.01
...
Expected Status Code
200
| HTTP Method | URL |
|---|---|
GET |
/webserv/closedPositions |
Gets either a list of all closed positions or a list of closed positions originated by a specific trader entity (if the login parameter is specified).
Note that each row in the output represents one specific result of closing a position, be it wholly or partially. As a result, you may see cases where
positionIdis repeated across several rows. This is intended behavior as it represents positions that were closed via multiple deals.
Parameters
| Parameter | Parameter Type | Required? | Data Type | Description |
|---|---|---|---|---|
from |
query | Yes | string | The position creation timestamp; only positions that have been created at or after the specified timestamp will be shown in the results. This value is formatted as yyyy-MM-ddTHH:mm:ss.SSS in UTC (e.g., 2018-01-01T12:12:12.000). |
to |
query | Yes | string | The position creation timestamp; only positions that have been created before the specified timestamp will be shown in the results. This value is formatted as yyyy-MM-ddTHH:mm:ss.SSS in UTC (e.g., 2018-03-01T12:12:12.000). |
login |
query | No | integer | The number of a specific trading account. |
The difference between the timestamps specified in the
fromandtoparameters must be equal to two days or less.
Request Body
No request body.
Output
This API call returns a comma-separated ‘grid’ containing information about position entities and their details.
| Column | Data Type | Description |
|---|---|---|
login |
integer | The number of a specific trading account. |
positionId |
integer | The unique identifier of a position entity. |
dealId |
integer | The unique identifier of the deal entity that has closed the position with the given positionId.If multiple results are returned with the same positionId but with different dealIds, the position was closed via several closing deals. |
openTimestamp |
string | The timestamp of the moment when the position was opened. This value is formatted as yyyy-MM-ddTHH:mm:ss.SSS in UTC (e.g., 2018-01-01T12:12:12.000). |
closeTimestamp |
string | The timestamp of the moment when position was closed. This value is formatted as yyyy-MM-ddTHH:mm:ss.SSS in UTC (e.g., 2018-01-01T12:12:12.000). |
entryPrice |
decimal | The VWAP of the volume that was used in the closing deal(s) of the position with the given positionId.E.g., the position was opened via two deals; the first one was executed for 50,000 units at 1.2, the second one was executed at 20,000 units at 1.3. There was only one closing deal for the full volume of 70,000. The entryPrice was calcuated as (1.2 * 50 + 1.3 * 20)/70 = 1.22857. |
closePrice |
decimal | The price at which the position was closed (wholly or partially). |
direction |
string | The position direction. The following values are permitted."BUY". Denotes a long position."SELL". Denotes a short position. |
volume |
double | The traded volume denoted in units of the base asset. |
symbol |
string | The symbol for which the position is opened. Permitted values include all valid symbol names that exist on the server. |
commission |
double | The commission paid for opening the position; denoted in USD. |
swap |
double | The SWAPs charged for holding the position open overnight; denoted in USD. |
pnl |
double | The net realized PnL generated by the position. |
depositConversionRate |
decimal | The conversion rate between the base asset of the symbol for which the position was opened and the account deposit currency of the trader entity that has opened the position. |
usdConversionRate |
decimal | The conversion rate between the base asset of the symbol for which the position was opened and USD. |
bookType |
string | The order execution book that was used for opening the position. The following values are permitted."BOOK_A". Denotes Book A execution."BOOK_B". Denotes Book B execution. |
stake |
double | The spread betting stake of the position; denoted in the account deposit currency. |
spreadBetting |
boolean | A flag that determines whether the position is of the spread betting type. |
Request Example
curl -X GET "https://HOST:PORT/v2/webserv/closedPositions?from=2020-01-01T12%3A12%3A12.000&to=2020-01-03T12%3A12%3A12.000&token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc" -H "Accept: */*"
Response Example
The following output is produced if the login parameter is omitted.
login,positionId,dealId,openTimestamp,closeTimestamp,entryPrice,closePrice,direction,volume,symbol,commission,swap,pnl,depositConversionRate,usdConversionRate,bookType,stake,spreadBetting
9013206,6101,4690813,2018-03-19T13:44:21.224,2020-01-02T09:01:53.613,0.69999,0.70132,BUY,1000.00,AUD/USD,0.01,142.74,76.17,0.96911,0.70132,BOOK_B,0.00,false
9013197,13313,5690189,2018-08-30T12:15:29.154,2020-01-02T09:01:54.748,1.32315,1.32214,BUY,1000.00,GBPUSD,0.00,25.83,44.79,0.96911,1.32214,BOOK_B,0.00,false
...
The following output is produced if the login parameter is specified.
login,positionId,dealId,openTimestamp,closeTimestamp,entryPrice,closePrice,direction,volume,symbol,commission,swap,pnl,depositConversionRate,usdConversionRate,bookType,stake,spreadBetting
9013206,6101,4690813,2019-12-27T13:44:21.224,2020-01-02T09:01:53.613,0.69999,0.70132,BUY,1000.00,AUD/USD,0.01,142.74,76.17,0.96911,0.70132,BOOK_B,0.00,false
9013206,15987,7840162,2020-08-30T12:15:29.154,2021-01-01T09:01:54.748,1.52333,1.52214,BUY,1000.00,GBPUSD,0.00,25.83,44.79,0.98911,1.32214,BOOK_B,0.00,false
...
Expected Status Code
200