1. About this Document

This document is a high-level specification for the Devexperts Notifications API. This API extends the REST API (described in a separate document) with realtime push notifications.

1.1. Revision History

Table shows updates of this document:

Revision Date Version Change Details

29-August-2023

216

Added SERVICE_CHARGE transfer type for Cash Transaction

26-October-2023

217

Added DIVIDEND, EXPIRATION, DELISTING, SPIN_OFF, RENAME, MERGER_ACQUISITION, SPLIT, EXERCISE, POSITION_UPDATE transfer types for Cash Transaction

23-November-2023

218

Removed riskLevelThreshold and actualRiskLevel fields from Account Event. Added reason field to Account Event.

28-May-2024

XT 70

Fixed Ping request and response format specification in section Session Keep-Alive ("Ping")

14-October-2025

XT 310.7, XT 324

Updated response of Instrument Subscription Request to send instruments in batches.

2. General Details

The API is aimed to deliver realtime updates about events happening with accounts in the platform in a publish-subscribe manner. Consumers of the API express interest in receiving certain type of notifications for certain entities with a subscription request. The API tracks the subscription and delivers notifications asynchronously to the subscribed consumers. The API can also support a "B2B" integration when all the updates are streamed over a single channel without explicit subscription.

Notification API is transport-agnostic (meaning any push notification channel can be integrated) however reference implementation is over Websocket protocol (see https://en.wikipedia.org/wiki/WebSocket).

2.1. Accompanying APIs

Notifications API doesn’t provide any means of issuing commands to the system. A separate REST API is used for that purpose.

2.2. Supported Data Formats

Notification API supports the same data formats as the REST API:

  • XML (as de-facto communication standard).

  • JSON (as a more lightweight and browser-friendly standard).

Data format is selected when API session is established (see Establish a Session). All the messages in a session are encoded into the initially selected format. Unlike in REST API, consumers must explicitly indicate the desired format.

2.3. Supported Encodings

Notification API always processes and distributes messages in UTF-8 encoding.

2.4. Supported Compressions

Notification API supports the standard "gzip" compression for the data. Client’s compression preference is communicated when API session is established (see Establish a Session) and remains active for all messages sent in this session.

2.5. API Versioning

The Notification API attempts (if possible) to maintain backward compatibility with the clients provided the following:

  • Clients ignore the data they do not understand

  • Clients only use the data they need

For example, in case of XML representation, clients must make sure they do not couple their logic with current XML representation in such a way that adding new fields causes their application to malfunction. This allows adding new data to resources without breaking clients.

If data is removed or data meaning is changed, a new notification API version is introduced. Switch between different versions is based on the URI of the API (e.g. http://host/api/v1 for version 1 and http://host/api/v2 for version 2).

API versioning supports only major integer versions such as 1,2,3 etc. With the API, there is no notion of minor releases.

Change New Version Released?

Addition of a new data field to data representation

No

Changing the logical meaning of a field

Yes

Removing a field

Yes

Changing the default representation, currency units etc.

Yes

Addition of new independent requests

No

New business rules and/or application flow

Yes

New default values for optional request parameters or fields

Yes

2.6. Entity Versioning

Notification API (together with the REST API) supports the notion of entity versions. Each business entity (such an account) has a version which is a number that increases monotonically with any changes. It is possible to find out the order of updates by comparing versions: most recent entity’s version will be greater.

2.7. Messages

Notification API is based around asynchronous messages sent from the client to the system and vice versa.

Each message contains the following fields:

type

Type of the message that indicates its purpose (e.g. subscription or account update notifications). See API details below for the list of valid messages.

requestId

Request id assigned by the sender. Arbitrary string up to 64 characters. Used to correlate incoming and outgoing messages in request-response scenarios.

inReplyTo

For response messages, contains the id of the corresponding request message (see requestId field).

refRequestId

Id of the related request. For example, in case of canceling subscription contains requestId of the original subscription request. Omitted otherwise.

timestamp

Timestamp in UTC when the message has been sent. Note that this timestamp may differ from the business timestamp of the message payload.

session

Token of the session this message belongs to. This is used for authorization purpose and for multiplexing multiple sessions in a single physical channel. See Authentication & Authorization.

payload

Optional field representing the message payload specific for message type as a separate object.

Example

Client
{
    "type": "AccountPortfoliosSubscriptionRequest",
    "requestId": "1",
    "timestamp": "2016-07-27T14:50:30.053Z",
    "session": "11tndgiuj3c2tu74ko6c33atnc",
    "payload": {
        "requestType": "LIST",
        "accounts": ["default:demo1", "default:demo2"]
    }
}
Server
{
    "type": "AccountPortfolios",
    "inReplyTo": "1",
    "timestamp": "2016-07-27T14:50:30.054Z",
    "session": "11tndgiuj3c2tu74ko6c33atnc",
    "payload": {
        "portfolios": [...]
    }
}

2.8. Reject

If an incoming message cannot be processed by the server, it is rejected and a special Reject message is sent. This message contains details about the rejection, such as error code and human-readable details. Upon receiving a reject the client may elect to fix the errors on its side and retry the request.

Server Message

type

Reject

inReplyTo

RequestId of the corresponding client message.

payload

Error object.

2.9. Common Errors

The following errors may be triggered by any request message:

Code Details Description

1

Authorization required

Either client did not provide an session code or the session code is invalid or the session is expired.

32

Incorrect request parameters

Client sent a malformed request.

3. Data Types and Formats

3.1. Numbers

The API expects (and returns) numeric values formatted according to W3C XML schema rules for “double” and “integer” types (see double and integer). The format is portable and country-independent. Dot (“.”) is used as a decimal separator; other separators (such as thousands) are not supported. Samples are: 123.456, +1234.456, -1234.456, -.456, 123, -1E4, +INF.

3.2. Booleans

Boolean values are encoded as "true" or "false" strings. Absence of value (where appropriate) is interpreted as "false".

3.3. Times and Dates

All times and dates in the API are encoded according to RFC 3339. This is a standard convention which is supported by most of the programming languages and frameworks.

RFC 3339-formatted dates and times have the following characteristics:

  • This format is human readable.

  • Two values can be compared using lexicographical comparison (i.e. sort values as strings)

Times and dates are either in UTC coordinated time or include timezone offset information.

The following formats are supported:

Format Sample When used

2013-01-24T23:05:08.52Z

UTC timestamp with milliseconds precision used everywhere when a timestamp is expected.

2013-01-24Z

UTC date, used everywhere when a date is expected.

Monday, 23:00:00Z

UTC week date, used everywhere when a week-relative date is expected.

23:05:08.52Z

UTC time

01:05:08

Time interval

1464264688310

UNIX milliseconds since epoch

3.4. Currencies

Currency information is encoded according to ISO 4217. This is an international standard which specifies three-letter currency codes.

3.5. Languages

Language information is encoded according to BCP 47 (http://tools.ietf.org/html/bcp47). This is a document which concatenates two RFCs (5646 and 5645) and defines values of language tags to be used. Examples include en for English, en-CA for Canadian English, and ja-JP for Japanese as used in Japan.

3.6. Client-originated Identifiers

The system allows clients to submit arbitrary identifiers during trading (so that the client can distinguish orders on its side). Client-originated identifiers can comprise any latin alphanumeric characters (A..Z,a..z,0..9) and any of the following special characters:

~ , . - _ / \ : ; ! @ ‘ “ # $ % ^ & ? * ( ) [ ] = + \`

Length of a client-originated identifier should not exceed 64 characters.

Identifiers are case-sensitive (so that ‘Aa’ and ‘AA’ are two different identifiers).

The API rejects requests if an identifier contains any characters other than listed above or its length exceeds 64 characters.

Client-originated identifiers must be URL-encoded when used in queries (see https://en.wikipedia.org/wiki/Percent-encoding).

3.7. Account Code

Accounts in the system are addressed with a two-component account code that uniquely corresponds to a single account in the system. Account code is assigned by the system and is of 'clearing:account' format (two strings separated with a colon).

Account code should be URL-encoded when used in HTTP queries (see https://en.wikipedia.org/wiki/Percent-encoding).

3.8. Order Statuses

An order can be in one of the following statuses:

Status Details

ACCEPTED

Order has been accepted by the system.

WORKING

An order is working in the system: either pending execution or (in case of limit or stop order) waiting for a trigger quote

CANCELED

Order has been cancelled in its entirety. This is a final state.

COMPLETED

Order has been filled (either completely or partially). This is a final state.

EXPIRED

Order has been expired. This is a final state.

REJECTED

Order has been rejected. This is a final state.

IN_REVIEW

Order has been put in review.

3.9. Price Offset

Price offset - offset of one price from another. Could be specified in two formats:

  • Absolute - absolute offset from another price. Specified as a number. See Numbers.

  • Relative - percentage offset from another price. Specified as a number with '%' at the end. See Numbers.

4. Security Aspects

4.1. Transport Protocol Security

The Notification API is deployed to work over secure transport protocol such as WS over TLS (WSS) or secure VPN. The protocol must ensure that no traffic towards and from the API is exposed to public unencrypted.

4.2. Authentication & Authorization

Notification API relies on REST API for authentication and authorization. A client that wishes to use the notification API must obtain a session token using the corresponding REST API call (Basic Authorization). Then all the requests / subscriptions to the notification API should be accompanied with a valid session token obtained from the REST API. Once a session token expires on the server, events are no longer sent over notification API.

HMAC authentication is not supported in the notification API.

5. Session

5.1. Establish a Session

Details

In order to start using the Notification API, the client must obtain session token via REST API (Basic Authorization). Then the client should establish a web socket connection.

There are two web socket resources: first is used for any subscription except market data (instruments, orders, account portfolios etc.), second resource is used for market data like quotes.

During connection establishment the client expresses its preferences for data format and compression (see Supported Data Formats and Supported Compressions).

Once the session token is obtained and the connection is established, the client can use the connection to subscribe for business events and market data. All incoming and outgoing messages will be bound to this session token with the help of the "session" field (see Messages). It means that multiple session tokens can be used in a single physical channel.

Any requests or subscription attempts made with invalid session token will be rejected. See Reject

Resource

wss://<host>/<path>/ws?format=<format>&compression=<compression>

wss://<host>/<path>/md?format=<format>&compression=<compression>

  • format argument is optional and is used to select the desired data format (can be either XML or JSON, case-insensitive, see Supported Data Formats). Default value is platform-specific.

  • compression argument is optional and is used to select compression type for the session. The value can only be "gzip". If this argument is omitted, no compression is used.

5.2. Session Keep-Alive ("Ping")

Details

The nature of notification functionality does not assume a lot of requests from client side. In some cases the client can subscribe on interesting data on start and does not send any subsequent requests at all. At the same time "the session" between client and server is restricted in time and automatically prolonged only if both side use it.

To be sure the client is still "alive" and to prolong his session token the server will periodically send a PingRequest message and client is expected to send a Ping in reply. Upon receiving a Ping message, the server extends the session. If the server doesn’t receive a Ping and timeout passes, the server closes the session.

Server Message

The server sends a PingRequest message:

type

PingRequest

requestId

Absent.

inReplyTo

Absent.

refRequestId

Absent.

timestamp

Timestamp of the message.

session

Session token.

payload

Absent.

Client Message

Upon receiving a PingRequest message, the client should send Ping message in response:

type

Ping

requestId

Absent.

inReplyTo

Absent.

refRequestId

Absent

timestamp

Timestamp of the message (optional)

session

Session token.

payload

Absent.

As the result, user session will be prolonged.

Example

Server
{
   "type": "PingRequest",
   "session": "2gkbiva152dov44d968sf9s0eh",
   "timestamp": "2024-05-27T21:33:23.659Z"
}
Client
{
    "type": "Ping",
    "session": "2gkbiva152dov44d968sf9s0eh"
}

6. Operations

6.1. Account Portfolios Subscription Request

Details

The API allows to subscribe for updates of account portfolio for selected (or all) accounts. Client sends a subscription message and server starts streaming update messages. Updates are send sequentially whenever any of these changes happen with the account:

  • An order is issued, modified or cancelled

  • A position is opened, closed, extended or reduced

  • Cash balance on an account is changed

The API sends the full account portfolio whenever anything changes (no diffs are sent). Orders in final states and closed positions are present in portfolio only when they were completed (closed) during the subscription and only once in the first update after the completion (closing). Client may use account version in the portfolio message (see Entity Versioning) to track the order of updates.

Client Message

type

AccountPortfoliosSubscriptionRequest

payload

Accounts Request object.

Server Message

Upon receiving a AccountPortfolioSubscriptionRequest message the system sends an initial snapshot of account portfolios the client subscribes to and then starts streaming updates as soon anything changes on an account. The following message is used to send the portfolio:

type

AccountPortfolios

inReplyTo

requestId of the corresponding AccountPortfoliosSubscriptionRequest message.

payload

Account Portfolio List object.

Errors

Request does not trigger any special errors. See Common Errors.

Example

Client
{
    "type": "AccountPortfoliosSubscriptionRequest",
    "requestId": "1",
    "session": "12345",
    "payload": {
        "requestType": "LIST",
        "accounts": ["default:demo1", "default:demo2"]
    }
}
Server
{
    "type": "AccountPortfolios",
    "inReplyTo": "1",
    "session": "12345",
    "payload": {
        "portfolios": [...]
    }
}

6.2. Account Portfolios Close Subscription Request

Details

If account portfolio updates are not required anymore client of API should close subscription.

Client Message

type

AccountPortfoliosCloseSubscriptionRequest

refRequestId

requestId of the original subscription request.

payload

Absent.

Server Message

Upon receiving an AccountPortfolioCloseSubscriptionRequest message the system closes corresponding subscription and sends the following response message:

type

AccountPortfoliosSubscriptionClosed

inReplyTo

requestId of the corresponding AccountPortfoliosCloseSubscriptionRequest message.

payload

Absent.

Errors

In addition to Common Errors request can trigger following error:

Code Details Description

2

Entity not found

Subscription does not exist or is already closed.

Example

Client
{
    "type": "AccountPortfoliosCloseSubscriptionRequest",
    "requestId": "2",
    "refRequestId": "1",
    "session": "12345"
}
Server
{
    "type": "AccountPortfoliosSubscriptionClosed",
    "inReplyTo": "2",
    "session": "12345"
}

6.3. Instrument Subscription Request

Details

This API allows to subscribe for instrument updates.

Updates are sent sequentially whenever new instruments are created, existing instruments are deleted, or any instrument fields are updated.

Client Message

The client sends a subscription message with the following values:

type

InstrumentSubscriptionRequest

payload

Instrument Subscription object.

Server Message

Upon receiving an InstrumentSubscriptionRequest message the system sends an initial message of empty instrument list, the client subscribes to and then sends updates on every instruments' change. For performance purpose the server may return instruments in batches. There is a guarantee that the server does not mix updates sending data in batches sequentially. In the other words, the client receives all batches representing one update and only then another one if any. The following message is used to send the response:

type

InstrumentBatch

inReplyTo

requestId of the corresponding InstrumentSubscriptionRequest message.

payload

Instrument Batch object.

Errors

Request does not trigger any special errors. See Common Errors.

Example

Client
{
   "type": "InstrumentSubscriptionRequest",
   "requestId": "test",
   "session": "2gkbiva152dov44d968sf9s0eh",
   "payload": {
      "types": ["CFD_OPTION"],
      "instruments": ["EUR/USD", "AUD/CAD"]
   }
}
Server
{
    "type": "InstrumentBatch",
    "inReplyTo": "test",
    "session": "2gkbiva152dov44d968sf9s0eh",
    "payload": {
        "instruments": [...],
        "batchIndex": 0,
        "isLastBatch": false
    }
}

{
    "type": "InstrumentBatch",
    "inReplyTo": "test",
    "session": "2gkbiva152dov44d968sf9s0eh",
    "payload": {
        "instruments": [...],
        "batchIndex": 1,
        "isLastBatch": true
    }
}

6.4. Instrument Close Subscription Request

Details

If instrument updates are not required anymore client of API should close subscription.

Client Message

type

InstrumentCloseSubscriptionRequest

refRequestId

requestId of the original subscription request.

payload

Absent.

Server Message

type

InstrumentSubscriptionClosed

inReplyTo

requestId of the corresponding InstrumentCloseSubscriptionRequest message.

payload

Absent.

Errors

In addition to Common Errors request can trigger following error:

Code Details Description

2

Entity not found

Subscription does not exist or is already closed.

Example

Client
{
   "type": "InstrumentCloseSubscriptionRequest",
   "requestId": "2",
   "refRequestId": "1",
   "session": "2gkbiva152dov44d968sf9s0eh"
}
Server
{
   "type": "InstrumentSubscriptionClosed",
   "inReplyTo": "2",
   "session": "2gkbiva152dov44d968sf9s0eh"
}

6.5. Account Metrics Subscription Request

Details

The API allows to subscribe for updates of account metrics (such as PnL and margin) for selected (or all) accounts. Client sends a subscription message and server starts streaming update messages. Subscription are send periodically (with server-configured frequency).

Client may use account version in the metrics message (see Entity Versioning) to track the order of updates.

Client Message

The client sends a subscription message with the following values:

type

AccountMetricsSubscriptionRequest

payload

Account Metrics Request object.

Server Message

Upon receiving an AccountMetricsSubscriptionRequest message the system sends an initial snapshot of account metrics the client subscribes to and then starts streaming updates. The following message is used to send the metrics:

type

AccountMetrics

inReplyTo

requestId of the corresponding AccountMetricsSubscriptionRequest message.

payload

Account Metrics List object.

Errors

Request does not trigger any special errors. See Common Errors.

Example

Client
{
   "type": "AccountMetricsSubscriptionRequest",
   "requestId": "test",
   "session": "2gkbiva152dov44d968sf9s0eh",
   "payload": {
      "accounts": ["default:iqtest01"],
      "requestType": "LIST",
      "includePositions": "true"
   }
}
Server
{
    "type": "AccountMetrics",
    "inReplyTo": "test",
    "session": "2gkbiva152dov44d968sf9s0eh",
    "payload": {
        "metrics": [...]
    }
}

6.6. Account Metrics Close Subscription Request

Details

If account metrics updates are not required anymore client of API should close subscription.

Client Message

type

AccountMetricsCloseSubscriptionRequest

refRequestId

requestId of the original subscription request.

payload

Absent.

Server Message

Upon receiving an AccountMetricsCloseSubscriptionRequest message the system closes corresponding subscription and sends the following response message:

type

AccountMetricsSubscriptionClosed

inReplyTo

requestId of the corresponding AccountMetricsCloseSubscriptionRequest message.

payload

Absent.

Errors

In addition to Common Errors request can trigger following error:

Code Details Description

2

Entity not found

Subscription does not exist or is already closed.

Example

Client
{
    "type": "AccountMetricsCloseSubscriptionRequest",
    "requestId": "2",
    "refRequestId": "1",
    "session": "2gkbiva152dov44d968sf9s0eh"
}
Sever
{
    "type": "AccountMetricsSubscriptionClosed",
    "inReplyTo": "2",
    "session": "2gkbiva152dov44d968sf9s0eh"
}

6.7. Account Events Subscription Request

Details

The API allows to subscribe for various 'events' regarding the account, such as liquidations or margin calls. Client sends a subscription message and server starts streaming event messages. Events are send sequentially whenever any of these changes happen with the account:

  • A margin call happens

  • An account is liquidated

Client Message

The client sends a subscription message with the following values:

type

AccountEventsSubscriptionRequest

payload

Accounts Request object.

Server Message

Upon receiving an AccountEventsSubscriptionRequest message the system sends an empty list of account events which means that subscription is happened and then starts streaming updates (no initial snapshot is sent). The following message is used to send account events:

type

AccountEvents

inReplyTo

requestId of the corresponding AccountEventsSubscriptionRequest message.

payload

Account Event List object.

Errors

Request does not trigger any special errors. See Common Errors.

Example

Client
{
   "type": "AccountEventsSubscriptionRequest",
   "requestId": "test",
   "session": "2gkbiva152dov44d968sf9s0eh",
    "payload": {
        "requestType": "LIST",
        "accounts": ["default:demo1", "default:demo2"]
    }
}
Server
{
    "type": "AccountEvents",
    "inReplyTo": "test",
    "session": "2gkbiva152dov44d968sf9s0eh",
    "payload": {
        "accountEvents": [...]
    }
}

6.8. Account Events Close Subscription Request

Details

If account events updates are not required anymore client of API should close subscription.

Client Message

type

AccountEventsCloseSubscriptionRequest

refRequestId

requestId of the original subscription request.

payload

Absent.

Server Message

Upon receiving an AccountEventsCloseSubscriptionRequest message the system closes corresponding subscription and sends the following response message:

type

AccountEventsSubscriptionClosed

inReplyTo

requestId of the corresponding AccountEventsSubscriptionRequest message.

payload

Absent.

Errors

In addition to Common Errors request can trigger following error:

Code Details Description

2

Entity not found

Subscription does not exist or is already closed.

Example

Client
{
    "type": "AccountEventsCloseSubscriptionRequest",
    "requestId": "2",
    "refRequestId": "1",
    "session": "2gkbiva152dov44d968sf9s0eh"
}
Server
{
    "type": "AccountEventsSubscriptionClosed",
    "inReplyTo": "2",
    "session": "2gkbiva152dov44d968sf9s0eh"
}

6.9. Cash Transfers Subscription Request

Details

The API allows to subscribe for cash transfers (such as deposits, withdrawals and PnL settlement) on an account or a set of accounts).

Client Message

The client sends a subscription message with the following values:

type

CashTransfersSubscriptionRequest

payload

Accounts Request object.

Server Message

Upon receiving a CashTransfersSubscriptionRequest message the system sends an empty list of cash transfers which means that subscription is happened and then starts streaming updates (no initial snapshot is sent). The following message is used to send cash transfers:

type

CashTransfers

inReplyTo

requestId of the corresponding CashTransfersSubscriptionRequest message.

payload

Cash Transfer List object.

Errors

Request does not trigger any special errors. See Common Errors.

Example

Client
{
    "type": "CashTransfersSubscriptionRequest",
    "requestId": "1",
    "session": "12345",
    "payload": {
        "requestType": "LIST",
        "accounts": ["default:demo1", "default:demo2"]
    }
}
Server
{
    "type": "CashTransfers",
    "inReplyTo": "1",
    "session": "12345",
    "payload": {
        "cashTransfers": [...]
    }
}

6.10. Cash Transfers Close Subscription Request

Details

If cash transfers updates are not required anymore client of API should close subscription.

Client Message

type

CashTransfersCloseSubscriptionRequest

refRequestId

requestId of the original subscription request.

payload

Absent.

Server Message

Upon receiving a CashTransfersCloseSubscriptionRequest message the system closes corresponding subscription and sends the following response message:

type

CashTransfersSubscriptionClosed

inReplyTo

requestId of the corresponding CashTransfersCloseSubscriptionRequest message.

payload

Absent.

Errors

In addition to Common Errors request can trigger following error:

Code Details Description

2

Entity not found

Subscription does not exist or is already closed.

Example

Client
{
    "type": "CashTransfersCloseSubscriptionRequest",
    "requestId": "2",
    "refRequestId": "1",
    "session": "12345"
}
Server
{
    "type": "CashTransfersSubscriptionClosed",
    "inReplyTo": "2",
    "session": "12345"
}

7. Data Types

7.1. Error

errorCode

Code of error.

description

Human-readable description of the issue (in English; subject to change without changes in API version).

7.2. Accounts Request

accounts

List of account codes (see Account Code). Required for request type LIST.

requestType

Type of request. Possible values:

ALL

requests info for all accounts,

LIST

returns info for enumeration from accounts field.

7.3. Account Portfolio List

portfolios

List of Account Portfolio objects.

7.4. Account Portfolio

account

Code of the account. See Account Code.

version

Numeric version of the account. Client can use this value to find out which of the updates is more recent (its version is greater). See Numbers

balances

Cash balances in various currencies as array of Balance objects. Zero balances are not included.

positions

Current positions on an account as array of Position objects.

orders

Current orders on an account as array of Order objects.

7.5. Balance

account

Code of the account the balance belongs to. See Account Code.

version

Numeric version of the account to which this balance relates. Client can use this value to find out which of the updates is more recent (its version is greater). See Numbers.

value

Balance in the given currency, signed.

currency

Currency of the balance (see Currencies).

7.6. Position

account

Code of the account. See Account Code.

version

Numeric version of the account. Client can use this value to find out which of the updates is more recent (its version is greater). See Numbers.

symbol

Symbol of the position’s instrument.

quantity

Current quantity of the position in units (not in lots); unsigned value. See Numbers.

side

Side of the position. Either BUY (long) or SELL (short).

openTime

Timestamp in UTC when this position was opened. See Times and Dates.

openPrice

Price at which the position was opened. See Numbers.

lastUpdateTime

Timestamp in UTC when this position was last updated. See Times and Dates.

7.7. Order

account

Code of the account the order belongs to. See Numbers.

orderId

Internal numeric id of an order chain in the system. This value is assigned when an order is initially placed and does not change when an order is replaced or cancelled. See Numbers.

orderCode

Internal unique string code of an order chain in the system. This value is assigned when an order is initially placed and does not change when an order is replaced or cancelled.

version

Numeric version of the account to which last update of this order is related. Client can use this value to find out which of the updates is more recent (its version is greater). See Numbers.

clientOrderId

Unique order id assigned by the client during order placement. See Client-originated Identifiers.

actionCode

Internal unique code of the last order modification. String value.

legCount

Number of legs in the order.

type

Order type. Possible values:

  • MARKET

  • LIMIT

  • STOP

  • STOP_LIMIT

  • TRAILING_STOP

  • TRAILING_STOP_LIMIT

instrument

Symbol of the order’s instrument

cashQuantity

Cash (notional) order quantity.

limitPrice

Limit price of an order.

stopPrice

Stop price of an order.

stopPriceOffset

Trailing stop orders price offset. See Price Offset.

limitPriceOffset

Trailing stop limit orders limit price offset. See Price Offset.

intermediateLimitPrice

Intermediate limit price of Trailing Stop Limit order. Present only if real limit price is not known yet (set as offset from stop price and stop part is not triggered yet).

intermediateStopPrice

Intermediate stop price of Trailing Stop (Limit) order. Present only if real stop price is not known yet (not triggered).

status

Current state of the order. See Order Statuses.

finalStatus

Boolean value indicating if order is in final state.

legs

Statuses of all the legs as a list of Order Leg objects.

side

Order operation. Possible values are:

  • BUY

  • SELL

tif

Time in force (expiration time for the order). One of:

  • DAY

  • GTC

  • IOC

  • FOK

  • GTD (in this case expireDate field will be present)

  • ATC

  • GTX

expireDate

Order expiration timestamp or date in UTC (see Times and Dates). The value is present if tif field is GTD.

issueTime

Timestamp in UTC when this order was accepted by the system. See Times and Dates.

transactionTime

Timestamp in UTC of the last order modification or fill. See Times and Dates.

links

List of the links between this order and other orders in its group as Order Link objects. Absent if the order is not a part of a group. Links calculated only for [list-open-orders] request. If parent order in group with parent or one of orders in OCO group is final, then links will be absent for such groups.

executions

List of all executions for this order. This includes order status changes, replaces, cancels and trades. Reports are ordered chronologically. See Execution.

cashTransactions

List of all cash transactions related to this order. Reports are ordered chronologically. See Cash Transaction.

7.8. Order Leg

instrument

Symbol of the leg’s instrument

positionEffect

Indicates expected position effect after a trade. Possible values (case-insensitive):

  • OPEN

  • CLOSE

side

Leg operation. Possible values are:

  • BUY

  • SELL

legRatio

Ratio of the leg relative to the quantity of parent order (as specified during request). Equals to 1.0 for single leg orders.

quantity

Initial quantity of the order in units (not in lots) as specified in a "Place" request.

filledQuantity

Quantity filled so far in units (not in lots). If no fills took place, this field equals to 0.0.

remainingQuantity

Quantity available for further execution (in units).

cashQuantity

Initial cash (notional) quantity of order leg.

filledCashQuantity

Cash (notional) quantity filled so far. If no fills took place, this field equals to 0.0.

remainingCashQuantity

Cash (notional) quantity available for further execution.

averagePrice

Volume-weighted average price of all fills for this leg. The value is ‘0.0’ if there are no fills yet.

linkType

One of the following values:

  • PARENT – this order is a parent of the linked one

  • CHILD – this order is a child of the linked one

  • OCO – this order is a member of an OCO group with the linked one.

linkedOrder

Internal unique string code of the linked order. Corresponds to orderCode field in the Order object.

linkedClientOrderId

Unique order id of the linked order. Corresponds to clientOrderId field in the Order object.

7.10. Execution

account

Code of the account the order belongs to. See Account Code.

executionCode

Unique string code of the execution.

orderCode

Internal unique string code of the corresponding order chain in the system.

updateOrderId

Internal numeric id of an updated order.

version

Numeric version of the account to which this execution relates. Client can use this value to find out which of the updates is more recent (its version is greater). See Numbers.

clientOrderId

Unique order id assigned by the client during order placement. See Client-originated Identifiers.

actionCode

Internal unique code of the last order modification. String value.

instrument

Symbol of the instrument

status

State of the order after this execution. See Order Statuses.

finalStatus

Boolean value indicating if order is in final state after this execution.

filledQuantity

Quantity filled so far in units (not in lots); signed value. If no fills took place, this field equals to 0.0.

remainingQuantity

Quantity available for further execution after this execution (in units).

remainingCashQuantity

Cash (notional) quantity available for further execution after this execution. Not zero only if order was created with cash quantity.

lastQuantity

The quantity of the fill, reported by the execution in units (not in lots); signed value. If the execution is not a fill, this field equals to 0.0.

lastPrice

For executions of TRADE execution type, price of the trade. Omitted for all other execution types.

averagePrice

Volume-weighted average price of all fills for this order up to (and including) this execution. The value equals to lastPrice if an order is filled with a single trade.

transactionTime

Timestamp of this execution in UTC. See Times and Dates.

rejectReason

If an order is rejected, this field contains a human-readable reject reason. In this case rejectCode field is also present.

rejectCode

Numeric code of an error in case of order rejections. Present (along with rejectReason) only if an order has been rejected.

7.11. Cash Transaction

account

Code of the account the transaction belongs to. See Account Code.

transactionCode

Unique string code of the transaction.

orderCode

Internal unique string code of the corresponding order chain in the system. Absent if transaction is not related to an order.

tradeCode

Unique string code of the trade. Corresponds to executionCode of a trade Execution.

version

Numeric version of the account to which this transaction relates. Client can use this value to find out which of the updates is more recent (its version is greater). See Numbers.

clientOrderId

Unique order id assigned by the client during order placement. See Client-originated Identifiers.

type

Transaction type. One of COMMISSION, FINANCING, DEPOSIT, WITHDRAWAL, COST, SETTLEMENT, EX_DIVIDEND, REBATE, MANUAL_CORRECTION, BUST, SERVICE_CHARGE, DIVIDEND, EXPIRATION, DELISTING, SPIN_OFF, RENAME, MERGER_ACQUISITION, SPLIT, EXERCISE, POSITION_UPDATE

value

Amount of the transaction in account’s base currency, signed (positive means profit, negative means loss).

currency

Currency of the transaction (see Currencies).

transactionTime

Timestamp of this transaction in UTC. See Times and Dates.

createdTime

Timestamp in UTC of this transaction request creation. It could take some time till actual transaction happens, exact transaction time is shown in transactionTime field. See Times and Dates.

7.12. Instrument Subscription

types
(optional)

List of instrument types to subscribe to. If this and instruments fields are presented, subscribes to concrete instruments of selected types.

instruments
(optional)

List of instrument symbols to subscribe for.

The '*' (asterisk) wildcard indicates any number of any characters.

Examples:

  • symbols=[EUR/USD] – an instrument with the EUR/USD symbol

  • symbols=[EUR/*] - all instruments with EUR as first currency and

  • symbols=[*.sb] - all spread bets

  • symbols=[EUR/USD,AAPL,GOOG] – three instruments with symbols of EUR/USD, AAPL, GOOG.

The system can be configured to permit subscription for updates on all instruments in the system. In this case this both fields should be absent.

7.13. Instrument List

instruments

List of Instrument object.

7.14. Instrument Batch

instruments

List of Instrument object in batch.

batchIndex

Batch index in a queue.

isLastBatch

true if the current list of instruments is the last batch in a queue.

7.15. Instrument

type

Instrument type as configured on the platform (e.g. INDEX).

symbol

Unique instrument symbol

version

Version of the instrument. Numeric value

description

Description of an instrument

tradingStatus

Instrument’s trading status.

priceIncrement

Specifies the minimum price difference by which the instrument’s price can be changed. It is represented as a String. For more detailed information, you can refer to the PriceIncrements.

For example, if the priceIncrement is "0.0001," it means that the price of the instrument can change in increments of 0.0001.

Examples:

  • priceIncrement=0.0001 - Simple Increment

  • priceIncrement=0.1 1.0; 0.5 10.0; 100.0 - Multiple increments and ranges

    • Increment of 0.1 for the range from 0.0 (inclusive) to 1.0 (exclusive).

    • Increment of 0.5 for the range from 1.0 (inclusive) to 10.0 (exclusive).

    • Increment of 100.0 for the range from 10.0 (inclusive) to infinity.

  • priceIncrement="" - Empty string uses sole increment with value 0.

pipSize

Size of 1 PIP in the system (e.g. 0.001), see Numbers.

currency

Trading currency of the instrument

lotSize

Lot size of the instrument

multiplier

Multiplier of the instrument

underlying

Symbol of the underlying instrument. Omitted if an instrument has no underlying.

product

Symbol of the product instrument (e.g. DJIA).

optionDetails

Details of an option instrument. If the instrument is not an option, this field is absent. See Option Details.

expirationDetails

Expiration details for derivative instruments (such as Futures or Options). See Expiration Details.

settlementType

For derivative instruments (such as Options and Futures) contains settlement type for the contract (either CASH or PHYSICAL). Absent for non-derivatives

firstCurrency

For Forex instruments, contains the first currency in pair (e.g. EUR for EUR/USD). Absent for all the other instrument types.

tradingHours

Trading calendar for this as a list of See Instrument Session objects. Sessions are order by time.

currencyType

For Currency instruments contains the currency type(FIAT, CRYPTO_CURRENCY or CRYPTO_TOKEN). Absent for all the other instrument types.

marginRates

Instrument’s margin rates in case of Stocks (also ETF, CFD-Stock, SB-Stock) in percents.

Example:

{
    "initialMarginRateLong": "10.8%",
    "initialMarginRateShort": "10.8%",
    "maintenanceMarginRateLong": "10.8%",
    "maintenanceMarginRateShort": "10.8%"
}

futuresMarginRequirements

Instrument’s margin requirements in case of Futures (also CFD-Futures, SB-Futures). Simple dollar values, not percents.

Example:

{
    "futuresInitialMarginRequirement": 3.5,
    "futuresMaintenanceMarginRequirement": 3.7
}

additionalFields

Additional fields which are set on the instruments

7.16. Option Details

strike

Strike of the option. See Numbers.

optionSide

Either CALL or PUT

optionStyle

Either EUROPEAN or AMERICAN

sharesPerContract

Number of shares per option contract. See Numbers.

7.17. Expiration Details

maturityDate

Instrument’s maturity date in month-year format. String value.

expirationDate

UTC date of the expiration of the contract. See Times and Dates.

lastTradeDate

UTC date of the last trading date of the contract. See Times and Dates.

7.18. Instrument Session

weekDay

UTC week date the event occurs (e.g. Monday, 23:00:00Z). See Times and Dates.

eventType

Either SESSION_OPEN or SESSION_CLOSE.

7.19. Account Metrics Request

accounts

List of account codes. See Account Code. Required for request type LIST.

requestType

Type of request. Possible values:

ALL

requests info for all accounts,

LIST

returns info for enumeration from accounts field.

includePositions

Boolean value. If true, result will include individual per-position metrics as Position Metrics objects, otherwise omitted.

7.20. Account Metrics List

metrics

List of Account Metrics objects.

7.21. Account Metrics

account

Code of the account. See Account Code.

version

Numeric version of the account. Client can use this value to find out which of the updates is more recent (its version is greater). See Numbers.

equity

Balance + SUM(Market Value across positions)

balance

Total balance of the account in account’s base currency

availableFunds

The "available funds" of the account in the account’s base currency.

availableBalanceForWithdrawal

Amount of money (in account’s base currency) available for withdrawal.

openPl

Open (Unrealized) Profit/Loss.

initialMargin

Initial margin

maintenanceMargin

Maintenance margin

maintenanceExcess

Excess of maintenance margin

dayClosedPl

Day Realized PL

netLiquidation

Net Liquidation value

openPositionsCount

Number of open (non-zero quantity) positions on tradable instruments

openOrdersCount

Number of order chains in non-final state

autoLiquidationPeak

The portfolio peak that defines the Max Drawdown auto liquidation threshold. The calculation formula depends on Max Drawdown mode.
Won’t be present if Max Drawdown validation is disabled.

maxDrawdown

The portfolio peak that defines the Max Drawdown auto liquidation threshold. The calculation formula depends on Max Drawdown mode.
Won’t be present if Max Drawdown validation is disabled.

drawdownMode

  • Real-time Trailing - Max Drawdown moves relative to Auto Liquidation Peak, which constantly updates.

  • Daily Trailing - Max Drawdown moves relative to EOD Net Liquidation/Equity, defined at EOD.

  • Static - Max Drawdown is fixed at a value.

Won’t be present if Max Drawdown validation is disabled.

trailingDrawdownDelta

Trailing drawdown delta
Won’t be present if Max Drawdown validation is disabled.

staticMaxDrawdown

A fixed drawdown threshold that does not change with the portfolio’s performance.
Won’t be present if Max Drawdown validation is disabled.

positions

If specified during request, contains a list of individual position metrics as Position Metrics objects, otherwise omitted.

7.22. Position Metrics

version

Numeric version of the account. Client can use this value to find out which of the updates is more recent (its version is greater). See Numbers.

symbol

Symbol of the position’s instrument.

quantity

Current quantity of the position in units (not in lots); signed value. See Numbers.

openPl

Floating profit-loss in account’s base currency

initialMargin

Initial margin in account’s base currency

maintenanceMargin

Maintenance margin in account’s base currency

markPrice

Mark price

dayClosedPl

Realized PL for the current business day for the position

avgOpenPrice

Average price for the position

7.23. Account Event List

accountEvents

List of Account Event objects.

7.24. Account Event

account

Code of the account. See Account Code.

eventType

One of the following values:

  • MARGIN_CALL

  • LIQUIDATION

reason

Account event reason message

7.25. Cash Transfer List

cashTransfers

List of Cash Transfer objects.

7.26. Cash Transfer

account

Code of the account the transaction belongs to. See Account Code.

version

Numeric version of the account to which this transaction relates. Client can use this value to find out which of the updates is more recent (its version is greater). See Numbers.

transferCode

Unique code of a transfer. String value. Can be absent if this transfer is originated from a trade.

comment

Transfer comment (if present)

transactionTime

Transfer’s timestamp in UTC. See Times and Dates.

createdTime

Timestamp in UTC of this transaction request creation. It could take some time till actual transaction happens, exact transaction time is shown in transactionTime field. See Times and Dates.

cashTransactions

List of all cash transactions related to this transfer. Reports are ordered chronologically. See Cash Transaction.