xstation API Communication Protocol Documentation v. 2.2

(1)

xStation API

Communication Protocol

Documentation

v. 2.2

(2)

2

1. C

ONTENTS

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

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

(4)

2. I

NTRODUCTION

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

EFINITIONS

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 <string, j-value>); 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.

xStation API – Communication Protocol 2013-05-20

(5)

4. G

ENERAL 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” } }

(6)

5. C

OMMUNICATION WITH THE X

S

TATION

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

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

(7)

2. D

EFAULT LOGIN CREDENTIALS

Default login credentials can be obtained at: http://developers.xstore.pro/panel/.

3. I

NPUT 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. O

UTPUT 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. T

IME FORMAT

(8)

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

6. F

LOATING NUMBER FORMAT

In all Floating numbers '.' (period) is used as a decimal separator.

6. A

VAILABLE

C

OMMANDS

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

1. L

OGIN

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

}

(9)

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

OGOUT

Format of input: {

„command”: „logout” String

}

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

3. R

ETRIEVING TRADING DATA

Command: getAllSpreads

Description: returns current spreads for all instruments available.

(10)

{

„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:

(11)

{

„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

(12)

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.

(13)

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 }

}

(14)

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

}

Format of returnData field in output: {

„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_H1 = 60 60 minutes (1 hour)

PERIOD_H4 = 240 240 minutes (4 hours)

PERIOD_D1 = 1440 1440 minutes (1 day)

(15)

PERIOD_W1 = 10080 10080 minutes (1 week)

PERIOD_MN1 = 43200 43200 minutes (30 days)

„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<0 then api return N candles to time start.

It's possible situation when api return less chart candles than is set in tick field.

Command: getCommissionDef

Description: returns calculation of commission and rate of exchange. The value is calculated as expected value, and therefore might not be perfectly accurate.

Format of input:

(16)

{

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

(17)

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:

(18)

{

„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”: „<HTML>....</HTML>”, 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

(19)

} }

„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

(20)

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): {

„askVolume”: 15000, Number, null if not

applicable

„bidVolume”: 16000, Number, null if not

(21)

applicable

„symbol”: „KOMB.CZ”, String

„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

(22)

„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

„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

„taxes”: 0.0, Floating number

„tp”: 0.0, Floating number, zero if

take profit is not set

}

„cmd” is the operation code, for user's trade operations it equals to „cmd” from TRADE_TRANS_INFO record used as an argument in tradeTransactionandconfirmPriced 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

(23)

} }

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

(24)

4 Thursday 5 Friday 6 Saturday 7 Sunday

4. S

ENDING 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

(25)

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 Format of returnData field in output:

{

„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

}, }

„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

(26)

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

VAILABLE 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

„streamSessionId”: „8469308861804289383”

String

}

Format of input to unsubscribe: {

„command”: „stopTickPrices”, 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:

(27)

{

„command”: „tickPrices”, String

„data”: STREAMING_TICK_RECORD

}

STREAMING_TICK_RECORD: {

„askVolume”: 15000, Number, null if not

applicable

„bidVOlume”: 16000, Number, null if not

applicable

„symbol”: „KOMB.CZ”, String

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

(28)

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

„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

„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

}

New STREAMING_TRADE_RECORD are sent by streaming socket only in several cases: - Opening the trade

(29)

- 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

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

(30)

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

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

(31)

„order”: 123456 Number, order number

}

Command: getProfits

Description: subscribes and unsubscribes for profits. Format of input to subscribe:

{

„command”: „getProfits”, String

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

RROR MESSAGES

(32)

G

ENERATED BY

T

RANSACTION 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

(33)

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

(34)