j-object (JSON object): a record containing any number of named j-values (pair );

j-array (JSON array): an array where each element is j-value;

j-subvalue: j-value which is a component of a j-object.

A j-object can contain zero elements. A j-array can have zero length. The name of j-value can be an empty string.

Encoding of strings is set to UTF-8. In this format the server sends and receives data.

Definition of unix-time:

Unix time, or POSIX time, is a system for describing points in time, defined as the number of milliseconds elapsed since midnight Coordinated Universal Time (UTC) of January 1, 1970.

General data format

Each packet consists of exactly one main, unnamed j-value. The data stream consists of consecutive j–values, with no punctuation.

The main j-value is a j-object containing exactly two j-subvalues which are j-objects. The first j-subobject is named header and consists of at least a field type as a simple type string. This is a packet type. The second j-subobject of the main packet j-object is named data and its content is specific to a given packet type. The specifications for different types of packages are described in the next chapter.

Every single command sent to the API is allowed to contain an optional field called customTag. The API guarantees to return the very same customTag in the command’s response. For example, the following command:

Communication with the API

There are two addresses (that can be used interchangeably) where the servers are located:

xapia.x-station.eu

xapib.x-station.eu

Here are the details of DEMO and REAL servers hosted on each of the addresses above:

DEMO: main port: 5124, streaming port: 5125,

REAL: main port: 5112, streaming port: 5113.

Furthermore, WebSockets can be used to connect to the API using the following addresses:

wss://ws.xapi.pro/demo

wss://ws.xapi.pro/demoStream

wss://ws.xapi.pro/real

wss://ws.xapi.pro/realStream

There is also a set of old WebSocket addresses, which are currently deprecated and should no longer be used. What is more, the addresses below do not have an SSL certificate which is verified by the certification authority (CA).

wss://62.181.0.153:8079/demo

wss://62.181.0.153:8079/demoStream

wss://62.181.0.153:8079/real

wss://62.181.0.153:8079/realStream

All servers use SSL connection.

Communication is established as long as both server and client have opened and connected sockets.

For convenience server guarantees that every separate reply to client command returned by server will be separated by two new line characters ("\n").

Connection validation

In order to provide best service for all users API set rules on connection and data send process. If any of the following rules is breached, then connection is closed immediately without server notification.

List of rules:

At most 50 simultaneous connections from the same client address are allowed (an attempt to obtain the 51st connection returns the error EX008). If you need this rule can be lenified please contact the xStore Support Team.

Every new connection that fails to deliver data within one second from when it is established may be forced to close with no notification.

Each command invocation should not contain more than 1kB of data.

User should send requests in 200 ms intervals. This rule can be broken, but if it happens 6 times in a row the connection is dropped.

Each command should be a proper JSON object.

Exception:

If the client sends a request that is a valid JSON object, but does not conform to the published API (incorrect command, missing fields, etc.), the response is sent back with the error description but the connection is not closed.

This rule prevents incorrect messages from reaching further down the processing chain and allows clients to analyze and understand the source of problem.

The status of the correct login process is true. If the status is false, REDIRECT_RECORD may be present which defines the server that the user should log into instead of the current one. It is assumed that when using REDIRECT_RECORD data, secure connection (SSL) should be used.

The streamSessionId field of the string type, if present, is a token that can be used to establish a streaming subscription on a separate network connection. streamSessionId is used in streaming subscription commands.

streamSessionId is unique for the given main session and will change between login sessions.

Logout

Format of input:

{
"command": "logout"
}

No returnData field in output. Only status message is sent.

Retrieving trading data

Command: getAllSymbols

Description: Returns array of all symbols available for the user.

Request:

Example:

{
"command": "getAllSymbols"
}

Response:

Please be advised that result values for profit and margin calculation can be used optionally, because server is able to perform all profit/margin calculations for Client application by commands described later in this document.

name

type

description

ask

Floating number

Ask price in base currency

bid

Floating number

Bid price in base currency

categoryName

String

Category name

contractSize

Number

Size of 1 lot

currency

String

Currency

currencyPair

Boolean

Indicates whether the symbol represents a currency pair

currencyProfit

String

The currency of calculated profit

description

String

Description

expiration

Time

Null if not applicable

groupName

String

Symbol group name

high

Floating number

The highest price of the day in base currency

initialMargin

Number

Initial margin for 1 lot order, used for profit/margin calculation

instantMaxVolume

Number

Maximum instant volume multiplied by 100 (in lots)

leverage

Number

Symbol leverage

longOnly

Boolean

Long only

lotMax

Floating number

Maximum size of trade

lotMin

Floating number

Minimum size of trade

lotStep

Floating number

A value of minimum step by which the size of trade can be changed (within lotMin - lotMax range)

Command: getChartLastRequest

Description: Please note that this function can be usually replaced by its streaming equivalent getCandles which is the preferred way of retrieving current candle data. Returns chart info, from start date to the current time. If the chosen period of CHART_LAST_INFO_RECORD is greater than 1 minute, the last candle returned by the API can change until the end of the period (the candle is being automatically updated every minute).

Command: getChartRangeRequest

Description: Please note that this function can be usually replaced by its streaming equivalent getCandles which is the preferred way of retrieving current candle data. Returns chart info with data between given start and end dates.

Request:

Ticks field - if ticks is not set or value is 0, getChartRangeRequest works as before (you must send valid start and end time fields).
If ticks value is not equal to 0, field end is ignored.
If ticks >0 (e.g. N) then API returns N candles from time start.
If ticks <0 then API returns N candles to time start.
It is possible for API to return fewer chart candles than set in tick field.

name

type

description

end

Time

End of chart block (rounded down to the nearest interval and excluding)

period

Number

Period code

start

Time

Start of chart block (rounded down to the nearest interval and excluding)

symbol

String

Symbol

ticks

Number

Number of ticks needed, this field is optional, please read the description above

Command: getMarginLevel

Description: Please note that this function can be usually replaced by its streaming equivalent getBalance which is the preferred way of retrieving account indicators. Returns various account indicators.

Request:

Response:

Parameters:

name

type

description

margin

Floating number

calculated margin in account currency

Example:

{
"status": true,
"returnData": {
"margin": 4399.350
}
}

Command: getNews

Description: Please note that this function can be usually replaced by its streaming equivalent getNews which is the preferred way of retrieving news data. Returns news from trading server which were sent within specified period of time.

Command: getProfitCalculation

Description: Calculates estimated profit for given deal data Should be used for calculator-like apps only. Profit for opened transactions should be taken from server, due to higher precision of server calculation.

Response:

Please be advised that result values for profit and margin calculation can be used optionally, because server is able to perform all profit/margin calculations for Client application by commands described later in this document.

name

type

description

ask

Floating number

Ask price in base currency

bid

Floating number

Bid price in base currency

categoryName

String

Category name

contractSize

Number

Size of 1 lot

currency

String

Currency

currencyPair

Boolean

Indicates whether the symbol represents a currency pair

currencyProfit

String

The currency of calculated profit

description

String

Description

expiration

Time

Null if not applicable

groupName

String

Symbol group name

high

Floating number

The highest price of the day in base currency

initialMargin

Number

Initial margin for 1 lot order, used for profit/margin calculation

instantMaxVolume

Number

Maximum instant volume multiplied by 100 (in lots)

leverage

Number

Symbol leverage

longOnly

Boolean

Long only

lotMax

Floating number

Maximum size of trade

lotMin

Floating number

Minimum size of trade

lotStep

Floating number

A value of minimum step by which the size of trade can be changed (within lotMin - lotMax range)

Command: getTickPrices

Description: Please note that this function can be usually replaced by its streaming equivalent getTickPrices which is the preferred way of retrieving ticks data. Returns array of current quotations for given symbols, only quotations that changed from given timestamp are returned. New timestamp obtained from output will be used as an argument of the next call of this command.

Request:

Parameters:

name

type

description

level

Number

price level

symbols

array

Array of symbol names (Strings)

timestamp

Time

The time from which the most recent tick should be looked for. Historical prices cannot be obtained using this parameter. It can only be used to verify whether a price has changed since the given time.

Read only. Used in getTradesHistory for manager's deposit/withdrawal operations (profit>0 for deposit, profit<0 for withdrawal).

CREDIT

7

Read only

Command: getTradesHistory

Description: Please note that this function can be usually replaced by its streaming equivalent getTrades which is the preferred way of retrieving trades data. Returns array of user's trades which were closed within specified period of time.

Command: getVersion

Request:

Example:

{
"command": "getVersion"
}

Response:

Parameters:

name

type

description

version

String

current API version

Example:

{
"status": true,
"returnData": {
"version": "2.4.5"
}
}

Command: ping

Description: Regularly calling this function is enough to refresh the internal state of all the components in the system. It is recommended that any application that does not execute other commands, should call this command at least once every 10 minutes. Please note that the streaming counterpart of this function is called getKeepAlive .

Response:

Parameters:

name

type

description

order

Number

order

Example:

{
"status": true,
"returnData": {
"order": 43
}
}

Command: tradeTransactionStatus

Description: Please note that this function can be usually replaced by its streaming equivalent getTradeStatus which is the preferred way of retrieving transaction status data. Returns current transaction status. At any time of transaction processing client might check the status of transaction on server side. In order to do that client must provide unique order taken from tradeTransaction invocation.

Available streaming commands

Each streaming command takes as an argument streamSessionId which is sent in response message for login command performed in main connection. streamSessionId token allows to identify user in streaming connection. In one streaming connection multiple commands with different streamSessionId can be invoked. It will cause sending streaming data for multiple login sessions in one streaming connection. streamSessionId is valid until logout command is performed on main connection or main connection is disconnected.

Command: getBalance

Description: Allows to get actual account indicators values in real-time, as soon as they are available in the system.

Command: getTickPrices

Description: Establishes subscription for quotations and allows to obtain the relevant information in real-time, as soon as it is available in the system. The getTickPrices command can be invoked many times for the same symbol, but only one subscription for a given symbol will be created. Please beware that when multiple records are available, the order in which they are received is not guaranteed.

Subscribe format:

Parameters:

name

type

description

symbol

String

Symbol

minArrivalTime

Number

This field is optional and defines the minimal interval in milliseconds between any two consecutive updates. If this field is not present, ticks are sent to the client as soon and as frequently as they are available.

maxLevel

Number

This field is optional and specifies the maximum level of the quote that the user is interested in. If this field is not specified, the subscription is active for all levels that are managed in the system.

Command: getTrades

Description: Establishes subscription for user trade status data and allows to obtain the relevant information in real-time, as soon as it is available in the system. Please beware that when multiple records are available, the order in which they are received is not guaranteed.

Situation that trade was closed can be checked by field closed set to true in STREAMING_TRADE_RECORD format. Also
close_time field will NOT be set to null. Various reasons of trade close could be found out by information in
comment field of STREAMING_TRADE_RECORD for closed order. If the comment remained unchanged from that
of opened order, then the order was closed by user. If there is annotation in comment string like:

Command: getTradeStatus

Description: Allows to get status for sent trade requests in real-time, as soon as it is available in the system. Please beware that when multiple records are available, the order in which they are received is not guaranteed.