DXtrade XT Amazon Simple Queue Service (Amazon SQS) API Specification

Introduction

This document is a high-level specification for the Devexperts DXtrade XT Amazon SQS API. The API complements the "DX Notification API" with reliable message delivery via Amazon Simple Queue Service.

The API is aimed to support a "B2B" integration when all the updates about events happening with accounts in the platform are streamed over a reliable channel without explicit subscription.

Every type of messages is sent to a separate pre-configured Amazon SQS queue. The following types of messages are supported:

• Account Portfolio Incremental Updates
• Instruments
• Account Metrics
• Account Events
• Cash Transfers

A list of pre-configured Amazon SQS queues for the required message types will be provided by DXtrade XT when setting up the system. It is possible to configure multiple Amazon SQS queues for a single message type. In this case, all messages will be sent to each queue.

The DXtrade XT Amazon SQS API encodes its messages in JSON (application/json).

Please, see SQS Developer Guide

Amazon provides AWS SDK for many popular programming languages.

AWS SDK requires the following properties:

These properties will be provided by DXtrade when setting up the system.

Example

String endpoint = ...;
String region = ...;
String accessKeyId = ...;
String secretAccessKey = ...;
String accountId = ...;

SqsClient sqsClient = SqsClient.builder()
        .endpointOverride(URI.create(endpoint))
        .region(Region.of(region))
        .credentialsProvider(
                StaticCredentialsProvider.create(
                        AwsBasicCredentials.builder()
                                .accessKeyId(accessKeyId)
                                .secretAccessKey(secretAccessKey)
                                .accountId(accountId)
                                .build()
                )
        ).build();

String queueName = ...;
String queueUrl = sqsClient.getQueueUrl(
        GetQueueUrlRequest.builder()
                .queueName(queueName)
                .build()
).queueUrl();

List<Message> messages = sqsClient.receiveMessage(
        ReceiveMessageRequest.builder()
                .queueUrl(queueUrl)
                .maxNumberOfMessages(10)
                .build()
).messages();

// Process messages here
// ...

List<DeleteMessageBatchRequestEntry> entries = messages.stream()
        .map(message -> DeleteMessageBatchRequestEntry.builder()
                .id(message.messageId())
                .receiptHandle(message.receiptHandle())
                .build()
        ).toList();

sqsClient.deleteMessageBatch(
        DeleteMessageBatchRequest.builder()
				.queueUrl(queueUrl)
				.entries(entries)
				.build()
);

Pricing

Amazon charges for SQS API requests. DXtrade XT Amazon SQS API uses FIFO queues. Please, see Amazon SQS pricing for details.

API Versioning :id=api-versioning

The DXtrade XT Amazon SQS API attempts 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, when dealing with JSON representation, clients should avoid coupling their logic with the current JSON structure. This way, adding new fields won't disrupt their application's functionality, allowing adding new data into resources without breaking client systems.

Entity Versioning

The DXtrade XT Amazon SQS API supports the notion of entity versions. Each business entity, like an account, is assigned a version number that increases monotonically with any changes. By comparing these versions, one can determine the sequence of updates: the entity with the most recent changes will have the highest version number.

Message Envelope :id=message-envelope

The Amazon SQS API is based around asynchronous JSON-encoded messages sent from the DXtrade XT system to the Amazon SQS. Each message contains the following fields:

Also, for account metrics compact format is supported, where fields names are present in a short form and zero fields are not present.

Example

{
    "type": "SomeMessageType",
    "timestamp": "2024-08-06T08:30:05.469Z",
    "payload": {
        ...
    }
}

Account Portfolio Incremental Updates

The API allows to retrieve updates of account portfolio for all accounts. A portfolio contains information about open positions and working orders on an account.

This API allows to retrieve only updated fields of Account Portfolio instead of the whole chunk of data with each message. It makes the messages significantly smaller which improves performance and allows not to lose data on accounts with large amount of orders and executions.

Account Portfolio Incremental Updates are fired whenever following changes are made 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 only updated orders, positions and executions whenever any change on account is made. It means, that you will see every update only once, including non-closed orders and positions, and those updates should be applied in the order of account version. All the other fields like balances or account code are always sent on any update, same as for Account Portfolio queue. Client may use account version in the portfolio message to track the order of updates.

The system sends an initial snapshot of all account portfolios and then starts streaming updates as soon anything changes on the account.

Message Format

The following message is used to send account portfolio incremental updates:

Example

{
    "type": "AccountPortfolioIncrementalUpdates",
    "timestamp": "2022-07-27T14:50:30.238Z",
    "payload": {
        "portfolios": [...]
    }
}

Instruments

This API allows to retrieve instrument updates. Updates are sent sequentially whenever new instruments are created, existing instruments are deleted, or any instrument fields are updated.

The system sends an initial snapshot of the data for all instruments and then starts sending updates.

Message Format

The following message is used to send instruments:

Example

{
    "type": "Instruments",
    "timestamp": "2022-07-27T14:50:30.238Z",
    "payload": {
        "instruments": [...]
    }
}

Account Metrics

The API allows to retrieve updates of account metrics (such as PnL and margin) for all accounts. Updates are sent periodically (with server-configured frequency).

For accounts without trading activity, metrics updates are sent less frequently (this frequency is also configured on the server).

For account metrics 'compact' message format is supported, where fields names are present in a short form and zero fields are not present. It will be enabled by default in one of the upcoming releases.

Message Format

The following message is used to send account metrics:

Compact Message Format

The following message is used to send account metrics:

Example

{
    "type": "AccountMetrics",
    "timestamp": "2022-07-27T14:50:30.238Z",
    "payload": {
        "metrics": [...]
    },

    "type":"AccountMetrics",
    "timestamp":"2026-04-28T15:14:15.007Z",
    "payload": { 
        "metrics":[
            {
                "account":"default:dma1acc3_demo",
                "version":126,
                "equity":9999686.18,
                "balance":9998138.52,
                "openPL":75.485,
                "initialMargin":1412.08,
                "maintenanceMargin":1392.89,
                "availableFunds":9998274.10,
                "availableBalanceForWithdrawal":9998293.29,
                "maintenanceExcess":9998293.29,
                "dayClosedPl":0.0,
                "netLiquidation":9999686.18,
                "openPositionsCount":2,
                "openOrdersCount":0,
                "maxDrawdown":"NaN",
                "autoLiquidationPeak":"NaN",
                "drawdownMode":"REAL_TIME_TRAILING",
                "trailingDrawdownDelta":2000.0,
                "staticMaxDrawdown":0.0,
                "positions":[
                    {
                        "version":126,
                        "symbol":"MSFT",
                        "markPrice":425.5,
                        "dayClosedPl":0.0,
                        "avgOpenPrice":405.4717,
                        "openPl":60.085,
                        "initialMargin":1276.5,
                        "maintenanceMargin":1148.85,
                        "quantity":3.0
                    },
                    {
                        "version":126,
                        "symbol":"AAPL",
                        "markPrice":271.16,
                        "dayClosedPl":0.0,
                        "avgOpenPrice":255.76,
                        "openPl":15.4,
                        "initialMargin":135.58,
                        "maintenanceMargin":244.04,
                        "quantity":1.0
                    }
                ]
            }
        ]
    }
}

Account Events

The API allows to retrieve various 'events' regarding the account, such as liquidations or margin calls. Events are sent sequentially whenever any of these changes happen with the account:

• A margin call happens
• An account is liquidated

Message Format

The following message is used to send account events:

Example

{
    "type": "AccountEvents",
    "timestamp": "2022-07-27T14:50:30.238Z",
    "payload": {
        "accountEvents": [...]
    }
}

Cash Transfers

The API allows to retrieve cash transfers (such as deposits, withdrawals and PnL settlement) on all accounts.

Message Format

The following message is used to send cash transfers:

Example

{
    "type": "CashTransfers",
    "timestamp": "2022-07-27T14:50:30.238Z",
    "payload": {
        "cashTransfers": [...]
    }
}