Skip to main content

Order identification in Ember

This document describes concept of order identity in Ember.

Definitions​

The API follows the FIX protocol when it comes to identifying orders and requests.

Order ID​

Each API client or algorithm provides ID with each order. This textual identifier is unique only in scope of a specific order source (identified by Source ID).

Each time the order is amended, the client provides a new order ID and must specify the original order ID. Once the change is approved, the working order will be identified by the ID of the replacement order request. In case of the replace-reject, the order keeps its original identity. Users familiar with the FIX protocol will recognize this approach.

Terms Amendment, Replacement, and Modification are used interchangeably to describe OrderCancelReplace workflow.

For the convenience of handling the large chain of cancellation replaces requests, the API supports Correlation Order ID. This optional attribute matches the ID of the first order in the replacement chain.

Concept of Correlation ID can be found on trading venues like CME iLink.

External Order ID​

Trading Venues may assign their identifiers to the orders, represented as an "external order ID". These identifiers are unique only in the scope of each trading venue (identified by Destination ID and Exchange).

An external order ID is typically reported with order events and may or may not change each time the order is amended using CancelReplaceRequest.

Request ID​

To distinguish repeated attempts to cancel the same order, each CancelRequest is identified by a Request ID. This required identifier is subsequently reported in the ACK / NACK events OrderCancelEvent and OrderCancelRejectEvent cancel events.

Correlation Order ID​

When order undergoes Cancel Replace workflow each OrderReplaceRequest uses separate unique order ID and identifies which predecessor order request it replaces using Original Order ID attribute. For example, if order was replaced twice, cancel replace chain will have three order identifies - original order and two replacement requests.

For any Cancel Replace chain of messages optional attribute Correlation Order ID identifies the very first order in the chain.  This attribute can be provided by API user. OMS automatically populate this attribute for downstream messages.

ID uniqueness​

As we described above Ember uses composite {SourceID, OrderID} to identify orders internally.  Each order source may use own ID scheme.

Trading algorithms running in Ember frequently rely on Ember’s helper service to generate identifiers for their orders.

This default sequence generator algorithm works as follows:

  • On Ember start up sequence is initialized to current Linux epoch time, in microseconds (for example, 1627048166000 for June 23, 2021).
  • Each algorithm consumes its own order ID sequence during Ember run time.

The following factors should be taken in consideration

  • Current version of Ember OMS has throughput cap of 250-500 thousand of trading requests/second
  • Ember process restart takes at least few seconds. This startup time is proportional to the size of ember journal that stores past trading activity. Ember does compact journal and expunge historical orders from deep past, but remaining historical orders will be re-processed by OMS (under the same throughput cap). See ember Journal documentation for more information about Journal compaction.

Consider the following aggressive scenario:

  1. Ember start’s up at T0.
  2. Ember runs for 10 seconds during which it produces 5 million orders. Here we assume that Ember hosts only one trading algorithm (additional algorithms will share OSM throughput cap). Last order had ID T0+5,000,000.
  3. Ember restarts at T1 = T0 + 10 seconds (aggressively assuming zero seconds startup time).
  4. After restart order ID generator will be using T0+10,000,000 as order identifier base.

Order ID transformation by Trading Connectors​

Some execution venues have trading APIs that limit order ID to certain length or character type (e.g. ICE has 12 digits limit). When limitation like this is in place trading connectors may introduce an internal ID mapping (e.g. rely on order request sequence number that survives system restart).

Frequently used mapping methods are listed below:

  • Concatenation: Connector concatenates order source ID with order ID using dollar sign as separator: TWAP$1627043902
  • Request sequence: Connector uses ember journal sequence number (INT64) as order identity communicated by exchange. This sequence number is preserved on system restart. Note: in some special situations' ember journal may be deleted, in which case this sequence number will reset to 1.