Operations with Accounts

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.

Create a Trader

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=false) or administrative fees (swapFree=true).

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

Read a Trader's Details

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

Read Multiple Traders' Details

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.

warning

The fromLastDealTimestamp and toLastDealTimestamp parameters must be both specified or unspecified.

info

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
}

info

The data chunk size in a response is limited to 100,000 by default. A response always includes the hasMore parameter. When hasMore is true in a response, then the to parameter in the next request should be changed to the earliest received registrationTimestamp+1 so that the new response provides the next chunk of data. The accounts included in any response are filtered based on from <= registrationTimestamp < to.

Expected Status Code

200

Read the Details of a Sub-Account

HTTP Method	URL
GET	/webserv/traders/{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
}

Update a Trader (All Parameters)

HTTP Method	URL
PUT	/webserv/traders/{login}

Updates a trader entity.

info

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 null or their respective default values.

warning

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

Update a Trader (Specific Parameters)

HTTP Method	URL
PATCH	/webserv/traders/{login}

Updates a trader entity.

info

In contrast to API call 4.5.1., you do not have to specify all parameters of the trader entity when performing this call.

warning

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=false) or administrative fees (swapFree=true).

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

Delete a Trader

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

Change a Trader's Balance

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.
skipMarginValidation	No	boolean	If true, margin requirements will be skipped. This may result in Stop Out, negative balance or both.

info

Note that only positive values are accepted when specifying the preciseAmount parameter. The direction of the balance change is regulated entirely by the type parameter.

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, "skipMarginValidation": true, "source": "Source One", "type": "DEPOSIT"}'

Output Example

{
  "balanceHistoryId": 6340680
}

Expected Status Code

200

Change a Trader's Password

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

Check a Trader's Password

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

Change a Trader's Bonus

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

Request a List of All Trader Groups

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

Request a List of Open Positions

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

Request a List of Closed Positions

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).

info

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 positionId is 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.

info

The difference between the timestamps specified in the from and to parameters 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

List Trader Attributes

HTTP Method	URL
POST	/webserv/traders/attributes/list

Fetches the current attributes for one or more traders.

Parameters

No parameters

Request Body

Key	Required?	Data Type	Description
traderIds	No	array	An array of trader IDs (1–10,000). When omitted or empty, all visible traders that own at least one attribute row are returned.
limit	No	integer	The number of records to be returned per page (1–10,000, default 10,000). Only allowed when traderIds is omitted.
pageAfterTraderId	No	integer	Cursor for the next page (≥0, default 0). Only allowed when traderIds is omitted.
nameFilter	No	string	Case-insensitive substring filter on attribute name (0–64 characters).
fromUtcLastUpdateTimestamp	No	integer	The epoch unix timestamp (in milliseconds) used to return only traders whose latest attribute row is greater than or equal to this value.

Output

Key	Data Type	Description
results	array	An array containing one entry per authorised trader with at least one attribute row.
results.traderId	integer	The unique identifier of a trader.
results.attributes	array	An array of objects containing { name, value } pairs.
results.utcLastUpdateTimestamp	integer	The epoch unix timestamp (in milliseconds) of the latest attribute row for the trader.
nextPageAfterTraderId	integer or null	Cursor for the next call. Present only when more pages are available.

Request Example

curl -X POST 'https://HOST:PORT/v2/webserv/traders/attributes/list?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -d '{"traderIds":[101,102]}'

Response Example

{
  "results": [
    {
      "traderId": 101,
      "attributes": [
        {"name": "colorCode", "value": "FFAA00"},
        {"name": "prefixLabel", "value": "VIP"}
      ],
      "utcLastUpdateTimestamp": 1688923200000
    },
    {
      "traderId": 102,
      "attributes": [
        {"name": "colorCode", "value": "00FF00"}
      ],
      "utcLastUpdateTimestamp": 1688923200000
    }
  ],
  "nextPageAfterTraderId": null
}

Expected Status Code

200

List Trader Group Attributes

HTTP Method	URL
POST	/webserv/tradergroups/attributes/list

Fetches the current attributes for one or more trader groups. Only groups that have at least one attribute row are returned.

Parameters

No parameters

Request Body

Key	Required?	Data Type	Description
traderGroupIds	Yes	array	An array of trader group IDs (1–10,000). No "all" mode. No paging.
nameFilter	No	string	Case-insensitive substring on attribute name (0–64 characters). Field nameFilter must have length of 0–64.
fromUtcLastUpdateTimestamp	No	integer	The epoch unix timestamp (in milliseconds). Only groups whose most recent attribute row is greater than or equal to this value are returned.

Output

Key	Data Type	Description
results	array	One object per authorised trader group that has at least one attribute row.
results.traderGroupId	integer	The unique identifier of a trader group.
results.attributes	array	An array of objects containing { name, value } pairs.
results.utcLastUpdateTimestamp	integer	The epoch unix timestamp (in milliseconds) of the most recent attribute row for this group.

Request Example

curl -X POST 'https://HOST:PORT/v2/webserv/tradergroups/attributes/list?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -d '{"traderGroupIds":[456,457]}'

Response Example

{
  "results": [
    {
      "traderGroupId": 456,
      "attributes": [
        {"name": "colorCode", "value": "FFFF00"},
        {"name": "prefixLabel", "value": "GroupVIP"}
      ],
      "utcLastUpdateTimestamp": 1688923200000
    }
  ]
}

Expected Status Code

200

List Manager Attributes

HTTP Method	URL
POST	/webserv/managers/attributes/list

Fetches the current attributes for one or more managers. Only managers that have at least one attribute row are returned.

Parameters

No parameters

Request Body

Key	Required?	Data Type	Description
managerIds	Yes	array	An array of manager IDs (1–10,000). For a regular manager, only their own ID is allowed; for a super-admin, any ID is allowed. No paging is available.
nameFilter	No	string	Case-insensitive substring on attribute name (0–64 characters).
fromUtcLastUpdateTimestamp	No	integer	The epoch unix timestamp (in milliseconds). Only managers whose most recent attribute row is greater than or equal to this value are returned.

Output

Key	Data Type	Description
results	array	One object per authorised manager that has at least one attribute row.
results.managerId	integer	The unique identifier of a manager.
results.attributes	array	An array of objects containing { name, value } pairs.
results.utcLastUpdateTimestamp	integer	The epoch unix timestamp (in milliseconds) of the most recent attribute row for this manager.

Request Example

curl -X POST 'https://HOST:PORT/v2/webserv/managers/attributes/list?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -d '{"managerIds":[789,790]}'

Response Example

{
  "results": [
    {
      "managerId": 789,
      "attributes": [
        {"name": "theme", "value": "dark"},
        {"name": "uiColor", "value": "123456"}
      ],
      "utcLastUpdateTimestamp": 1688923200000
    },
    {
      "managerId": 790,
      "attributes": [
        {"name": "theme", "value": "light"}
      ],
      "utcLastUpdateTimestamp": 1688923200000
    }
  ]
}

Expected Status Code

200

Update Trader Attributes

HTTP Method	URL
PUT	/webserv/traders/attributes

Creates or updates (upserts) multiple traders’ attribute sets in one call.

info

The call succeeds for authorised trader IDs, while unauthorised ones are omitted from the response. When none of the supplied IDs pass access control, the call returns 403.

Parameters

No parameters

Request Body

Key	Required?	Data Type	Description
attributeSets	Yes	array	An array (1–100 items) of objects, each containing the fields traderId and attributes. Only authorised trader IDs are processed.
attributeSets.traderId	Yes	integer	The unique identifier of a trader to upsert or delete attributes for.
attributeSets.attributes	Yes	array	An array (1–100 items) of { name, value } pairs. name must be 1–64 UTF-8 characters, not empty. value must be 1–512 UTF-8 characters and not null.

Output

An empty object {} is returned upon success.

Request Example

curl -X PUT 'https://HOST:PORT/v2/webserv/traders/attributes?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -d '{"attributeSets":[{"traderId":102,"attributes":[{"name":"prefixLabel","value":"VIP"}]},{"traderId":999,"attributes":[{"name":"colorCode","value":"FFFFFF"}]}]}'

Response Example

{}

Expected Status Code

200

Update Trader Group Attributes

HTTP Method	URL
PUT	/webserv/tradergroups/attributes

Creates or upserts multiple trader groups' attribute sets in one call.

info

The call succeeds for authorised trader group IDs, while unauthorised ones are omitted from the response. When none of the supplied IDs pass access control, the call returns 403.

Parameters

No parameters

Request Body

Key	Required?	Data Type	Description
attributeSets	Yes	array	An array (1–100 items) of objects, each containing the fields traderGroupId and attributes. Only authorised trader group IDs are processed.
attributeSets.traderGroupId	Yes	integer	The unique identifier of a trader group to upsert or delete attributes for.
attributeSets.attributes	Yes	array	An array (1–100 items) of { name, value } pairs. name must be 1–64 UTF-8 characters, not empty. value must be 1–512 UTF-8 characters and not null.

Output

An empty object {} is returned upon success.

Request Example

curl -X PUT 'https://HOST:PORT/v2/webserv/tradergroups/attributes?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -d '{"attributeSets":[{"traderGroupId":456,"attributes":[{"name":"colorCode","value":"FFAA00"}]},{"traderGroupId":999,"attributes":[{"name":"prefixLabel","value":"VIP"}]}]}'

Response Example

{}

Expected Status Code

200

Update Manager Attributes

HTTP Method	URL
PUT	/webserv/managers/attributes

Creates or updates (upserts) multiple managers’ attribute sets in one call.

info

The call succeeds for authorised manager IDs, while unauthorised ones are omitted from the response. When none of the supplied IDs pass access control, the call returns 403.

Parameters

No parameters

Request Body

Key	Required?	Data Type	Description
attributeSets	Yes	array	An array (1–100 items) of objects, each containing the fields managerId and attributes. Only authorised manager IDs are processed.
attributeSets.managerId	Yes	integer	The unique identifier of a manager to upsert or delete attributes for. For a regular manager, only their own ID is allowed; for a super-admin, any ID is allowed.
attributeSets.attributes	Yes	array	An array (1–100 items) of { name, value } pairs. name must be 1–64 UTF-8 characters, not empty. value must be 1–512 UTF-8 characters and not null.

Output

An empty object {} is returned upon success.

Request Example

curl -X PUT 'https://HOST:PORT/v2/webserv/managers/attributes?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -d '{"attributeSets":[{"managerId":789,"attributes":[{"name":"theme","value":"dark"},{"name":"uiColor","value":"123456"}]},{"managerId":999,"attributes":[{"name":"prefixLabel","value":"VIP"}]}]}'

Response Example

{}

Expected Status Code

200

Delete Trader Attributes

HTTP Method	URL
DELETE	/webserv/traders/attributes

Deletes one or more traders' attributes in bulk.

info

The call succeeds for authorised trader IDs, while unauthorised ones are omitted from the operation. A 403 status is returned only if none of the supplied IDs are authorised. If names is omitted or empty, all attributes for the specified traders are deleted.

Parameters

No parameters

Request Body

Key	Required?	Data Type	Description
traderIds	Yes	array	An array (1–10,000) of trader IDs whose attributes are to be deleted.
names	No	array	An array (0–100) of attribute names to delete. If omitted or empty, all attributes for the specified traders are deleted. Each name must be 1–64 UTF-8 characters, not empty.

Output

An empty object {} is returned upon success.

Request Example

curl -X DELETE 'https://HOST:PORT/v2/webserv/traders/attributes?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -d '{"traderIds":[101,102],"names":["colorCode"]}'

Response Example

{}

Expected Status Code

200

Delete Trader Group Attributes

HTTP Method	URL
DELETE	/webserv/tradergroups/attributes

Deletes one or more trader groups’ attributes in bulk.

info

The call succeeds for authorised trader group IDs, while unauthorised ones are omitted from the operation. A 403 status is returned only if none of the supplied IDs are authorised. If names is omitted or empty, all attributes for the specified trader groups are deleted.

Parameters

No parameters

Request Body

Key	Required?	Data Type	Description
traderGroupIds	Yes	array	An array (1–10,000) of trader group IDs whose attributes are to be deleted.
names	No	array	An array (0–100) of attribute names to delete. If omitted or empty, all attributes for the specified trader groups are deleted. Each name must be 1–64 UTF-8 characters, not empty.

Output

An empty object {} is returned upon success.

Request Example

curl -X DELETE 'https://HOST:PORT/v2/webserv/tradergroups/attributes?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -d '{"traderGroupIds":[456,457],"names":["colorCode"]}'

Response Example

{}

Expected Status Code

200

Delete Manager Attributes

HTTP Method	URL
DELETE	/webserv/managers/attributes

Deletes one or more managers’ attributes in bulk.

info

The call succeeds for authorised manager IDs, while unauthorised ones are omitted from the operation. A 403 status is returned only if none of the supplied IDs are authorised. If names is omitted or empty, all attributes for the specified managers are deleted.

warning

Regular (non-super-admin) managers may only delete their own ID; super-admins may delete any.

Parameters

No parameters

Request Body

Key	Required?	Data Type	Description
managerIds	Yes	array	An array (1–10,000) of manager IDs whose attributes are to be deleted.
names	No	array	An array (0–100) of attribute names to delete. If omitted or empty, all attributes for the specified managers are deleted. Each name must be 1–64 UTF-8 characters, not empty.

Output

An empty object {} is returned upon success.

Request Example

curl -X DELETE 'https://HOST:PORT/v2/webserv/managers/attributes?token=1dd4ef40-c5b3-61c0-0689-b1b40c97fadc' -H 'Content-Type: application/json' -d '{"managerIds":[789,790],"names":["theme"]}'

Response Example

{}

Expected Status Code

200