This section provides the JSON schemas for all major server entities on which you can perform operations while using the WebServices API.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Trader",
"description": "The entity responsible for performing trading operations",
"type": "object",
"properties": {
"login": {
"description": "The number of a specific trading account",
"type": "long",
"examples": [
9017800
]
},
"groupName": {
"description": "The name of the group to which the account is assigned",
"type": "string",
"examples": [
"Default"
]
},
"depositCurrency": {
"description": "The name of the currency that the account uses for making deposits and withdrawals",
"type": "string",
"examples": [
"EUR",
"USD",
"CHF"
]
},
"name": {
"description": "The first name of the account holder",
"type": "string",
"examples": [
"John"
]
},
"lastName": {
"description": "The last name of the account holder",
"type": "string",
"examples": [
"Smith"
]
},
"description" : {
"description": "The description of the account",
"type": "string",
"examples": [
"John's account"
]
},
"accessRights": {
"description": "The access rights of the account",
"type": "enum",
"oneOf": [
{
"const": "FULL_ACCESS",
"description": "The account can perform all operations with no restrictions"
},
{
"const": "CLOSE_ONLY",
"description": "The account can only close existing positions"
},
{
"const": "NO_TRADING",
"description": "The account cannot perform any trading operations"
},
{
"const": "NO_LOGIN",
"description": "The account cannot log into cTrader"
}
]
},
"balance": {
"description": "The total balance of the new account",
"type": "long",
"examples": [
1234512
]
},
"bonus": {
"description": "The total amount of bonus funds allocated to the account",
"type": "long",
"examples": [
1234512
]
},
"cashEquity": {
"description": "The total amount of funds that the account owner can withdraw",
"type": "long",
"examples": [
1234512
]
},
"nonWithdrawableBonus": {
"description": "The total amount of credit allocated to the account",
"type": "long",
"examples": [
1234512
]
},
"leverageInCents": {
"description": "The total amount of leverage available to the account; is specified in 10^2",
"type": "int",
"examples": [
100
]
},
"contactDetails": {
"description": "An object containing the trader’s address, phone number, and other details",
"type": "object",
"properties": {
"address": {
"description": "The trader’s address of residence",
"type": "string",
"examples": [
"Moon"
]
},
"city": {
"description": "The trader’s city of residence",
"type": "string",
"examples": [
"Lake"
]
},
"countryId": {
"description": "The identifier denoting the trader's country of residence",
"type": "integer",
"examples": [
8
]
},
"documentId": {
"description": "The trader’s unique document ID",
"type": "string",
"examples": [
"01234"
]
},
"email": {
"description": "The trader's email address",
"type": "string",
"examples": [
"president@bestbroker.com"
]
},
"phone": {
"description": "The trader's phone number",
"type": "string",
"examples": [
"+50987654321"
]
},
"state": {
"description": "The trader's state of residence",
"type": "string",
"examples": [
"RE"
]
},
"zipCode": {
"description": "The zip code of the trader’s residence",
"type": "string",
"examples": [
"5500"
]
},
"introducingBroker1": {
"description": "A custom designation of the first-level partner to which the trader is attributed",
"type": "string",
"examples": [
"CoolPartner"
]
},
"introducingBroker2": {
"description": "A custom designation of the second-level partner to which the trader is attributed",
"type": "string",
"examples": [
"GreatPartner"
]
},
"required": []
}
},
"accountType": {
"description": "The type of the trading account",
"type": "enum",
"oneOf": [
{
"const": "HEDGED",
"description": "The account can open positions in both directions for the same symbol simultaneously"
},
{
"const": "NETTED",
"description": "The account can only positions in one direction for a given symbol"
},
{
"const": "SPREAD_BETTING",
"description": "The account can perform spread betting operations"
}
]
},
"sendOwnStatement": {
"description": "A flag determining whether a daily trading statement is sent to the trader",
"type": "boolean",
"examples": [
true
]
},
"swapFree": {
"description": "A flag determining whether the account is charged swaps or administrative fees",
"type": "boolean",
"examples": [
false
]
},
"brokerName": {
"description": "A unique name denoting a specific broker (including White Labels)",
"type": "string",
"examples": [
"BESTBROKER"
]
},
"totalMarginCalculationType": {
"description": "The strategy via which the account margin is calculated",
"type": "enum",
"oneOf": [
{
"const": "MAX",
"description": "The total margin requirements per symbol are equal to the maximum margin requirements for all positions opened for this symbol"
},
{
"const": "SUM",
"description": "The total margin requirements per symbol are equal to the sum of all margin requirements of all positions opened for this symbol"
},
{
"const": "NET",
"description": "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."
}
]
},
"maxLeverage": {
"description": "The maximum amount of leverage (in the base currency units) available to the account",
"type": "integer",
"examples": [
10000
]
},
"isLimitedRisk": {
"description": "The trader’s limited risk (LR) status",
"type": "boolean"
},
"limitedRiskMarginCalculationStrategy": {
"description": "The margin calculation strategy used for a limited risk account",
"type": "enum",
"oneOf": [
{
"const": "ACCORDING_TO_LEVERAGE",
"description": "Margin requirements have to be calculated based on the account leverage"
},
{
"const": "ACCORDING_TO_GSL",
"description": "Margin requirements have to be calculated based on the distance between the position open price and the guaranteed stop loss"
},
{
"const": "ACCORDING_TO_GSL_AND_LEVERAGE",
"description": "cServer calculates the leverage-based and GSL-based margin requirements, and chooses the larger of the two values"
}
]
},
"sendStatementToBroker": {
"description": " A flag determining whether a daily account trading statement is sent to the broker",
"type": "boolean",
"examples": [
false
]
},
"registrationTimestamp": {
"description": " A timestamp with the date and time of account registration",
"type": "long",
"examples": [
1680087970
]
},
"lastUpdateTimeStamp": {
"description": "A timestamp with the date and time of the last account update",
"type": "long",
"examples": [
1680087970
]
},
"lastConnectionTimestamp": {
"description": "A timestamp with the date and time of the last connection to cTrader by the account",
"type": "long",
"examples": [
1680087970
]
}
},
"required": [
"login", "groupName", "depositCurrency", "accessRights", "balance", "bonus", "nonWithdrawableBonus", "leverageInCents", "contactDetails", "registrationTimestamp", "lastUpdateTimestamp", "equity", "usedMargin", "freeMargin", "accountType"
]
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Group",
"description": "The entity that aggregates traders based on custom criteria",
"type": "object",
"properties": {
"id": {
"description": "The identifier of an account group",
"type": "long",
"examples": [
51350
]
},
"name": {
"description": "The name of an account group",
"type": "string",
"examples": [
"Default Group"
]
},
"description": {
"description": "The description of an account group",
"type": "string",
"examples": [
"Default group for new traders"
]
}
},
"required": ["id", "name"]
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "User",
"description": "The entity responsible for user authorization",
"type": "object",
"properties": {
"userId": {
"description": "The unique identifier of a user entity",
"type": "string",
"examples": [
10333,
]
},
"nickname": {
"description": "The nickname of a user entity",
"type": "string",
"examples": [
"ctid10333"
]
},
"email": {
"description": "The email assigned to the user entity",
"type": "string",
"examples": [
"president@bestbroker.com"
]
},
"utcCreateTimestamp": {
"description": "The epoch unix timestamp of the creation of the user entity",
"type": "long",
"examples": [
1679898064783
]
},
"preferredLanguage": {
"description": "An Alpha-2 code denoting the preferred language of the user entity",
"type": "string",
"examples": [
"en"
]
},
"status": {
"description": "The status of the user entity",
"type": "enum",
"oneOf": [
{
"const": "CTID_NEW",
"description": "The default status for any new user"
},
{
"const": "CTID_ACTIVE",
"description": "The status denoting an existing active user"
},
{
"const": "CTID_DELETED",
"description": "The status denoting a deleted user entity"
}
]
},
},
"required": ["userId", "email", "nickname"]
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Symbol",
"description": "The entity for which orders are placed, deals are executed, and positions are opened/closed",
"type": "object",
"properties": {
"name": {
"description": "The name of a symbol",
"type": "string",
"examples": [
"EURUSD",
"GBPJPY",
]
},
"id": {
"description": "The identifier of a symbol",
"type": "integer",
"examples": [
34,
98,
]
},
"description": {
"description": "The description of a symbol",
"type": "string",
"examples": [
"EUR to USD",
"GBP to JPY",
]
},
"assetClass": {
"description": "The name of the asset class to which a symbol belongs to",
"type": "string",
"examples": [
"Forex",
"Commodities",
]
},
"category": {
"description": "The name of the symbol category to which a symbol belongs to",
"type": "string",
"examples": [
"Majors",
"Metals",
]
},
"quotesEnabled": {
"description": "The flag that determines whether a symbol is currently receiving quotes",
"type": "boolean",
"examples": [
true,
false,
]
},
"showInCtrader": {
"description": "The flag that determines whether a symbol is currently shown in cTrader applications",
"type": "boolean",
"examples": [
true,
false,
]
}
},
"required": ["name", "id", "assetClass", "category", "quotesEnabled", "showInCtrader"]
}