Integration guide

See Releases & Changelog for API changes, compatibility, and downloads.

Introduction

The API enables clients to have enhanced control over their XCore environment and manage every aspect of the system in the most efficient way. It gives great flexibility to the clients, allowing integration with any internal systems and logic available.

The API can be used for these purposes:

• receive current XCore configuration
• make changes through commands to the current XCore configuration (e.g. markups, enable flags, etc.)
• request account data for margin, risk, commissions, etc.
• make changes to the account data (e.g. deposits, withdrawals, position amendments, etc.)

XCore API RabbitMQ Client

To facilitate integration to the PrimeXM XCore Configuration API, XCoreApiRabbitMqClient implementations have been made available in Java and C# programming languages.

The XCoreApiRabbitMqClient is a class responsible for session connectivity, session re-connect, and XCore API data subscription handling.

Client integration to the PrimeXM Configuration API using the XCoreApiRabbitMqClient consists of the following steps:

• Create XCoreApiRabbitMqClient using the provided connection settings/credentials.
• Assign onAuthenticated, onMessage, onError handlers (as per PxmMessageHandler interface implementation in Java or by subscribing to specific events in C#).
• Call respective connection methods to initiate the login process.
• API subscriptions/requests can be called after a successful authentication event

Connectivity

Connecting via the API will be available during market hours (i.e. from SUN 17:00:00 EST to FRI 17:00:00 EST). Outside of the market hours access will still be available, however, during system maintenance windows, access may be revoked.

Communication via the XCore API is SSL encrypted, therefore connections via Internet are supported. Additionally, clients can connect via site-to-site VPN or dedicated x-connects.

Messages

Session Messages

A communication channel with the PrimeXM servers is established with the following steps:

• using RabbitMQ client library and provided configuration parameters, establish a connection to the PrimeXM RabbitMQ broker (due to security reasons only TLS 1.2 and TLS 1.3 encrypted connections are supported)
• initiate a session by sending QueueAuthenticationRequest message with the correct username and password combination
• upon receiving a successful QueueAuthenticationResponse message communication channel is ready
• when XServer closes the session, a QueueSessionReset message is sent.

Note:

• all RabbitMQ messages must have property “replyTo” set to “amq.rabbitmq.reply-to” to ensure successful reply delivery
• QueuePing and QueuePong message combination can be used as the heartbeat mechanism

Application Messages

Retrieving data

The API uses a subscribe approach for retrieving the data. The client can request (i.e. subscribe) to receive updates regarding specific resources/components, including in the request message a unique RequestID. However please note that there is a limit of 10 subscriptions per specific resource/component per session.

The initial reply will contain the current configuration for the requested resource or component or an error message if the subscription limit for the requested resource/component is reached. Moving forward, any changes to the data the client is subscribed to will trigger an update message to be pushed via the API. In the case of a refresh of the XCore environment, a snapshot of the up-to-date configuration subscribed to will be pushed via the API. All such response messages will contain the unique RequestID specified by the client in the request message.

Note: the components that the client can subscribe to follow a flat structure and are split into 3 categories: the Subscription, Static and Historic Data Access components.

Subscription Data Access Components

Subscription Data Access Components will automatically receive an update message to any changes to the data or in case of a refresh of the XCore environment in order to obtain the snapshot of the up-to-date configuration.

Subscription Data Access Component Types are as follows:

• Account Component Data Types
  • AccountData
  • AccountPositionData
  • AccountExposure
  • AccountPnlDelta

XServer also sends Reset notifications to existing account-data subscribers when their cached data must be cleared. Reset is a control notification, not a separate data component to subscribe to.

Note:

• Subscription – Update response communication method is implemented for the Account Component Data Types which allows receiving the respective data, as well as triggering an update message to be pushed via the API.
• Account and Position update operation requests are available via the below Account module operations requests:
  • AccountApiOperationRequest_AccountUpdate
  • AccountApiOperationRequest_PositionUpdate

Upon receiving Account and Position update operation requests the system will send an AccountApiOperationResponse as a confirmation. This does not guarantee that the response received with a specific request ID will contain the change request since between request and response other changes might occur.

For example, the system may send a single AccountApiResponse_AccountPosition refresh for the bulk of deals or changes that took place. The request ID of a refresh message will hold the last request ID that was not equal to -1 in this specific bulk. This would therefore mean that not necessarily the amount on refresh with a specific request ID would be the same as expected since the updates occur all the time, and positions might be changed at any moment between updates.

• Configuration Component Data Types

Note:

• The Configuration Component Data Types listed above identify the data available for subscriptions.
• Configuration Component Data Types which have respective update requests can trigger an update message to be pushed via the API.

For example, in the case of the configuration settings for the XCore, if it is required to receive all the configurations for the connector accounts, then the client must subscribe to the respective Configuration Component Data Types.

> Connector
> ConnectorAccount
> ConnectorAccountSymbol

• Configuration Component Data Type responses include a new field called UpdateType with the below possible values:
  • Replace – for a full refresh response
  • Update – for incremental refresh response
  • Remove – the listed items were deleted

Static Data Access Components

Static Data Access Components will receive message response upon request.

Static Data Access Component Types are as follows:

• ConnectorType
• ConnectorAccountMode
• ConnectorStreamMode
• PoolExecMode
• LqProfileSpread
• LqSource
• SecurityType
• ProviderType
• MarkupType
• ModuleState
• TradeLockBy
• TradeLockOrderType
• TradeLockUnit
• TradeLockMode
• TradeLockRefPrice
• DealerValueDateHolidays
• AccountGroupTypes
• AccountGroupKeys
• GiveupDataMode
• PrecisionType

The list follows the ConfigReferenceType enum of ApiEnums.proto; a reference is requested with ConfigApiReferenceRequest and answered with ConfigApiReferenceResponse.

Note: Static Data Access Components allow requests to retrieve the respective data as a dataset in a single response

Historic Data Access Components

Historic Data Access Components will receive message responses upon request.

Historic Data Access Component Types are as follows:

• AccountApiHistoryRequestAccount
• AccountApiHistoryRequestPosition

Note:

• Historic Data Access Component Types allow requests to retrieve the respective data as a dataset in a single response

Update requests

The API supports update requests which allow the client to make changes to specific resources/components. Update requests for several components of the same component type might be submitted at once.

• In order to receive the new configuration of the resources/components after the update has been performed the client has to be subscribed to receive changes for the respective components.

For example, if several MarkupProfileSettings need to be changed, then all update requests might be sent in one request. However, the response will be received in a form of a subscription notification with the same requestId.

• If updates do not pass basic validation, the server is unavailable or other errors occur, ConfigApiResponse will be sent with descriptions of the identified issues
• Update requests are supported only for the Account Component Data Types and for the Configuration Component Data Types with the same change as per the PrimeXM GUI functionality.

Connector route requests

Connector routes support add, update and delete operations:

To receive route data, subscribe using ConfigObjectType.ConnectorRouteAdd. ConnectorRouteUpdate and ConnectorRouteDelete identify write operations, not separate subscriptions.

Supported API messages

The ApiEnums.proto file contains all available object types and their respective code segments. The structure of all requests, objects, and messages used are contained in the respective .proto files. All files are contained in the XCore API JAR library.

• If a GUI user makes changes to any of the above-mentioned components, then an update message will also be sent via the XCore API.

Client Implementation Example

With the XCore Configuration API libraries, several implementation examples are provided:

FailoverProvider – ready to use console application. Allows switching the Liquidity Pool settings and link a Liquidity Pool to the selected Failover Liquidity Provider, as well as revert to the previously saved Liquidity Pool provider parameter settings.
ScheduledMarkups – ready to use console application. Allows switching the Markup Profiles assigned on a Connector Account and/or Connector Stream level based on the defined schedule.
AccountOperations – an example demonstrating the use of the XCore Configuration API to adjust the balance of XCore Accounts.
ConfigOperations – an example demonstrating the use of the XCore Configuration API to adjust system settings for several XCore components.
MultiHandler – an example demonstrating the use of the XCore Configuration API in handling various subscriptions/response messages over a single application to obtain XCore component parameters.

Download libraries, protocol files, JavaDoc, and examples from the Releases & Changelog.

Possible Configuration API Errors

If something goes wrong in a Configuration API request, an error or warning will be thrown.

• In case QueueErrorResponse = Unexpected Exception, we have the following error types:
  • GeneralError // Any other error; the description is in the message
  • SessionNotFound, // Must reconnect. The session disconnected or the server was restarted and all sessions dropped
  • UnknownMessage, // Must check that API version is up to date. The message ids were parsed successfully but they are not supported anymore or yet  
  • SerializationFailure // Must check that API version is up to date. The message received is in a completely unknown format

Note: Every Saturday we are restarting Xserver which is dropping all connections to the Configuration API as well. So after this, if the application is having no persistence, it will need to reconnect again by bouncing back the connection.

XCore API Languages

To connect and interact using the XCore API, any language supported by both RabbitMQ and ProtoBuf can be used:

• for RabbitMQ clients – https://www.rabbitmq.com/devtools.html
• for Protocol Buffers – https://developers.google.com/protocol-buffers/docs/reference/other

Overview of steps needed:

• choose the language of choice that is supported by both RabbitMQ and ProtoBuf
• get the respective RabbitMQ client for the respective language
• using a compiler for Google ProtoBuf, compile the proto files of the release (Accounts.proto, ApiEnums.proto, Configuration.proto, General.proto and Modules.proto) to create a library for the respective language
• use the above 2 points to connect via RabbitMQ and request messages from the XCore API using ProtoBuf

Glossary

• RabbitMQ – https://www.rabbitmq.com/
• Protobuf – https://developers.google.com/protocol-buffers/

Resources

• Protobuf Editor – http://protobufeditor.sourceforge.net/

Disclaimer

PrimeXM endeavours to ensure that the data and other material in this publication are correct and complete but do not accept liability for any error herein or omissions.