Version 2.3
This document presents information on API communication protocol. The communication protocol of the API uses JSON format.
JSON format used by the server doesn't allow extensions (e.g. comments, other flags). JSON format standardization document is available under the following link: http://tools.ietf.org/html/rfc4627.
The connection is performed by clean socket connection. For real trading SSL connection will be used.
The following definitions will be used in this specification document:
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.
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.
A sample of properly defined packet:
{ "command" : "login", "arguments" : { "userId" : 1000, "password": "PASSWORD" } }
There are two IPs, that can be used interchangeably:
Here are the addresses of DEMO and REAL servers:
Both 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").
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:
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.
Default login credentials can be obtained at: http://developers.xstore.pro/panel/.
The input data format is a JSON object that consists of service name and command name. Some commands also require an object of command's arguments.
If optional prettyPrint
field is set to true, an output JSON is printed in human-readable format. prettyPrint
field can be omitted.
{ "command": "commandName", "arguments": { "arg1Name": 10, "arg2Name": "Some text", ... }, "prettyPrint": true }
The output data format is a JSON object that consists of status
and returnData
fields if command succeeded, or status
, errorCode
and errorDescr
fields if an error occurred.
{ "status": true, "returnData": JSON value }
or, in case of an error:
{ "status": false, "errorCode": "E123", "errorDescr": "Error description" }
Time is number of milliseconds from 01.01.1970, 00:00 GMT.
In all Floating numbers '.' (period) is used as a decimal separator.
Request-Reply commands are performed on main connection socket. The reply is sent by main connection socket.
In order to perform any action client application have to perform login process. No functionality is available before proper login process.
After initial login, a new session is created and all commands are executed for a logged user until he/she logs out or drops the connection.
Parameters:
Name | Type | Desc |
---|---|---|
userId | Number | userId |
password | String | password |
appId | String | (optional) application ID provided by the xStore Support Team |
appName | String | (optional) application name |
Example:
{ "command": "login", "arguments": { "userId": 100, "password": "PASSWORD", "appId": "test", "appName": "test" } }
After successful login the system responds with the status
message that can contain the String representing streamSessionId
field:
{ "status": true, "streamSessionId": "8469308861804289383" }
Alternatively, when redirect is needed, the system responds with:
{ "status": false, "redirect": REDIRECT_RECORD (optional) }
Format of REDIRECT_RECORD
:
name | type | description |
---|---|---|
mainPort | Number | Main port for communication |
streamingPort | Number | streaming port |
address | String | address that the user should reconnect to in order to login |
Example:
{ "mainPort": 1234, "streamingPort": 1235, "address": "xapia.x-station.eu" }
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.
Format of input:
{ "command": "logout" }
No returnData
field in output. Only status
message is sent.
Description: Returns array of all symbols available for the user.
Example:
{ "command": "getAllSymbols" }
Parameters:
name | type | description |
---|---|---|
array | Array of SYMBOL_RECORD |
Example:
{ "status": true, "returnData" : [SYMBOL_RECORD, SYMBOL_RECORD, ...] }
Format of SYMBOL_RECORD
:
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 |
bid | Floating number | Bid |
categoryName | String | Category name |
contractSize | Number | Size of 1 lot in currency |
currency | String | Currency |
currencyProfit | String | The currency of calculated profit |
description | String | Description |
expiration | Time | Null if not applicable |
groupName | String | Group name |
high | Floating number | High |
initialMargin | Number | Initial margin for 1 lot order, used for profit/margin calculation |
instantMaxVolume | Number | Maximum instant volume multiplied by 100 |
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) |
low | Floating number | Low |
marginHedged | Number | Used for profit calculation |
marginHedgedStrong | Boolean | For margin calculation |
marginMaintenance | Number | For margin calculation, null if not applicable |
marginMode | Number | For margin calculation |
percentage | Floating number | Percentage |
precision | Number | Number of symbol's price decimal places |
profitMode | Number | For profit calculation |
quoteId | Number | Source of price |
starting | Time | Null if not applicable |
stopsLevel | Number | Stop level |
swap_rollover3days | Number | Time when additional swap is accounted for weekend |
swapEnable | Boolean | Indicates whether swap value is added to position on end of day |
swapLong | Floating number | Swap value for long positions |
swapShort | Floating number | Swap value for short positions |
swapType | Number | Type of swap calculated |
symbol | String | Symbol |
tickSize | Floating number | Smallest possible price change, used for profit/margin calculation, null if not applicable |
tickValue | Floating number | Value of smallest possible price change, used for profit/margin calculation, null if not applicable |
time | Time | Time |
timeString | String | Time in String |
type | Number | Instrument class number |
Example:
{ "ask": 4000.0, "bid": 4000.0, "categoryName": "Forex", "contractSize": 100000, "currency": "USD", "currencyProfit": "SEK", "description": "USD/PLN", "expiration": null, "groupName": "Minor", "high": 4000.0, "initialMargin": 0, "instantMaxVolume": 0, "longOnly": false, "lotMax": 10.0, "lotMin": 0.1, "lotStep": 0.1, "low": 3500.0, "marginHedged": 0, "marginHedgedStrong": false, "marginMaintenance": null, "marginMode": 4, "percentage": 0.1, "precision": 2, "profitMode": 1, "quoteId": 1, "starting": null, "stopsLevel": 15, "swap_rollover3days": 0, "swapEnable": true, "swapLong": -2.55929, "swapShort": 0.131, "swapType": 0, "symbol": "USDPLN", "tickSize": 1.0, "tickValue": 1.0, "time": 1272446136891, "timeString": "Thu May 23 12:23:44 EDT 2013", "type": 21 }
Possible values of quoteId
field:
name | value | description |
---|---|---|
fixed | 1 | fixed |
float | 2 | float |
depth | 3 | depth |
cross | 4 | cross |
Description: Returns calendar with market events.
Example:
{ "command": "getCalendar" }
Parameters:
name | type | description |
---|---|---|
array | Array of CALENDAR_RECORD |
Example:
{ "status": true, "returnData" : [CALENDAR_RECORD, CALENDAR_RECORD, ...] }
Format of CALENDAR_RECORD
:
name | type | description |
---|---|---|
country | String | Two letter country code |
current | String | Market value (current), empty before time of release of this value (time from "time" record) |
forecast | String | Forecasted value |
impact | String | Impact on market |
period | String | Information period |
previous | String | Value from previous information release |
time | Time | Time, when the information will be released (in this time empty "current" value should be changed with exact released value) |
title | String | Name of the indicator for which values will be released |
Example:
{ "country": "CA", "current": "", "forecast": "", "impact": "3", "period": "(FEB)", "previous": "58.3", "time": 1374846900000, "title": "Ivey Purchasing Managers Index" }
Possible values of impact
field:
name | value | description |
---|---|---|
low | 1 | low |
medium | 2 | medium |
high | 3 | high |
Description: Returns chart info, from start date to the current time.
Parameters:
name | type | description |
---|---|---|
info | CHART_LAST_INFO_RECORD | info |
Example:
{ "command": "getChartLastRequest", "arguments": { "info": CHART_LAST_INFO_RECORD } }
Format of CHART_LAST_INFO_RECORD
:
name | type | description |
---|---|---|
period | Number | Period code |
start | Time | Start of chart block |
symbol | String | Symbol |
Example:
{ "period": 5, "start": 1262944112000, "symbol": "PKN.PL" }
Possible values of period
field:
name | value | description |
---|---|---|
PERIOD_M1 | 1 | 1 minute |
PERIOD_M5 | 5 | 5 minutes |
PERIOD_M15 | 15 | 15 minutes |
PERIOD_M30 | 30 | 30 minutes |
PERIOD_H1 | 60 | 60 minutes (1 hour) |
PERIOD_H4 | 240 | 240 minutes (4 hours) |
PERIOD_D1 | 1440 | 1440 minutes (1 day) |
PERIOD_W1 | 10080 | 10080 minutes (1 week) |
PERIOD_MN1 | 43200 | 43200 minutes (30 days) |
Parameters:
name | type | description |
---|---|---|
digits | Number | price precision |
rateInfos | array | Array of RATE_INFO_RECORD |
Example:
{ "status": true, "returnData" : { "digits": 2, "rateInfos": [RATE_INFO_RECORD, RATE_INFO_RECORD, ...] } }
Format of RATE_INFO_RECORD
:
Price values must be divided by 10 to the power of digits in order to obtain exact prices.
Ticks field - if ticks is not set or value is 0, getChartRangeRequest
work 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 return N candles from time start.
If ticks <0 then api return N candles to time start.
It is possible for api to return fewer chart candles than set in tick field.
name | type | description |
---|---|---|
close | Floating number | Value of close price (shift from open price) |
ctm | Time | Rate time |
ctmString | String | Value of close price (shift from open price) |
high | Floating number | Highest value in period (shift from open price) |
low | Floating number | Lowest value in period (shift from open price) |
open | Floating number | Example value of real open price: 119.87 |
vol | Floating number | Volume |
Example:
{ "close": 1.0, "ctm": 1262944112000, "ctmString": "Mar 21, 2013 4:15:00 PM", "high": 6.0, "low": 0.0, "open": 41848.0, "vol": 12.00 }
Description: Returns chart info with data between given start and end dates. Method retrieves two oldest RATE_INFO_RECORD
in case no data is available for selected period.
Parameters:
name | type | description |
---|---|---|
info | CHART_RANGE_INFO_RECORD | info |
Example:
{ "command": "getChartRangeRequest", "arguments": { "info": CHART_RANGE_INFO_RECORD } }
Format of CHART_RANGE_INFO_RECORD
:
name | type | description |
---|---|---|
end | Time | End of chart block |
period | Number | Period code |
start | Time | Start of chart block |
symbol | String | Symbol |
ticks | Number | Numbers needed ticks, this field is optional, please read description below |
Example:
{ "end": 1262944412000, "period": 5, "start": 1262944112000, "symbol": "PKN.PL", "ticks": 0 }
Possible values of period
field:
name | value | description |
---|---|---|
PERIOD_M1 | 1 | 1 minute |
PERIOD_M5 | 5 | 5 minutes |
PERIOD_M15 | 15 | 15 minutes |
PERIOD_M30 | 30 | 30 minutes |
PERIOD_H1 | 60 | 60 minutes (1 hour) |
PERIOD_H4 | 240 | 240 minutes (4 hours) |
PERIOD_D1 | 1440 | 1440 minutes (1 day) |
PERIOD_W1 | 10080 | 10080 minutes (1 week) |
PERIOD_MN1 | 43200 | 43200 minutes (30 days) |
Parameters:
name | type | description |
---|---|---|
digits | Number | price precision |
rateInfos | array | Array of RATE_INFO_RECORD |
Example:
{ "status": true, "returnData" : { "digits": 2, "rateInfos": [RATE_INFO_RECORD, RATE_INFO_RECORD, ...] } }
Format of RATE_INFO_RECORD
:
Price values must be divided by 10 to the power of digits in order to obtain exact prices.
Ticks field - if ticks is not set or value is 0, getChartRangeRequest
work 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 return N candles from time start.
If ticks <0 then api return N candles to time start.
It is possible for api to return fewer chart candles than set in tick field.
name | type | description |
---|---|---|
close | Floating number | Value of close price (shift from open price) |
ctm | Time | Rate time |
ctmString | String | Value of close price (shift from open price) |
high | Floating number | Highest value in period (shift from open price) |
low | Floating number | Lowest value in period (shift from open price) |
open | Floating number | Example value of real open price: 119.87 |
vol | Floating number | Volume |
Example:
{ "close": 1.0, "ctm": 1262944112000, "ctmString": "Mar 21, 2013 4:15:00 PM", "high": 6.0, "low": 0.0, "open": 41848.0, "vol": 12.00 }
Description: Returns calculation of commission and rate of exchange. The value is calculated as expected value, and therefore might not be perfectly accurate.
Parameters:
name | type | description |
---|---|---|
symbol | String | symbol |
volume | Floating number | volume |
Example:
{ "command": "getCommissionDef", "arguments": { "symbol": "T.US", "volume": 1.0 } }
Parameters:
name | type | description |
---|---|---|
commission | Floating number | calculated commission, could be null if not applicable |
rateOfExchange | Floating number | rate of exchange between account currency and instrument base currency, could be null if not applicable |
Example:
{ "status": true, "returnData" : { "commission": 0.51, "rateOfExchange": 0.1609 } }
Description: Returns information about account currency, and account leverage.
Example:
{ "command": "getCurrentUserData" }
Parameters:
name | type | description |
---|---|---|
currency | String | account currency |
leverage | Number | Leverage for account. Leverage is used for margin calculation for Forex instruments. |
Example:
{ "status": true, "returnData" : { "currency": "PLN", "leverage": 100 } }
Description: Returns margin level for account.
Example:
{ "command": "getMarginLevel" }
Parameters:
name | type | description |
---|---|---|
balance | Floating number | balance |
currency | String | user currency |
equity | Floating number | sum of balance and all profits |
margin | Floating number | margin requirements |
margin_free | Floating number | free margin |
margin_level | Floating number | margin level |
Example:
{ "status": true, "returnData" : { "balance": 995800269.43, "currency": "PLN", "equity": 995985397.56, "margin": 572634.43, "margin_free": 995227635.00, "margin_level": 173930.41 } }
Description: Returns expected margin for given instrument and volume. The value is calculated as expected margin value, and therefore might not be perfectly accurate.
Parameters:
name | type | description |
---|---|---|
symbol | String | symbol |
volume | Floating number | volume |
Example:
{ "command": "getMarginTrade", "arguments": { "symbol": "EURPLN", "volume": 1.0 } }
Parameters:
name | type | description |
---|---|---|
Floating number | calculated margin |
Example:
{ "status": true, "returnData" : 4399.35 }
Description: Returns news from trading server which were sent within specified period of time.
Parameters:
name | type | description |
---|---|---|
end | Time | Time, 0 means current time for simplicity |
start | Time | Time |
Example:
{ "command": "getNews", "arguments": { "end": 0, "start": 1275993488000 } }
Parameters:
name | type | description |
---|---|---|
array | Array of NEWS_TOPIC_RECORD |
Example:
{ "status": true, "returnData" : [NEWS_TOPIC_RECORD, NEWS_TOPIC_RECORD, ...] }
Format of NEWS_TOPIC_RECORD
:
name | type | description |
---|---|---|
body | String | Body |
bodylen | Number | Body length |
key | String | News key |
time | Time | Time |
timeString | String | Time string |
title | String | News title |
Example:
{ "body": "<html>...</html>", "bodylen": 110, "key": "1f6da766abd29927aa854823f0105c23", "time": 1262944112000, "timeString": "May 17, 2013 4:30:00 PM", "title": "Breaking trend" }
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.
Parameters:
name | type | description |
---|---|---|
closePrice | Floating number | theoretical close price of order |
cmd | Number | Operation code |
openPrice | Floating number | theoretical open price of order |
symbol | String | symbol |
volume | Floating number | volume |
Example:
{ "command": "getProfitCalculation", "arguments": { "closePrice": 1.3000, "cmd": 0, "openPrice": 1.2233, "symbol": "EURPLN", "volume": 1.0 } }
Possible values of cmd
field:
name | value | description |
---|---|---|
BUY | 0 | buy |
SELL | 1 | sell |
BUY_LIMIT | 2 | buy limit |
SELL_LIMIT | 3 | sell limit |
BUY_STOP | 4 | buy stop |
SELL_STOP | 5 | sell stop |
BALANCE | 6 | Read only. Used for manager's deposit/withdrawal operations (profit>0 for deposit, profit<0 for withdrawal). |
Parameters:
name | type | description |
---|---|---|
profit | Floating number | profit |
Example:
{ "status": true, "returnData" : { "profit": 714.303 } }
Description: Returns current time on trading server.
Example:
{ "command": "getServerTime" }
Parameters:
name | type | description |
---|---|---|
time | Time | Time |
timeString | String | Time described in form set on server (local time of server) |
Example:
{ "status": true, "returnData" : { "time": 123456789, "timeString": "Oct 25, 2012 3:39:53 PM" } }
Description: Gets information about symbol available for the user.
Parameters:
name | type | description |
---|---|---|
symbol | String | symbol |
Example:
{ "command": "getSymbol", "arguments": { "symbol": "EURPLN" } }
Parameters:
name | type | description |
---|---|---|
array | Array of SYMBOL_RECORD |
Example:
{ "status": true, "returnData" : [SYMBOL_RECORD, SYMBOL_RECORD, ...] }
Format of SYMBOL_RECORD
:
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 |
bid | Floating number | Bid |
categoryName | String | Category name |
contractSize | Number | Size of 1 lot in currency |
currency | String | Currency |
currencyProfit | String | The currency of calculated profit |
description | String | Description |
expiration | Time | Null if not applicable |
groupName | String | Group name |
high | Floating number | High |
initialMargin | Number | Initial margin for 1 lot order, used for profit/margin calculation |
instantMaxVolume | Number | Maximum instant volume multiplied by 100 |
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) |
low | Floating number | Low |
marginHedged | Number | Used for profit calculation |
marginHedgedStrong | Boolean | For margin calculation |
marginMaintenance | Number | For margin calculation, null if not applicable |
marginMode | Number | For margin calculation |
percentage | Floating number | Percentage |
precision | Number | Number of symbol's price decimal places |
profitMode | Number | For profit calculation |
quoteId | Number | Source of price |
starting | Time | Null if not applicable |
stopsLevel | Number | Stop level |
swap_rollover3days | Number | Time when additional swap is accounted for weekend |
swapEnable | Boolean | Indicates whether swap value is added to position on end of day |
swapLong | Floating number | Swap value for long positions |
swapShort | Floating number | Swap value for short positions |
swapType | Number | Type of swap calculated |
symbol | String | Symbol |
tickSize | Floating number | Smallest possible price change, used for profit/margin calculation, null if not applicable |
tickValue | Floating number | Value of smallest possible price change, used for profit/margin calculation, null if not applicable |
time | Time | Time |
timeString | String | Time in String |
type | Number | Instrument class number |
Example:
{ "ask": 4000.0, "bid": 4000.0, "categoryName": "Forex", "contractSize": 100000, "currency": "USD", "currencyProfit": "SEK", "description": "USD/PLN", "expiration": null, "groupName": "Minor", "high": 4000.0, "initialMargin": 0, "instantMaxVolume": 0, "longOnly": false, "lotMax": 10.0, "lotMin": 0.1, "lotStep": 0.1, "low": 3500.0, "marginHedged": 0, "marginHedgedStrong": false, "marginMaintenance": null, "marginMode": 4, "percentage": 0.1, "precision": 2, "profitMode": 1, "quoteId": 1, "starting": null, "stopsLevel": 15, "swap_rollover3days": 0, "swapEnable": true, "swapLong": -2.55929, "swapShort": 0.131, "swapType": 0, "symbol": "USDPLN", "tickSize": 1.0, "tickValue": 1.0, "time": 1272446136891, "timeString": "Thu May 23 12:23:44 EDT 2013", "type": 21 }
Possible values of quoteId
field:
name | value | description |
---|---|---|
fixed | 1 | fixed |
float | 2 | float |
depth | 3 | depth |
cross | 4 | cross |
Description: 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.
Parameters:
name | type | description |
---|---|---|
level | Number | price level |
symbols | array | Array of symbol names (Strings) |
timestamp | Time | timestamp |
Example:
{ "command": "getTickPrices", "arguments": { "level": 0, "symbols": ["EURPLN", "AGO.PL", ...], "timestamp": 1262944112000 } }
Possible values of level
field:
name | value | description |
---|---|---|
-1 | all available levels | |
0 | base level bid and ask price for instrument | |
>0 | specified level |
Parameters:
name | type | description |
---|---|---|
quotations | array | Array of TICK_RECORD |
Example:
{ "status": true, "returnData" : { "quotations": [TICK_RECORD, TICK_RECORD, ...] } }
Format of TICK_RECORD
:
name | type | description |
---|---|---|
ask | Floating number | Ask |
askVolume | Number | Number of available lots to buy at given price or null if not applicable |
bid | Floating number | Bid |
bidVolume | Number | Number of available lots to buy at given price or null if not applicable |
high | Floating number | High |
level | Number | Price level |
low | Floating number | Low |
symbol | String | Symbol |
timestamp | Time | Timestamp |
Example:
{ "ask": 4000.0, "askVolume": 15000, "bid": 4000.0, "bidVolume": 16000, "high": 4000.0, "level": 0, "low": 3500.0, "symbol": "KOMB.CZ", "timestamp": 1272529161605 }
Possible values of level
field:
name | value | description |
---|---|---|
-1 | all available levels | |
0 | base level bid and ask price for instrument | |
>0 | specified level |
Description: Returns array of trades listed in orders
argument.
Parameters:
name | type | description |
---|---|---|
orders | array | Array of orders (integers) |
Example:
{ "command": "getTradeRecords", "arguments": { "orders": [7489839, 7489841, ...] } }
Parameters:
name | type | description |
---|---|---|
array | Array of TRADE_RECORD |
Example:
{ "status": true, "returnData" : [TRADE_RECORD, TRADE_RECORD, ...] }
Format of TRADE_RECORD
:
cmd
is the operation code, for user's trade operations it equals to cmd
from TRADE_TRANS_INFO
record used as an argument in tradeTransaction
command
name | type | description |
---|---|---|
close_price | Floating number | Close price |
close_time | Time | Null if order is not closed |
close_timeString | String | Null if order is not closed |
closed | Boolean | Closed |
cmd | Number | Operation code |
comment | String | Comment |
commission | Floating number | Commission |
customComment | String | The value the customer may provide in order to retrieve it later. |
digits | Number | Price precision |
expiration | Time | Null if order is not closed |
expirationString | String | Null if order is not closed |
margin_rate | Floating number | Margin rate |
open_price | Floating number | Open price |
open_time | Time | Open time |
open_timeString | String | Open time string |
order | Number | Order number for opened transaction |
order2 | Number | Order number for closed transaction |
position | Number | Order number common both for opened and closed transaction |
profit | Floating number | Profit |
sl | Floating number | Zero if stop loss is not set |
storage | Floating number | order swaps |
symbol | String | Symbol |
timestamp | Floating number | Timestamp |
tp | Floating number | Zero if take profit is not set |
volume | Floating number | Volume |
Example:
{ "close_price": 1.3256, "close_time": null, "close_timeString": null, "closed": false, "cmd": 0, "comment": "Web Trader", "commission": 0.0, "customComment": "Some text", "digits": 4, "expiration": null, "expirationString": null, "margin_rate": 3.9149000, "open_price": 1.4, "open_time": 1272380927000, "open_timeString": "Fri Jan 11 10:03:36 CET 2013", "order": 7497776, "order2": 1234567, "position": 1234567, "profit": -2196.44, "sl": 0.0, "storage": -4.46, "symbol": "EURUSD", "timestamp": 1272540251000, "tp": 0.0, "volume": 0.10 }
Possible values of cmd
field:
name | value | description |
---|---|---|
BUY | 0 | buy |
SELL | 1 | sell |
BUY_LIMIT | 2 | buy limit |
SELL_LIMIT | 3 | sell limit |
BUY_STOP | 4 | buy stop |
SELL_STOP | 5 | sell stop |
BALANCE | 6 | Read only. Used for manager's deposit/withdrawal operations (profit>0 for deposit, profit<0 for withdrawal). |
Description: Returns array of user's trades.
Parameters:
name | type | description |
---|---|---|
openedOnly | boolean | if true then only opened trades will be returned |
Example:
{ "command": "getTrades", "arguments": { "openedOnly": true } }
Parameters:
name | type | description |
---|---|---|
array | Array of TRADE_RECORD |
Example:
{ "status": true, "returnData" : [TRADE_RECORD, TRADE_RECORD, ...] }
Format of TRADE_RECORD
:
cmd
is the operation code, for user's trade operations it equals to cmd
from TRADE_TRANS_INFO
record used as an argument in tradeTransaction
command
name | type | description |
---|---|---|
close_price | Floating number | Close price |
close_time | Time | Null if order is not closed |
close_timeString | String | Null if order is not closed |
closed | Boolean | Closed |
cmd | Number | Operation code |
comment | String | Comment |
commission | Floating number | Commission |
customComment | String | The value the customer may provide in order to retrieve it later. |
digits | Number | Price precision |
expiration | Time | Null if order is not closed |
expirationString | String | Null if order is not closed |
margin_rate | Floating number | Margin rate |
open_price | Floating number | Open price |
open_time | Time | Open time |
open_timeString | String | Open time string |
order | Number | Order number for opened transaction |
order2 | Number | Order number for closed transaction |
position | Number | Order number common both for opened and closed transaction |
profit | Floating number | Profit |
sl | Floating number | Zero if stop loss is not set |
storage | Floating number | order swaps |
symbol | String | Symbol |
timestamp | Floating number | Timestamp |
tp | Floating number | Zero if take profit is not set |
volume | Floating number | Volume |
Example:
{ "close_price": 1.3256, "close_time": null, "close_timeString": null, "closed": false, "cmd": 0, "comment": "Web Trader", "commission": 0.0, "customComment": "Some text", "digits": 4, "expiration": null, "expirationString": null, "margin_rate": 3.9149000, "open_price": 1.4, "open_time": 1272380927000, "open_timeString": "Fri Jan 11 10:03:36 CET 2013", "order": 7497776, "order2": 1234567, "position": 1234567, "profit": -2196.44, "sl": 0.0, "storage": -4.46, "symbol": "EURUSD", "timestamp": 1272540251000, "tp": 0.0, "volume": 0.10 }
Possible values of cmd
field:
name | value | description |
---|---|---|
BUY | 0 | buy |
SELL | 1 | sell |
BUY_LIMIT | 2 | buy limit |
SELL_LIMIT | 3 | sell limit |
BUY_STOP | 4 | buy stop |
SELL_STOP | 5 | sell stop |
BALANCE | 6 | Read only. Used for manager's deposit/withdrawal operations (profit>0 for deposit, profit<0 for withdrawal). |
Description: Returns array of user's trades which were closed within specified period of time.
Parameters:
name | type | description |
---|---|---|
end | Time | Time, 0 means current time for simplicity |
start | Time | Time |
Example:
{ "command": "getTradesHistory", "arguments": { "end": 0, "start": 1275993488000 } }
Parameters:
name | type | description |
---|---|---|
array | Array of TRADE_RECORD |
Example:
{ "status": true, "returnData" : [TRADE_RECORD, TRADE_RECORD, ...] }
Format of TRADE_RECORD
:
cmd
is the operation code, for user's trade operations it equals to cmd
from TRADE_TRANS_INFO
record used as an argument in tradeTransaction
command
name | type | description |
---|---|---|
close_price | Floating number | Close price |
close_time | Time | Null if order is not closed |
close_timeString | String | Null if order is not closed |
closed | Boolean | Closed |
cmd | Number | Operation code |
comment | String | Comment |
commission | Floating number | Commission |
customComment | String | The value the customer may provide in order to retrieve it later. |
digits | Number | Price precision |
expiration | Time | Null if order is not closed |
expirationString | String | Null if order is not closed |
margin_rate | Floating number | Margin rate |
open_price | Floating number | Open price |
open_time | Time | Open time |
open_timeString | String | Open time string |
order | Number | Order number for opened transaction |
order2 | Number | Order number for closed transaction |
position | Number | Order number common both for opened and closed transaction |
profit | Floating number | Profit |
sl | Floating number | Zero if stop loss is not set |
storage | Floating number | order swaps |
symbol | String | Symbol |
timestamp | Floating number | Timestamp |
tp | Floating number | Zero if take profit is not set |
volume | Floating number | Volume |
Example:
{ "close_price": 1.3256, "close_time": null, "close_timeString": null, "closed": false, "cmd": 0, "comment": "Web Trader", "commission": 0.0, "customComment": "Some text", "digits": 4, "expiration": null, "expirationString": null, "margin_rate": 3.9149000, "open_price": 1.4, "open_time": 1272380927000, "open_timeString": "Fri Jan 11 10:03:36 CET 2013", "order": 7497776, "order2": 1234567, "position": 1234567, "profit": -2196.44, "sl": 0.0, "storage": -4.46, "symbol": "EURUSD", "timestamp": 1272540251000, "tp": 0.0, "volume": 0.10 }
Possible values of cmd
field:
name | value | description |
---|---|---|
BUY | 0 | buy |
SELL | 1 | sell |
BUY_LIMIT | 2 | buy limit |
SELL_LIMIT | 3 | sell limit |
BUY_STOP | 4 | buy stop |
SELL_STOP | 5 | sell stop |
BALANCE | 6 | Read only. Used for manager's deposit/withdrawal operations (profit>0 for deposit, profit<0 for withdrawal). |
Description: Returns quotes and trading times.
Parameters:
name | type | description |
---|---|---|
symbols | array | Array of symbol names (Strings) |
Example:
{ "command": "getTradingHours", "arguments": { "symbols": ["EURPLN", "AGO.PL", ...] } }
Parameters:
name | type | description |
---|---|---|
quotes | array | Array of QUOTES_RECORD |
symbol | String | symbol |
trading | array | Array of TRADING_RECORD |
Example:
{ "status": true, "returnData" : { "quotes": [QUOTES_RECORD, QUOTES_RECORD, ...], "symbol": "EURPLN", "trading": [TRADING_RECORD, TRADING_RECORD, ...] } }
Format of QUOTES_RECORD
:
name | type | description |
---|---|---|
day | Number | Day of week |
fromT | Time | Start time from 00:00 in ms |
toT | Time | End time from 00:00 in ms |
Example:
{ "day": , "fromT": 63000000, "toT": 63300000 }
Possible values of day
field:
name | value | description |
---|---|---|
1 | Monday | |
2 | Tuesday | |
3 | Wednesday | |
4 | Thursday | |
5 | Friday | |
6 | Saturday | |
7 | Sunday |
Format of TRADING_RECORD
:
name | type | description |
---|---|---|
day | Number | Day of week |
fromT | Time | Start time from 00:00 in ms |
toT | Time | End time from 00:00 in ms |
Example:
{ "day": 2, "fromT": 63000000, "toT": 63300000 }
Possible values of day
field:
name | value | description |
---|---|---|
1 | Monday | |
2 | Tuesday | |
3 | Wednesday | |
4 | Thursday | |
5 | Friday | |
6 | Saturday | |
7 | Sunday |
Description: Returns the current API version.
Example:
{ "command": "getVersion" }
Parameters:
name | type | description |
---|---|---|
version | String | current API version |
Example:
{ "status": true, "returnData" : { "version": "2.3" } }
Description: Starts trade transaction. tradeTransaction sends main transaction information to the server.
Parameters:
name | type | description |
---|---|---|
tradeTransInfo | TRADE_TRANS_INFO | tradeTransInfo |
Example:
{ "command": "tradeTransaction", "arguments": { "tradeTransInfo": TRADE_TRANS_INFO } }
Format of TRADE_TRANS_INFO
:
name | type | description |
---|---|---|
cmd | Number | Operation code |
customComment | String | The value the customer may provide in order to retrieve it later. |
expiration | Time | Pending order expiration time |
order | Number | Order number (0 if new trade is opened) |
price | Floating number | Trade price |
sl | Floating number | Stop loss |
symbol | String | Trade symbol |
tp | Floating number | Take profit |
type | Number | Trade transaction type |
volume | Floating number | Trade volume |
Example:
{ "cmd": 0, "customComment": "Some text", "expiration": 1262944112000, "order": 7497776, "price": 37.47, "sl": 0.0, "symbol": "PKN.PL", "tp": 0.0, "type": 0, "volume": 5.00 }
Possible values of cmd
field:
name | value | description |
---|---|---|
BUY | 0 | buy |
SELL | 1 | sell |
BUY_LIMIT | 2 | buy limit |
SELL_LIMIT | 3 | sell limit |
BUY_STOP | 4 | buy stop |
SELL_STOP | 5 | sell stop |
BALANCE | 6 | Read only. Used for manager's deposit/withdrawal operations (profit>0 for deposit, profit<0 for withdrawal). |
Possible values of type
field:
name | value | description |
---|---|---|
ORDER_OPEN | 0 | Used for opening order |
ORDER_PENDING | 1 | Pending order |
ORDER_CLOSE | 2 | order close |
ORDER_MODIFY | 3 | order modify |
ORDER_DELETE | 4 | order delete |
Parameters:
name | type | description |
---|---|---|
order | Number | order |
Example:
{ "status": true, "returnData" : { "order": 43 } }
Description: 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.
Parameters:
name | type | description |
---|---|---|
order | Number | order |
Example:
{ "command": "tradeTransactionStatus", "arguments": { "order": 43 } }
Parameters:
name | type | description |
---|---|---|
ask | Floating number | ask |
bid | Floating number | bid |
customComment | String | The value the customer may provide in order to retrieve it later. |
message | String | can be null |
order | Number | should be filled with order number when new trade order was opened successfully |
requestStatus | Number | request status code, described below |
Example:
{ "status": true, "returnData" : { "ask": 1.392, "bid": 0.0, "customComment": "Some text", "message": null, "order": 0, "requestStatus": 3 } }
Possible values of requestStatus
field:
name | value | description |
---|---|---|
ERROR | 0 | error |
PENDING | 1 | pending |
REQUOTED | 2 | Price was requoted by dealer |
ACCEPTED | 3 | The transaction has been executed successfully |
REJECTED | 4 | The transaction has been rejected |
PRICED | 5 | Prices received |
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.
Description: Allows to get actual balance value for an account in real-time, as soon as it is available in the system.
Example:
{ "command" : "getBalance", "streamSessionId" : "8469308861804289383" }
Example:
{ "command" : "stopBalance" }
{ "command" : "balance", "data" : STREAMING_BALANCE_RECORD }
Format of STREAMING_BALANCE_RECORD
:
name | type | description |
---|---|---|
balance | Floating number | balance |
equity | Floating number | sum of balance and all profits |
margin | Floating number | margin requirements |
marginFree | Floating number | free margin |
marginLevel | Floating number | margin level |
Example:
{ "balance": 995800269.43, "equity": 995985397.56, "margin": 572634.43, "marginFree": 995227635.00, "marginLevel": 173930.41 }
Description: Subscribes for and unsubscribes from news.
Example:
{ "command" : "getNews", "streamSessionId" : "8469308861804289383" }
Example:
{ "command" : "stopNews" }
{ "command" : "news", "data" : STREAMING_NEWS_RECORD }
Format of STREAMING_NEWS_RECORD
:
name | type | description |
---|---|---|
body | String | Body |
key | String | News key |
time | Time | Time |
title | String | News title |
Example:
{ "body": "<html>...</html>", "key": "1f6da766abd29927aa854823f0105c23", "time": 1262944112000, "title": "Breaking trend" }
Description: Subscribes for and unsubscribes from profits.
Example:
{ "command" : "getProfits", "streamSessionId" : "8469308861804289383" }
Example:
{ "command" : "stopProfits" }
{ "command" : "profit", "data" : STREAMING_PROFIT_RECORD }
Format of STREAMING_PROFIT_RECORD
:
name | type | description |
---|---|---|
order | Number | Order number |
order2 | Number | Transaction ID |
position | Number | Position number |
Profit | Floating number | Profit |
Example:
{ "order": 7497776, "order2": 7497777, "position": 7497776, "Profit": 7076.52 }
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. This command has no confirmation
Parameters:
name | type | description |
---|---|---|
symbol | String | Symbol |
Example:
{ "command" : "getTickPrices", "streamSessionId" : "8469308861804289383", "symbol": "EURUSD" }
Parameters:
name | type | description |
---|---|---|
symbol | String | Symbol |
Example:
{ "command" : "stopTickPrices", "symbol": "EURUSD" }
{ "command" : "tickPrices", "data" : STREAMING_TICK_RECORD }
Format of STREAMING_TICK_RECORD
:
name | type | description |
---|---|---|
ask | Floating number | Ask |
askVolume | Number | Number of available lots to buy at given price or null if not applicable |
bid | Floating number | Bid |
bidVolume | Number | Number of available lots to buy at given price or null if not applicable |
high | Floating number | High |
level | Number | Price level |
low | Floating number | Low |
quoteId | Number | Source of price, detailed description below |
symbol | String | Symbol |
timestamp | Time | Timestamp |
Example:
{ "ask": 4000.0, "askVolume": 15000, "bid": 4000.0, "bidVolume": 16000, "high": 4000.0, "level": 0, "low": 3500.0, "quoteId": 0, "symbol": "KOMB.CZ", "timestamp": 1272529161605 }
Possible values of quoteId
field:
name | value | description |
---|---|---|
fixed | 1 | fixed |
float | 2 | float |
depth | 3 | depth |
cross | 4 | cross |
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.
Example:
{ "command" : "getTrades", "streamSessionId" : "8469308861804289383" }
Example:
{ "command" : "stopTrades" }
{ "command" : "trade", "data" : STREAMING_TRADE_RECORD }
Format of STREAMING_TRADE_RECORD
:
New STREAMING_TRADE_RECORD
are sent by streaming socket only in several cases:
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:
The annotation are in brackets (regular or square, depending on situation) with additional data about the closing action.
name | type | description |
---|---|---|
close_price | Floating number | Close price |
close_time | Time | Null if order is not closed |
closed | Boolean | Closed |
cmd | Number | Operation code |
comment | String | Comment |
commission | Floating number | Commission |
customComment | String | The value the customer may provide in order to retrieve it later. |
digits | Number | Price precision |
expiration | Time | Null if order is not closed |
margin_rate | Floating number | Margin rate |
open_price | Floating number | Open price |
open_time | Time | Open time |
order | Number | Order number for opened transaction |
order2 | Number | Transaction id |
position | Number | Position number (if type is 0 and 2) or transaction parameter (if type is 1) |
profit | Floating number | null unless the trade is closed (type=2) |
sl | Floating number | Zero if stop loss is not set |
state | String | Trade state, should be used for detecting pending order's cancellation |
storage | Floating number | Storage |
symbol | String | Symbol |
timestamp | Floating number | Timestamp |
tp | Floating number | Zero if take profit is not set |
type | Number | type |
volume | Floating number | Volume |
Example:
{ "close_price": 1.3256, "close_time": null, "closed": false, "cmd": 0, "comment": "Web Trader", "commission": 0.0, "customComment": "Some text", "digits": 4, "expiration": null, "margin_rate": 3.9149000, "open_price": 1.4, "open_time": 1272380927000, "order": 7497776, "order2": 1234567, "position": 1234567, "profit": 68.392, "sl": 0.0, "state": "Modified", "storage": -4.46, "symbol": "EURUSD", "timestamp": 1272540251000, "tp": 0.0, "type": 0, "volume": 0.10 }
Possible values of state
field:
name | value | description |
---|---|---|
MODIFIED | "Modified" | pending order has been created |
DELETED | "Deleted" | pending order has been cancelled |
Possible values of type
field:
name | value | description |
---|---|---|
ORDER_OPEN | 0 | Used for opening order |
ORDER_PENDING | 1 | Pending order |
ORDER_CLOSE | 2 | order close |
ORDER_MODIFY | 3 | order modify |
ORDER_DELETE | 4 | order delete |
Description: Allows to get status for sent trade requests in real-time, as soon as it is available in the system.
Example:
{ "command" : "getTradeStatus", "streamSessionId" : "8469308861804289383" }
Example:
{ "command" : "stopTradeStatus" }
{ "command" : "tradeStatus", "data" : STREAMING_TRADE_STATUS_RECORD }
Format of STREAMING_TRADE_STATUS_RECORD
:
name | type | description |
---|---|---|
customComment | String | The value the customer may provide in order to retrieve it later. |
message | String | message |
order | Number | Order number |
requestStatus | Number | Request status code, described below |
Example:
{ "customComment": "Some text", "message": "Invalid s/l or t/p price", "order": 75, "requestStatus": 3 }
Possible values of requestStatus
field:
name | value | description |
---|---|---|
ERROR | 0 | error |
PENDING | 1 | pending |
REQUOTED | 2 | Price was requoted by dealer |
ACCEPTED | 3 | The transaction has been executed successfully |
REJECTED | 4 | The transaction has been rejected |
PRICED | 5 | Prices received |
Main reason of generated transaction server error messages is an error in the business logic of the application.
Errors list returned from transaction server:
Error code | Error description |
---|---|
BE001 | Invalid price |
BE002 | Invalid StopLoss or TakeProfit |
BE003 | Invalid Volume |
BE004 | Login disabled |
BE005 | Login not found |
BE006 | Market for instrument is closed |
BE007 | Mismatched parameters |
BE008 | Modification is denied |
BE009 | Not enough money on account to perform trade |
BE010 | Off quotes |
BE011 | Opposite positions prohibited |
BE012 | Short positions prohibited |
BE013 | Price has changed |
BE014 | Request too frequent |
BE015 | Requote |
BE016 | Too many trade requests |
BE017 | Too many trade requests |
BE018 | Trading on instrument disabled |
BE019 | Trading timeout |
BE020-BE033, BE099 | Other error |
BE094 | Symbol do not exist for given account |
BE095 | Account cannot trade on given symbol |
BE096 | Pending order cannot be closed. Pending order must be deleted |
BE097 | Cannot close already closed order |
BE098 | No such transaction |
BE101 | Unknown instrument symbol |
BE102 | Unknown transaction type |
BE103 | User is not logged |
BE104 | Method not exist |
BE105 | Incorrect period given |
BE106 | Missing data |
BE107 | Sort category not recognized |
BE109 | Incorrect parameter given |
BE110 | Incorrect command format |
BE111, BE112 | Incorrect provider chart parameter |
BE113 | Invalid provider chart parameter |
BE115, BE116 | Symbol does not exist |
BE118 | User already logged |
EX001, SExxx | Internal error, in case of such error, please contact support |