xStore Developers - xStation API Communication Protocol ...developers.xstore.pro/public/files/xStation_API.pdf2.INTRODUCTION This document presents information on xStation API communication

xStation API

Communication Protocol

Documentation

v. 2.2

xStation API – Communication Protocol 2013-05-20

© 2013, Unauthorized reproduction prohibited.

2

1. CONTENTS2. Introduction .................................................................................................................................................... 4

3. Definitions ...................................................................................................................................................... 4

4. General data format ....................................................................................................................................... 5

5. Communication with the xStation API ........................................................................................................... 6

1. Connection validation ................................................................................................................................ 6

2. Default login credentials ............................................................................................................................ 7

3. Input data format ....................................................................................................................................... 7

4. Output data format .................................................................................................................................... 7

5. Time format ............................................................................................................................................... 7

6. Floating number format ............................................................................................................................. 8

6. Available Commands ...................................................................................................................................... 8

1. Login ........................................................................................................................................................... 8

2. Logout ........................................................................................................................................................ 9

3. Retrieving trading data .............................................................................................................................. 9

Command: getAllSpreads ................................................................................................................................ 9

Command: getAllSymbolGroups ................................................................................................................... 10

Command: getAllSymbols ............................................................................................................................. 10

Command: getCalendar ................................................................................................................................ 12

Command: getChartLastRequest .................................................................................................................. 13

Command: getChartRangeRequest ............................................................................................................... 14

Command: getCommissionDef ..................................................................................................................... 15

Command: getCurrentUserData ................................................................................................................... 16

Command: getMarginLevel ........................................................................................................................... 16

Command: getMarginTrade .......................................................................................................................... 17

Command: getNews ...................................................................................................................................... 17

Command: getProfitCalculation .................................................................................................................... 18

Command: getServerTime ............................................................................................................................ 19

Command: getSpreads .................................................................................................................................. 19

Command: getSymbol ................................................................................................................................... 19

Command: getTickPrices ............................................................................................................................... 20

Command: getTradeRecords......................................................................................................................... 21



3

Command: getTrades .................................................................................................................................... 21

Command: getTradesHistory ........................................................................................................................ 22

Command: getTradingHours ......................................................................................................................... 23

4. Sending orders ......................................................................................................................................... 24

Command: tradeTransaction ........................................................................................................................ 24

Command: tradeTransactionStatus .............................................................................................................. 25

7. Available streaming commands ................................................................................................................... 26

Command: getTickPrices ............................................................................................................................... 26

Command: getTrades .................................................................................................................................... 27

Command: getBalance .................................................................................................................................. 29

Command: getReqStatus .............................................................................................................................. 30

Command: getProfits .................................................................................................................................... 31

8. Error messages ............................................................................................................................................. 31

Generated by Transaction server ..................................................................................................................... 32

2. INTRODUCTION This document presents information on xStation API communication protocol. The communication protocol of the xStation 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.

3. DEFINITIONS The following definitions will be used in this specification document:

simple type: type, which value is itself: int, int64, string, double, bool; j-value (JSON value): any simple type, j-object or j-array; 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.



4

http://tools.ietf.org/html/rfc4627

4. 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 for 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”

}

}



5

5. COMMUNICATION WITH THE XSTATION API There are two IPs, that can be used interchangeably:

• xapia.x-station.eu • xapib.x-station.eu

Here are the addresses of DEMO and REAL servers:

• DEMO: main port: 5124, streaming port: 5125. • REAL: main port: 5112, streaming port: 5113.

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

1. CONNECTION VALIDATION In order to provide best service for all users xStation 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:

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

• Each command invocation should not contain more than 1kB of data • user should send requests in 200 ms interval. However, this rule can be broken, but after 6th exceeding

in a row the connection is dropped. • Each command should be 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.



6

2. DEFAULT LOGIN CREDENTIALS Default login credentials can be obtained at: http://developers.xstore.pro/panel/.

3. INPUT DATA FORMAT 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”, String „arguments”: { „arg1Name”: 10, „arg2Name”: „Some text”, ... }, „prettyPrint”: true Boolean }

4. OUTPUT DATA FORMAT 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, Boolean „returnData”: JSON value JSON value }

or, in case of error massage:

{ „status”: false, Boolean „errorCode”: „E123”, String „errorDescr”: „Error description” String }

5. TIME FORMAT



7

http://developers.xstore.pro/panel/

Time is number of milliseconds from 01.01.1970, 00:00 GMT.

6. FLOATING NUMBER FORMAT In all Floating numbers '.' (period) is used as a decimal separator.

6. AVAILABLE COMMANDS Request-Reply commands are performed on main connection socket. The reply is sent by main connection socket.

1. LOGIN 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 drop the connection.

Format of input:

{ „command”: „login”, String „arguments”: { „userId”: 100, Number „password”: „PASSWORD”, String „appId”: „test”, String (optional), application id, given by the xStore Support „appName”: „test” String (optional), application name } }

After successful login the system responds with the status message that can contain the streaming session id field:

{ „status”: true, Boolean „streamSessionId”: „8469308861804289383”, String }



8

Alternatively, when redirect is needed, the system responds with:

{ „status”: false, Boolean „redirect”: REDIRECT_RECORD (optional) }

Format of REDIRECT_RECORD:

{ „mainPort”: 1234, Number, main port for communication „streamingPort”: 1235, Number, streaming port „address”: „xapia.x-station.eu” String, address that the user should reconnect to in order to login }

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.

2. LOGOUT Format of input:

{ „command”: „logout” String }

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

3. RETRIEVING TRADING DATA

Command: getAllSpreads

Description: returns current spreads for all instruments available.



9

{ „command”: „getAllSpreads” String }

Format of returnData field in output (example data):

[SPREAD_RECORD, SPREAD_RECORD, SPREAD_RECORD,...]

Format of SPREAD_RECORD (example data):

{ „precision”: 3, Number of decimal places of symbol „quoteId”: 2, Number „symbol”: "FTE.FR", String „value”: 0 Number, in pips }

Command: getAllSymbolGroups

Description: returns object with all groups of instruments available for given account.

Format of input:

{ „command”: „getAllSymbolGroups” String }

Format of returnData field in output:

[SYMBOL_GROUP_RECORD, SYMBOL_GROUP_RECORD …]

Format of SYMBOL_GROUP_RECORD (example data):

{ „description”: „Foreign Exchange”, String „name”: „Forex”, String „type”: 0 Number: Instrument group number, is used for type field in SYMBOL_RECORD }

Command: getAllSymbols Description: returns array of all symbols available for the user.

Format of input:



10

{ „command”: „getAllSymbols” String }


[SYMBOL_RECORD, SYMBOL_RECORD ...]

Format of SYMBOL_RECORD (example data):

{ „ask”: 4000.0, Floating number „bid”: 4000.0, Floating number „categoryName”: „Forex” String „contractSize”: 100000, Number, size of 1 lot in currency „currency”: „USD”, String „currencyProfit”: „SEK”, The currency of calculated profit „description”: „USD/PLN”, String „digits”: 0, Number, price precision „exemode”: 2, Number, mode of execution „expiration”: null Time or null if not applicable „groupName”: „Minor”, String „high”: 4000.0, Floating number „initialMargin”: 0, Number, initial margin for 1 lot order, used for profit/margin calculation „instantMaxVolume”: 0, Number, maximum instant volume multiplied by 100 „longOnly”: false, Boolean „lotMax”: 10.0, Floating number, maximum size of trade „lotMin”: 0.1, Floating number, minimum size of trade „lotStep”: 0.1, Floating number, A value of minimum step by which the size of trade can be changed (within lotMin - lotMax range). „low”: 3500.0, Floating number „marginHedged”: 0, Number, used for profit calculation „marginHedgedStrong”: false, Boolean, for margin calculation „marginMaintenance”: null, Number, for margin calculation. Null if not applicable „marginMode”: 4, Number, for margin



11

calculation „percentage”: 0.1, Floating number, „precision”: 2, Number, symbol precision „profitMode”: 1, Number, for profit calculation „quoteId”: 1, Number, source of price: 1 – fixed 2 – float 3 – depth 4 - cross „starting”: null, Time, null if not applicable „stopsLevel”: 15, Number, stop level „swapEnable”: true, Boolean, indicates whether swap value is added to position on end of day „swapLong”: -2.559290000000, Floating number, swap value for long positions „swapShort”: 0E-12, Floating number, swap value for short positions „swapType”: 0, Number, type of swap calculated „swap_rollover3days”: 0, Number, time when additional swap is accounted for weekend „symbol”: „USDPLN”, String „tickSize”: null, Floating number, smallest possible price change, used for profit/margin calculation. Null if not applicable „tickValue”: null, Floating number, value of smallest possible price change, used for profit/margin calculation. Null if not applicable „time”: 1272446136891, Time „timeString”: „Thu May 23 12:23:44 EDT 2013”, Time in String „type”: 21, Number, corresponds to key of SYMBOL_GROUP_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.

Command: getCalendar Description: returns calendar with market events.



12

Format of input:

{ „command”: „getCalendar” String }


[CALENDAR_RECORD, CALENDAR_RECORD...]

Format of CALENDAR_RECORD (example data):

{ „country”: „CA”, 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”: „3”, String: Impact on market (1- low, 2 - medium, 3 - high) „period”: „(FEB)”, String: Information period „previous”: „58.3”, String: Value from previous information release „time”: 1354806000000, Time: Time, when the information will be released (in this time empty “current” value should be changed with exact released value) „title”: „Ivey Purchasing Managers Index”, String: Name of the indicator for which values will be released }

Command: getChartLastRequest Description: returns chart info, from start date to the current time.

Format of input:

{ „command”: „getChartLastRequest”, String „arguments”: { „info”: CHART_LAST_INFO_RECORD } }



13

Format of CHART_LAST_INFO_RECORD (example data):

{ „symbol”: „PKN.PL”, String: symbol „period”: 5, Number: period code „start”: 1262944112000 Time: start of chart block }


{ „digits”: 2, Number, price precision „exemode”: 2, Number „rateInfos”: [RATE_INFO_RECORD,RATE_INFO_RECORD,...] Array of RATE_INFO_RECORDs }

Command: getChartRangeRequest Description: returns chart info with data between given start and end dates.

Format of input:

{ „command”: „getChartRangeRequest”, String „arguments”: { „info”: CHART_RANGE_INFO_RECORD } }

Format of CHART_RANGE_INFO_RECORD (example data):

{ „symbol”: „PKN.PL”, String: symbol „period”: 5, Number: period code „start”: 1262944112000, Time: start of chart block „end”: 1262944412000 Time: end of chart block „ticks”: 0 Number: numbers needed ticks, this field is optional, please read description below }

Chart period codes:

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)



14

PERIOD_W1 = 10080 10080 minutes (1 week) PERIOD_MN1 = 43200 43200 minutes (30 days)


„digits”: 2, Number, price precision „exemode”: 2, Number „rateInfos”: [RATE_INFO_RECORD, RATE_INFO_RECORD,...] Array of RATE_INFO_RECORDs

Method receives two oldest RATE_INFO_RECORDS in case no data is available for selected period.

Format of RATE_INFO_RECORD (example data):

{ „close”: 1.0, Floating number: value of close price (shift from open price) „ctm”: 1262944112000, Time: rate time „ctmString”: „Mar 21, 2013 4:15:00 PM”, Number: value of close price (shift from open price) „high”: 6.0, Floating number: highest value in period (shift from open price) „low”: 0.0, Floating number: lowest value in period (shift from open price) „open”: 41848.0, Floating number: example value of real open price: 119.87 „vol”: 12.00 Floating number: volume }

Price values must be divided by 10digits 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 field start and end time. If ticks value not equal 0, field end is ignored. If ticks>0 (e.g. N) then api return N candles from time start. If ticks

{ „command”: „getCommissionDef”, String „arguments”: { „symbol”: „T.US”, String „volume”: 1.0 Floating number } }

Format of returnData field in output if commission is applicable:

{ „commission”: 0.51 Floating: calculated commission „rateOfExchange”: 0.1609 Floating: rate of exchange between account currency and instrument base currency

„showComDef”: false Boolean }

Format of returnData field in output if commission is NOT applicable:

{ „commission”: null, null value „rateOfExchange”: null null value }

Command: getCurrentUserData Description: returns information about account currency, and account leverage.

Format of input:

{ „command”: „getCurrentUserData”, String }


{ „currency”: „PLN”, String, account currency „leverage”: 100 Number, leverage for account. Leverage is used for margin calculation for Forex instruments. User might want to have such information. }

Command: getMarginLevel Description: returns margin level for account. This command can be invoked more often than once a second.



16

Format of input:

{ „command”: „getMarginLevel” String }


{ „balance”: 10768.10, Floating number, balance + credit „currency”: „CZK” String: user currency „equity”: 10762.10, Floating number, equity „margin”: 75.00, Floating number: margin requirements „margin_free”: 10597.10, Floating number: free margin „margin_level”: 14229.47, Floating number: margin level }

Command: getMarginTrade Description: returns expected margin for given instrument and volume. The value is calculated as expected margin value, and therefore might not be perfectly accurate.

Format of input:

{ "arguments": { "symbol": "EURPLN", String "volume": 1.0 Floating number

}, "command": "getMarginTrade" String }


{ "returnData": 4399.350 Floating number, calculated margin "status": true }

Command: getNews Description: returns news from trading server which were sent within specified period of time.

Format of input:



17

{ „command”: „getNews”, String „arguments”: { „start”: 1275993488000, Time „end”: 0 Time, 0 means current time for simplicity } }


[NEWS_TOPIC_RECORD, NEWS_TOPIC_RECORD ...] Array of NEWS_TOPIC_RECORDs

Format of NEWS_TOPIC_RECORD (example data):

{ „body”: „....”, String: body „bodylen”: 110, Number: body length „category”: „Normal”, String: news category, can be null „key”: „278599”, String: news key „keywords”: „”, String: news keywords, can be null „priority”: 0, Number: news priority: 0-general, 1-high „read”: false, Boolean „time”: 1262944112000, Time „timeString”: „May 17, 2013 4:30:00 PM”, String „title”: „”, String: news title „topic”: „”, String: news topic }

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.

Format of input:

{ „command”: „getProfitCalculation”, String „arguments”: { „symbol”: „EURUSD”, String „volume”: 1.0, Floating number „cmd”: 0, Number, OPERATION_CODE „openPrice”: 1.2233 Floating number, theoretical open price of order „closePrice”: 1.3000 Floating number, theoretical close price of order



18

} }


{ „profit”: 714.3030, Floating number }

Command: getServerTime Description: returns current time on trading server.

Format of input:

{ „command”: „getServerTime” String }

Format of returnData field in output (example data):

{ „time”: 1272462188000 Time „timeString”: „Oct 25, 2012 3:39:53 PM” String, time described in form set on server (local time of server) }

Command: getSpreads Description: returns current spreads for predeterminded instruments.

Format of input:

{ „command”: „getSpreads”, String „arguments”: { „symbols”: [ „EURPLN”, String „AGO.PL” String ] } }

Format of returnData field return the same fields as getAllSpreads.

Command: getSymbol



19

Description: gets information about symbol available for the user.

Format of input:

{ „command”: „getSymbol”, String „arguments”: { „symbol”: „EURPLN” String } }

Format of returnData field return the same fields as getAllSymbols.

Command: getTickPrices 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.

Format of input:

{ „command”: „getTickPrices”, String „arguments”: { „symbols”: [„KOMB.CZ”,”AGO.PL”,...], Array of symbols „timestamp”: 1262944112000, Time „level”: 0 Number, price level, level equals -1: all available levels greater than -1: only specified level. Zero indicates base level (Bid and Ask price) for instrument. } }


{ „quotations”: [TICK_RECORD, TICK_RECORD ...] Array of quotations }

Format of TICK_RECORD (example data):

{ „ask”: 4000.0, Floating number „bid”: 4000.0, Floating number „askVolume”: 15000, Number, null if not applicable „bidVolume”: 16000, Number, null if not



20

applicable „exemode”: 2, Number „high”: 4000.0, Floating number „low”: 3500.0, Floating number „symbol”: „KOMB.CZ”, String „timestamp”: 1272529161605, Time „level”: 0 Number, price level }

Command: getTradeRecords Description: returns array of trades listed in „orders” argument.

Format of input:

{ „command”: „getTradeRecords”, String „arguments”: { „orders”: [7489839,7489841,...] Array of orders } }


[TRADE_RECORD, TRADE_RECORD ...] Array of TRADE_RECORDs

Command: getTrades Description: returns array of user's trades

Format of input:

{

„command”: „getTrades” String „arguments”: { „openedOnly”: true Boolean, if true then only opened trades will be returned } }



Format of TRADE_RECORD (example data):

{ „close_price”: 1.3256, Floating number „close_time”: null, Time or null if order is not closed



21

„close_timeString”: null, Time or null if order is not closed „closed”: false, Boolean „cmd”: 0, Number, operation code „comment”: „Web Trader”, String „commission”: 0.0, Floating number „digits”: 4, Number, price precision „expiration”: null, Time or null if not applicable „expirationString”: null, String or null if not applicable „login”: 100, Number „margin_rate”: 3.9149000, Floating number „open_price”: 1.4, Floating number „open_time”: 1272380927000, Time „open_timeString”: „Fri Jan 11 10:03:36 CET 2013”, String „order”: 7497776, Number, order number for opened transaction „order2”: 1234567, Number, order number for closed transaction „position”: 1234567, Number, order number common both for opened and closed transaction „profit”: -2196.44, Floating number „sl”: 0.0, Floating number, zero if stop loss is not set „spread”: 0, Number „storage”: -4.46, Floating number „symbol”: „EURUSD”, String „taxes”: 0.0, Floating number „timestamp”: 1272540251000, Time „tp”: 0.0, Floating number, zero if take profit is not set „volume”: 0.10 Floating number }

„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 and confirmPriced commands.

Command: getTradesHistory Description: returns array of user's trades which were closed within specified period of time.

Format of input:

{ „command”: „getTradesHistory”, String „arguments”: { „start”: 1275993488000, Time „end”: 0 Time, 0 means current time for simplicity



22

} }



Command: getTradingHours Description: returns quotes and trading times.

Format of input:

{ „command”: „getTradingHours”, String „arguments”: { „symbols”: [ Array of Strings „EURPLN”, „AGO.PL”, „EURJPY”, „SAN.ES”, „EURUSD” ] } }


{ „symbol”: „EURPLN”, String „quotes”: [QUOTES_RECORD, QUOTES_RECORD, ...], Array of QUOTES_RECORDs „trading”: [TRADING_RECORD, TRADING_RECORD, ...] Array of TRADING_RECORDS }

Format of QUOTES_RECORD and TRADING_RECORD(example data):

{ „day”: 2, Number, day of week „fromT”: 63000000, Time, start time from 00:00 in ms „toT”: 63300000 Time, end time from 00:00 in ms }

Possible day field values:

1 Monday 2 Tuesday 3 Wednesday



23

4 Thursday 5 Friday 6 Saturday 7 Sunday

4. SENDING ORDERS

Command: tradeTransaction Description: starts trade transaction. tradeTransaction sends main transaction information to the server.

Format of input:

{ „command”: „tradeTransaction”, String „arguments”: { „tradeTransInfo”: TRADE_TRANS_INFO } }

Format of TRADE_TRANS_INFO (example data):

{ „cmd”: 0, Number, trade operation „type”: 0, Number, trade transaction type „price”: 37.47, Floating number, trade price „sl”: 0.0, Floating number, stop loss „tp”: 0.0, Floating number, take profit „symbol”: „PKN.PL”, String, trade symbol „volume”: 5.00, Floating number, trade volume „ie_deviation”: 0, Number, deviation on instant execution „order”: 7489843, Number, order number (0 if new trade is opened) „comment”: „Some text”, String, comment „expiration”: 1262944112000 Time, pending order expiration time }

Operation codes:

BUY = 0 SELL = 1 BUY_LIMIT = 2 SELL_LIMIT = 3 BUY_STOP = 4 SELL_STOP = 5



24

Transaction type codes:

ORDER_OPEN = 0 Used for opening order, also for asking for prices in EXE_REQUEST mode ORDER_CLOSE = 2 ORDER_MODIFY = 3 ORDER_DELETE = 4


{ „requestId”: 43 Number, unique request id, can be negative }

Command: tradeTransactionStatus 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 requestID taken from tradeTransaction invocation.

Format of input:

{ „command”: „tradeTransactionStatus”, String „arguments”: { „requestId”: 43 Number }, }


{ „ask”: 1.392, Floating number „bid”: 0.0, Floating number „order”: 0, Number „requestId”: 43, Number, can be negative „requestStatus”: 3 Number „message”: null String, can be null }

Request status codes:

ERROR = 0 PENDING = 1 REQUOTED = 2 Price was requoted by dealer, used in EXE_INSTANT mode ACCEPTED = 3 The transaction has been executed successfully



25

REJECTED = 4 The transaction has been rejected. PRICED = 5 Prices received, used in EXE_REQUEST mode

Field order should be filled with order number always when new trade order was opened successfully.

7. AVAILABLE STREAMING COMMANDS Streaming commands are performed on streaming connection on port 23461 of the server.

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: getTickPrices Description: The getTickPrices command establishes subscription for quotations and allows to obtain the relevant information in real-time, as soon as it is available in the system. Moreover, getTickPrices command response send profit information for all opened orders with given symbol number.

Format of input to subscribe:

{ „command”: „getTickPrices”, String „symbol”: „EURUSD”, String „streamSessionId”: „8469308861804289383” String }

Format of input to unsubscribe:

{ „command”: „stopTickPrices”, String „symbol”: „EURUSD”, String }

The streamSessionId should contain the string value that was obtained from the system after successful login (see the description of the login command).

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.

After the subscription is established, the system sends data packets of the STREAMING_TICK_RECORD format.

Format of tick prices in stream:



26

{ „command”: „tickPrices”, String „data”: STREAMING_TICK_RECORD }

STREAMING_TICK_RECORD:

{ „ask”: 4000.0, Floating number „bid”: 4000.0, Floating number „askVolume”: 15000, Number, null if not applicable „bidVOlume”: 16000, Number, null if not applicable „high”: 4000.0, Floating number „low”: 3500.0, Floating number „symbol”: „KOMB.CZ”, String „timestamp”: 1272529161605, Time „level”: 0, Number, price level „quoteId”: 0, Number, source of price: 1 – fixed 2 – float 3 – depth 4 - cross }

Command: getTrades Description: The getTrades command 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.


{ „command” : „getTrades”, String „streamSessionId” : „8469308861804289383” String }


{ „command”: „stopTrades” String }

The streamSessionId should contain the string value that was obtained from the system after successful login (see the description of the login command).



27

The getTrades command can be invoked many times, but only one subscription for the trade data will be created. This command has no confirmation.

After the subscription is established, the system sends data packets of the STREAMING_TRADE_RECORD format.

Format of trade in stream:

{ „command”: „trade”, String „data”: STREAMING_TRADE_RECORD }

STREAMING_TRADE_RECORD:

{ „close_price”: 1.3256, Floating number „close_time”: null, Time or null if order is not closed „closed”: false, Boolean „cmd”: 0, Number, operation code „comment”: „Web Trader”, String „commission”: 0.0, Floating number „digits”: 4, Number, price precision „expiration”: null, Time or null if not applicable „margin_rate”: 3.9149000, Floating number „open_price”: 1.4, Floating number „open_time”: 1272380927000, Time „order”: 7497776, Number, order number for opened transaction „order2”: 7497777, Number, transaction id „position”: 123456, Number, position number (if type is 0 and 2) or transaction parameter (if type is 1) „sl”: 0.0, Floating number, zero if stop loss is not set „storage”: -4.46, Floating number „symbol”: „EURUSD”, String „timestamp”: 1272540251000, Time „tp”: 0.0, Floating number, zero if take profit is not set „type”: 0.0, Number, 0 – order opened, 1 – order pending, 2 – order closed „volume”: 0.10 Floating number }

New STREAMING_TRADE_RECORD are sent by streaming socket only in several cases:

- Opening the trade



28

- Closing the trade - Modification of trade parameters - Explicit trade update done by server system to synchronize data.

Situation that trade was closed can be checked by field closed set to true in 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:

- „sl”, then the trade was closed by stop loss - „tp”, then the trade was closed by take profit - „so”, then the trade was closed because of Stop Out (lack of money to maintain position)

The annotation are in brackets (regular or square, depending on situation) with additional data about the closing action.

Command: getBalance Description: The getBalance command allows to get actual balance value for an account in real-time, as soon as it is available in the system.


{ „command”: „getBalance”, String „streamSessionId”: „8469308861804289383” String }


{ „command”: „stopBalance”, String }

Format of balance in stream:

{ „command”: „balance”, String „data”: STREAMING_BALANCE_RECORD }

Format of STREAMING_BALANCE_RECORD:

{ „balance”: 10023.13, Floating number, sum of balance and credit „margin”: 75.00 Floating number, margin



29

requirements „equity”: 75.00 Floating number, sum of balance and all profits }

Command: getReqStatus Description: The getReqStatus command allows to get status for sent requests in real-time, as soon as it is available in the system.


{ „command”: „getReqStatus”, String „streamSessionId”: „8469308861804289383” String }


{ „command”: „stopReqStatus”, String }


{ „command”: „reqStatus”, String „data”: STREAMING_REQ_STATUS_RECORD }

Format of STREAMING_REQ_STATUS_RECORD:

{ „requestId”: 123, Number, unique request id, can be negative „requestStatus”: 23 , Request status codes: ERROR=0 PENDING=1 REQUOTED=2 Price was requoted by dealer, used in EXE_INSTANT mode ACCEPTED=3 The transaction has been executed successfully



30

„order”: 123456 Number, order number }

Command: getProfits Description: subscribes and unsubscribes for profits.


{ „command”: „getProfits”, String „streamSessionId”: „8469308861804289383” String }


{ „command”: „stopProfits”, String }


{ „command”: „profit”, String „data”: STREAMING_PROFIT_RECORD }

Format of STREAMING_PROFIT_RECORD:

{ „profit”: 7076.52, Floating number „order”: 7497776, Number, order number „order2”: 7497777, Number, transaction ID „position”: 7497776 Number, position number }

8. ERROR MESSAGES



31

GENERATED BY TRANSACTION SERVER

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



32

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, BE111 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



33



34

2. Introduction3. Definitions4. General data format5. Communication with the xStation API1. Connection validation2. Default login credentials3. Input data format4. Output data format5. Time format6. Floating number format

6. Available Commands1. Login2. Logout3. Retrieving trading dataCommand: getAllSpreadsCommand: getAllSymbolGroupsCommand: getAllSymbolsCommand: getCalendarCommand: getChartLastRequestCommand: getChartRangeRequestCommand: getCommissionDefCommand: getCurrentUserDataCommand: getMarginLevelCommand: getMarginTradeCommand: getNewsCommand: getProfitCalculationCommand: getServerTimeCommand: getSpreadsCommand: getSymbolCommand: getTickPricesCommand: getTradeRecordsCommand: getTradesCommand: getTradesHistoryCommand: getTradingHours

4. Sending ordersCommand: tradeTransactionCommand: tradeTransactionStatus

7. Available streaming commandsCommand: getTickPricesCommand: getTradesCommand: getBalanceCommand: getReqStatusCommand: getProfits

8. Error messagesGenerated by Transaction server

Documents

xStore Developers - xStation API Communication Protocol ...developers.xstore.pro/public/files/xStation_API.pdf2.INTRODUCTION This document presents information on xStation API communication