Order management

Overview

There are a number of functions provided by MarketGrid for Order Management. These are:

• Order Hold/Release
• Order Cancel
• Order Amend

Each of these is described in the following sections.

Order Hold/Release

An Order may be held or released by a User that has appropriate permissions for the operation on the Order. The UpdateUser will reflect the User that held the Order.

Holding an Order means that it is taken out of the market and will not participate in the Order Book for matching. It is effectively moving the Order to a 'blotter' from where it may be released to the market at a later time.

An Order that is held will have its Status set to Held and it will be removed from the Order Book (if it is currently in an Order Book). There is no effect on any Trades that have already been generated for the Order.

While it is held, an Order may be amended or cancelled. If it is amended, the new Order that results from the amendment will remain in the held state.

An Order that is held can be released at any time. When an Order is released, it will be validated as if it was a new Order being entered into the market. If any validation fails, the Order will remain in a held state. Otherwise, the Order will be placed into the Order Book at end of the time-priority list for its price (since it is considered a new Order coming into the market). The Status of an Order that has been released is Active. Again, the UpdateUser will reflect the User that released the Order.

Holdings and Limit Positions for Hold/Release

When an Order is held, if Holdings are being tracked, PlannedBuy, PlannedSell and AvailableBalance positions in Holdings (for both securities and cash) are adjusted as the Order is no longer in the market. When the Order is released, Holdings positions will be checked and adjusted in the normal manner for the Order's current balance as if it was a new Order.

When an Order is held, if limit positions are being tracked, PlannedBuyVal and PlannedSellVal positions for the Order's Firm, User and Account limits are adjusted as the Order is no longer in the market. When the Order is released, limit positions will be checked and adjusted in the normal manner for the Order's current value balance as if it was a new Order.

Order Cancel

An Order may be cancelled by a User that has appropriate permission for the operation on the Order. The UpdateUser will reflect the User that cancelled the Order.

Cancelling an Order means that it is taken out of the market and is no longer able to participate in the Order Book for matching. Once an Order is cancelled, there is no way to un-cancel it, cancel is a terminal state.

An Order that is cancelled will have its Status set to Cancelled and it will be removed from the Order Book (if it is currently in an Order Book). There is no effect on any Trades that have already been generated for the Order.

Note that an Order may be effectively cancelled by the System, independent of any action by a User, for example, if an Order expires, the System will cancel it. In this case, the Order's Status will be set to Withdrawn which indicates that this was a System rather than a User action.

Holdings and Limit Positions for Cancel

When an Order is cancelled, if Holdings are being tracked, PlannedBuy, PlannedSell and AvailableBalance positions in Holdings (for both securities and cash) are adjusted as the Order is no longer in the market.

When an Order is cancelled, if limit positions are being tracked, PlannedBuyVal and PlannedSellVal positions for the Order's Firm, User and Account limits are adjusted as the Order is no longer in the market.

Order Amend

An Order may be amended by a User that has appropriate permission for the operation on the Order.

Amending an Order means that one or more of the Order's field values are changed.

The amended Order's Status is changed to Amended and it is replaced with a new Order that has the field value changes that were specified in the amendment transaction.

The amended Order is taken out of the market and is no longer able to participate in the Order Book for matching.

As such, the terminal Amended Order record shows the UpdateUser as the User who amended the Order. The new replacement Order record retains the OriginatingUser of the original Order, but CreateUser, OwnerUser and UpdateUser will reflect the amending User.

There is no effect on any Trades that have already been generated for the amended Order, they continue to reference the amended Order. Any further trades will reference the new Order. Thus, Trades always reference the specific Order for which they are generated.

The new Order is placed into the Order Book. The time-priority of the new Order depends on what fields were amended – it may retain the priority of the amended Order or it may enter the Order Book with a new (lowest) priority (see section Fields that may be Amended)

Holdings and Limit Positions for Amend

When an Order is amended, if Holdings are being tracked, PlannedBuy, PlannedSell and AvailableBalance positions in Holdings (for both securities and cash) are checked and adjusted according to the change (if any) to the Order's securities and cash balances.

When an Order is amended, if limit positions are being tracked, PlannedBuyVal and PlannedSellVal positions for the Order's Firm, User and Account limits are checked and adjusted according to the change (any) to the Order's value.

Amended Order Status

Amended Order

When an Order is amended, its Status will be set to Amended. In this state, the Order can no longer be further amended, cancelled or otherwise managed. It will be removed from the Order Book (if it is currently in an Order Book) and it will not participate in the market – amended is a terminal state.

New Order

The Status for the new Order that is created as a result of an amendment to an existing Order depends on several factors.

If the TotalQuantity of the new Order is equal to the amount that has already been matched for the Order being amended, effectively setting the TotalBalance for the new Order to zero, the new Order will be cancelled immediately and its Status will be Cancelled.

If the Order being amended currently has Status Held, the new Order will have that Status and the new Order will be held.

Otherwise the new Order will have Status Active and will be available in the Order Book to be matched. The priority of the new Order in the Order Book depends on which fields were amended and their values (see section Fields that may be Amended).

Fields that may be Amended

The following table describes the fields that may be Amended for an Order and indicates whether amending the field will result in the new Order losing its time-priority in the Order Book.

Order Amend High-Level Flow

The following diagram illustrates the high-level logic flow for an amendment, showing what happens to the Amended Order and the New Order that is generated by the amendment.

graph TD
  A[Amend Transaction] --> B{Parameters valid?}
  B -->|Yes| D[Generate new order]
  B -->|No| C[Reject transaction]:::red
  D --> o2
  D --> E{Balance zero?}
  E -->|Yes| F[Cancel new order]
  F --> n1
  E -->|No| G{Amended order held?}
  G -->|Yes| H[Hold new order]
  H --> n2
  G -->|No| I{Lose Priority?}
  I -->|Yes| J[Add to book]
  J --> n3
  I -->|No| K[Replace in book]
  K --> n3
  subgraph Original order
    o1{{Active}}:::green
    o2{{Amended}}:::red
  end
  subgraph New order
    n1{{Cancelled}}:::red
    n2{{Held}}:::yellow
    n3{{Active}}:::green
  end
  classDef red fill:#fcc
  classDef green fill:#cfc
  classDef yellow fill:#ffc

Order Ids

Every Order in MarketGrid has a unique numeric Id that is generated by the System. Order Ids are unique forever and always increasing. In addition to an Id field, each Order has the fields OriginalOrder and AmendedOrder.

For a new Order that has not been amended:

• Order.OriginalOrder == Order.Id
• Order.AmendedOrder == NULL

When an Order is amended, its status will be changed to Amended and a new OrderA will be created with the amended field values. For the new OrderA:

• OrderA.OriginalOrder == Order.Id
• OrderA.AmendedOrder == Order.Id

If OrderA is subsequently amended, its status will be changed to Amended and a new OrderB will be created with the amended field values. For the new OrderB:

• OrderB.OriginalOrder == Order.Id
• OrderB.AmendedOrder == OrderA.Id

Thus, for a chain of amended Orders, the OrignalOrder field for each always has the Id of the original (first) Order in the chain and the AmendedOrder always has the Id of the amended Order immediately prior in the chain.

Example Order Id lifecycle (for one order)

A sample order lifecycle is shown below in chronological order (top down). Note that some steps occur at the same Time Step (as the system may generate 2 order updates within the one transaction, for example for Amend and also for notification of a first trade against an order).