Document Type

Technical specification

Document Purpose

Describe the communication protocols of ArenaXT server, the connectivity requirements and the format of messages.

Revision History

Version

Date

Notes

v1.0

2015-02-26

First version of the specification

v1.1

2015-04-16

New command: <<ADD TEMP SUBSCRIPTION>>
New field Device (device) for <<LOGIN>> command.
Clarifications for <<_internaltradedto_structure, InternalTradeDto>> object

v1.2

2015-12-02

Changes to the payload for <<L1 DATA SNAPSHOT>> command.
New possible values for Status field (sts) and External Account Type field (act) in InternalOrderDto objects.
New field Ready (rdy) in OrderRequestDto objects.

v1.3

2016-04-01

New commands: <<GET TRADING SUMMARY>> and <<GET OUTSTANDING PENDING ORDERS>>
New possible value for Market Priority field (mkp) in InternalOrderDto objects.
New possible value for Type field (type) in OrderRequestDto objects.

v1.4

2017-01-17

New fields Final Fee (ffee) and Aquisition Value (aqval) in InternalTradeDto objects
New field Gain (gain) in TradingSummaryDto objects.

v1.5

2017-07-12

New field First Order Execution (foe) in InternalTradeDto objects
New field Accumulated Quantity (cqy) in InternalOrderDto and PendingOrderDto objects.
New field Currency (ccy) in InternalAccountDto objects.
New field Currency (ccy) in ActivityDto objects.

v1.6

2017-10-26

New fields ccy in InternalOrderDto objects.
New fields alg in InternalTradeDto objects
New fields ccy in OrderRequestDto objects.
New fields sco in UserDto objects.
New fields for [ADD ORDER], [REPLACE ORDER] and [CANCEL ORDER] commands.

v1.7

2018-01-18

New commands: <<APPROVE ORDER REQUEST>> and <<CANCEL PENDING ORDER REQUEST>>
New report: <<GET OUTSTANDING ORDER REQUESTS>>


Table of Contents

1. Communication with ArenaXT

1.1. Connecting to the ArenaXT Server

The client application can communicate with the server in two complementary ways:

  • in real-time (for time-sensitive trading operations and market data)

  • in a request-reply manner (for non-critical data).

1.1.1. Real-Time Communication

Real-time communication is required for disseminating market data from server to clients and for bidirectional exchange of time-critical trading-related messages such as order requests, trade reports and notifications.

This communication pattern requires that the communication channel remain open as long as the end-user is connected to the server. This can be achieved through a TCP connection kept active during the end-user’s session life-span.

The ArenaXT server supports two types of persistent TCP connections for real-time communication:

  • Web-Socket Secure connections

  • plain SSL-encrypted TCP/IP connections

There are no differences between the two connection types in terms of business processing. A client application can chose any of the two types, depending on its own internal capabilities.

Web-Socket Secure connections

Clients connecting to the server through Web-Socket Secure connections have the ability to choose the internal communication protocol (TEXT or BINARY) to be used for exchanging messages.

Note
The communication protocol refers to how the messages will be formatted and encoded before being sent through the WSS connection; it does not refer to the Web-Socket transfer mode (binary/text). The ArenaXT communication protocols are described in the following sections.

WSS connections are opened through the standard Web-Socket hand-shake mechanism. The only requirement is that the client specifies the communication protocol it chooses to use, in the form of Web-Socket sub-protocol (sent as Sec-WebSocket-Protocol header of the hand-shake request). The server will confirm the chosen communication protocol in the hand-shake response it sends back to the client.

Once the hand-shake completes and the connection is upgraded to Web-Socket, the client and the server can start sending messages encoded according to the agreed communication format.

Sample JavaScript code to open a Web-Socket Secure connection
Plain SSL-encrypted TCP/IP connections

Clients connecting to the server through plain SSL-encrypted TCP/IP connections are restricted to the BINARY communication protocol only.

There are no special requirements for this type of connections: once the communication channel is opened, the message exchange can begin.

1.1.2. Request-reply communication

Request-reply communication is used for data which is not time-sensitive and is not required to be disseminated in real-time. This includes reports, chart data and other non-critical pieces of information. Under this communication pattern, the data is provided only upon request, and after it is delivered, the underlying communication channel is closed.

The ArenaXT server provides request-reply support through the HTTPS protocol.

All HTTPS requests must use the POST method. There are no special requirements in regards to the headers of the HTTPS requests, as long as they are used correctly and in correspondence with the request body.

The body of the HTTPS request contains the message to be sent to the server, formatted according to the desired communication protocol. The request body must not be further transformed or encoded by the client (for example, URL-encoded), but sent as it is. Using the correct Content-Type header is usually enough to prevent interfering with it.

For each HTTPS request, the client application must state the communication protocol to be used. This can be done by specifying the protocol name as the ws query string in the requested URL. Failing to do so will result in the BINARY communication protocol to be used by default.

The message from the server will be formatted according to the specified communication protocol and will be sent as the HTTPS response body.

Sample HTTPS request using TEXT protocol
POST https://demo.arenaxt.ro/report?ws=TEXT HTTP/1.1
Host: demo.arenaxt.ro
Accept: application/json, text/plain, */*
Accept-Encoding: gzip, deflate
Content-Type: text/plain;charset=utf-8
Content-Length: 126

...
Sample HTTPS request using BINARY protocol
POST https://demo.arenaxt.ro/report?ws=BINARY HTTP/1.1
Host: demo.arenaxt.ro
Accept: application/octet-stream, */*
Accept-Encoding: gzip, deflate
Content-Type: application/octet-stream
Content-Length: 240

...

1.2. Communication Protocol

All business messages between server and the client must be formatted in JSON and encoded as UTF-8. The content of each JSON message differs from command to command and is described in detail for each type of message.

Before the JSON-formatted messages can be sent to the destination (in any direction), they are/need to be decorated with different data for validation purposes. The type of decoration, as well as the encoding of the final message depends on the communication protocol agreed between the client and the server.

The ArenaXT server supports two communication protocols. Depending on its capabilities, the client application can request one of the protocols when opening the connections with the server.

The following is the list of communication protocols:

  1. TEXT protocol

  2. BINARY protocol

The server does not enforce the use of the same communication protocol for both types of connections. Clients can use different communication protocols at the same time for the two connection types.

1.2.1. The TEXT Protocol

This communication protocol can be used by any client application and has no specific requirements.

With this protocol, the communication will be done in plain text, for both real-time (WSS) and HTTPS connections. All content will be encoded in UTF-8.

Note
The TEXT protocol is supported only for real-time communication over Web-Socket. Client applications cannot use this protocol for plain TCP/IP connections.

This protocol is intended to be used mainly by clients using Web-Socket connections (i.e. web browsers), but it can be used by other type of clients also (for example, for HTTPS connections).

Client Requests

All requests initiated by the client must have the following structure, for both real-time and request-reply messages:

<message length>:<message>

The parts of the request are described below:

  • <message length> represents the number of UTF-8 characters contained in <message>.

  • <message> represents the actual business message that must be processed by the server (UTF-8 text).

For HTTPS connections, in order to make sure the message passes correctly through any gateway, the client should include Content-Type: text/plain in the headers section of the HTTPS request.

Server Responses

All server responses will be in UTF-8 plain-text, with no additional data decoration. The client must process them as they are.

1.2.2. The BINARY Protocol

This protocol can be used by clients supporting binary communication and ZLIB compression.

With this protocol, the communication will be done through binary data (stream of bytes), for both real-time (WSS or plain TCP/IP) and HTTPS connections. The client applications must be able to send and receive stream of bytes and to properly decode/encode them from/to UTF-8 text. Also, they should be able to decompress data received from the server.

Client Requests

All requests initiated by the client must have the following structure, for both real-time and request-reply messages:

<4-byte integer><1-byte integer><message>

The parts of the request are described below:

  • The first 4 bytes (<4-byte integer>) must contain a 32-bit integer number representing the number of the bytes remained in the message (after the first 4 bytes).

  • The 5th byte (<1-byte integer>) must contain an 8-bit integer with the value 1 if the content of <message> is compressed, or the value 0 if the content will be sent uncompressed.

  • The <message> represents the actual stream of bytes of the business message that must be processed by the server. The original message must be a valid UTF-8-encoded text. If the client application considers it necessary, the message may be compressed through ZLIB Deflate algorithm, in which case the <1-byte integer> must be 1; otherwise the message can be sent uncompressed.

Note
  • The <4-byte integer> number represents the size of the actual representation of the message (either compressed or uncompressed), plus the size of <1-byte integer> flag (which is 1).

  • For HTTPS connections, in order to make sure the message passes correctly through any gateway, the client should include Content-Type: application/octet-stream in the headers section of the HTTPS request.

Server Responses

The responses received from the server will have the same structure as the input messages. The client must be able to read the size of the message, the compression flag and the rest of the data and decode it to UTF-8 text. In case the response received from the server is compressed, the client must use the ZLIB Inflate algorithm to decompress the data before decoding it to UTF-8 text.

2. ArenaXT Messages

2.1. Message Structure

All business messages between server and the client must be JSON-formatted and must have a fixed structure, as detailed below:

Table 1. The structure of a Business Message

Field

Type

Description

Mandatory for requests

pid

int

Command ID

Y

user

String

Client user

Y

sessionId

String

The ID of the session, received at login

Y for most commands

csq

long

Client sequence number; Used to match a server response against the client’s request. Must be positive long.

Y

payload

Object

Message content (payload)

Y for some commands

error

int

Error code; irrelevant for client requests. 0 means command was processed with success.

N

ktime

long

Server response message time; irrelevant for client requests

N

kmessage

String

Server response message details; irrelevant for client requests

N

longid

long

Sequence number used by the server; irrelevant for client requests

N

swst

String

User remote IP; irrelevant for client requests

N

Note
The field sessionId is mandatory for all commands initiated by the client except for LOGIN and HEART BEAT.

The above structure must be sent as bm in the actual message. The resulted JSON object will therefore have only one field (bm) with the business message as its value. Responses from server will have the same structure: the JSON object will have a field called bm with the above structure.

Table 2. Example of valid requests sent to the server and their responses

Request

Response

Via Real-Time Connection

{"bm":{"pid":100, "user":"admin", "csq":1}}

{"bm":{"pid":100, "user":"admin", "ktime":0, "longid":0, "csq":1}}

Via HTTPS Connections

{"bm":{"sessionId":"3193E...", "user":"admin", "pid":190, "csq":2}}

{"bm":{"pid":190, "user":"admin", "ktime":1423492506421, "swst":"127.0.0.1", "longid":0, "csq":2, "payload":{"@class":"p.ResultPage", "bottom":true}}}

2.2. Message Flow

Every command sent by the client must specify a sequence (in the csq field). The related response from the server will have the same csq field so the client can correlate it with the initial request.

Unsolicited messages sent by the server when new events occur at the exchange have -1 for csq.

Note
The server does not enforce the sequences (csq) to be unique across requests, but it is recommended that they have strictly ascending values throughout the same session.

Depending on the command, the client might be requested to provide a payload. The server validates the payload and if there are any errors, it will reply with an error response (having an error code different than 0) containing the list of validation errors. In this case, the error response will have a particular payload (ResultPage<string>), regardless of the ID of the command.

If the request payload contains valid data, the server continues with processing it. If any processing error occurs, the server will send back an error response with a specific error message and, usually, no payload.

If processing takes place successfully, the server sends back a response with no error flag and a confirmation message. Responses for successful commands usually contain a payload.

2.2.1. Flow for Real-Time Communication

Real-time messages are received in the same order the corresponding market events occurred. They need to be processed at the client side in the order they are received, in an asynchronous manner.

The client application must not assume that the message it receives represents the response for its outstanding request. It is not unusual for a client to receive an unrelated unsolicited message (with csq == -1) right after a request, before the server could send the response for that particular request. The client application must always use the csq field to link a response with a request.

2.2.2. Flow for Request-Reply Communication

Messages sent through HTTPS connections are synchronous in nature, however the requests should be performed asynchronously in terms of functionality, without blocking user interaction or the processing of other messages.

Almost all reports are paginated on the server side. Usually, commands that get a ResultPage<T> response have results paginated. Also, for these commands, the client application needs to provide a ReportingPayload specifying the requested page and the data filters, if any.

The response from the server will contain only the requested page of elements, according to the maximum page size setting configured for the current user. If there are more results available, the server will state it in one of the response payload fields. The client application must check this field and update the user interface accordingly (for example, by displaying a Next button). Subsequent requests to get the next pages should use the same filters and a different requested page.

For other commands sent through HTTPS connections which don’t receive a ResultPage<T> payload, all requested data will be contained in the response, so the client application is not required to perform further verifications.

2.2.3. Message Rate Limits

The server imposes a limit on the number of messages a client application can send during one second time. The current maximum rate is 5 messages per second. If this rate is exceeded, the server will disconnect the client.

A client can, however, send all the requests needed for data initialization, right after login, without being penalized. The server allows clients to go beyond the maximum rate for a short period of time after login, particularly for this reason. Once initialization is performed, the client application should make sure it does not exceed the maximum allowed message rate.

2.3. Error Processing

When a request initiated by the client cannot be processed, the server sends back a response with an error code and an error message. Optionally, it can also include a payload, depending on the command and the type of error.

Below is a list of error codes and their meaning.

Code

Internal Name

Description

-1

UNKNOWN_ERROR

Reserved (not used)

0

NO_ERROR

No error (for successful requests only)

1

FATAL_ERROR

Internal server error

2

LOGIN_ERROR

Login error

3

TIME_OUT

Reserved (not used)

4

CONNECTION_DROPPED

Reserved (not used)

5

CHANGE_PASSWORD_ERROR

Error when changing password or PIN

6

SUBSCRIPTION_ERROR

Error when adding/removing symbols to/from watch list

7

XAP_ERROR

Error received from the exchange server

8

ACCESS_ERROR

Permission error or invalid access

9

RISK_ERROR

Risk manager error

10

NOT_LOGGED_IN

Reserved (not used)

11

VALIDATION

Invalid data was provided in the request payload

12

BACKOFFICE

Back-office error

13

REQUEST_EXCEEDS_MESSAGE_THROTTLE

Too many messages per second

14

IO_MESSAGE_TOO_LARGE

Reserved (not used)

15

ADMIN

Administration-related error

16

RESET

Reserved (not used)

17

XAP_BUSINESS_ERROR

Exchange-related error

18

ALREADY_PROCESSED_ERROR

Reserved (not used)

Important

When a request cannot be validated (error code 11), the server either sends a payload of type ResultPage<string>, or doesn’t send a payload at all.

For login errors (error code 2), the server will always send a payload of type Login.

For throttling errors (error code 13), the server will never send a payload.

For other errors, the server doesn’t usually send a payload. See the [Command IDs] section below for specific details of each command.

2.4. Command IDs

All valid command IDs, as well as their details, are listed below.

Command ID

Internal name

Initiated Via*

Initiated By

Request Payload**

Response Payload**

Error Payload***

100

[HEART BEAT]

RT

Client

-

-

-

101

[LOGIN]

RT

Client

Login

UserEnvDto

Login

102

[LOGOUT]

RT

Client / Server

-

-

-

103

[CHANGE PASSWORD]

RT

Client

ChangePassword

-

no payload / ResultPage<string>

104

[GET EXCHANGES]

RT

Client

-

ResultPage<ExchangeDto>

-

105

[GET SYMBOLS]

RT

Client

no payload / GenericIoPayload

ResultPage<SymbolDto>

-

106

[INDICES SNAPSHOT]

RT

Client

no payload / GenericIoPayload

ResultPage<IndexDto>

-

108

[ADD SUBSCRIPTION]

RT

Client

Subscription

ResultPage<L1DataDto>

no payload / ResultPage<string>

109

[REMOVE SUBSCRIPTION]

RT

Client

Subscription

Subscription

no payload / ResultPage<string>

110

[L1 DATA SNAPSHOT]

RT

Client

no payload / GenericIoPayload

ResultPage<L1DataDto>

-

111

[L1 DATA UPDATE]

RT

Server

-

L1UpdateDto

-

112

[INDICES UPDATE]

RT

Server

-

IndexUpdateDto

-

113

[L2 DATA SNAPSHOT]

RT

Client

GetL2Data

L2DataDto

no payload / ResultPage<string>

114

[L2 DATA UPDATE]

RT

Server

-

L2UpdateDto

-

115

[SMK STATUS UPDATE]

RT

Server

-

SmkStatusDto

-

117

[ADD ORDER]

RT

Client

AddOrder

OrderRequestDto

no payload / ResultPage<string>

118

[CANCEL ORDER]

RT

Client

CancelOrder

OrderRequestDto

no payload / ResultPage<string>

119

[REPLACE ORDER]

RT

Client

ReplaceOrder

OrderRequestDto

no payload / ResultPage<string>

120

[REQUEST UPDATE]

RT

Server

-

OrderRequestDto

OrderRequestDto

121

[ORDER UPDATE]

RT

Server

-

InternalOrderDto

-

122

[TRADE]

RT

Server

-

InternalTradeDto

-

123

[GET USER ACCOUNTS]

HTTPS

Client

-

ResultPage<InternalAccountDto>

-

124

[GET OUTSTANDING ORDERS]

HTTPS

Client

ReportingPayload

ResultPage<InternalOrderDto>

no payload / ResultPage<string>

125

[GET DAILY TRADES]

HTTPS

Client

ReportingPayload

ResultPage<InternalTradeDto>

no payload / ResultPage<string>

127

[UNSUBSCRIBE L2]

RT

Client

GetL2Data

GetL2Data

-

133

[GET TRADING SUMMARY]

HTTPS

Client

ReportingPayload

ResultPage<TradingSummaryDto>

no payload / ResultPage<string>

136

[CHANGE PIN]

RT

Client

ChangePIN

-

no payload / ResultPage<string>

154

[GET SPOT PORTFOLIO]

HTTPS

Client

PortfolioPayload

SpotPortfolioPayload

no payload / ResultPage<string>

155

[NOTIFICATION MESSAGE]

RT

Server

-

NotificationPayload

-

184

[XAP CONNECTED]

RT

Server

-

GenericIoPayload

-

185

[XAP DISCONNECTED]

RT

Server

-

GenericIoPayload

-

190

[GET SYMBOL MARKETS]

HTTPS

Client

-

ResultPage<SymbolMarketDto>

no payload / ResultPage<string>

201

[GET FUTURES PORTFOLIO]

HTTPS

Client

PortfolioPayload

FuturesPortfolioPayload

no payload / ResultPage<string>

203

[GET ACTIVITY]

HTTPS

Client

ReportingPayload

ResultPage<ActivityDto>

no payload / ResultPage<string>

296

[GET POSITION EVAL]

HTTPS

Client

GetPositionEvalPayload

PositionEvalPayload

no payload / ResultPage<string>

316

[CHANGE SUBSCRIPTION FILTERING]

RT

Client / Server

SetUserField

SetUserField

no payload / ResultPage<string>

319

[ADD TEMP SUBSCRIPTION]

RT

Client

Subscription

ResultPage<L1DataDto>

no payload / ResultPage<string>

321

[GET OUTSTANDING PENDING ORDERS]

RT

Client

ReportingPayload

ResultPage<PendingOrderDto>

no payload / ResultPage<string>

Note

(*) RT - real-time connections (WSS or plain TCP/IP), HTTPS - HTTPS connections
(*) if no payload is indicated, then no payload is required, or no payload will be sent by the server.
(\
**) if the ResultPage<string> payload is indicated for a command, then it may returned by the server when the incoming request payload is not valid

3. ArenaXT Common Types

The following are some types which are used by multiple commands and reponses.

3.1. GenericIoPayload

Payload of type GenericIoPayload is used for some of the commands that request initialization data, as well as a few messages initiated by the server. It has a simple structure, with only one field allowing to send a single parameter.

This payload is usually used to send the code of the exchange to which the response data relates.

Table 3. The structure of GenericIoPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

p.GenericIoPayload

The name of the payload object type

content

ComplexString

-

-

-

Object holding the data which needs to be passed to the other party

Table 4. The structure of ComplexString type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value string

The name of the payload object type

$

String

-

-

-

The data which needs to be passed to the other party

An example of a GenericIoPayload object is included below:

Sample GenericIoPayload object containing the text "BVB"
{
    "@class": "p.GenericIoPayload",
    "content": {
        "@class": "string",
        "$": "BVB"
    }
}

3.2. ReportingPayload

The type ReportingPayload is a request payload used for some of the HTTPS commands initiated by the client.

Table 5. The structure of ReportingPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

p.ReportingPayload

The name of the payload object type

startPosition

int

-

-

-

The number of the requested page, starting at 1

pageSize

int

-

-

-

The number of records to display per page (taken from user’s details)

parameters

Map

-

-

May be null

A hash-map containing the filters that must be applied on the server side. Each command has a different set of filters

3.3. Map

Map is a representation of a hash-map (a collection of key-value pairs). It contains only one field, entry, holding the list of hash-map entries.

Table 6. The structure of Map type

Field

Type

Min. Length

Max. Length

Restrictions

Description

entry

Array of MapEntry objects

-

-

-

A collection of hash-map entries

The MapEntry type is a dynamic type holding the key and the value of the actual hash-map entry. A MapEntry object will always have at most 2 fields: the first one for the hash-map entry key and the second one for the hash-map entry value. The name of the fields, however, is dynamic and depends on the type of the value they hold.

Below is the structure of a MapEntry object, with all possible fields it may have.

Table 7. The structure of MapEntry type

Field

Type

Min. Length

Max. Length

Restrictions

Description

int

int

-

-

-

Field holding an integer value

big-decimal

decimal

-

-

-

Field holding a decimal value

string

String

-

-

-

Field holding a text

boolean

boolean

-

-

-

Field holding a boolean value

sql-timestamp

String

-

-

-

Field holding the textual representation of a timestamp

date

String

-

-

-

Field holding the textual representation of a date

As mentioned above, a MapEntry object will have at most 2 fields at any time, since it carries only 2 pieces of data (the entry key and the entry value).

When the entry key and the entry value have different types, the object will have exactly 2 fields, named after the type of the key and value, respectively. The entry key will always be the first runtime field of the object, while the entry value will be the second.

Example of MapEntry objects with 2 keys

However, when both the entry key and the entry value have the same type, the MapEntry object will have only one field (the type name) with an array of 2 elements as its value. The array will contain the entry key (first element) and the entry value (second element).

Example of MapEntry objects with 1 key
Important
Since the Map type is used by multiple commands, a client application must be able to properly construct and process such objects.

3.4. ResultPage<T>

ResultPage<T> is a response payload used generally for commands returning a list of elements. This payload is used for validation errors and for all paginated reports.

Table 8. The structure of ResultPage<T> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

start

int

-

-

-

Position of the first record, related to the total number of records

end

int

-

-

-

Position of the last record

crtpage

int

-

-

-

Page number

bottom

boolean

-

-

-

Flag indicating if the last page has been reached.

lines

Lines<T>

-

-

-

Object holding the list of elements

The type Lines<T> represents a list of multiple objects of the type T. T is a type identifier and can consist in the name of other payload types or the type string.

The structure of the generic Lines<T> type is described below:

Table 9. The structure of Lines<T> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

t

Array of T objects

-

-

-

Array of T objects.

Note
The t from the field list represents a textual representation of the actual type T name and can vary from command to command. The actual structure of specific Lines<T> types will be described in detail for each command using the ResultPage<T> payload.

3.5. ResultPage<string>

The type ResultPage<string> is a specialization of the generic type ResultPage<T> described above. It is used for error payloads sent by the server whenever it receives an invalid request.

The ResultPage<string> payload contains a list of detailed messages about all payload fields which contain invalid data.

The structure of this payload type is the same as that of the generic type, with the exception of lines field, which has the specific type Lines<string>, detailed below.

Table 10. The structure of Lines<string> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

string

Array of strings

-

-

-

Array of strings representing validation error messages.

Sample ResultPage<string> payload from an error message
{
    "@class": "p.ResultPage",
    "start": 1,
    "end": 3,
    "crtpage": 0,
    "bottom": true,
    "lines": {
        "string": [
            "Old password must be not null.",
            "New password must be not null.",
            "Password must be between 8 and 20 characters."
        ]
    }
}

3.6. OrderRequestDto

The type OrderRequestDto is used for payloads sent by the server in response to order-related requests, and for unsolicited updates of outstanding requests.

Once it passes all verifications and validations, an order request is sent to the exchange. If accepted, it will turn into an outstanding order, represented as InternalOrderDto. If not accepted by the exchange, the order request will be deleted.

The following is a typical flow for an order request which is accepted by the brokerage server and by the exchange.

Step

Client

Dir.

Server

Notes

1

Client initiates an order request
  • AddOrder

  • ReplaceOrder

  • CancelOrder

 

The client application should store the csq of the request to be able to identify the response.

2

 

Server replies with a message to inform that the request is valid and will be further processed. The reply has the same csq as the initial request and an OrderRequestDto payload.

The client application can correlate response with the request by comparing the `csq`.

Then, it must store the ID of the request (OrderRequestDto.id) to be able to identify further updates.

3

 

Server sends a message confirming the request is accepted by the local system. The message has the ID 120 (REQUEST UPDATE), no csq (-1) and an updated OrderRequestDto payload. Then it forwards the request to the exchange.

The client application can correlate the update with the initial request by comparing the request's `id`.

Note: Multiple such REQUEST UPDATE messages can be sent for a single request.

4

 

When the confirmation from the exchange arrives on the server side, it is sent to the client application. The confirmation message has the ID 121 (ORDER UPDATE), no csq (-1) and an InternalOrderDto payload.

The response payload (`InternalOrderDto`) contains the ID of the initial request in the `csq` field (different from the business message `csq`, which is `-1` in this case).

The client application can use this field (InternalOrderDto.csq) to correlate the confirmation with the initial request.

Then it must store the ID of the outstanding order (InternalOrderDto.id) to be able to identify subsequent order updates and trade executions.

Note: Multiple such ORDER UPDATE messages can be sent for a single request.

As a request goes through different stages during its life-span, its fields will change, so the client application must make sure it processes all updates received from the server. Once a request reaches the exchange (either turning into an accepted order or being rejected), it is no longer of interest for the client application and can be discarded. The server itself will not send further updates for a request accepted or rejected by the exchange.

OrderRequestDto Structure

The structure of an OrderRequestDto is detailed below.

Table 11. The structure of OrderRequestDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

ccy

String

3

3

-

Currency

clr

int

-

-

-

Clearing term

cti

Timestamp

-

-

-

Creation time

dcv

long

-

-

-

Disclosed volume

exc

String

1

5

-

Exchange code

fee

decimal

-

-

-

Fee value

iacc

String

0

11

-

Trading account

iaccn

String

-

-

-

Full name of the account holder

id

long

-

-

-

Generated ID of the request

ini

String

0

20

-

Initiator user ID

mkt

String

1

20

-

Market code

nmb

int

-

-

-

External order number, as assigned by the exchange (for replace/cancel requests)

opd

int

-

-

Date in YYYYMMDD format (for GTD orders) or 0 (for open orders)

Expiration date

origId

long

-

-

-

Order number, as assigned by the brokerage server (for replace/cancel requests)

prc

decimal

-

-

-

Order price

rcd

int

-

-

-

Reason code

rdy

int

-

-

Enumeration

Indicator specifying whether request is ready to be sent to exchange

ref

String

0

200

-

Reference (comments)

sde

int

-

-

Enumeration

Side

siz

long

-

-

-

Order size

ssl

int

-

-

Enumeration

Short sell indicator

status

int

-

-

Enumeration

Request status

std

int

-

-

Date in YYYYMMDD format

Settlement date

stt

int

-

-

Enumeration

Settlement type

sym

String

1

20

-

Symbol code

tgp

decimal

-

-

-

Trigger price

tms

Timestamp

-

-

-

Order timestamp

tpa

int

-

-

Enumeration

Trigger type

trm

int

-

-

Enumeration

Order term

type

int

-

-

Enumeration

Request type

uti

Timestamp

-

-

-

Last update time

uui

String

0

20

-

Updater user ID

value

decimal

-

-

-

Order value

ver

int

-

-

Enumeration

Volume restriction

dea

String

1

1

Y,N,-

DEA

ewf

int

-

-

-

Execution Responsibility Code

eal

String

1

1

Y,N,-

Execution Responsibility Algo

iwf

int

-

-

-

Investment Decision Code

ial

String

1

1

Y,N,-

Investment Decision Algo

acc

int

-

-

-

External account

diffFee

decimal

-

-

-

Difference of frozen fee to be applied

diffSize

long

-

-

-

Difference of volume to be applied

diffValue

decimal

-

-

-

Difference of value to be applied

osq

long

-

-

-

Order audit sequence

Note
The fields in italics are not relevant in client context and can be ignored by the client application.

The structure of an OrderRequestDto is the same regardless the type of the request (add, change or delete). There is, however, a field (type) indicating the action of the original request.

OrderRequestDto Enumerations

Below are the descriptions of all enumerations used for OrderRequestDto fields.

Table 12. Order Request Status

OrderRequestDto.status

Description

1

Initiated

2

Pending confirmation from exchange

3

Rejected (by the brokerage server)

4

Deleted (by the exchange)

5

Confirmed (by the brokerage server)

6

Error from the exchange

7

Accepted (by the exchange)

8

Resent to the exchange

Table 13. Order Request Type

OrderRequestDto.type

Description

-1

Cancel request

0

Change request

1

Add request

2

N/A

Table 14. Order Request Ready Flag

OrderRequestDto.rdy

Description

-1

Pending Approval

0

Not Ready for Exchange

1

Ready for Exchange

Table 15. Order Side

OrderRequestDto.sde

Description

1

Buy

2

Sell

Table 16. Order Term

OrderRequestDto.trm

Description

0

Fill-or-kill

1

Day

2

Open (good-til-cancel)

3

Good-til-date

4

Immediate or cancel

5

Valid for auction

6

Valid for closing

7

Valid for opening

Table 17. Order Settlement Type

OrderRequestDto.stt

Description

1

Standard

2

Non-standard

Table 18. Order Short Sell Indicator

OrderRequestDto.ssl

Description

0

Not short sell

1

Short sell

2

Market-making short sell

Table 19. Order Trigger Type

OrderRequestDto.tpa

Description

1

Ordinary

2

Stop

3

If-touched

4

TAL

Table 20. Order Volume Restriction

OrderRequestDto.ver

Description

0

No restriction

1

Minimum fill

2

Minimum block

3

All or none

4. ArenaXT Real-Time Commands

Below are all commands which a client can send or receive through the real-time connections (WSS or plain TCP/IP).

4.1. HEART BEAT

Informs the server that the client is still active and connected.

Command ID

100

Initiated via

Real-time connection

Initiated by

Client

Request Payload

none

Response Payload

none

Error Payload

n/a

Heart beat messages need to be sent periodically by the client application to keep the connection alive.

Note
For this command, the client application can omit the sessionId field from the business message. This field is not required in this case.

4.1.1. Message Payloads

Request Payload

No payload is required to be sent in the request.

Response Payload

No payload is received from the server.

Error Response Payload

This command will never fail on the server side.

4.1.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.1.3. Sample Messages

Request
{
    "bm": {
        "pid": 100,
        "user": "admin",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 100,
        "user": "admin",
        "ktime": 0,
        "longid": 0,
        "csq": 1
    }
}

4.2. LOGIN

Attempts to authenticate the client application with the server.

Command ID

101

Initiated via

Real-time connection

Initiated by

Client

Request Payload

Login

Response Payload

UserEnvDto

Error Payload

Login

Login message must be the first message sent after the connection is established.

Note
For this command, the client application can omit the sessionId and user fields from the business message. These fields are not required in this case.

4.2.1. Message Payloads

Request Payload

Requests must contain the Login payload, detailed below.

Table 21. The structure of Login type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.Login

The name of the payload object type

username

String

4

20

Can contain only alphanumeric characters and at most one dot

User code

password

String

8

20

-

User password

device

String

0

10

Optional

The identification of the connecting device

Response Payload

For valid requests which are successfully processed, a response with the UserEnvDto payload will be sent by the server.

The structure of UserEnvDto is detailed below.

Table 22. The structure of UserEnvDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

user

UserDto

-

-

-

User details

symbols

Lines<SubscriptionDto>

-

-

May be null if watch list is empty

Object holding the list of symbols from user’s watch list

tksType

String

3

1024

-

The identification of the server

The structure of an UserDto object is detailed below.

Table 23. The structure of UserDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

ckpn

boolean

-

-

-

Flag indicating whether PIN is required for trading operations

code

String

3

20

-

User code

flts

boolean

-

-

-

Ticker filtering flag

hec

int

-

-

Strictly positive when password is expired

Password expired warning count

name

String

3

40

-

User’s full name

pet

Timestamp

-

-

-

Password expiration time

pgl

int

-

-

-

Page size for reports

pnec

int

-

-

Strictly positive when PIN is expired

PIN expired warning count

pnet

Timestamp

-

-

-

PIN expiration time

role

int

-

-

Enumeration

User role

sid

String

0

40

-

Session ID

sco

int

-

-

-

Short code

lco

String

0

50

-

Long code

com

String

1

20

Always sent blank

Connection restrictions

cst

int

-

-

Enumeration

Connection status

dropcpy

boolean

-

-

-

Drop-copy flag

efc

String

0

15

Always sent blank

Connection type

grp

String

0

10

-

User group

ipa

String

1

40

Always sent blank

IP restriction list

lec

int

-

-

-

Number of failed login attempts

lpc

Timestamp

-

-

-

Last password change

lsi

String

0

15

Always sent blank

Last IP

lst

Timestamp

-

-

-

Last connection time

mxs

int

-

-

-

Maximum subscriptions

pec

int

-

-

-

Number of failed PIN attempts

pin

String

-

-

Always sent blank

PIN hash

prf

String

0

15

-

User profile

pwd

String

-

-

Always sent blank

Password hash

ref

String

0

40

-

Reference (comments)

status

int

-

-

Enumeration

Status

uti

Timestamp

-

-

-

Last update time

uty

int

-

-

Enumeration

Update type

uui

String

0

20

-

Updater user id

uws

String

0

15

-

Workstation

Note
The fields in italics are not relevant in client context and can be ignored by the client application.

The structure of a Lines<SubscriptionDto> object is detailed below:

Table 24. The structure of Lines<SubscriptionDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.SubscriptionDto

Array of SubscriptionDto objects

1

-

-

Array of subscription details

The structure of a SubscriptionDto object is detailed below:

Table 25. The structure of SubscriptionDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

Error Response Payload

For failed login attempts, as well as invalid requests, the server will always return an error with a Login payload with the following structure:

Table 26. The structure of Login type (for errors)

Field

Type

Min. Length

Max. Length

Restrictions

Description

username

String

4

20

-

User code

efc

String

0

15

-

Connection type

4.2.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 27. User Status

UserDto.status

Description

0

Disabled

1

Enabled

Table 28. Connection Status

UserDto.cst

Description

0

Disconnected

1

Connected

Table 29. User Role

UserDto.role

Description

0

System Admin

1

Admin

2

Trader

3

Client

4

View-Only

Table 30. Update Type

UserDto.uty

Description

0

Deleted

1

New

2

Changed

4.2.3. Sample Messages

Request
{
    "bm": {
        "pid": 101,
        "csq": 1,
        "payload": {
            "@class": "p.Login",
            "username": "admin",
            "password": "admin"
        }
    }
}
Response
{
    "bm": {
        "pid": 101,
        "user": "admin",
        "ktime": 1423557964529,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.UserEnvDto",
            "user": {
                "code": "admin",
                "status": 1,
                "name": "Administrator",
                "grp": "ADMIN",
                "pwd": "",
                "pgl": 100,
                "ipa": "*",
                "lsi": "192.168.250.205",
                "lec": 0,
                "cst": 1,
                "mxs": 10000,
                "flts": false,
                "lst": "2015-02-10 10:46:04.527",
                "com": "*",
                "efc": "WS",
                "lpc": "2014-11-05 13:15:45.793",
                "sid": "4C6B5478588248B60A6D0B46B3D57B707CB9A073",
                "prf": "ADMIN",
                "ref": "",
                "uty": 2,
                "uti": "2015-02-10 10:46:04.527",
                "uui": "admin",
                "uws": "192.168.250.205",
                "role": 0,
                "ckpn": false,
                "pin": "",
                "pet": "2024-10-31 00:00:00.0",
                "pnet": "2023-07-03 00:00:00.0",
                "hec": 0,
                "pnec": 0,
                "pec": 0,
                "dropcpy": false
            },
            "symbols": {
                "d.SubscriptionDto": [{
                    "exchange": "BVB",
                    "symbol": "SIF1"
                },
                {
                    "exchange": "BVB",
                    "symbol": "SIF2"
                }]
            },
            "tksType": "tickstream.alex.local.net 1.6.5"
        }
    }
}
Response with error
{
    "bm": {
        "pid": 101,
        "error": 2,
        "user": "admin",
        "ktime": 1423552020874,
        "kmessage": "Invalid credentials or connection restrictions.",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.Login",
            "username": "admin",
            "efc": "WS"
        }
    }
}

4.3. LOGOUT

Logs the current user out from the server and closes the connection.

Command ID

102

Initiated via

Real-time connection

Initiated by

Client or Server

Request Payload

none

Response Payload

none

Error Payload

n/a

Logout messages can be initiated by either the client or the server. If the client receives a LOGOUT message, it must close the connection with the server, in case it is still active. Conversely, there might be situations when the connection is closed by the server, without a LOGOUT message being sent. In this case, the client application should consider the disconnection event as an implicit LOGOUT message.

4.3.1. Message Payloads

Request Payload

No payload is required to be sent in the request.

Response Payload

No payload is received from the server.

Error Response Payload

This command will never fail on the server side.

4.3.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.3.3. Sample Messages

Request
{
    "bm": {
        "pid": 102,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 102,
        "user": "admin",
        "ktime": 0,
        "longid": 0,
        "csq": 1
    }
}

4.4. CHANGE PASSWORD

Requests the change of the login password for the logged in user.

Command ID

103

Initiated via

Real-time connection

Initiated by

Client

Request Payload

ChangePassword

Response Payload

none

Error Payload

no payload at all, or ResultPage<string>

4.4.1. Message Payloads

Request Payload

Requests must contain the ChangePassword payload, detailed below.

Table 31. The structure of ChangePassword type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.ChangePassword

The name of the payload object type

oldPassword

String

8

20

-

The current password

newPassword

String

8

20

-

The new password

confirmedNewPassword

String

8

20

-

The new password

Response Payload

For successful requests, a response with no payload will be sent. The response will contain a confirmation message (in the kmessage field) which the client application can present to the end-user as a confirmation of the change.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent. The client application can use the error message (from the kmessage field) to inform the end-user about the failure.

4.4.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.4.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ChangePassword",
            "oldPassword": "test",
            "newPassword": "test",
            "confirmedNewPassword": "test"
        },
        "pid": 103,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 103,
        "user": "admin",
        "ktime": 1423836961563,
        "kmessage": "Password changed",
        "longid": 0,
        "csq": 1
    }
}
Response with validation error
{
    "bm": {
        "pid": 103,
        "error": 11,
        "user": "admin",
        "ktime": 1423836961563,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 3,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Old password must be not null.",
                    "New password must be not null.",
                    "Password must be not null."
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 103,
        "error": 5,
        "user": "admin",
        "ktime": 1423836961563,
        "kmessage": "Wrong password.",
        "longid": 0,
        "csq": 1
    }
}

4.5. GET EXCHANGES

Requests the list of exchanges the server has links with.

Command ID

104

Initiated via

Real-time connection

Initiated by

Client

Request Payload

none

Response Payload

ResultPage<ExchangeDto>

Error Payload

none

4.5.1. Message Payloads

Request Payload

No payload is required to be sent in the request.

Response Payload

For requests which are successfully processed by the server, a response with a ResultPage<ExchangeDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<ExchangeDto>, described below.

Table 32. The structure of Lines<ExchangeDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.ExchangeDto

Array of ExchangeDto objects

-

-

-

Array of objects

The structure of an ExchangeDto object is detailed below.

Table 33. The structure of ExchangeDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

code

String

1

5

-

Exchange code

name

String

0

40

-

Exchange name

status

int

-

-

Enumeration

Connection status

tzid

String

0

20

-

Time zone ID

eod

String

0

8

-

End of day

sod

String

0

8

-

Start of day

Note
The fields in italics are not relevant in client context and can be ignored by the client application.

The data returned for this command is not paginated on the server side, so all linked exchanges will be returned in a single response.

Error Response Payload

For failed requests the server will always return an error with no payload.

4.5.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 34. Connection Status

ExchangeDto.status

Description

0

Offline

1

Online

4.5.3. Sample Messages

Request
{
    "bm": {
        "pid": 104,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 104,
        "user": "admin",
        "ktime": 1423752973067,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.ExchangeDto": [{
                    "code": "BVB",
                    "name": "Bucharest Stock Exchange",
                    "tzid": "Europe\/Bucharest",
                    "sod": "01:00:00",
                    "eod": "23:00:00",
                    "status": 0
                }]
            }
        }
    }
}
Response with error
{
    "bm": {
        "pid": 104,
        "error": 1,
        "user": "admin",
        "ktime": 1423552020874,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

4.6. GET SYMBOLS

Requests the list of financial instruments defined on the server.

Command ID

105

Initiated via

Real-time connection

Initiated by

Client

Request Payload

GenericIoPayload (optional)

Response Payload

ResultPage<SymbolDto>

Error Payload

none

4.6.1. Message Payloads

Request Payload

Requests may be sent without any payload, in which case all symbols are received, or they may contain a payload with the type GenericIoPayload, which allows specifying a particular exchange code by which the symbols to be filtered on the server side. The structure of the GenericIoPayload type is detailed in ArenaXT Common Types chapter.

Response Payload

For valid requests which are successfully processed, a response with a ResultPage<SymbolDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<SymbolDto>, described below.

Table 35. The structure of Lines<SymbolDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.SymbolDto

Array of SymbolDto objects

-

-

-

Array of objects

The structure of a SymbolDto object is detailed below.

Table 36. The structure of SymbolDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

code

String

1

20

-

Symbol code

coupons

String

0

2000

-

Coupons (for bonds)

defStlm

int

-

-

-

Default settlement term

isin

String

1

30

-

ISIN

issueDate

int

-

-

-

Issue date

kind

int

-

-

Enumeration

Symbol type

maturity

int

-

-

-

Maturity date

mul

decimal

-

-

-

Price multiplier

name

String

1

40

-

Full instrument name

prevSettle

decimal

-

-

-

Previous evaluation price (for futures)

refPrice

decimal

-

-

-

Reference price

settle

decimal

-

-

-

Evaluation price

underlying

String

0

25

-

Underlying symbol

xchange

String

1

5

-

Exchange code

accfnc

String

-

-

Enumeration

External account function

id

int

-

-

-

Internal ID

priceStep

String

0

15

-

Step for price modification

settlementCurrency

String

0

15

-

Settlement currency

tradeCurrency

String

0

15

-

Trading currency

Note
The fields in italics are not relevant in client context and can be ignored by the client application.

The data returned for this command is not paginated on the server side, so all requested symbols will be returned in a single response.

Important
Instruments are uniquely identified in the system by the combination of code and xchange fields.
Error Response Payload

For failed requests, as well as invalid requests, the server will always return an error with no payload.

4.6.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 37. Symbol Type

SymbolDto.kind

Description

0

Share

1

Future

2

Option

3

Bond

4

Bill

Table 38. External Account Function

SymbolDto.accfnc

Description

AGG

Aggregate external account

IND

Individual external account

UND

Undefined account function

4.6.3. Sample Messages

Request without a payload
{
    "bm": {
        "pid": 105,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Request with payload
{
    "bm": {
        "pid": 105,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1,
        "payload": {
            "@class": "p.GenericIoPayload",
            "content": {
                "@class": "string",
                "$": "BVB"
            }
        }
    }
}
Response
{
    "bm": {
        "pid": 105,
        "user": "admin",
        "ktime": 1423740001771,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 2,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.SymbolDto": [{
                    "id": 248,
                    "xchange": "BVB",
                    "code": "SNP13MAR",
                    "isin": "ROF0000018B3",
                    "kind": 1,
                    "name": "SNP Futures March 2013",
                    "underlying": "S.SNP",
                    "priceStep": "futures2",
                    "refPrice": "0.987600",
                    "prevSettle": "0.987600",
                    "tradeCurrency": "RON",
                    "settlementCurrency": "RON",
                    "issueDate": 0,
                    "maturity": 20130315,
                    "defStlm": 1,
                    "coupons": "",
                    "mul": "1000.000000",
                    "settle": "0.987600",
                    "accfnc": "IND"
                },
                {
                    "id": 355,
                    "xchange": "BVB",
                    "code": "TGN",
                    "isin": "ROTGNTACNOR8",
                    "kind": 0,
                    "name": "SNTGN TRANSGAZ MEDIAS",
                    "underlying": "",
                    "priceStep": "share2",
                    "refPrice": "229.400000",
                    "prevSettle": "0.000000",
                    "tradeCurrency": "RON",
                    "settlementCurrency": "RON",
                    "issueDate": 0,
                    "maturity": 0,
                    "defStlm": 3,
                    "coupons": "",
                    "mul": "0.000000",
                    "settle": "217.700000",
                    "accfnc": "AGG"
                }
                ]
            }
        }
    }
}
Response with error
{
    "bm": {
        "pid": 105,
        "error": 1,
        "user": "admin",
        "ktime": 1423552020874,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

4.7. INDICES SNAPSHOT

Requests the list of exchange indices.

Command ID

106

Initiated via

Real-time connection

Initiated by

Client

Request Payload

GenericIoPayload (optional)

Response Payload

ResultPage<IndexDto>

Error Payload

none

4.7.1. Message Payloads

Request Payload

Requests may be sent without any payload, in which case indices from all linked exchanges are received, or they may contain a payload with the type GenericIoPayload, which allows specifying a particular exchange code by which the indices to be filtered on the server side. The structure of the GenericIoPayload type is detailed in ArenaXT Common Types chapter.

Response Payload

For valid requests which are successfully processed, a response with a ResultPage<IndexDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<IndexDto>, described below.

Table 39. Structure of Lines<IndexDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.IndexDto

Array of IndexDto objects

-

-

-

Array of objects

The structure of an IndexDto object is detailed below.

Table 40. The structure of IndexDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

xchangeCode

String

1

5

-

Exchange code

code

String

1

20

-

Index code

change

decimal

-

-

-

Price absolute change

changePercent

decimal

-

-

-

Price percentage change

close

decimal

-

-

-

Close price

high

decimal

-

-

-

Highest price

low

decimal

-

-

-

Lowest price

name

String

0

40

-

Index full name

open

decimal

-

-

-

Open price

uti

Timestamp

-

-

-

Last update time

The data returned for this command is not paginated on the server side, so all requested indices will be returned in a single response.

Important
Indices are uniquely identified in the system by the combination of code and xchangeCode fields.
Error Response Payload

For failed requests, as well as invalid requests, the server will always return an error with no payload.

4.7.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.7.3. Sample Messages

Request without a payload
{
    "bm": {
        "pid": 106,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Request with payload
{
    "bm": {
        "pid": 106,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1,
        "payload": {
            "@class": "p.GenericIoPayload",
            "content": {
                "@class": "string",
                "$": "BVB"
            }
        }
    }
}
Response
{
    "bm": {
        "pid": 106,
        "user": "admin",
        "ktime": 1423752973083,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.IndexDto": [{
                    "code": "BET",
                    "name": "BET",
                    "open": "6656.640000",
                    "close": "6623.660000",
                    "high": "6656.640000",
                    "low": "6575.950000",
                    "change": "-32.980000",
                    "changePercent": "-0.500000",
                    "uti": "2015-02-10 18:31:37.72",
                    "xchangeCode": "BVB"
                }]
            }
        }
    }
}
Response with error
{
    "bm": {
        "pid": 106,
        "error": 1,
        "user": "admin",
        "ktime": 1423552020874,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

4.8. ADD SUBSCRIPTION

Requests the server to mark the specified symbol as watched.

Command ID

108

Initiated via

Real-time connection

Initiated by

Client

Request Payload

Subscription

Response Payload

ResultPage<L1DataDto>

Error Payload

no payload at all, or ResultPage<string>

This command has two effects on the server:

  • marks the specified symbol as watched, so that it will be included in the list of symbols the user receives at login

  • subscribes the current user for level 1 market data updates related to the specified symbol

4.8.1. Message Payloads

Request Payload

Requests must contain the Subscription payload, detailed below.

Table 41. The structure of Subscription type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.Subscription

The name of the payload object type

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

Response Payload

For successful requests, the server will send a response with a ResultPage<L1DataDto> payload, containing L1 market data related to the requested symbol. The client application must add the L1DataDto objects to its own snapshot of market data and process them the same way it does for <<L1 DATA SNAPSHOT>> command (ID 110).

Note
The response of L1 DATA SNAPSHOT command contains only the market data for watched symbols. Therefore, when a new symbol is marked as watched, the client application needs to receive the related market data. This is the reason the response payload of this command is a ResultPage<L1DataDto>.
Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.8.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.8.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.Subscription",
            "exchange": "BVB",
            "symbol": "FP"
        },
        "pid": 108,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 108,
        "user": "admin",
        "ktime": 1423841871786,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.L1DataDto": [{
                    "exchange": "BVB",
                    "market": "REGS",
                    "symbol": "FP",
                    "pkMarket": 1,
                    "smkStatus": 1,
                    "efectiveDate": 20150210,
                    "tradesNo": 165,
                    "totalValue": "16774.550000",
                    "openPrice": "0.843000",
                    "lastPrice": "0.860000",
                    "averagePrice": "0.856000",
                    "lowPrice": "0.843000",
                    "highPrice": "0.861000",
                    "bestBuyPrice": "0.855000",
                    "bestBuyVolume": 900,
                    "bestSellPrice": "0.860000",
                    "bestSellVolume": 700,
                    "lastVolume": 100,
                    "fixingPrice": "0.000000",
                    "fixingVolume": 0,
                    "crtRefPrice": "0.000000",
                    "crtSettle": "0.000000",
                    "direction": 1,
                    "uti": "2015-02-10 18:27:33.635",
                    "openInterest": 0,
                    "basis": 0,
                    "change": 0,
                    "changePercent": 0,
                    "averageChange": 0,
                    "averageChangePercent": 0,
                    "settleChange": 0,
                    "settleChangePercent": 0,
                    "totalVolume": 19600
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 108,
        "error": 11,
        "user": "admin",
        "ktime": 1423841871786,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": ["Symbol code is empty"]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 108,
        "error": 6,
        "user": "admin",
        "ktime": 1423841871786,
        "kmessage": "Market data is unavailable for FP",
        "longid": 0,
        "csq": 1
    }
}

4.9. REMOVE SUBSCRIPTION

Requests the server to remove the specified symbol from the watch list.

Command ID

109

Initiated via

Real-time connection

Initiated by

Client

Request Payload

Subscription

Response Payload

Subscription

Error Payload

no payload at all, or ResultPage<string>

This command has two effects on the server:

  • marks the specified symbol as not-watched, so that it will be removed from the watch list the user receives at login

  • unsubscribes the current user from level 1 market data updates related to the specified symbol

4.9.1. Message Payloads

Request Payload

Requests must contain the Subscription payload, detailed below.

Table 42. The structure of Subscription type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.Subscription

The name of the payload object type

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

Response Payload

For successful requests, the server will send a response with a payload having the same type and content as the request.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.9.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.9.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.Subscription",
            "exchange": "BVB",
            "symbol": "FP"
        },
        "pid": 109,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 109,
        "user": "admin",
        "ktime": 1423841871786,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.Subscription",
            "exchange": "BVB",
            "symbol": "FP"
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 109,
        "error": 11,
        "user": "admin",
        "ktime": 1423841871786,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": ["Symbol code is empty"]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 109,
        "error": 6,
        "user": "admin",
        "ktime": 1423841871786,
        "kmessage": "L1 data not found",
        "longid": 0,
        "csq": 1
    }
}

4.10. L1 DATA SNAPSHOT

Requests the first level of market data for all watched symbols.

Command ID

110

Initiated via

Real-time connection

Initiated by

Client

Request Payload

GenericIoPayload (optional)

Response Payload

ResultPage<L1DataDto>

Error Payload

none

L1 data is disseminated by symbol and the markets it is currently traded on (the so-called symbol-market combination). Therefore, for a symbol, there will be multiple L1DataDto entries, one for each market.

At the exchange level, a symbol has a main market, called the primary market, which is the default place for trading that symbol. The trades occurring on the primary market will set the closing price and give all related market statistics for that symbol.

The client application should display, by default, the L1 data for the primary market (for example, in Watch List), but it should also keep the information related to the other symbol-markets and make it available upon request.

4.10.1. Message Payloads

Request Payload

Requests may be sent without any payload, in which case the L1 market data for all watched symbols is received, or they may contain a payload with the type GenericIoPayload, which allows specifying a particular criteria by which the L1 data to be filtered on the server side. The structure of the GenericIoPayload type is detailed in ArenaXT Common Types chapter.

The possible values for the criteria are listed below:

Table 43. The content of GenericIoPayload for L1 DATA SNAPSHOT command

BVB

Returns the L1 data for all symbols traded on the main market

ATS

Returns the L1 data for ATS symbols traded on the AeRO market

ATSI

Returns the L1 data for ATS symbols traded on the ATS International market

BONDS

Returns the L1 data for bonds and t-bills

CERTS

Returns the L1 data for structured products

PRTF

Returns the L1 data for portfolio symbols (symbols from the portfolios the user has access to)

FAV

Returns the L1 data for watched symbols (similar to the result returned when no payload is provided)

Response Payload

For valid requests which are successfully processed, a response with a ResultPage<L1DataDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<L1DataDto>, described below.

Table 44. The structure of Lines<L1DataDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.L1DataDto

Array of L1DataDto objects

-

-

-

Array of objects

The structure of a L1DataDto object is detailed below.

Table 45. The structure of L1DataDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

market

String

1

20

-

Market code

averagePrice

decimal

-

-

-

Average price

basis

decimal

-

-

-

Basis (for futures)

bestBuyPrice

decimal

-

-

-

Best bid price

bestBuyVolume

long

-

-

-

Best bid volume

bestSellPrice

decimal

-

-

-

Best ask price

bestSellVolume

long

-

-

-

Best ask volume

crtRefPrice

decimal

-

-

-

Current reference price

crtSettle

decimal

-

-

-

Current evaluation price

direction

int

-

-

Enumeration

Last trade direction

efectiveDate

int

-

-

Date in YYYYMMDD format

The date for which the data is valid

fixingPrice

decimal

-

-

-

Potential open price

fixingVolume

long

-

-

-

Potential open volume

highPrice

decimal

-

-

-

Highest trade price

lastPrice

decimal

-

-

-

Last price

lastVolume

long

-

-

-

Last trade volume

lowPrice

decimal

-

-

-

Lowest trade price

openInterest

long

-

-

-

Open interest (for futures)

openPrice

decimal

-

-

-

Open price

pkMarket

int

-

-

Enumeration

Primary market indicator

smkStatus

int

-

-

Enumeration

Symbol-market status

totalValue

decimal

-

-

-

Accumulated value of all trades

totalVolume

long

-

-

-

Accumulated volume of all trades

tradesNo

int

-

-

-

Number of trades executed

uti

Timestamp

-

-

-

Last update time

averageChange

decimal

-

-

Always sent as 0

Price average absolute change

averageChangePercent

decimal

-

-

Always sent as 0

Price average percentage change

change

decimal

-

-

Always sent as 0

Price absolute change

changePercent

decimal

-

-

Always sent as 0

Price percentage change

settleChange

decimal

-

-

Always sent as 0

Evaluation price absolute change

settleChangePercent

decimal

-

-

Always sent as 0

Evaluation price percentage change

Note
The fields in italics are not relevant in client context and can be ignored by the client application.

The data returned for this command is not paginated on the server side, so all existing data will be returned in a single response.

Important
L1 data is uniquely identified in the system by the combination of symbol, market and exchange fields.
Error Response Payload

For failed requests, as well as invalid requests, the server will always return an error with no payload.

4.10.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 46. Primary Market Indicator

L1DataDto.pkMarket

Description

0

Secondary market

1

Primary market

Table 47. Symbol-Market Status

L1DataDto.smkStatus

Description

1

Opened

2

Suspended

3

Closed

4

Fixing

5

Pre-Opened

6

Pre-Closed

7

Trading-At-Last

Table 48. Last Trade Direction

L1DataDto.direction

Description

-1

Down

0

Constant

1

Up

4.10.3. Sample Messages

Request without a payload
{
    "bm": {
        "pid": 110,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Request with payload
{
    "bm": {
        "pid": 110,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1,
        "payload": {
            "@class": "p.GenericIoPayload",
            "content": {
                "@class": "string",
                "$": "BVB"
            }
        }
    }
}
Response
{
    "bm": {
        "pid": 110,
        "user": "admin",
        "ktime": 1423740003086,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.L1DataDto": [{
                    "exchange": "BVB",
                    "market": "REGS",
                    "symbol": "SIF2",
                    "pkMarket": 1,
                    "smkStatus": 3,
                    "efectiveDate": 20150210,
                    "tradesNo": 0,
                    "totalValue": "0.000000",
                    "openPrice": "0.000000",
                    "lastPrice": "0.000000",
                    "averagePrice": "0.000000",
                    "lowPrice": "0.000000",
                    "highPrice": "0.000000",
                    "bestBuyPrice": "0.000000",
                    "bestBuyVolume": 0,
                    "bestSellPrice": "0.000000",
                    "bestSellVolume": 0,
                    "lastVolume": 0,
                    "fixingPrice": "0.000000",
                    "fixingVolume": 0,
                    "crtRefPrice": "0.000000",
                    "crtSettle": "0.000000",
                    "direction": 0,
                    "uti": "2015-02-10 00:29:59.837",
                    "openInterest": 0,
                    "basis": 0,
                    "change": 0,
                    "changePercent": 0,
                    "averageChange": 0,
                    "averageChangePercent": 0,
                    "settleChange": 0,
                    "settleChangePercent": 0,
                    "totalVolume": 0
                }]
            }
        }
    }
}
Response with error
{
    "bm": {
        "pid": 110,
        "error": 1,
        "user": "admin",
        "ktime": 1423552020874,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

4.11. L1 DATA UPDATE

Sends level 1 market data updates to client applications.

Command ID

111

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

L1UpdateDto

Error Payload

n/a

L1 data updates are received as differential updates from the L1 market data received through <<L1 DATA SNAPSHOT>> command (ID 110). Therefore, only the fields which are updated on the server are disseminated through L1 DATA UPDATE messages.

It is also possible for the server to send updates in batches. If there are multiple fields changed during a market event, the server will send a single L1 DATA UPDATE message containing a list of updates.

The client application must be able to identify all the updates that are disseminated and correctly update the stored snapshot of L1 data.

In order to reduce the size of the message, the server does not send the name of the L1 data elements which have changed, but a numeric code. The correspondence between the numeric code and the market data elements is included in the Constants and Enumerations section below.

4.11.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have a L1UpdateDto payload with the following structure.

Table 49. The structure of L1UpdateDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

market

String

1

20

-

Market code

smkStatus

int

-

-

-

Symbol-market status

updates

Map

-

-

-

List of updates

The field updates has a the type Map whose structure is described in chapter ArenaXT Common Types.

Important
The numeric codes indicating which market data elements have changed have the int runtime type and will be sent as entry keys; the updated value of the market data elements will be sent as entry values.
Error Response Payload

This command will never fail on the server side.

4.11.2. Constants and Enumerations

Below is the list of all numeric codes which are disseminated as L1 data updates.

Table 50. L1 Data Update Codes

Code

Description

0

Effective Date

1

Trades Count

3

Total Value

4

Open Price

5

Last Price

6

Average Price

7

Lowest Price

8

Highest Price

9

Best Buy Price

10

Best Buy Volume

11

Best Sell Price

12

Best Sell Volume

13

Last Volume

14

Fixing Price

15

Fixing Volume

16

Current Reference Price

17

Current Evaluation Price

18

Direction

19

Last Update Time

20

Open Interest

21

Basis

22

Price Change (Absolute)

23

Price Change (Percent)

24

Average Price Change (Absolute)

25

Average Price Change (Percent)

26

Evaluation Price Change (Absolute)

27

Evaluation Price Change (Percent)

28

Total Volume

29

Last Trade Price

30

Default Settlement Term

31

Last Trades Count

32

Accumulated Volume

Note
The codes in italics are not currently disseminated by the server, so the client must compute the updated values manually if they are needed on the client side.

4.11.3. Sample Messages

Response
{
    "bm": {
        "pid": 111,
        "ktime": 0,
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "d.L1UpdateDto",
            "exchange": "BVB",
            "market": "REGS",
            "symbol": "BIO",
            "smkStatus": 0,
            "updates": {
                "entry": [{
                    "int": [1,
                    256]
                },
                {
                    "int": 19,
                    "sql-timestamp": "2015-02-12 17:37:43.948"
                },
                {
                    "int": 32,
                    "long": 300
                },
                {
                    "int": [18,
                    -1]
                },
                {
                    "int": 3,
                    "big-decimal": "20995.4000"
                },
                {
                    "int": 5,
                    "big-decimal": "0.3130"
                },
                {
                    "int": 6,
                    "big-decimal": 0.3414
                },
                {
                    "int": 29,
                    "big-decimal": "0.3130"
                },
                {
                    "int": 12,
                    "long": 4700
                },
                {
                    "int": 13,
                    "long": 300
                },
                {
                    "int": 28,
                    "long": 61500
                },
                {
                    "int": [31,
                    1]
                }]
            }
        }
    }
}

4.12. INDICES UPDATE

Sends indices updates to client applications.

Command ID

112

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

IndexUpdateDto

Error Payload

n/a

Indices updates are received as differential updates from the indices data received through <<INDICES SNAPSHOT>> command (ID 106). Therefore, only the fields which are updated on the server are disseminated through INDICES UPDATE messages.

It is also possible for the server to send updates in batches. If there are multiple fields changed during a market event, the server will send a single INDICES UPDATE message containing a list of updates.

The client application must be able to identify all the updates that are disseminated and correctly update the stored snapshot of indices.

In order to reduce the size of the message, the server does not send the name of the index elements which have changed, but a numeric code. The correspondence between the numeric code and the index elements is included in the Constants and Enumerations section below.

4.12.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have an IndexUpdateDto payload with the following structure.

Table 51. The structure of IndexUpdateDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

exchange

String

1

5

-

Exchange code

code

String

-

-

-

Index code

updates

Map

-

-

-

List of updates

The field updates has a the type Map whose structure is described in chapter ArenaXT Common Types.

Important
The numeric codes indicating which index elements have changed have the int runtime type and will be sent as entry keys; the updated value of the index elements will be sent as entry values.
Error Response Payload

This command will never fail on the server side.

4.12.2. Constants and Enumerations

Below is the list of all numeric codes which are disseminated as index data updates.

Table 52. Index Update Codes

Code

Description

0

Index Code

1

Open Price

3

Close Price

4

Highest Price

5

Lowest Price

6

Price Change (Absolute)

7

Price Change (Percent)

8

Last Update Time

9

Exchange Code

4.12.3. Sample Messages

Response
{
    "bm": {
        "pid": 112,
        "ktime": 0,
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "d.IndexUpdateDto",
            "exchange": "BVB",
            "code": "BET",
            "updates": {
                "entry": [{
                    "int": 3,
                    "big-decimal": 7396.94
                },
                {
                    "int": 6,
                    "big-decimal": 671.09
                },
                {
                    "int": 7,
                    "big-decimal": 9.98
                },
                {
                    "int": 8,
                    "sql-timestamp": "2015-02-12 17:45:51.168"
                }]
            }
        }
    }
}

4.13. L2 DATA SNAPSHOT

Requests the second level of market data for the specified symbol.

Command ID

113

Initiated via

Real-time connection

Initiated by

Client

Request Payload

GetL2Data

Response Payload

L2DataDto

Error Payload

no payload at all, or ResultPage<string>

This command has two effects on the server:

  • returns the snapshot of the L2 market data as it existed at the moment of the request;

  • subscribes the current user for level 2 market data updates related to the specified symbol and market.

L2 data represents the full market depth for a symbol and a market and consists of the public information about all outstanding orders from the order book.

The initial snapshot of data received with this command can be used to initialize the order book view and to apply subsequent updates received as <<L2 DATA UPDATE>> messages (ID 114). The client application can request the server to stop sending L2 data updates by issuing the command <<UNSUBSCRIBE L2>> (ID 127).

4.13.1. Message Payloads

Request Payload

Requests must contain the GetL2Data payload, detailed below.

Table 53. The structure of GetL2Data type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.GetL2Data

The name of the payload object type

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

market

String

1

20

-

Market code

Response Payload

For valid requests which are successfully processed, a response with a L2DataDto payload will be sent by the server.

The structure of a L2DataDto object is detailed below.

Table 54. The structure of L2DataDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

market

String

1

20

-

Market code

bids

Lines<BookEntryDto>

-

-

-

Object holding the list of buy orders

asks

Lines<BookEntryDto>

-

-

-

Object holding the list of sell orders

The type of bids and asks fields is a specialization of the generic type Lines<T> and has the following structure.

Table 55. The structure of Lines<BookEntryDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.BookEntryDto

Array of BookEntryDto objects

-

-

-

Array of objects

The structure of a BookEntryDto object is detailed below.

Table 56. The structure of BookEntryDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

orderNo

long

-

-

-

Order number (as allocated by the exchange)

price

decimal

-

-

-

Order price

volume

long

-

-

-

Order volume (size)

hidden

boolean

-

-

-

Flag indicating whether the order has hidden volume

The data returned for this command is not paginated on the server side, so all existing order book entries will be returned in a single response.

Important
L2 data is uniquely identified in the system by the combination of symbol, market and exchange fields.
Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.13.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.13.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.GetL2Data",
            "exchange": "BVB",
            "symbol": "ATB",
            "market": "REGS"
        },
        "pid": 113,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 113,
        "user": "admin",
        "ktime": 0,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.L2DataDto",
            "exchange": "BVB",
            "symbol": "ATB",
            "market": "REGS",
            "bids": {
                "@class": "linked-list",
                "d.BookEntryDto": [{
                    "hidden": false,
                    "volume": 1400,
                    "price": "35.9100",
                    "orderNo": 7367146
                },
                {
                    "hidden": false,
                    "volume": 1200,
                    "price": "35.5100",
                    "orderNo": 7359797
                }]
            },
            "asks": {
                "@class": "linked-list",
                "d.BookEntryDto": [{
                    "hidden": false,
                    "volume": 1199,
                    "price": "36.790000",
                    "orderNo": 7328180
                },
                {
                    "hidden": false,
                    "volume": 300,
                    "price": "36.800000",
                    "orderNo": 7234740
                },
                {
                    "hidden": false,
                    "volume": 100,
                    "price": "36.800000",
                    "orderNo": 7283626
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 113,
        "error": 11,
        "user": "admin",
        "ktime": 1424703480814,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Exchange code is empty"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 113,
        "error": 1,
        "user": "admin",
        "ktime": 1424703480814,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

4.14. L2 DATA UPDATE

Sends L2 data updates to client applications.

Command ID

114

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

L2UpdateDto

Error Payload

n/a

L2 data updates are received as differential updates from the L2 data received through <<L2 DATA SNAPSHOT>> command (ID 113). Therefore, only the order book entries which are updated on the server are disseminated.

It is also possible for the server to send updates in batches. If there are multiple entries changed during a market event, the server will send a single L2 DATA UPDATE message containing a list of updates.

The client application must be able to identify all the updates that are disseminated and correctly update the stored snapshot of L2 data.

4.14.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have an L2UpdateDto payload with the following structure.

Table 57. The structure of L2UpdateDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

market

String

1

20

-

Market code

actions

Lines<BookActionDto>

-

-

-

Object holding the list of order book changes

The type of the actions field is a specialization of the generic type Lines<T> and has the following structure.

Table 58. The structure of Lines<BookActionDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.BookActionDto

Array of BookActionDto objects

-

-

-

Array of objects

The structure of a BookActionDto object is detailed below.

Table 59. The structure of BookActionDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

action

int

-

-

Enumeration

Order book action

position

int

-

-

-

Order book position

side

int

-

-

Enumeration

Order book side

value

BookEntryDto

-

-

May be empty

Order book entry

Important
The client application must apply all L2 data updates in the order they are received from the server. If there are multiple changes disseminated in the same L2 DATA UPDATE message, the order in which BookActionDto entries are sent in the actions field is the order in which they must be processed. Failing to process the changes in the advised order will result in an inconsistent market depth view.
Error Response Payload

This command will never fail on the server side.

4.14.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 60. Order Book Action

BookActionDto.action

Description

-1

Delete

1

Add

Table 61. Order Book Side

BookActionDto.side

Description

1

Buy

2

Sell

4.14.3. Sample Messages

Response
{
    "bm": {
        "pid": 114,
        "ktime": 0,
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "d.L2UpdateDto",
            "exchange": "BVB",
            "symbol": "ATB",
            "market": "REGS",
            "actions": {
                "@class": "linked-list",
                "d.BookActionDto": [{
                    "action": -1,
                    "position": 50,
                    "side": 1
                },
                {
                    "action": 1,
                    "position": 50,
                    "side": 1,
                    "value": {
                        "hidden": false,
                        "volume": 300,
                        "price": "32.5000",
                        "orderNo": 7369371
                    }
                }]
            }
        }
    }
}

4.15. SMK STATUS UPDATE

Sends symbol-market status updates to client applications.

Command ID

115

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

ResultPage<SmkStatusDto>

Error Payload

n/a

This message is sent by the server when one or multiple markets change their trading status. The client application should process this message and update the related L1 market data.

4.15.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have a ResultPage<SmkStatusDto> payload, containing the new status for one or multiple symbol-markets. The type of this payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<SmkStatusDto>, described below.

Table 62. The structure of Lines<SmkStatusDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.SmkStatusDto

Array of SmkStatusDto objects

-

-

-

Array of objects

The structure of a SmkStatusDto object is detailed below.

Table 63. The structure of SmkStatusDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

market

String

1

20

-

Market code

pmk

int

-

-

Enumeration

Primary market indicator

status

int

-

-

Enumeration

Symbol-market status

sub

int

-

-

Enumeration

Subscription indicator

Note
The fields in italics are not relevant in client context and can be ignored by the client application.

The data contained in the response is not paginated on the server side, so all status updates will be sent in a single response.

Error Response Payload

This command will never fail on the server side.

4.15.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 64. Primary Market Indicator

SmkStatusDto.pmk

Description

0

Secondary market

1

Primary market

Table 65. Symbol-Market Status

SmkStatusDto.status

Description

1

Opened

2

Suspended

3

Closed

4

Fixing

5

Pre-Opened

6

Pre-Closed

7

Trading-At-Last

Table 66. Subscription Indicator

SmkStatusDto.sub

Description

0

Not subscribed

1

Subscribed

4.15.3. Sample Messages

Response
{
    "bm": {
        "pid": 115,
        "ktime": 0,
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.SmkStatusDto": [{
                    "exchange": "BVB",
                    "market": "REGS",
                    "symbol": "BVB",
                    "status": 3,
                    "sub": 1,
                    "pmk": 1
                }]
            }
        }
    }
}

4.16. ADD ORDER

Requests a new trading order to be sent to the exchange.

Command ID

117

Initiated via

Real-time connection

Initiated by

Client

Request Payload

AddOrder

Response Payload

OrderRequestDto

Error Payload

no payload at all, or ResultPage<string>

This command initiates an 'add' request which will result in a new order being sent to the exchange.

If the request is accepted by the server, the client application will receive updated information about it in the form of <<REQUEST UPDATE>> messages (ID 120). After the request is processed at the exchange side, the server will send the result in the form of <<ORDER UPDATE>> messages (ID 121).

The description of the typical request flow can also be found in the ArenaXT Common Types chapter.

4.16.1. Message Payloads

Request Payload

Requests must contain the AddOrder payload, detailed below.

Table 67. The structure of AddOrder type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.AddOrder

The name of the payload object type

exc

String

1

5

-

Exchange code

sym

String

1

20

-

Symbol code

mkt

String

1

20

-

Market code

clr

int

-

-

-

Clearing term

dcv

long

-

-

-

Disclosed volume

iacc

String

1

11

-

Trading account

opd

int

-

-

Date in YYYYMMDD format (for GTD orders) or 0 (for open orders)

Expiration date

pin

String

0

40

-

Trading password (PIN)

prc

decimal

-

-

-1, 0 or a strictly positive number

Order price

ref

String

1

40

-

Reference (comments)

sde

int

-

-

Enumeration

Order side

siz

long

-

-

-

Order size

ssl

int

-

-

Enumeration

Short sell indicator

std

int

-

-

Date in YYYYMMDD format (for specific date) or 0 (for standard date)

Settlement date

stt

int

-

-

Enumeration

Settlement type

tgp

decimal

-

-

Strictly positive number or 0 if no trigger price is used

Trigger price

tpa

int

-

-

Enumeration

Trigger type

trm

int

-

-

Enumeration

Order term

ver

int

-

-

Enumeration

Volume restriction

iwf

int

-

-

-

Investment Decision Code

ial

String

1

1

Y,N,-

Investment Decision Algo

ewf

int

-

-

-

Execution Responsibility Code

eal

String

1

1

Y,N,-

Execution Responsibility Algo

dea

String

1

1

Y,N,-

DEA

Depending on the type of the order that needs to be added, the price field must be populated with different values, as described below.

Table 68. Price Values Based on Order Type

Order Type

Price Value

Market order

-1

Unpriced order

0

Limit order

Strictly positive number

Response Payload

For valid requests which are successfully processed, a response with an OrderRequestDto payload will be sent by the server.

Note
The structure of OrderRequestDto is detailed in the ArenaXT Common Types chapter.
Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.16.2. Constants and Enumerations

Enumerations

The enumerations used for this command are described in the ArenaXT Common Types chapter, since they are shared by AddOrder and OrderRequestDto types.

4.16.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.AddOrder",
            "exc": "BVB",
            "sym": "ATB",
            "mkt": "REGS",
            "sde": "2",
            "iacc": "A000000002",
            "siz": 1,
            "prc": "36.2900",
            "trm": 1,
            "opd": 0,
            "stt": 1,
            "clr": 2,
            "std": 0,
            "tpa": 1,
            "tgp": 0,
            "ver": 0,
            "dcv": 0,
            "ssl": 0,
            "ref": "",
            "pin": "12345"
        },
        "pid": 117,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 117,
        "user": "admin",
        "ktime": 1424790483398,
        "kmessage": "Add order request 469,262 accepted by broker server (sell 1 BIO\/REGS\/BVB at 0.3630 for account A000000002)",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.OrderRequestDto",
            "id": 469262,
            "origId": 0,
            "status": 1,
            "type": 1,
            "iacc": "A000000002",
            "diffSize": 0,
            "value": "0.3630",
            "diffValue": 0,
            "fee": "0.000000",
            "diffFee": 0,
            "exc": "BVB",
            "sym": "BIO",
            "mkt": "REGS",
            "ver": 0,
            "tpa": 1,
            "sde": 2,
            "trm": 1,
            "opd": 0,
            "clr": 2,
            "std": 0,
            "stt": 1,
            "acc": 8000067,
            "prc": "0.3630",
            "tgp": 0,
            "siz": 1,
            "dcv": 0,
            "ref": "",
            "nmb": 0,
            "tms": "1970-01-01 02:00:00.0",
            "osq": -1,
            "ssl": 0,
            "rcd": 0,
            "ini": "admin",
            "uui": "admin",
            "uti": "2015-02-24 11:37:47.032",
            "cti": "2015-02-24 11:37:47.032"
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 117,
        "error": 11,
        "user": "admin",
        "ktime": 1424790483398,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": ["Volume must be between 1 and 9223372036854775807"]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 117,
        "error": 8,
        "user": "admin",
        "ktime": 1424790483398,
        "kmessage": "No external account found for A000000002 to ATB@BVB",
        "longid": 0,
        "csq": 1
    }
}

4.17. CANCEL ORDER

Requests an outstanding trading order to be cancelled at the exchange.

Command ID

118

Initiated via

Real-time connection

Initiated by

Client

Request Payload

CancelOrder

Response Payload

OrderRequestDto

Error Payload

no payload at all, or ResultPage<string>

This command initiates a 'cancel' request which will result in an attempt to delete the specified outstanding order at the exchange.

If the request is accepted by the server, the client application will receive updated information about it in the form of <<REQUEST UPDATE>> messages (ID 120). After the request is processed at the exchange side, the server will send the result in the form of <<ORDER UPDATE>> messages (ID 121).

The description of the typical request flow can also be found in the ArenaXT Common Types chapter.

4.17.1. Message Payloads

Request Payload

Requests must contain the CancelOrder payload, detailed below.

Table 69. The structure of CancelOrder type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.CancelOrder

The name of the payload object type

exc

String

1

5

-

Exchange code

sym

String

1

20

-

Symbol code

mkt

String

1

20

-

Market code

nmb

long

-

-

-

ID of the order to cancel

pin

String

0

40

-

Trading password (PIN)

ref

String

1

40

-

Reference (comments)

iwf

int

-

-

-

Investment Decision Code

ial

String

1

1

Y,N,-

Investment Decision Algo

ewf

int

-

-

-

Execution Responsibility Code

eal

String

1

1

Y,N,-

Execution Responsibility Algo

dea

String

1

1

Y,N,-

DEA

Response Payload

For valid requests which are successfully processed, a response with an OrderRequestDto payload will be sent by the server.

Note
The structure of OrderRequestDto is detailed in the ArenaXT Common Types chapter.
Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.17.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.17.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.CancelOrder",
            "exc": "BVB",
            "sym": "BRK",
            "mkt": "REGS",
            "nmb": 184303,
            "ref": "",
            "pin": "12345"
        },
        "pid": 118,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 118,
        "user": "admin",
        "ktime": 1424792703076,
        "kmessage": "Cancel order request 469,264 accepted by broker server (sell 1 BRK\/REGS\/BVB at 0.1200 for account A000000002)",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.OrderRequestDto",
            "id": 469264,
            "origId": 184303,
            "status": 1,
            "type": -1,
            "iacc": "A000000002",
            "diffSize": 0,
            "value": 0,
            "diffValue": 0,
            "fee": 0,
            "diffFee": 0,
            "exc": "BVB",
            "sym": "BRK",
            "mkt": "REGS",
            "ver": 0,
            "tpa": 1,
            "sde": 2,
            "trm": 1,
            "opd": 20150224,
            "clr": 2,
            "std": 0,
            "stt": 1,
            "acc": 8000067,
            "prc": "0.120000",
            "tgp": "0.000000",
            "siz": 1,
            "dcv": 0,
            "ref": "",
            "nmb": 7456549,
            "tms": "2015-02-24 17:35:12.051",
            "osq": 21061941,
            "ssl": 0,
            "rcd": 0,
            "ini": "admin",
            "uui": "admin",
            "uti": "2015-02-24 17:45:03.054",
            "cti": "2015-02-24 17:45:03.054"
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 118,
        "error": 11,
        "user": "admin",
        "ktime": 1424792703076,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": ["Order number is a positive number"]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 118,
        "error": 7,
        "user": "admin",
        "ktime": 1424792703076,
        "kmessage": "Order 184,303 was not found",
        "longid": 0,
        "csq": 1
    }
}

4.18. REPLACE ORDER

Requests an outstanding trading order to be modified at the exchange.

Command ID

119

Initiated via

Real-time connection

Initiated by

Client

Request Payload

ReplaceOrder

Response Payload

OrderRequestDto

Error Payload

no payload at all, or ResultPage<string>

This command initiates a 'replace' request which will result in an attempt to modify the specified outstanding order at the exchange.

If the request is accepted by the server, the client application will receive updated information about it in the form of <<REQUEST UPDATE>> messages (ID 120). After the request is processed at the exchange side, the server will send the result in the form of <<ORDER UPDATE>> messages (ID 121).

The description of the typical request flow can also be found in the ArenaXT Common Types chapter.

4.18.1. Message Payloads

Request Payload

Requests must contain the ReplaceOrder payload, detailed below.

Table 70. The structure of ReplaceOrder type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.ReplaceOrder

The name of the payload object type

exc

String

1

5

-

exchange code

sym

String

1

20

-

symbol code

mkt

String

1

20

-

market code

nmb

long

-

-

-

ID of the order to replace

clr

int

-

-

-

Clearing term

dcv

long

-

-

-

Disclosed volume

opd

int

-

-

Date in YYYYMMDD format (for GTD orders) or 0 (for open orders)

Expiration date

pin

String

0

40

-

Trading password (PIN)

prc

decimal

-

-

-1, 0 or a strictly positive number

Order price

ref

String

1

40

-

Reference (comments)

siz

long

-

-

-

Order size

ssl

int

-

-

Enumeration

Short sell indicator

std

int

-

-

Date in YYYYMMDD format (for specific date) or 0 (for standard date)

Settlement date

stt

int

-

-

Enumeration

Settlement type

tgp

decimal

-

-

Strictly positive number or 0 if no trigger price is used

Trigger price

trm

int

-

-

Enumeration

Order term

iwf

int

-

-

-

Investment Decision Code

ial

String

1

1

Y,N,-

Investment Decision Algo

ewf

int

-

-

-

Execution Responsibility Code

eal

String

1

1

Y,N,-

Execution Responsibility Algo

dea

String

1

1

Y,N,-

DEA

If the type of the order needs to be changed, the price field must be populated with different values, as described below.

Table 71. Price Values Based on Order Type

Order Type

Price Value

Market order

-1

Unpriced order

0

Limit order

Strictly positive number

Response Payload

For valid requests which are successfully processed, a response with an OrderRequestDto payload will be sent by the server.

Note
The structure of OrderRequestDto is detailed in the ArenaXT Common Types chapter.
Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.18.2. Constants and Enumerations

Enumerations

The enumerations used for this command are described in the ArenaXT Common Types chapter, since they are shared by ReplaceOrder and OrderRequestDto types.

4.18.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ReplaceOrder",
            "nmb": 184304,
            "exc": "BVB",
            "sym": "BIO",
            "mkt": "REGS",
            "siz": 1,
            "prc": 0.151,
            "osq": 0,
            "trm": 1,
            "opd": 0,
            "stt": 1,
            "clr": 2,
            "std": 0,
            "tgp": 0,
            "dcv": 0,
            "ssl": 0,
            "ref": "",
            "pin": "12345"
        },
        "pid": 119,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 119,
        "user": "admin",
        "ktime": 1424793662198,
        "kmessage": "Replace order request 469,266 accepted by broker server (buy 2 BIO\/REGS\/BVB at 0.3510 for account A000000002)",
        "longid": 0,
        "csq": 51,
        "payload": {
            "@class": "d.OrderRequestDto",
            "id": 469266,
            "origId": 184304,
            "status": 1,
            "type": 0,
            "iacc": "A000000002",
            "diffSize": 1,
            "value": "0.7020",
            "diffValue": "0.351000",
            "fee": "0.000000",
            "diffFee": "0.000000",
            "exc": "BVB",
            "sym": "BIO",
            "mkt": "REGS",
            "ver": 0,
            "tpa": 1,
            "sde": 1,
            "trm": 1,
            "opd": 0,
            "clr": 2,
            "std": 0,
            "stt": 1,
            "acc": 8000067,
            "prc": "0.3510",
            "tgp": 0,
            "siz": 2,
            "dcv": 0,
            "ref": "",
            "nmb": 7458309,
            "tms": "2015-02-24 17:59:44.219",
            "osq": 21065229,
            "ssl": 0,
            "rcd": 0,
            "ini": "admin",
            "uui": "admin",
            "uti": "2015-02-24 18:02:19.987",
            "cti": "2015-02-24 18:02:19.987"
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 119,
        "error": 11,
        "user": "admin",
        "ktime": 1424793662198,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 35,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": ["Volume must be between 1 and 9223372036854775807"]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 119,
        "error": 9,
        "user": "admin",
        "ktime": 1424793662198,
        "kmessage": "Price tunnel for BIO\/REGS is [0.2916, 0.3944]",
        "longid": 0,
        "csq": 1
    }
}

4.19. REQUEST UPDATE

Sends request updates to client applications.

Command ID

120

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

OrderRequestDto

Error Payload

OrderRequestDto

This message is sent by the server when an order request passes through different stages on its way towards the exchange. The payload of this message always contains the most up-to-date version of the original request data.

The description of the typical request flow can be found in the ArenaXT Common Types chapter.

4.19.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have an OrderRequestDto payload and a message describing the circumstances under which the request update took place.

Note
The structure of OrderRequestDto is detailed in the ArenaXT Common Types chapter.
Error Response Payload

Error messages will also have an OrderRequestDto payload so that the client can identify the request which failed.

4.19.2. Constants and Enumerations

All enumerations related to this command are described in the ArenaXT Common Types chapter.

4.19.3. Sample Messages

Response
{
    "bm": {
        "pid": 120,
        "user": "admin",
        "ktime": 1424860226566,
        "kmessage": "Cancel order request 16.850 sent to exchange (sell 300 SIF3\/REGS\/BVB at 0,1010 for account House)",
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "d.OrderRequestDto",
            "id": 16850,
            "origId": 62613,
            "status": 2,
            "type": -1,
            "iacc": "House",
            "diffSize": 0,
            "value": "0.000000",
            "diffValue": "0.000000",
            "fee": "0.000000",
            "diffFee": "0.000000",
            "exc": "BVB",
            "sym": "SIF3",
            "mkt": "REGS",
            "ver": 0,
            "tpa": 1,
            "sde": 2,
            "trm": 1,
            "opd": 20150225,
            "clr": 2,
            "std": 0,
            "stt": 1,
            "acc": 8000215,
            "prc": "0.101000",
            "tgp": "0.000000",
            "siz": 300,
            "dcv": 0,
            "ref": "",
            "nmb": 7521298,
            "tms": "2015-02-25 12:29:06.306",
            "osq": 21156465,
            "ssl": 0,
            "rcd": 0,
            "ini": "admin",
            "uui": "admin",
            "uti": "2015-02-25 12:30:26.564",
            "cti": "2015-02-25 12:30:26.49"
        }
    }
}
Response with error
{
    "bm": {
        "pid": 120,
        "error": 7,
        "user": "admin",
        "ktime": 1424860226566,
        "kmessage": "Connection with the exchange is interrupted",
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "d.OrderRequestDto",
            "id": 16845,
            "origId": 61893,
            "status": 2,
            "type": -1,
            "iacc": "House",
            "diffSize": 0,
            "value": "0.000000",
            "diffValue": "0.000000",
            "fee": "0.000000",
            "diffFee": "0.000000",
            "exc": "BVB",
            "sym": "STZ",
            "mkt": "REGS",
            "ver": 0,
            "tpa": 1,
            "sde": 2,
            "trm": 1,
            "opd": 20150225,
            "clr": 2,
            "std": 0,
            "stt": 1,
            "acc": 8000215,
            "prc": "0.482000",
            "tgp": "0.000000",
            "siz": 200,
            "dcv": 0,
            "ref": "added by arena fix client",
            "nmb": 7508646,
            "tms": "2015-02-25 09:57:05.179",
            "osq": 21130863,
            "ssl": 0,
            "rcd": 0,
            "ini": "admin",
            "uui": "admin.horia",
            "uti": "2015-02-25 10:41:11.373",
            "cti": "2015-02-25 09:58:28.161"
        }
    }
}

4.20. ORDER UPDATE

Sends order confirmations from the exchange to the client applications.

Command ID

121

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

InternalOrderDto

Error Payload

n/a

This message is sent by the server when an order is processed by the exchange (either accepted, updated, filled or removed).

Note
ORDER UPDATE messages might be related to an user-initiated request or might be stand-alone confirmations/updates related to orders created through a different medium.

4.20.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have an InternalOrderDto payload, detailed below, and a message describing the circumstances under which the order update took place.

Table 72. The structure of InternalOrderDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

bok

int

-

-

Enumeration

Order book

brk

String

0

10

-

Trading member code

ccy

String

3

3

-

Currency

clr

int

-

-

-

Clearing term

csq

long

-

-

-

Generated sequence

cqy

long

-

-

-

Accumulated executed quantity

dcv

long

-

-

-

Disclosed volume

eft

Timestamp

-

-

-

Effective time

exc

String

1

5

-

Exchange code

ewf

int

-

-

-

Execution Responsibility Code

eal

String

1

1

Y,N,-

Execution Responsibility Algo

dea

String

1

1

Y,N,-

DEA

fee

decimal

-

-

-

Order fee

grs

int

-

-

Enumeration

Gross settlement indicator

hdi

long

-

-

Enumeration

Hidden indicator

hdv

long

-

-

-

Hidden volume

iacc

String

0

11

-

Trading account

iaccn

String

-

-

-

Full name of the account holder

id

long

-

-

-

Order number, as assigned by the brokerage server (internal ID)

iini

String

0

20

-

Initiator user

ind

int

-

-

Enumeration

Indicative quote

isiz

long

-

-

-

Initial order size

itrd

long

-

-

-

Last trade number (internal ID)

iuui

String

0

20

-

Updater user

iwf

int

-

-

-

Investment Decision Code

ial

String

1

1

Y,N,-

Investment Decision Algo

lastPx

decimal

-

-

-

Last trade price

lastVol

long

-

-

-

Last trade volume

lnk

int

-

-

-

Order link (for quotes)

lut

Timestamp

-

-

-

Local update time

mkp

int

-

-

Enumeration

Market priority flag

mkt

String

1

20

-

Market code

nmb

int

-

-

-

Order number, as assigned by the exchange (external ID)

odt

int

-

-

Enumeration

Order type

opd

int

-

-

Date in YYYYMMDD format (for GTD orders) or 0 (for open orders)

Expiration date

prc

decimal

-

-

-

Order price

prt

int

-

-

Enumeration

Price type

ref

String

0

40

-

Reference (comments)

sde

int

-

-

Enumeration

Order side

shv

long

-

-

-

Display volume

siz

long

-

-

-

Order size

ssl

int

-

-

Enumeration

Short sell indicator

std

int

-

-

Date in YYYYMMDD format

Settlement date

sts

int

-

-

Enumeration

Order status

stt

int

-

-

Enumeration

Settlement type

sty

String

1

40

-

Symbol type

sym

String

1

20

-

Symbol code

tgp

decimal

-

-

-

Trigger price

tob

String

0

20

-

To external broker code

tou

String

0

20

-

To external user code

tpa

int

-

-

Enumeration

Trigger type

trd

int

-

-

-

Last trade number (external ticket)

trm

int

-

-

Enumeration

Order term

uti

Timestamp

-

-

-

Last update time

uty

int

-

-

Enumeration

Update type

value

decimal

-

-

-

Order value

ver

int

-

-

Enumeration

Volume restriction

acc

int

-

-

-

External account

act

int

-

-

Enumeration

External account type

bka

String

0

40

-

Settlement bank account

bnk

String

0

40

-

Settlement bank code

diffFee

decimal

-

-

-

Difference of fee to be applied

diffSize

long

-

-

-

Difference of volume to be applied

diffValue

decimal

-

-

-

Difference of value to be applied

ini

String

0

20

-

Initiator user id

mbr

String

0

10

-

Clearing member code

osq

long

-

-

-

Order audit sequence

rgr

int

-

-

Enumeration

External registry operation

uui

String

0

20

-

Updater user id

uws

String

0

15

-

Change location

Note
The fields in italics are not relevant in client context and can be ignored by the client application.
Error Response Payload

This command will never fail on the server side.

4.20.2. Constants and Enumerations

Enumerations

Below are the descriptions of some of the enumerations used for this command. Other enumerations are described in the ArenaXT Common Types chapter, since they are shared by InternalOrderDto and OrderRequestDto types.

Table 73. External Account Type

InternalOrderDto.act

Description

0

Not available

1

Client

2

Financial

3

House

4

Staff

5

Insider

6

Mixed

Table 74. Gross Settlement Indicator

InternalOrderDto.grs

Description

0

Net settlement

1

Gross settlement

Table 75. Hidden Order Flag

InternalOrderDto.hdi

Description

-1

Hidden order

0

Regular order (not hidden)

Table 76. Indicative Order Flag

InternalOrderDto.ind

Description

0

Firm order (not indicative)

1

Indicative order

Table 77. Market Priority Indicator

InternalOrderDto.mkp

Description

0

No priority

1

Market priority

2

Market priority (unpriced)

Table 78. Order Book Indicator

InternalOrderDto.bok

Description

1

Regular order book

2

Special order book

3

Contingent order book

Table 79. Order Status

InternalOrderDto.sts

Description

0

Inactive

1

Active

2

Suspended

Table 80. Order Type

InternalOrderDto.odt

Description

1

Order

2

Cross-order

3

Quote

4

Deal

5

Market-order

Table 81. Price Type

InternalOrderDto.prt

Description

0

Not applicable

1

Market price

2

Unpriced

3

Limit price

Table 82. Registry Link Indicator

InternalOrderDto.rgr

Description

0

Not linked

1

Linked with registry

Table 83. Update Type

InternalOrderDto.uty

Description

-1

Pending activation

0

Deleted

1

New

2

Changed

3

Filled

4

Rejected

5

Confirmed

6

Released

7

Suspended

8

Activated

9

Rejected / Fill-or-kill

10

Rejected / Odd-lot fill-or-fill

11

Rejected / Out of term

12

Rejected / Out of price tunel

13

Rejected / Cross account

14

New order request rejected

15

Cancel request rejected

16

Replace request rejected

17

Update request rejected (MM order)

18

Cancel request rejected (MM order)

4.20.3. Sample Messages

Response
{
    "bm": {
        "pid": 121,
        "user": "admin",
        "ktime": 1424861574538,
        "kmessage": "Order 62.699 was replaced (buy 200 EPT\/REGS\/BVB at 0,0299 for account House)",
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "d.InternalOrderDto",
            "id": 62699,
            "iacc": "House",
            "itrd": 0,
            "isiz": 200,
            "iuui": "admin",
            "iini": "RIVER",
            "lastVol": 0,
            "lastPx": 0,
            "diffSize": -100,
            "value": "5.980000",
            "diffValue": "-2.990000",
            "fee": "0.000000",
            "diffFee": "0.000000",
            "sts": 1,
            "ind": 0,
            "hdi": 0,
            "ver": 0,
            "tpa": 1,
            "bok": 1,
            "hdv": 0,
            "nmb": 7522921,
            "csq": 16851,
            "lnk": 0,
            "eft": "2015-02-25 12:52:10.842",
            "sde": 1,
            "trm": 1,
            "opd": 20150225,
            "odt": 1,
            "rgr": 0,
            "exc": "BVB",
            "sym": "EPT",
            "sty": "SHARE",
            "mkt": "REGS",
            "clr": 2,
            "std": 0,
            "stt": 1,
            "brk": "I7",
            "mbr": "I7",
            "trd": 0,
            "acc": 8000215,
            "act": 3,
            "mkp": 0,
            "tob": "",
            "tou": "",
            "prc": 0.0299,
            "tgp": "0.000000",
            "siz": 200,
            "dcv": 0,
            "shv": 0,
            "bnk": "",
            "bka": "",
            "grs": 0,
            "ref": "added by arena fix client",
            "uty": 2,
            "uti": "2015-02-25 12:52:55.037",
            "uui": "UI7GW01",
            "ini": "UI7FIX01",
            "ssl": 0,
            "prt": 3,
            "lut": "2015-02-25 12:52:54.536",
            "osq": 21159266,
            "cqy": 0,
        }
    }
}

4.21. TRADE

Sends trade reports from the exchange to the client applications.

Command ID

122

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

InternalTradeDto

Error Payload

n/a

This message is sent by the server when an order is executed (filled) at the exchange.

4.21.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have an InternalTradeDto payload, detailed below, and a message describing the trade that took place.

Table 84. The structure of InternalTradeDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

ald

int

-

-

Enumeration

Allocated trade indicator

alv

long

-

-

-

Allocated volume

aqval

decimal

-

-

Always sent as 0 for Buy trades

The acquisition value of the instruments, computed based on the VWAP of the instrument position, effective at the time the trade was registered

ava

decimal

-

-

-

Allocated value

brk

String

0

10

-

Trading member code

cls

String

0

10

Enumeration

Instrument class

clt

int

-

-

Enumeration

Settlement status

clv

long

-

-

-

Cleared volume

din

int

-

-

Enumeration

Deal indicator

dtp

decimal

-

-

-

Dirty price

exc

String

1

5

-

Exchange code

ext

int

-

-

Enumeration

External trade flag

fal

int

-

-

Enumeration

For allocation indicator

fee

decimal

-

-

-

Initial fee value

ffee

decimal

-

-

-

Final fee value

foe

int

-

-

Enumeration

First execution of the associated order

fst

int

-

-

Enumeration

For settlement indicator

grs

int

-

-

Enumeration

Gross settlement indicator

iacc

String

0

11

-

Trading account

iaccn

String

-

-

-

Full name of the account holder

id

long

-

-

-

Trade number, as assigned by the brokerage server (internal ID)

iord

long

-

-

-

Related order number (internal ID)

iusr

String

0

20

-

Internal user

lut

Timestamp

-

-

-

Local update time

mkt

String

1

20

-

Market code

ord

int

-

-

-

Related order number (external ID)

oref

String

0

40

-

Order reference

otk

int

-

-

-

Old ticket

prc

decimal

-

-

-

Clean price

ref

String

0

40

-

Reference (comments)

sde

int

-

-

Enumeration

Trade side

siz

long

-

-

-

Trade size

ssl

int

-

-

Enumeration

Short sell indicator

std

int

-

-

Date in YYYYMMDD format

Settlement date

sts

int

-

-

Enumeration

Trade status

sty

String

0

40

-

Symbol type

sym

String

1

20

-

Symbol code

tck

int

-

-

-

Trade ticket, as assigned by the exchange (external ticket)

tcs

int

-

-

-

Clearing sequence

trt

Timestamp

-

-

-

Trade time

tss

int

-

-

-

Allocation sequence

uty

int

-

-

Enumeration

Update type

val

decimal

-

-

-

Clearing value

vlt

decimal

-

-

-

Trading value

ccy

String

3

3

-

Clearing currency

neg

String

1

1

A,N,1,2,3-

Negotiated trade flag

alg

String

1

1

Y,N,-

Algo trade flag

acc

int

-

-

-

External account

act

int

-

-

Enumeration

External account type

bka

String

0

40

-

Settlement bank account

bnk

String

0

40

-

Settlement bank code

feeValue

decimal

-

-

-

Remaining fee value

grp

int

-

-

Enumeration

Group account

ini

String

0

20

-

Initiator user id

mbr

String

0

10

-

Clearing member code

ordValue

decimal

-

-

-

Remaining order value

osq

long

-

-

-

Order audit sequence

uid

String

0

20

-

Updater user id

Note
The fields in italics are not relevant in client context and can be ignored by the client application.
Error Response Payload

This command will never fail on the server side.

4.21.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 85. Allocation Indicator

InternalTradeDto.fal InternalTradeDto.ald

Description

0

Not for allocation / Not allocated

1

For allocation / Allocated

Table 86. First Order Execution Indicator

InternalTradeDto.foe

Description

0

No, not the first execution

1

Yes, the trade is the first execution of the associated order

Table 87. For Settlement Indicator

InternalTradeDto.fst

Description

0

Not for settlement

1

For settlement

Table 88. Settlement Status

InternalTradeDto.clt

Description

0

Not cleared (not settled) / Pending

1

Cleared (settled)

Table 89. Deal Indicator

InternalTradeDto.din

Description

0

Not deal

1

Deal

Table 90. External Account Type

InternalTradeDto.act

Description

1

Client

2

Financial

3

House

4

Staff

5

Insider

6

Mixed

Table 91. External Trade Indicator

InternalTradeDto.ext

Description

0

Regular Trade

1

External Trade

Table 92. Group Account Indicator

InternalTradeDto.grp

Description

0

Not group account

1

Group account

Table 93. Gross Settlement Indicator

InternalTradeDto.grs

Description

0

Net settlement

1

Gross settlement

Table 94. Trade Side

InternalTradeDto.sde

Description

1

Buy

2

Sell

Table 95. Short Sell Indicator

InternalTradeDto.ssl

Description

0

Not short sell

1

Short sell

2

Market-making short sell

Table 96. Symbol Class Name

InternalTradeDto.cls

Description

share

Share

future

Future

bond

Bond

bill

Bill

Table 97. Trade Status

InternalTradeDto.sts

Description

0

Inactive

1

Active

Table 98. Update Type

InternalTradeDto.uty

Description

0

Deleted

1

New

2

Changed

3

Allocated

4

Cleared

5

Deallocated

6

Discreetly cleared

4.21.3. Sample Messages

Response
{
    "bm": {
        "pid": 122,
        "user": "admin",
        "ktime": 1424862637747,
        "kmessage": "Trade 58.978 confirmed (buy 100 CGC\/REGS\/BVB at 0,0169 for account House)",
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "d.InternalTradeDto",
            "id": 58978,
            "iord": 0,
            "iacc": "House",
            "iusr": "RIVER",
            "sym": "CGC",
            "exc": "BVB",
            "mkt": "REGS",
            "oref": "",
            "ordValue": 0,
            "feeValue": 0,
            "ext": 0,
            "sty": "SHARE",
            "cls": "share",
            "sde": 1,
            "sts": 1,
            "tss": 0,
            "tcs": 0,
            "tck": 2307038,
            "trt": "2015-02-25 13:10:38.195",
            "prc": "0.016900",
            "dtp": 0.0169,
            "siz": 100,
            "val": "1.6900",
            "fee": 0,
            "vlt": "1.6900",
            "brk": "I7",
            "mbr": "I7",
            "acc": 8000215,
            "act": 3,
            "grp": 0,
            "alv": 0,
            "ava": 0,
            "clv": 0,
            "ord": 7367811,
            "uid": "UI7FIX01",
            "ini": "UI7FIX01",
            "bnk": "",
            "bka": "",
            "std": 20150227,
            "din": 0,
            "fst": 1,
            "clt": 0,
            "grs": 0,
            "fal": 0,
            "ald": 0,
            "ref": "",
            "uty": 1,
            "ssl": 0,
            "otk": 0,
            "lut": "2015-02-25 13:10:37.746",
            "osq": 21161458,
            "ccy": "EUR",
            "foe": false
        }
    }
}

4.22. UNSUBSCRIBE L2

Requests the server to stop sending l2 market data updates for the specified symbol-market.

Command ID

127

Initiated via

Real-time connection

Initiated by

Client

Request Payload

GetL2Data

Response Payload

GetL2Data

Error Payload

no payload at all, or ResultPage<string>

After the command <<L2 DATA SNAPSHOT>> (ID 113) is initiated, the server starts sending <<L2 DATA UPDATE>> (ID 114) messages as new events occur on the exchange. The UNSUBSCRIBE L2 command instructs the server to stop sending these updates.

4.22.1. Message Payloads

Request Payload

Requests must contain the GetL2Data payload, detailed below.

Table 99. The structure of GetL2Data type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.GetL2Data

The name of the payload object type

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

market

String

1

20

-

Market code

Response Payload

For successful requests, the server will send a response with a payload having the same type and content as the request.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.22.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.22.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.GetL2Data",
            "exchange": "BVB",
            "symbol": "ATB",
            "market": "REGS"
        },
        "pid": 127,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 127,
        "user": "admin",
        "sessionId": "1234567890",
        "ktime": 1424706251702,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.GetL2Data",
            "exchange": "BVB",
            "symbol": "ATB",
            "market": "REGS"
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 127,
        "error": 11,
        "user": "admin",
        "ktime": 1424706251702,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Exchange code is empty"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 127,
        "error": 1,
        "user": "admin",
        "ktime": 1424706251702,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

4.23. CHANGE PIN

Requests the change of the trading password (PIN) for the logged in user.

Command ID

136

Initiated via

Real-time connection

Initiated by

Client

Request Payload

ChangePIN

Response Payload

none

Error Payload

no payload at all, or ResultPage<string>

4.23.1. Message Payloads

Request Payload

Requests must contain the ChangePIN payload, detailed below.

Table 100. The structure of ChangePIN type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.ChangePIN

The name of the payload object type

oPin

String

4

10

-

The current PIN

nPin

String

4

10

-

The new PIN

cPin

String

4

10

-

Confirmation of the new PIN

Response Payload

For successful requests, a response with no payload will be sent. The response will contain a confirmation message (in the kmessage field) which the client application can present to the end-user as a confirmation of the change.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent. The client application can use the error message (from the kmessage field) to inform the end-user about the failure.

4.23.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.23.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ChangePIN",
            "oPin": "1234",
            "nPin": "4321",
            "cPin": "4321"
        },
        "pid": 136,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 136,
        "user": "admin",
        "ktime": 1423838683777,
        "kmessage": "PIN changed",
        "longid": 0,
        "csq": 1
    }
}
Response with validation error
{
    "bm": {
        "pid": 136,
        "error": 11,
        "user": "admin",
        "ktime": 1423838683777,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 2,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "PIN must be not null.",
                    "PIN must be between 4 and 10 characters."
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 136,
        "error": 5,
        "user": "admin",
        "ktime": 1423838683777,
        "kmessage": "Wrong PIN.",
        "longid": 0,
        "csq": 1
    }
}

4.24. NOTIFICATION MESSAGE

Sends notifications to client applications.

Command ID

155

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

NotificationPayload

Error Payload

n/a

4.24.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have a NotificationPayload content with the following structure.

Table 101. The structure of NotificationPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

source

String

-

-

-

The message initiator

txt

String

-

-

-

The message body

url

String

-

-

Usually empty

A related URL which may be accessed by the end-user.

destination

String

-

-

May be empty

The destination of the message

Note
The fields in italics are not relevant in client context and can be ignored by the client application.
Error Response Payload

This command will never fail on the server side.

4.24.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.24.3. Sample Messages

Response
{
    "bm": {
        "pid": 155,
        "user": "admin",
        "ktime": 1234567890,
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "p.NotificationPayload",
            "source": "system",
            "txt": "symbolmarket record:[symbol=TEL][market=POF] status changed to PreOpened",
            "url": ""
        }
    }
}

4.25. XAP CONNECTED

Informs the client applications that the connection with an exchange was established.

Command ID

184

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

GenericIoPayload

Error Payload

n/a

4.25.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have a GenericIoPayload content specifying the code of the exchange which became online. The structure of the GenericIoPayload type is detailed in ArenaXT Common Types chapter.

Important
The client application must reinitialize itself after receiving this command.
Error Response Payload

This command will never fail on the server side.

4.25.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.25.3. Sample Messages

Response
{
    "bm": {
        "pid": 184,
        "ktime": 1424165396847,
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "p.GenericIoPayload",
            "content": {
                "@class": "string",
                "$": "BVB"
            }
        }
    }
}

4.26. XAP DISCONNECTED

Informs the client applications that the connection with an exchange has been lost or cannot be established.

Command ID

185

Initiated via

Real-time connection

Initiated by

Server

Request Payload

n/a

Response Payload

GenericIoPayload

Error Payload

n/a

When the server attempts to connect to an offline exchange and it cannot establish a connection, a new XAP DISCONNECTED message is generated, even if the clients have already been informed about the disconnected state. It is, therefore, not unusual for a client application to receive multiple such messages during the time the exchange is offline.

4.26.1. Message Payloads

Request Payload

This message is initiated by the server. The client application is not allowed to initiate it.

Response Payload

Messages sent by the server will always have a GenericIoPayload content specifying the code of the exchange which became offline. The structure of the GenericIoPayload type is detailed in ArenaXT Common Types chapter.

Error Response Payload

This command will never fail on the server side.

4.26.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.26.3. Sample Messages

Response
{
    "bm": {
        "pid": 185,
        "ktime": 1424165396847,
        "longid": 0,
        "csq": -1,
        "payload": {
            "@class": "p.GenericIoPayload",
            "content": {
                "@class": "string",
                "$": "BVB"
            }
        }
    }
}

4.27. CHANGE SUBSCRIPTION FILTERING

Requests the server to change the ticker filtering mode for the current user.

Command ID

316

Initiated via

Real-time connection

Initiated by

Client or Server

Request Payload

SetUserField

Response Payload

SetUserField

Error Payload

no payload at all, or ResultPage<string>

This command changes what L1 market data updates are delivered to the client application. When filtering is enabled, the client will receive only tickers related to the watched symbols. Conversely, when filtering is disabled, the client will receive tickers for all existing symbols.

This command can also be initiated by the server.

4.27.1. Message Payloads

Request Payload

Requests must contain the SetUserField payload, detailed below.

Table 102. The structure of SetUserField type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.SetUserField

The name of the payload object type

user

String

1

20

-

The code of the affected user

field

String

1

20

Constant value flts

The name of the field representing the filtering mode

value

String

1

20

Enumeration

Filtering mode

Response Payload

For successful requests, the server will send a response with a payload having the same type and content as the request.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.27.2. Constants and Enumerations

Constants

The following fields will always have a constant value, so if the client is using them for this command, it should initialize them with the constant value from this table.

Field

Description

SetUserField.field

flts

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 103. Filtering mode

SetUserField.value

Description

true

Filtering mode enabled

false

Filtering mode disabled

4.27.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.SetUserField",
            "user": "admin",
            "field": "flts",
            "value": "false"
        },
        "pid": 316,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 316,
        "user": "admin",
        "ktime": 1424178748554,
        "kmessage": "Ticker filtering for admin has been disabled.",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.SetUserField",
            "user": "admin",
            "field": "flts",
            "value": "false"
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 316,
        "error": 11,
        "user": "admin",
        "ktime": 1424178748554,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Field value must be between 1 and 20 characters"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 316,
        "error": 15,
        "user": "admin",
        "ktime": 1424178748554,
        "kmessage": "User alex does not exist.",
        "longid": 0,
        "csq": 1
    }
}

4.28. ADD TEMP SUBSCRIPTION

Requests the server to send level 1 market data updates for the specified unwatched symbol.

Command ID

319

Initiated via

Real-time connection

Initiated by

Client

Request Payload

Subscription

Response Payload

ResultPage<L1DataDto>

Error Payload

no payload at all, or ResultPage<string>

This command is similar to [ADD SUBSCRIPTION] command with only one difference: it does not mark the specified symbol as watched. Therefore, after issuing this command, the current user will be subscribed for level 1 market data updates related to the specified symbol, but this subscription will last only during the client’s session. When the client application logs in again, it will not receive any market data updates and it must issue this command again to start receiving them.

Note
The response of L1 DATA SNAPSHOT command contains only the market data for watched symbols. If a client application needs the L1 market data for an unwatched symbol, it has two options: either mark the symbol as watched and subscribe for related L1 updates (through [ADD SUBSCRIPTION] command), or temporary subscribe for related L1 updates only, without marking the symbol as watched (through [ADD TEMP SUBSCRIPTION] command).

4.28.1. Message Payloads

Request Payload

Requests must contain the Subscription payload, detailed below.

Table 104. The structure of Subscription type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.Subscription

The name of the payload object type

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

Symbol code

Response Payload

For successful requests, the server will send a response with a ResultPage<L1DataDto> payload, containing L1 market data related to the requested symbol. The client application must add the L1DataDto objects to its own snapshot of market data and process them the same way it does for <<L1 DATA SNAPSHOT>> command (ID 110).

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.28.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

4.28.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.Subscription",
            "exchange": "BVB",
            "symbol": "FP"
        },
        "pid": 319,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 319,
        "user": "admin",
        "ktime": 1423841871786,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.L1DataDto": [{
                    "exchange": "BVB",
                    "market": "REGS",
                    "symbol": "FP",
                    "pkMarket": 1,
                    "smkStatus": 1,
                    "efectiveDate": 20150210,
                    "tradesNo": 165,
                    "totalValue": "16774.550000",
                    "openPrice": "0.843000",
                    "lastPrice": "0.860000",
                    "averagePrice": "0.856000",
                    "lowPrice": "0.843000",
                    "highPrice": "0.861000",
                    "bestBuyPrice": "0.855000",
                    "bestBuyVolume": 900,
                    "bestSellPrice": "0.860000",
                    "bestSellVolume": 700,
                    "lastVolume": 100,
                    "fixingPrice": "0.000000",
                    "fixingVolume": 0,
                    "crtRefPrice": "0.000000",
                    "crtSettle": "0.000000",
                    "direction": 1,
                    "uti": "2015-02-10 18:27:33.635",
                    "openInterest": 0,
                    "basis": 0,
                    "change": 0,
                    "changePercent": 0,
                    "averageChange": 0,
                    "averageChangePercent": 0,
                    "settleChange": 0,
                    "settleChangePercent": 0,
                    "totalVolume": 19600
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 319,
        "error": 11,
        "user": "admin",
        "ktime": 1423841871786,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": ["Symbol code is empty"]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 319,
        "error": 6,
        "user": "admin",
        "ktime": 1423841871786,
        "kmessage": "Market data is unavailable for FP",
        "longid": 0,
        "csq": 1
    }
}

4.29. APPROVE ORDER REQUEST

Approves a pending order request whose Ready For Exchange status is Pending Approval.

Command ID

323

Initiated via

Real-time connection

Initiated by

Client

Request Payload

ForceResendRequestPayload

Response Payload

OrderRequestDto

Error Payload

no payload at all, or ResultPage<string>

This command approves an existing order request that awaits further approval.

If the command is accepted by the server, the client application will receive first a confirmation and then updated information about the approved request in the form of <<REQUEST UPDATE>> messages (ID 120). After the request is processed at the exchange side, the server will send the result in the form of <<ORDER UPDATE>> messages (ID 121).

4.29.1. Message Payloads

Request Payload

Requests must contain the ForceResendRequestPayload payload, detailed below.

Table 105. The structure of ForceResendRequestPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.ForceResendRequestPayload

The name of the payload object type

requestId

long

-

-

Must be positive

The request id that is to be approved

Response Payload

For valid requests which are successfully processed, a response with an OrderRequestDto payload will be sent by the server.

Note
The structure of OrderRequestDto is detailed in the ArenaXT Common Types chapter.
Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.29.2. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ForceResendRequestPayload",
            "requestId": 111111
        },
        "pid": 323,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 323,
        "user": "admin",
        "ktime": 1424790483398,
        "kmessage": "Add order request 469,262 approved (sell 1 BIO\/REGS\/BVB at 0.3630 for account A000000002)",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.OrderRequestDto",
            "id": 469262,
            "origId": 0,
            "status": 1,
            "type": 1,
            "iacc": "A000000002",
            "diffSize": 0,
            "value": "0.3630",
            "diffValue": 0,
            "fee": "0.000000",
            "diffFee": 0,
            "exc": "BVB",
            "sym": "BIO",
            "mkt": "REGS",
            "ver": 0,
            "tpa": 1,
            "sde": 2,
            "trm": 1,
            "opd": 0,
            "clr": 2,
            "std": 0,
            "stt": 1,
            "acc": 8000067,
            "prc": "0.3630",
            "tgp": 0,
            "siz": 1,
            "dcv": 0,
            "ref": "",
            "nmb": 0,
            "tms": "1970-01-01 02:00:00.0",
            "osq": -1,
            "ssl": 0,
            "rcd": 0,
            "ini": "admin",
            "uui": "admin",
            "uti": "2015-02-24 11:37:47.032",
            "cti": "2015-02-24 11:37:47.032"
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 323,
        "error": 11,
        "user": "admin",
        "ktime": 1424790483398,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": ["Volume must be between 1 and 9223372036854775807"]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 323,
        "error": 8,
        "user": "admin",
        "ktime": 1424790483398,
        "kmessage": "No external account found for A000000002 to ATB@BVB",
        "longid": 0,
        "csq": 1
    }
}

4.30. CANCEL PENDING ORDER REQUEST

Cancels a pending order request whose Ready For Exchange status is not Yes.

Command ID

327

Initiated via

Real-time connection

Initiated by

Client

Request Payload

ForceDeleteRequest

Response Payload

OrderRequestDto

Error Payload

no payload at all, or ResultPage<string>

This command cancels an existing order request that has not already been sent to the exchange.

If the command is accepted by the server, the client application will receive an acknowledgement with an OrderRequestDto payload.

4.30.1. Message Payloads

Request Payload

Requests must contain the ForceDeleteRequest payload, detailed below.

Table 106. The structure of ForceDeleteRequest type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.ForceDeleteRequest

The name of the payload object type

requestId

long

-

-

Must be positive

The request id that is to be approved

reason

String

0

40

-

Free text

pin

String

0

40

-

Trading password (PIN)

Response Payload

For valid requests which are successfully processed, a response with an OrderRequestDto payload will be sent by the server.

Note
The structure of OrderRequestDto is detailed in the ArenaXT Common Types chapter.
Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

4.30.2. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ForceDeleteRequest",
            "requestId": 111111
        },
        "pid": 327,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 327,
        "user": "admin",
        "ktime": 1424790483398,
        "kmessage": "Add order request 469,262 removed (sell 1 BIO\/REGS\/BVB at 0.3630 for account A000000002)",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.OrderRequestDto",
            "id": 469262,
            "origId": 0,
            "status": 1,
            "type": 1,
            "iacc": "A000000002",
            "diffSize": 0,
            "value": "0.3630",
            "diffValue": 0,
            "fee": "0.000000",
            "diffFee": 0,
            "exc": "BVB",
            "sym": "BIO",
            "mkt": "REGS",
            "ver": 0,
            "tpa": 1,
            "sde": 2,
            "trm": 1,
            "opd": 0,
            "clr": 2,
            "std": 0,
            "stt": 1,
            "acc": 8000067,
            "prc": "0.3630",
            "tgp": 0,
            "siz": 1,
            "dcv": 0,
            "ref": "",
            "nmb": 0,
            "tms": "1970-01-01 02:00:00.0",
            "osq": -1,
            "ssl": 0,
            "rcd": 0,
            "ini": "admin",
            "uui": "admin",
            "uti": "2015-02-24 11:37:47.032",
            "cti": "2015-02-24 11:37:47.032"
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 327,
        "error": 11,
        "user": "admin",
        "ktime": 1424790483398,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": ["Volume must be between 1 and 9223372036854775807"]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 327,
        "error": 8,
        "user": "admin",
        "ktime": 1424790483398,
        "kmessage": "No external account found for A000000002 to ATB@BVB",
        "longid": 0,
        "csq": 1
    }
}

5. ArenaXT HTTPS Commands

Almost all commands sent through HTTPS connections have the same payload (ReportingPayload) and receive the same type of response payload (ResultPage<T>). These commands are generically called report requests, due to the structure of the returned data (resembling a report).

The structure of the request and response payloads for report commands are detailed in the [ArenaXT Common Types] chapter.

Below are all commands which a client can send through the HTTPS connections.

5.1. GET USER ACCOUNTS

Requests the list of trading accounts the current end-user has access to.

Command ID

123

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

none

Response Payload

ResultPage<InternalAccountDto>

Error Payload

none

5.1.1. Message Payloads

Request Payload

No payload is required to be sent in the request.

Response Payload

For requests which are successfully processed, a response with a ResultPage<InternalAccountDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<InternalAccountDto>, described below.

Table 107. The structure of Lines<InternalAccountDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.InternalAccountDto

Array of InternalAccountDto objects

-

-

-

Array of objects

The structure of an InternalAccountDto object is detailed below.

Table 108. The structure of InternalAccountDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

acc

String

0

11

-

Account ID

alias

String

0

20

-

Alternative account name

nam

String

0

40

-

Full name of the account holder

nin

String

3

20

-

ID of the account holder

sts

int

-

-

Enumeration

Account status

typ

int

-

-

Enumeration

Account type

ccy

String

-

-

-

Account currency

nii

int

-

-

-

Internal ID

ref

String

0

40

-

Reference (comments)

uti

Timestamp

0

255

-

Last update time

uty

int

-

-

-

Update type

uui

String

0

20

-

Updater user id

uws

String

0

15

-

Workstation

Note
The fields in italics are not relevant in client context and can be ignored by the client application.

The data returned for this command is not paginated on the server side, so all trading accounts will be returned in a single response.

Error Response Payload

For failed requests the server will always return an error with no payload.

5.1.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 109. Account Status

InternalAccountDto.status

Description

1

Opened

3

Locked

4

Closed

Table 110. Account Type

InternalAccountDto.typ

Description

1

Client

2

Financial

3

House

4

Staff

6

Mixed

5.1.3. Sample Messages

Request
{
    "bm": {
        "pid": 123,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 123,
        "user": "admin",
        "ktime": 1423827308535,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "d.InternalAccountDto": [{
                    "acc": "A001",
                    "alias": "",
                    "sts": 1,
                    "nam": "A001",
                    "typ": 1,
                    "nii": 336,
                    "nin": "A001",
                    "ref": "",
                    "uty": 2,
                    "uui": "admin.tests",
                    "uws": "192.168.250.205",
                    "uti": "2015-02-09 12:08:13.903"
                }]
            }
        }
    }
}
Response with error
{
    "bm": {
        "pid": 123,
        "error": 1,
        "user": "admin",
        "ktime": 1423827308535,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.2. GET OUTSTANDING ORDERS

Requests the list of outstanding orders the current end-user has access to.

Command ID

124

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

ReportingPayload

Response Payload

ResultPage<InternalOrderDto>

Error Payload

no payload at all, or ResultPage<string>

5.2.1. Message Payloads

Request Payload

Requests must contain a payload with the type ReportingPayload, detailed in the ArenaXT Common Types chapter.

The parameters field of the payload should contain a Map object with the following entries:

Parameter Key

Parameter Value

iob.iacc

The trading account under which the orders were placed, or * to get orders for all accounts

iob.sym

The code of the symbol for which to get the orders, or * (or empty) to get all orders

iob.sts

The status of the orders, or * to get all orders

iob.sde

The side by which to filter the orders, or * to get all orders

Note
Both the entry keys and the entry values have the type string. Details about the Map type can be found in the ArenaXT Common Types chapter.
Response Payload

For requests which are successfully processed, a response with a ResultPage<InternalOrderDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<InternalOrderDto>, described below.

Table 111. The structure of Lines<InternalOrderDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.InternalOrderDto

Array of InternalOrderDto objects

-

-

-

Array of objects

Note
The structure of an InternalOrderDto object is detailed in the <<_internalorderdto_structure, ORDER UPDATE>> command.

The data returned for this command is paginated on the server side, so the client must verify if more results are available.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

5.2.2. Constants and Enumerations

All enumerations related to this command are described in the ArenaXT Common Types chapter and the <<ORDER UPDATE>> section.

5.2.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ReportingPayload",
            "startPosition": 1,
            "pageSize": 50,
            "parameters": {
                "entry": [{
                    "string": ["iob.iacc","A000000002"]
                },
                {
                    "string": ["iob.sym","BRK"]
                },
                {
                    "string": ["iob.sts","*"]
                },
                {
                    "string": ["iob.sde","*"]
                }]
            }
        },
        "pid": 124,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 124,
        "user": "admin",
        "ktime": 1424687725990,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.InternalOrderDto": [{
                    "id": 184301,
                    "iacc": "A000000002",
                    "iaccn": "ALEXANDRU",
                    "itrd": 0,
                    "isiz": 1,
                    "iuui": "admin",
                    "iini": "admin",
                    "lastVol": 0,
                    "lastPx": "0.000000",
                    "diffSize": 0,
                    "value": "0.135000",
                    "diffValue": "0.000000",
                    "fee": "0.000000",
                    "diffFee": "0.000000",
                    "sts": 1,
                    "ind": 0,
                    "hdi": 0,
                    "ver": 0,
                    "tpa": 1,
                    "bok": 1,
                    "hdv": 0,
                    "nmb": 7350531,
                    "csq": 469261,
                    "lnk": 0,
                    "eft": "2015-02-23 12:35:16.479",
                    "sde": 2,
                    "trm": 1,
                    "opd": 20150223,
                    "odt": 1,
                    "rgr": 0,
                    "exc": "BVB",
                    "sym": "BRK",
                    "sty": "SHARE",
                    "mkt": "REGS",
                    "clr": 2,
                    "std": 0,
                    "stt": 1,
                    "brk": "F4",
                    "mbr": "F4",
                    "trd": 0,
                    "acc": 8000067,
                    "act": 1,
                    "mkp": 0,
                    "tob": "",
                    "tou": "",
                    "prc": "0.135000",
                    "tgp": "0.000000",
                    "siz": 1,
                    "dcv": 0,
                    "shv": 0,
                    "bnk": "",
                    "bka": "",
                    "grs": 0,
                    "ref": "",
                    "uty": 1,
                    "uti": "2015-02-23 12:35:16.479",
                    "uui": "UF4GW1",
                    "ini": "UF4GW1",
                    "ssl": 0,
                    "prt": 3,
                    "lut": "2015-02-23 12:35:16.544",
                    "osq": 20891841
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 124,
        "error": 11,
        "user": "admin",
        "ktime": 1424687725990,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Account must be between 1 and 20 characters"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 124,
        "error": 1,
        "user": "admin",
        "ktime": 1424687725990,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.3. GET DAILY TRADES

Requests the list of trades for the specified trading day.

Command ID

125

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

ReportingPayload

Response Payload

ResultPage<InternalTradeDto>

Error Payload

no payload at all, or ResultPage<string>

5.3.1. Message Payloads

Request Payload

Requests must contain a payload with the type ReportingPayload, detailed in the ArenaXT Common Types chapter.

The parameters field of the payload should contain a Map object with the following entries:

Parameter Key

Parameter Value

tradeDate

The trade date, in YYYY-MM-DD format

itb.iacc

The trading account under which the trades occurred, or * to get trades for all accounts

itb.sym

The code of the symbol for which to get the trades, or * (or empty) to get all trades

itb.sde

The side by which to filter the trades, or * to get all trades

Note
Both the entry keys and the entry values have the type string. Details about the Map type can be found in the ArenaXT Common Types chapter.
Response Payload

For requests which are successfully processed, a response with a ResultPage<InternalTradeDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<InternalTradeDto>, described below.

Table 112. The structure of Lines<InternalTradeDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.InternalTradeDto

Array of InternalTradeDto objects

-

-

-

Array of objects

Note
The structure of an InternalTradeDto object is detailed in the <<_internaltradedto_structure, TRADE>> command.

The data returned for this command is paginated on the server side, so the client must verify if more results are available.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

5.3.2. Constants and Enumerations

All enumerations related to this command are described in the <<TRADE>> section.

5.3.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ReportingPayload",
            "startPosition": 1,
            "pageSize": 50,
            "parameters": {
                "entry": [{
                    "string": ["tradeDate","2015-02-23"]
                },
                {
                    "string": ["itb.iacc","A000000002"]
                },
                {
                    "string": ["itb.sym","BRK"]
                },
                {
                    "string": ["itb.sde","*"]
                }]
            }
        },
        "pid": 125,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 125,
        "user": "admin",
        "ktime": 1424691571682,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.InternalTradeDto": [{
                    "id": 223571,
                    "iord": 184299,
                    "iacc": "A000000002",
                    "iaccn": "ALEXANDRU",
                    "iusr": "admin",
                    "sym": "BRK",
                    "exc": "BVB",
                    "mkt": "REGS",
                    "oref": "",
                    "ordValue": "0.135000",
                    "feeValue": "0.000000",
                    "ext": 0,
                    "sty": "SHARE",
                    "cls": "share",
                    "sde": 1,
                    "sts": 1,
                    "tss": 0,
                    "tcs": 0,
                    "tck": 2279751,
                    "trt": "2015-02-23 12:34:41.592",
                    "prc": "0.135000",
                    "dtp": "0.135000",
                    "siz": 1,
                    "val": "0.135000",
                    "fee": "0.000000",
                    "vlt": "0.135000",
                    "brk": "F4",
                    "mbr": "F4",
                    "acc": 8000067,
                    "act": 1,
                    "grp": 0,
                    "alv": 0,
                    "ava": "0.000000",
                    "clv": 0,
                    "ord": 7350488,
                    "uid": "UF4GW1",
                    "ini": "UF4GW1",
                    "bnk": "",
                    "bka": "",
                    "std": 20150225,
                    "din": 0,
                    "fst": 1,
                    "clt": 0,
                    "grs": 0,
                    "fal": 0,
                    "ald": 0,
                    "ref": "",
                    "uty": 1,
                    "ssl": 0,
                    "otk": 0,
                    "lut": "2015-02-23 12:34:41.651",
                    "osq": 20891767
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 125,
        "error": 11,
        "user": "admin",
        "ktime": 1424691571682,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Account must be between 1 and 20 characters"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 125,
        "error": 1,
        "user": "admin",
        "ktime": 1424691571682,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.4. GET TRADING SUMMARY

Requests a summary of all trades for a period of time.

Command ID

133

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

ReportingPayload

Response Payload

ResultPage<TradingSummaryDto>

Error Payload

no payload at all, or ResultPage<string>

5.4.1. Message Payloads

Request Payload

Requests must contain a payload with the type ReportingPayload, detailed in the ArenaXT Common Types chapter.

The parameters field of the payload should contain a Map object with the following entries:

Parameter Key

Parameter Value

itb.dates

The period start date, in YYYY-MM-DD format

itb.datee

The period end date, in YYYY-MM-DD format

itb.iacc

The trading account for which to get the summary, or * to get trades for all accounts

itb.sym

The code of the symbol for which to get the summary, or * (or empty) to get all trades

Note
Both the entry keys and the entry values have the type string. Details about the Map type can be found in the ArenaXT Common Types chapter.
Response Payload

For requests which are successfully processed, a response with a ResultPage<TradingSummaryDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<TradingSummaryDto>, described below.

Table 113. The structure of Lines<TradingSummaryDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.TradingSummaryDto

Array of TradingSummaryDto objects

-

-

-

Array of objects

The structure of an TradingSummaryDto object is detailed below.

Table 114. The structure of TradingSummaryDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

iacc

String

0

11

-

Trading account

iaccn

String

-

-

-

Full name of the account holder

sym

String

1

20

-

Symbol code

exc

String

1

5

-

Exchange code

mkt

String

1

20

-

Market code

sde

int

-

-

Enumeration

Side

trt

Timestamp

-

-

-

Trading date

prc

decimal

-

-

-

Average price

cnt

int

-

-

-

Number of trades

siz

long

-

-

-

Total volume of trades

val

decimal

-

-

-

Total value of trades

fee

decimal

-

-

-

Total fees

vlt

decimal

-

-

-

Total value of trades (before any rounding)

gain

decimal

-

-

-

Total recorded gain or loss

The data returned for this command is not paginated on the server side, so the client is not required to verify if other results are available.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

5.4.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 115. Side

TradingSummaryDto.sde

Description

1

Buy

2

Sell

5.4.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ReportingPayload",
            "startPosition": 1,
            "pageSize": 50,
            "parameters": {
                "entry": [{
                    "string": ["itb.dates","2016-03-20"]
                },
                {
                    "string": ["itb.datee","2016-03-23"]
                },
                {
                    "string": ["itb.iacc","A000000002"]
                },
                {
                    "string": ["itb.sym","BRK"]
                }]
            }
        },
        "pid": 133,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 133,
        "user": "admin",
        "ktime": 1458809044964,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 2,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.TradingSummaryDto": [{
                    "iacc": "A000000002",
                    "iaccn": "ALEXANDRU",
                    "sym": "BRK",
                    "exc": "BVB",
                    "mkt": "REGS",
                    "sde": 1,
                    "trt": "2016-03-23 00:00:00.0",
                    "prc": 0,
                    "cnt": 0,
                    "siz": 0,
                    "val": 0,
                    "fee": 0,
                    "vlt": 0
                }, {
                    "iacc": "A000000002",
                    "iaccn": "ALEXANDRU",
                    "sym": "BRK",
                    "exc": "BVB",
                    "mkt": "REGS",
                    "sde": 2,
                    "trt": "2016-03-23 00:00:00.0",
                    "prc": "0.27350000000000000000",
                    "cnt": 3,
                    "siz": 2900,
                    "val": "793.150000",
                    "fee": "39.115000",
                    "vlt": "793.150000"
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 133,
        "error": 11,
        "user": "admin",
        "ktime": 1458809044964,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Account must be between 1 and 20 characters"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 133,
        "error": 1,
        "user": "admin",
        "ktime": 1458809044964,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.5. GET SPOT PORTFOLIO

Requests the spot portfolio of the specified trading account.

Command ID

154

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

PortfolioPayload

Response Payload

SpotPortfolioPayload

Error Payload

no payload at all, or ResultPage<string>

5.5.1. Message Payloads

Request Payload

Requests must contain a payload with the type PortfolioPayload, detailed below.

Table 116. The structure of PortfolioPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.PortfolioPayload

The name of the payload object type

acc

String

1

-

-

Trading account

date

int

-

-

Date in YYYYMMDD format

Evaluation date

Response Payload

For requests which are successfully processed, a response with a SpotPortfolioPayload content will be sent by the server.

Table 117. The structure of SpotPortfolioPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

cash

SummaryCashDto

-

-

-

The portfolio summary

positions

Lines<SummarySpotDto>

-

-

-

The portfolio positions

The structure of a SummaryCashDto object is detailed below.

Table 118. The structure of SummaryCashDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

date

int

-

-

Date in YYYYMMDD format

Position date

symbol

String

1

20

-

Currency code

cbl

decimal

-

-

-

Close (current) balance of cash

pbl

decimal

-

-

-

Current balance including pending value

pval

decimal

-

-

-

Total pending cash

fval

decimal

-

-

-

Total frozen cash

ava

decimal

-

-

-

Total available cash

lck

decimal

-

-

-

Total locked cash

tval

decimal

-

-

-

Total value

gain

decimal

-

-

-

Total gain/loss

The type of the positions field from SpotPortfolioPayload is a specialization of the generic type Lines<T> and has the following structure.

Table 119. The structure of Lines<SummarySpotDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.SummarySpotDto

Array of SummarySpotDto objects

-

-

-

Array of objects

The structure of a SummarySpotDto object is detailed below.

Table 120. The structure of SummarySpotDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

date

int

-

-

Date in YYYYMMDD format

Position date

symbol

String

1

20

-

Symbol code

name

String

-

-

-

Symbol name

cbl

long

-

-

-

Close (current) balance of instruments

pbl

long

-

-

-

Current balance including pending volume

prc

decimal

-

-

-

Current instrument price

avg

decimal

-

-

-

Purchase average price

val

decimal

-

-

-

Evaluation value

pl

decimal

-

-

-

Current profit/loss

pvol

long

-

-

-

Pending volume

pval

decimal

-

-

-

Pending value

fvol

long

-

-

-

Frozen volume

fval

decimal

-

-

-

Frozen value

ava

long

-

-

-

Available volume

lck

long

-

-

-

Locked volume

uprc

decimal

-

-

-

Unit price

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

5.5.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

5.5.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.PortfolioPayload",
            "acc": "A000000002",
            "date": "20150223"
        },
        "pid": 154,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 154,
        "user": "admin",
        "ktime": 1424697859671,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.SpotPortfolioPayload",
            "cash": {
                "date": 20150223,
                "symbol": "RON",
                "cbl": "70884.982900",
                "pbl": "70884.847900",
                "pval": "-0.135000",
                "fval": "0.000000",
                "ava": "70884.847900",
                "lck": "0.000000",
                "tval": "130318.188900",
                "gain": "-113.954400"
            },
            "positions": {
                "d.SummarySpotDto": [{
                    "date": 20150223,
                    "symbol": "BCC",
                    "name": "BANCA COMERCIALA CARPATICA SIBIU",
                    "cbl": 990,
                    "pbl": 990,
                    "prc": 0.0754,
                    "avg": "0.000000",
                    "val": "74.6460",
                    "pl": "74.646000",
                    "pvol": 0,
                    "pval": "0.000000",
                    "fvol": 0,
                    "fval": "0.000000",
                    "ava": 990,
                    "lck": 0,
                    "uprc": 0.0754
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 154,
        "error": 11,
        "user": "admin",
        "ktime": 1424697859671,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Account must be between 1 and 20 characters"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 154,
        "error": 1,
        "user": "admin",
        "ktime": 1424697859671,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.6. GET SYMBOL MARKETS

Requests the list of markets each symbol can be traded on.

Command ID

190

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

none

Response Payload

ResultPage<SymbolMarketDto>

Error Payload

none

5.6.1. Message Payloads

Request Payload

No payload is required to be sent in the request.

Response Payload

For requests which are successfully processed, a response with a ResultPage<SymbolMarketDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<SymbolMarketDto>, described below.

Table 121. The structure of Lines<SymbolMarketDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.SymbolMarketDto

Array of SymbolMarketDto objects

-

-

-

Array of objects

The structure of a SymbolMarketDto object is detailed below.

Table 122. The structure of SymbolMarketDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

exchange

String

1

5

-

Exchange code

symbol

String

1

20

-

symbol code

market

String

1

20

-

Market code

orderp

int

-

-

Enumeration

Order permission indicator

pkMarket

int

-

-

Enumeration

Primary market indicator

Note
For some symbols, there are markets on which trading is permitted only under certain circumstances or using only special types of orders. Therefore, for these symbol-markets, the order permission indicator is set to No, so that client applications can know to disallow orders from end-users.

The data returned for this command is not paginated on the server side, so all symbol-markets will be returned in a single response.

Error Response Payload

For failed requests the server will always return an error with no payload.

5.6.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 123. Primary Market Indicator

SymbolMarketDto.pkMarket

Description

0

Secondary market

1

Primary market

Table 124. Order Permission Indicator

SymbolMarketDto.orderp

Description

0

Orders are not permitted

1

Orders are permitted

5.6.3. Sample Messages

Request
{
    "bm": {
        "pid": 190,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 190,
        "user": "admin",
        "ktime": 1423827308557,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 2,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "d.SymbolMarketDto": [{
                    "exchange": "BVB",
                    "market": "REGS",
                    "symbol": "SIF3",
                    "pkMarket": 1,
                    "orderp": 1
                },
                {
                    "exchange": "BVB",
                    "market": "REGS",
                    "symbol": "SIF4",
                    "pkMarket": 1,
                    "orderp": 1
                }]
            }
        }
    }
}
Response with error
{
    "bm": {
        "pid": 190,
        "error": 1,
        "user": "admin",
        "ktime": 1423827308557,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.7. GET FUTURES PORTFOLIO

Requests the futures portfolio of the specified trading account.

Command ID

201

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

PortfolioPayload

Response Payload

FuturesPortfolioPayload

Error Payload

no payload at all, or ResultPage<string>

5.7.1. Message Payloads

Request Payload

Requests must contain a payload with the type PortfolioPayload, detailed below.

Table 125. The structure of PortfolioPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.PortfolioPayload

The name of the payload object type

acc

String

1

-

-

Trading account

date

int

-

-

Date in YYYYMMDD format

Evaluation date

Response Payload

For requests which are successfully processed, a response with a FuturesPortfolioPayload content will be sent by the server.

Table 126. The structure of FuturesPortfolioPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

cash

SummaryMarginDto

-

-

-

The portfolio summary

positions

Lines<SummaryFuturesDto>

-

-

-

The portfolio positions

The structure of a SummaryMarginDto object is detailed below.

Table 127. The structure of SummaryMarginDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

date

int

-

-

Date in YYYYMMDD format

Position date

symbol

String

0

20

-

Currency code

cbl

decimal

-

-

-

Close (current) balance of cash

pl

decimal

-

-

-

Total profit/loss

dpl

decimal

-

-

-

Daily profit/loss

margin

decimal

-

-

-

Total required margin

ava

decimal

-

-

-

Total available cash

pending

decimal

-

-

-

Total pending cash

lock

decimal

-

-

-

Total locked cash

The type of the positions field from FuturesPortfolioPayload is a specialization of the generic type Lines<T> and has the following structure.

Table 128. The structure of Lines<SummaryFuturesDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.SummaryFuturesDto

Array of SummaryFuturesDto objects

-

-

-

Array of objects

The structure of a SummaryFuturesDto object is detailed below.

Table 129. The structure of SummaryFuturesDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

date

int

-

-

Date in YYYYMMDD format

Position date

symbol

String

0

20

-

Symbol code

name

String

-

-

-

Symbol name

cbl

long

-

-

-

Close (current) balance of instruments

prc

decimal

-

-

-

Current instrument price

avg

decimal

-

-

-

Purchase average price

pl

decimal

-

-

-

Current profit/loss

dpl

decimal

-

-

-

Daily profit/loss

margin

decimal

-

-

-

Required margin

exposure

decimal

-

-

-

Exposure

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

5.7.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

5.7.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.PortfolioPayload",
            "acc": "A000000002",
            "date": "20150223"
        },
        "pid": 201,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 201,
        "user": "admin",
        "ktime": 1424700147314,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.FuturesPortfolioPayload",
            "cash": {
                "date": 20150223,
                "symbol": "RON",
                "cbl": "99750.000000",
                "pl": "-250.000000",
                "dpl": "0.000000",
                "margin": "5.000000000000",
                "ava": "99745.000000000000",
                "pending": "0.000000",
                "lock": "0.000000"
            },
            "positions": {
                "d.SummaryFuturesDto": [{
                    "date": 20150223,
                    "symbol": "BVB14DEC",
                    "name": "BVB DEC 2014 FUTURES",
                    "cbl": 100,
                    "prc": "33.500000",
                    "avg": "36.0000",
                    "pl": "-250.000000",
                    "dpl": "0.000000",
                    "margin": "5.000000000000",
                    "exposure": "3350.000000"
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 201,
        "error": 11,
        "user": "admin",
        "ktime": 1424700147314,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Account must be between 1 and 20 characters"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 201,
        "error": 1,
        "user": "admin",
        "ktime": 1424700147314,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.8. GET ACTIVITY

Requests the trading activity for the current end-user.

Command ID

203

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

ReportingPayload

Response Payload

ResultPage<ActivityDto>

Error Payload

no payload at all, or ResultPage<string>

5.8.1. Message Payloads

Request Payload

Requests must contain a payload with the type ReportingPayload, detailed in the ArenaXT Common Types chapter.

The parameters field of the payload should contain a Map object with the following entries:

Parameter Key

Parameter Value

itb.dates

The start date, in YYYY-MM-DD format

itb.datee

The end date, in YYYY-MM-DD format

itb.account

The account for which data is requested, or * to get acctivity for all accounts

Note
Both the entry keys and the entry values have the type string. Details about the Map type can be found in the ArenaXT Common Types chapter.
Response Payload

For requests which are successfully processed, a response with a ResultPage<ActivityDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<ActivityDto>, described below.

Table 130. The structure of Lines<ActivityDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.ActivityDto

Array of ActivityDto objects

-

-

-

Array of objects

The structure of an ActivityDto object is detailed below.

Table 131. The structure of ActivityDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value d.ActivityDto

The name of the payload object type

account

String

0

11

-

Trading account

acctype

String

0

20

Enumeration

Account type

aref

String

0

20

-

Activity reference

atype

String

0

20

Enumeration

Activity type

comment

String

0

40

-

Comments

dir

int

-

-

Enumeration

Activity direction

exch

String

1

5

-

Exchange code

fee

decimal

-

-

-

Fee value

iaccn

String

-

-

-

Full name of the account holder

outi

Timestamp

-

-

-

Operation timestamp

sde

int

-

-

Enumeration

Activity side

symbol

String

1

20

-

Symbol code

text

String

0

200

-

Reference (comments)

usr

String

0

40

-

Initiator user id

value

decimal

-

-

-

Value

volume

long

-

-

-

Volume

id

long

-

-

-

generated identifier

uti

Timestamp

-

-

-

Last update time

wst

String

0

15

-

Workstation

Note
The fields in italics are not relevant in client context and can be ignored by the client application.

The data returned for this command is paginated on the server side, so the client must verify if more results are available.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

5.8.2. Constants and Enumerations

Enumerations

Below are the descriptions of all enumerations used for this command.

Table 132. Account Type

ActivityDto.acctype

Description

CASH

Spot cash

SPOT

Spot instruments

MARGIN

Futures cash

FTRS

Futures instruments

Table 133. Activity Type

ActivityDto.atype

Description

FEE

Fee

TRD

Trade

STLM

Settlement

CASH

Cash

FREEZE

Freeze

LOCK

Lock

NET_VAL

Net Val.

TRAN

Transfer

ORD_NEW

Order New

ORD_CAN

Order Cancel

ORD_RPL

Order Replace

ORD_REJ_NEW

Order Reject New

ORD_REJ_RPL

Order Reject Replace

REQ_NEW

Request New

REQ_CAN

Request Cancel

REQ_RPL

Request Replace

REQ_REJ_NEW

Request Reject New

REQ_REJ_RPL

Request Reject Replace

ADJ_FPOS

Adj. Futures Position

FRZFEE

Freeze Fee

FEESTLM

Fee Settlement

Table 134. Activity Direction

ActivityDto.dir

Description

-1

Out

0

None

1

In

Table 135. Activity Side

ActivityDto.sde

Description

0

None

1

Buy

2

Sell

5.8.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ReportingPayload",
            "startPosition": 1,
            "pageSize": 100,
            "parameters": {
                "entry": [{
                    "string": ["itb.dates", "2015-02-17"]
                },
                {
                    "string": ["itb.datee", "2015-02-17"]
                },
                {
                    "string": ["itb.account", "*"]
                }]
            }
        },
        "pid": 203,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 203,
        "user": "admin",
        "ktime": 1424189822197,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.ActivityDto": [{
                    "id": 899117,
                    "dir": 1,
                    "sde": 1,
                    "atype": "STLM",
                    "aref": 223540,
                    "acctype": "SPOT",
                    "account": 1011667,
                    "iaccn": "TEST HORIA",
                    "symbol": "SNG",
                    "exch": "BVB",
                    "volume": 10,
                    "value": "339.900000",
                    "fee": "0.000000",
                    "comment": "",
                    "usr": "jobagent",
                    "wst": "127.0.0.1",
                    "text": "",
                    "outi": "2015-02-17 12:30:00.326",
                    "uti": "2015-02-17 12:30:00.331"
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 203,
        "error": 11,
        "user": "admin",
        "ktime": 1424189822197,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Account must be between 1 and 20 characters"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 203,
        "error": 1,
        "user": "admin",
        "ktime": 1424189822197,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.9. GET POSITION EVAL

Requests the evaluation of a potential order and the effects it might have on the user’s portfolio.

Command ID

296

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

GetPositionEvalPayload

Response Payload

PositionEvalPayload

Error Payload

no payload at all, or ResultPage<string>

This command can be initiated for all types of order requests (add, replace, cancel), one at a time. The response will offer information about the effects of the request as if it was accepted by the server, in terms of order value, fee and portfolio.

5.9.1. Message Payloads

Request Payload

Requests must contain a payload with the type GetPositionEvalPayload, detailed below.

Table 136. The structure of GetPositionEvalPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

@class

String

-

-

Constant value p.GetPositionEvalPayload

The name of the payload object type

add

AddOrder

-

-

-

Add request to evaluate

replace

ReplaceOrder

-

-

-

Replace request to evaluate

cancel

CancelOrder

-

-

-

Cancel request to evaluate

The request payload can contain only one of the three fields at a time. Populating more than one field will result in a validation error.

The content of add, replace and cancel fields should be the same as the request payload of the corresponding order command. The same payload which would be sent in an order request can be used to populate one of these three fields.

Details about the type of the fields can be found in the section dedicated to each corresponding command: <<ADD ORDER>>, <<REPLACE ORDER>>, <<CANCEL ORDER>>.

Response Payload

For requests which are successfully processed, a response with a PositionEvalPayload content will be sent by the server.

Table 137. The structure of PositionEvalPayload type

Field

Type

Min. Length

Max. Length

Restrictions

Description

spot

SpotPositionEvalDto

-

-

-

Evaluation for spot orders

futures

FuturesPositionEvalDto

-

-

-

Evaluation for futures orders

The response payload will contain at most one of the two fields, depending on the type of symbol specified in the request. If, for some reason, the evaluation cannot complete, a payload with no fields will be sent.

The structure of a SpotPositionEvalDto object is detailed below.

Table 138. The structure of SpotPositionEvalDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

symbol

String

1

20

-

Symbol code

val

decimal

-

-

-

Clearing value

fee

decimal

-

-

-

Order fee

ava

decimal

-

-

-

Available cash

avg

decimal

-

-

-

Average price

avi

long

-

-

-

Available instruments

The structure of a FuturesPositionEvalDto object is detailed below.

Table 139. The structure of FuturesPositionEvalDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

symbol

String

1

20

-

Symbol code

dfm

decimal

-

-

-

Margin required for the request

val

decimal

-

-

-

Clearing value

fee

decimal

-

-

-

Order fee

avm

decimal

-

-

-

Available cash

avg

decimal

-

-

-

Average price

net

long

-

-

-

Available contracts

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent. There is also the situation when the evaluation cannot complete and the server will return a non-error response with an empty payload.

5.9.2. Constants and Enumerations

There are no relevant constants or enumerations related to this command.

5.9.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.GetPositionEvalPayload",
            "add": {
                "@class": "p.AddOrder",
                "exc": "BVB",
                "sym": "SIF4",
                "mkt": "REGS",
                "sde": 1,
                "iacc": "A001",
                "siz": 1,
                "prc": "0.880000",
                "trm": 1,
                "opd": 0,
                "stt": 1,
                "clr": 2,
                "std": 0,
                "tpa": 1,
                "tgp": 0,
                "ver": 0,
                "dcv": 0,
                "ssl": 0,
                "ref": ""
            }
        },
        "pid": 296,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 296,
        "user": "admin",
        "ktime": 1424185545588,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.PositionEvalPayload",
            "spot": {
                "symbol": "SIF4",
                "val": "0.8800",
                "fee": 0,
                "ava": "1000097.000000",
                "avg": 0,
                "avi": 0
            }
        }
    }
}
Response with no result
{
    "bm": {
        "pid": 296,
        "user": "admin",
        "ktime": 1424185545588,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "d.PositionEvalPayload"
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 296,
        "error": 11,
        "user": "admin",
        "ktime": 1424185545588,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": ["Must request one evaluation type at a time."]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 296,
        "error": 1,
        "user": "admin",
        "ktime": 1424185545588,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.10. GET OUTSTANDING PENDING ORDERS

Requests the list of outstanding orders and pending order requests the current end-user has access to.

The difference from [GET OUTSTANDING ORDERS] command is that this command returns a consolidated view of all orders confirmed by the exchange system along with the pending requests which have not been sent yet to the exchange system. Pending requests might be for modification or cancellation of existing orders, in which case they will be directly linked with the associated orders, or they may be for adding new orders.

Note
Order requests might be pending for various reasons, like the markets being closed or a manual approval is required from the broker.

The data returned by this command is a superset of the data returned by [GET OUTSTANDING ORDERS] command. The two commands cannot be interchanged because the type of the returned data are different.

Command ID

321

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

ReportingPayload

Response Payload

ResultPage<PendingOrderDto>

Error Payload

no payload at all, or ResultPage<string>

5.10.1. Message Payloads

Request Payload

Requests must contain a payload with the type ReportingPayload, detailed in the ArenaXT Common Types chapter.

The parameters field of the payload should contain a Map object with the following entries:

Parameter Key

Parameter Value

iob.iacc

The trading account under which the orders were placed, or * to get orders for all accounts

iob.sym

The code of the symbol for which to get the orders, or * (or empty) to get all orders

iob.sts

The status of the orders, or * to get all orders

iob.sde

The side by which to filter the orders, or * to get all orders

Note
Both the entry keys and the entry values have the type string. Details about the Map type can be found in the ArenaXT Common Types chapter.
Response Payload

For requests which are successfully processed, a response with a ResultPage<PendingOrderDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<PendingOrderDto>, described below.

Table 140. The structure of Lines<PendingOrderDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.PendingOrderDto

Array of PendingOrderDto objects

-

-

-

Array of objects

The structure of an PendingOrderDto object is detailed below.

Table 141. The structure of PendingOrderDto type

Field

Type

Min. Length

Max. Length

Restrictions

Description

bok

int

-

-

Enumeration

Order book

brk

String

0

10

-

Trading member code

clr

int

-

-

-

Clearing term

csq

long

-

-

-

Generated sequence

cqy

long

-

-

-

Accumulated executed quantity

csts

int

-

-

Enumeration

Computed status

dcv

long

-

-

-

Disclosed volume

eft

Timestamp

-

-

-

Effective time

exc

String

1

5

-

Exchange code

fee

decimal

-

-

-

Order fee

grs

int

-

-

Enumeration

Gross settlement indicator

hdi

long

-

-

Enumeration

Hidden indicator

hdv

long

-

-

-

Hidden volume

iacc

String

0

11

-

Trading account

iaccn

String

-

-

-

Full name of the account holder

id

long

-

-

-

Order number, as assigned by the brokerage server (internal ID)

iini

String

0

20

-

Initiator user

ind

int

-

-

Enumeration

Indicative quote

isiz

long

-

-

-

Initial order size

itrd

long

-

-

-

Last trade number (internal ID)

iuui

String

0

20

-

Updater user

lastPx

decimal

-

-

-

Last trade price

lastVol

long

-

-

-

Last trade volume

lnk

int

-

-

-

Order link (for quotes)

lut

Timestamp

-

-

-

Local update time

mkp

int

-

-

Enumeration

Market priority flag

mkt

String

1

20

-

Market code

nmb

int

-

-

-

Order number, as assigned by the exchange (external ID)

odt

int

-

-

Enumeration

Order type

opd

int

-

-

Date in YYYYMMDD format (for GTD orders) or 0 (for open orders)

Expiration date

prc

decimal

-

-

-

Order price

prt

int

-

-

Enumeration

Price type

rclr

int

-

-

-

Requested clearing term

rcti

Timestamp

-

-

-

Request creation time

rdcv

long

-

-

-

Requested disclosed volume

ref

String

0

40

-

Reference (comments)

rhdi

int

-

-

Enumeration

Requested hidden indicator

rid

int

-

-

-

Request ID

rini

String

0

20

-

Request initiator user

rmkp

int

-

-

Enumeration

Requested market priority flag

ropd

int

-

-

Date in YYYYMMDD format (for GTD orders) or 0 (for open orders)

Requested expiration date

rprc

decimal

-

-

-

Requested price

rrdy

int

-

-

Enumeration

Request ready indicator

rref

String

0

40

-

Request comments

rsiz

long

-

-

-

Requested order size

rstd

int

-

-

Date in YYYYMMDD format

Requested settlement date

rsts

int

-

-

Enumeration

Request status

rstt

int

-

-

Enumeration

Requested settlement type

rtgp

decimal

-

-

-

Requested trigger price

rtrm

int

-

-

Enumeration

Requested order term

rtype

int

-

-

Enumeration

Request type

ruti

Timestamp

-

-

-

Request update time

sde

int

-

-

Enumeration

Order side

shv

long

-

-

-

Display volume

siz

long

-

-

-

Order size

ssl

int

-

-

Enumeration

Short sell indicator

std

int

-

-

Date in YYYYMMDD format

Settlement date

sts

int

-

-

Enumeration

Order status

stt

int

-

-

Enumeration

Settlement type

sty

String

1

40

-

Symbol type

sym

String

1

20

-

Symbol code

tgp

decimal

-

-

-

Trigger price

tob

String

0

20

-

To external broker code

tou

String

0

20

-

To external user code

tpa

int

-

-

Enumeration

Trigger type

trd

int

-

-

-

Last trade number (external ticket)

trm

int

-

-

Enumeration

Order term

uti

Timestamp

-

-

-

Last update time

uty

int

-

-

Enumeration

Update type

value

decimal

-

-

-

Order value

ver

int

-

-

Enumeration

Volume restriction

acc

int

-

-

-

External account

act

int

-

-

Enumeration

External account type

bka

String

0

40

-

Settlement bank account

bnk

String

0

40

-

Settlement bank code

diffFee

decimal

-

-

-

Difference of fee to be applied

diffSize

long

-

-

-

Difference of volume to be applied

diffValue

decimal

-

-

-

Difference of value to be applied

ini

String

0

20

-

Initiator user id

mbr

String

0

10

-

Clearing member code

osq

long

-

-

-

Order audit sequence

rgr

int

-

-

Enumeration

External registry operation

rosq

int

-

-

-

Request order audit sequence

uui

String

0

20

-

Updater user id

Note
The fields in italics are not relevant in client context and can be ignored by the client application.

The data returned for this command is paginated on the server side, so the client must verify if more results are available.

The PendingOrderDto type and its correspondence with InternalOrderDto and OrderRequestDto

A PendingOrderDto offers an aggregated view over an InternalOrderDto, an OrderRequestDto or both at the same time. It is constructed at run-time with fields from one, or both of the objects it represents.

At any moment in time, a PendingOrderDto object might represent:

  • an OrderRequestDto (i.e. a pending add order request which has not yet been sent to the exchange)

  • an InternalOrderDto (i.e. a confirmed order standing at the exchange, for which there is no pending request)

  • both an InternalOrderDto and an OrderRequestDto (i.e. a confirmed order standing at the exchange, for which there is a pending request for modification or cancellation which has not yet been sent to the exchange)

Below is the correspondence between the fields of PendingOrderDto type and the other two types.

Table 142. PendingOrderDto fields mapping

PendingOrderDto Field

InternalOrderDto Field

OrderRequestDto Field

acc

acc

-

act

act

-

bka

bka

-

bnk

bnk

-

bok

bok

-

brk

brk

-

clr

clr

clr

csq

csq

id

csts

-

-

dcv

dcv

dcv

eft

eft

-

exc

exc

exc

diffFee

diffFee

-

diffSize

diffSize

-

diffValue

diffValue

-

fee

fee

fee

grs

grs

-

hdi

hdi

-

hdv

hdv

-

iacc

iacc

iacc

iaccn

iaccn

iaccn

id

id

-

iini

iini

ini

ind

ind

-

ini

ini

-

isiz

isiz

-

itrd

trd

-

iuui

iuui

uui

lastPx

lastPx

-

lastVol

lastVol

-

lnk

lnk

-

lut

lut

uti

mbr

mbr

-

mkp

mkp

-

mkt

mkt

mkt

nmb

nmb

-

odt

odt

-

opd

opd

opd

osq

osq

osq

prc

prc

prc

prt

prt

-

rclr

-

clr

rcti

-

cti

rdcv

-

dcv

ref

ref

ref

rgr

rgr

-

rhdi

hdi

-

rid

-

id

rini

-

ini

rmkp

mkp

-

ropd

-

opd

rosq

-

osq

rprc

-

prc

rrdy

-

rdy

rref

-

ref

rsiz

-

siz

rstd

-

std

rsts

-

sts

rstt

stt

stt

rtgp

-

tgp

rtrm

trm

trm

rtype

-

type

ruti

ruti

-

sde

sde

sde

shv

shv

-

siz

siz

siz

ssl

ssl

ssl

std

std

-

sts

sts

-

stt

stt

stt

sty

sty

-

sym

sym

sym

tgp

tgp

tgp

tob

tob

-

tou

tou

-

tpa

tpa

tpa

trd

trd

-

trm

trm

trm

uti

uti

uti

uty

uty

-

uui

uui

-

value

value

value

ver

ver

-

Note
  1. When an InternalOrderDto exists (i.e. for confirmed orders), the PendingOrderDto object is derived from it, using the correspondence table above. When, in addition, an OrderRequestDto exists (i.e. a pending modification/cancellation request for the confirmed order exists), additional fields (those starting in r...) are populated with data from OrderRequestDto. In this case, some fields from OrderRequestDto (those marked in italics) will be ignored, since they are redundant or not relevant for the corresponding field.

  2. When no InternalOrderDto exists (i.e. for add requests which were not yet sent to the exchange), the PendingOrderDto object is derived directly from the OrderRequestDto object. All PendingOrderDto fields are populated with data from OrderRequestDto, including the fields in italics, which would otherwise be ignored.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

5.10.2. Constants and Enumerations

Most of the enumerations related to this command are described in the OrderRequestDto Enumerations section and the InternalOrderDto Enumerations section, since they are shared by multiple data types. The direct correspondence between the fields can be seen from the mapping table above.

Additional enumerations specific to PendingOrderDto type are listed below.

Table 143. Computed status

PendingOrderDto.csts

Description

-3

Pending New

-2

Pending Change

-1

Pending Deletion

0

Inactive

1

Active

2

Suspended

5.10.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ReportingPayload",
            "startPosition": 1,
            "pageSize": 50,
            "parameters": {
                "entry": [{
                    "string": ["iob.iacc","A000000002"]
                },
                {
                    "string": ["iob.sym","BIO"]
                },
                {
                    "string": ["iob.sts","*"]
                },
                {
                    "string": ["iob.sde","*"]
                }]
            }
        },
        "pid": 321,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 321,
        "user": "admin",
        "ktime": 1459436427426,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.PendingOrderDto": [{
                    "id": 188764,
                    "iacc": "A000000002",
                    "iaccn": "ALEXANDRU",
                    "itrd": 0,
                    "isiz": 1000,
                    "iuui": "admin",
                    "iini": "admin",
                    "lastVol": 0,
                    "lastPx": "0.000000",
                    "diffSize": 0,
                    "value": "550.000000",
                    "diffValue": "0.000000",
                    "fee": "3.025000",
                    "diffFee": "0.000000",
                    "sts": 1,
                    "ind": 0,
                    "hdi": 0,
                    "ver": 0,
                    "tpa": 1,
                    "bok": 1,
                    "hdv": 0,
                    "nmb": 16842018,
                    "csq": 476235,
                    "lnk": 0,
                    "eft": "2016-03-29 14:55:01.812",
                    "sde": 1,
                    "trm": 2,
                    "opd": 0,
                    "odt": 1,
                    "rgr": 0,
                    "exc": "BVB",
                    "sym": "BIO",
                    "sty": "SHARE",
                    "mkt": "REGS",
                    "clr": 2,
                    "std": 0,
                    "stt": 1,
                    "brk": "F4",
                    "mbr": "F4",
                    "trd": 0,
                    "acc": 8000067,
                    "act": 1,
                    "mkp": 0,
                    "tob": "",
                    "tou": "",
                    "prc": "0.550000",
                    "tgp": "0.000000",
                    "siz": 1000,
                    "dcv": 0,
                    "shv": 0,
                    "bnk": "",
                    "bka": "",
                    "grs": 0,
                    "ref": "",
                    "uty": 2,
                    "uti": "2016-03-29 14:56:43.253",
                    "uui": "UF4GW1",
                    "ini": "UF4GW1",
                    "ssl": 0,
                    "prt": 3,
                    "lut": "2016-03-29 14:56:43.295",
                    "osq": 41399692,
                    "csts": -2,
                    "rid": 476245,
                    "rtype": 0,
                    "rrdy": 0,
                    "rsts": 1,
                    "rmkp": 0,
                    "rhdi": -1,
                    "rtrm": 2,
                    "ropd": 0,
                    "rclr": 2,
                    "rstd": 0,
                    "rstt": 1,
                    "rprc": "0.510000",
                    "rtgp": "0.000000",
                    "rsiz": 2000,
                    "rdcv": 100,
                    "rref": "test",
                    "rosq": 41399692,
                    "ruti": "2016-03-31 18:00:16.021",
                    "rcti": "2016-03-31 18:00:16.021",
                    "rini": "admin"
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 321,
        "error": 11,
        "user": "admin",
        "ktime": 1459436427426,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Account must be between 1 and 20 characters"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 321,
        "error": 1,
        "user": "admin",
        "ktime": 1459436427426,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

5.11. GET OUTSTANDING ORDER REQUESTS

Requests the list of outstanding order requests the current end-user has access to.

Command ID

126

Initiated via

HTTPS connection

Initiated by

Client

Request Payload

ReportingPayload

Response Payload

ResultPage<OrderRequestDto>

Error Payload

no payload at all, or ResultPage<string>

5.11.1. Message Payloads

Request Payload

Requests must contain a payload with the type ReportingPayload, detailed in the ArenaXT Common Types chapter.

The parameters field of the payload should contain a Map object with the following entries:

Parameter Key

Parameter Value

orb.iacc

The trading account under which the order requests were placed, or * to get orders for all accounts

orb.sym

The code of the symbol for which to get the order requests, or * (or empty) to get all order requests

orb.status

The status of the order requests, or * to get all order requests

orb.sde

The side by which to filter the order requests, or * to get all order requests

Note
Both the entry keys and the entry values have the type string. Details about the Map type can be found in the ArenaXT Common Types chapter.
Response Payload

For requests which are successfully processed, a response with a ResultPage<OrderRequestDto> payload will be sent by the server. The type of the response payload is a specialization of the generic type ResultPage<T> which is detailed in the ArenaXT Common Types chapter.

The lines field of the payload object has the specific type Lines<OrderRequestDto>, described below.

Table 144. The structure of Lines<InternalOrderDto> type

Field

Type

Min. Length

Max. Length

Restrictions

Description

d.OrderRequestDto

Array of OrderRequestDto objects

-

-

-

Array of objects

Note
The structure of an OrderRequestDto object is detailed at <<_orderrequestdto_structure>>.

The data returned for this command is paginated on the server side, so the client must verify if more results are available.

Error Response Payload

For invalid requests, which contain malformed input data, the server will send a validation error response, having error code 11 and a ResultPage<string> payload.

Note
The structure of ResultPage<string> type is described in ArenaXT Common Types chapter.

For valid requests which cannot be processed by the server, an error response with no payload will be sent.

5.11.2. Constants and Enumerations

All enumerations related to this command are described in the ArenaXT Common Types chapter.

5.11.3. Sample Messages

Request
{
    "bm": {
        "payload": {
            "@class": "p.ReportingPayload",
            "startPosition": 1,
            "pageSize": 50,
            "parameters": {
                "entry": [{
                    "string": ["orb.iacc","*"]
                },
                {
                    "string": ["orb.sym","*"]
                },
                {
                    "string": ["orb.status","*"]
                },
                {
                    "string": ["orb.sde","*"]
                }]
            }
        },
        "pid": 126,
        "user": "admin",
        "sessionId": "1234567890",
        "csq": 1
    }
}
Response
{
    "bm": {
        "pid": 124,
        "user": "admin",
        "ktime": 1424687725990,
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 1,
            "bottom": true,
            "lines": {
                "d.OrderRequestDto": [{
                    "id": 16850,
                    "origId": 62613,
                    "status": 2,
                    "type": -1,
                    "iacc": "House",
                    "diffSize": 0,
                    "value": "0.000000",
                    "diffValue": "0.000000",
                    "fee": "0.000000",
                    "diffFee": "0.000000",
                    "exc": "BVB",
                    "sym": "SIF3",
                    "mkt": "REGS",
                    "ver": 0,
                    "tpa": 1,
                    "sde": 2,
                    "trm": 1,
                    "opd": 20150225,
                    "clr": 2,
                    "std": 0,
                    "stt": 1,
                    "acc": 8000215,
                    "prc": "0.101000",
                    "tgp": "0.000000",
                    "siz": 300,
                    "dcv": 0,
                    "ref": "",
                    "nmb": 7521298,
                    "tms": "2015-02-25 12:29:06.306",
                    "osq": 21156465,
                    "ssl": 0,
                    "rcd": 0,
                    "ini": "admin",
                    "uui": "admin",
                    "uti": "2015-02-25 12:30:26.564",
                    "cti": "2015-02-25 12:30:26.49"
                }]
            }
        }
    }
}
Response with validation error
{
    "bm": {
        "pid": 126,
        "error": 11,
        "user": "admin",
        "ktime": 1424687725990,
        "kmessage": "Payload not validated",
        "longid": 0,
        "csq": 1,
        "payload": {
            "@class": "p.ResultPage",
            "start": 1,
            "end": 1,
            "crtpage": 0,
            "bottom": true,
            "lines": {
                "string": [
                    "Account must be between 1 and 20 characters"
                ]
            }
        }
    }
}
Response with other errors
{
    "bm": {
        "pid": 126,
        "error": 1,
        "user": "admin",
        "ktime": 1424687725990,
        "kmessage": "Invalid session id.",
        "longid": 0,
        "csq": 1
    }
}

Appendix A: Client application initialization

The following is a description of the usual message sequence a trading client should send in order to prepare for trading through ArenaXT server. Client implementations are free to choose any order in which they request initialization data from server, or they may skip this step whatsoever, if their requirements do not impose having that particular data loaded. However, for a client application to be able to provide full trading capabilities for all symbols on all markets, it needs to follow the recommendations below.

Steps to initialize the client application

  1. The client application should connect to the server through the WSS connection, using one of the 2 communication protocols.

  2. Once the connection is established, the client should send a <<LOGIN>> command (ID 101) with the credentials provided by the end-user. If the login fails, the client application should request different credentials from the end-user and repeat this step. The LOGIN command should be synchronous in term of functionality, meaning that the application should not permit other interactions until a response is received and processed.

  3. Once the LOGIN command succeeds (user logs in), the client application should:

    1. Store the user details from the response payload (Login.user) for later use throughout the trading session.

    2. Initialize the watch list with symbols from the response payload (Login.symbols). This list contains only the symbol code and exchange code, so at this step the watch list will not contain any other information.

    3. Start the process of sending periodical <<HEART BEAT>> (ID 100) commands.

    4. Continue with requesting data from the server.

    5. At this point it is also possible to display the main application UI and enable limited user interaction. Also, the application can display password/PIN expiration warnings. If UI and warnings are not displayed at this point, they need to be shown after data initialization ends.

  4. Initiate a WSS request to get the list of symbols with <<GET SYMBOLS>> command (ID 105).

  5. Initiate a HTTPS request to get the list of symbol-markets with <<GET SYMBOL MARKETS>> command (ID 190).

  6. Initiate a WSS request to get Level 1 market data for the watch list with <<L1 DATA SNAPSHOT>> command (ID 110).

  7. Initiate a HTTPS request to get the list of trading accounts with <<GET USER ACCOUNTS>> command (ID 123).

  8. Optionally initiate a WSS request to get the list of exchanges with <<GET EXCHANGES>> command (ID 104).

  9. Optionally initiate a WSS request to get the list of exchange indices with <<INDICES SNAPSHOT>> command (ID 106).

Processing initialization data

Symbols

When the response of the <<GET SYMBOLS>> (ID 105) command is received, the client application should store the list of symbols for later use. This list will be used mainly for the following purposes:

  • Allow end-user to search through this list and add new symbols to the watch-list

  • Use symbol details (reference price, default settlement term) when adding new orders

  • Use symbol’s reference price in watch list and other parts of the application.

No UI change is necessary when this list is received. The list is static, no updates will be received for it during the end-user’s session.

Symbol-Markets

When the response of <<GET SYMBOL MARKETS>> (ID 190) command is received, the client should store the list of symbol-market for later use. This list will be used mainly for the following purposes:

  • Populate the list of possible markets for a symbol in different parts of the application (order form, order book).

  • Determine which of the possible markets of a symbol is the primary one.

No UI change is necessary when this list is received. The list is static, no updates will be received for it during the end-user’s session.

L1 Data

When the response of <<L1 DATA SNAPSHOT>> (ID 110) command is received, the client should perform the following actions:

  • For each element from the list, compute the absolute price change and percentage price change, since they are not transmitted by the server.

  • Populate the watch list with data from the primary markets (L1DataDto.pkMarket == 1).

  • Store the L1 market data for later use in Order Book panel.

The L1 data must be updated by the client application as <<L1 DATA UPDATE>> (ID 111) and <<SMK STATUS UPDATE>> (ID 115) commands are received in real-time from the server.

Trading Accounts

When the response of <<GET USER ACCOUNTS>> (ID 123) command is received, the client application should store the list of accounts and populate the account selector in different parts of the application. The list is static, no updates will be received for it during the end-user’s session.

Exchanges

When the response of <<GET EXCHANGES>> (ID 104) command is received, the client application should inform the end-user if any exchange from the list is not connected with the server (is offline).

Updates for the status of the exchanges will be received in real-time from the server, as <<XAP CONNECTED>> (ID 184) and <<XAP DISCONNECTED>> (ID 185) messages. The client should be able to process these updates and modify the stored list of exchanges accordingly.

Indices

When the response of <<INDICES SNAPSHOT>> (ID 106) command is received, the client application should store the list of exchange indices for later use. This list will be used in the Indices panel to display the initial data.

Updates of indices will be received in real-time from the server as <<INDICES UPDATE>> (ID 112) commands. The client should be able to process these updates and modify the stored list of indices accordingly.

Getting the application ready for use

Once all the initialization data has been processed by the client application, full user interaction should be enabled, meaning that end-user can now start entering orders and view reports. User-related warnings for password/PIN expiration must be displayed now, if not already displayed earlier.

Reinitializing the application

The client application should reinitialize itself after any of the exchanges is reconnected to the server. Usually, this happens at the beginning of the day, when the server disconnects from the exchange to allow for exchange initialization; however disconnects are also possible during the day. Once the server reconnects to the exchange, it will send <<XAP CONNECTED>> (ID 184) messages to all client applications.

The client application should request the following data again whenever a <<XAP CONNECTED>> (ID 184) message is received:

  • Symbols, with <<GET SYMBOLS>> command (ID 105)

  • Symbol-markets, with <<GET SYMBOL MARKETS>> command (ID 190)

  • Level 1 market data, with <<L1 DATA SNAPSHOT>> command (ID 110)

  • Trading accounts, with <<GET USER ACCOUNTS>> command (ID 123)

The same processing must be performed as during the initialization phase described above.