Skip to main content

Order Identification in Ember

This document describes the concept of order identity in Ember.

Definitions​

The API follows the FIX protocol for identifying orders and requests.

Order ID​

Each API client or algorithm assigns a unique ID to each order within the context of a specific order source, which is identified by the Source ID.

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

Note: The terms "Amendment", "Replacement", and "Modification" are used interchangeably to describe the OrderCancelReplace workflow.

To simplify handling a large chain of cancellation replace requests, the API supports a Correlation Order ID. This optional attribute allows you to match the ID of the first order in the replacement chain.

Note: The concept of a Correlation ID can be found on trading venues like CME iLink.

External Order ID​

Trading venues have the option to assign their own identifiers to orders, that are represented as "external order IDs". These identifiers are unique only within the scope of each trading venue, which is identified by the 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​

In order to distinguish between repeated attempts to cancel the same order, each CancelRequest is identified by a Request ID. This identifier is required and subsequently reported in ACK/NACK (Acknowledgement/Negative Acknowledgement) events, such as OrderCancelEvent and OrderCancelRejectEvent cancel events.

Correlation Order ID​

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

For any Cancel Replace chain of messages, an optional attribute (Correlation Order ID) identifies the very first order in the chain. While API users can provide this attribute, the Order Management System (OMS) automatically populates this attribute for downstream messages.

ID Uniqueness​

As mentioned earlier, Ember uses a composite identifier of {SourceID, OrderID} to internally identify orders. Each order source may use its own ID scheme.

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

This default Order ID sequence generator algorithm works as follows:

  • On Ember start up, the sequence is initialized to the 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 starts 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 would share the OMS throughput cap). The ID of the last order generated would be T0+5,000,000.
  3. Ember restarts at T1 = T0 + 10 seconds (aggressively assuming a zero second startup time).
  4. After restart, the order ID generator uses T0+10,000,000 as the order identifier base.

Order ID Transformation by Trading Connectors​

Some execution venues have trading APIs that impose limits on the order ID, such as a maximum length or specific character type (e.g., ICE has a 12 digit limit). When limitations like this exist, trading connectors may introduce internal ID mapping mechanisms (e.g., relying on order request sequence numbers that survive system restarts).

Commonly used mapping methods include:

  • Concatenation: The connector concatenates the order source ID with the order ID, using a dollar sign as a separator. For example: TWAP$1627043902.
  • Request sequence: The connector uses the Ember journal sequence number (INT64) as the order identity communicated with the exchange. This sequence number is preserved even after system restarts. Please note that in exceptional situations, Ember journal may be deleted, resulting in the sequence number being reset to 1.