Documentation
Order Status and Lifespan
Orders go through various statuses and can live for defined periods of time.
Order Status
An Order can begin outside the Market, enter the Market, trade some or all of the required Transactional Tradeable Item, and then either complete, expire or be canceled. Each step in this process is indicated by the Order having a status code.
The possible Order statuses are:
- PENDING_NEW: The Order is suspended outside the Market waiting for a trigger condition.
- NEW: The Order has entered the Market and is available for matching.
- PARTIAL_FILL: The Order has been matched and had one or more executions, but is not yet completed.
- FILLED: The Order has executed its full requested quantity and has been removed from the Market.
- CANCELED: The Order has been cancelled before completion, either manually or because a Market or TimeInForce condition caused it to be removed.
- EXPIRED: The Order has been removed from the Market because the "Good Til Date" (GTD) time has passed.
PENDING_NEW
STOPMARKET, STOPLIMIT and Effective Orders are held outside of the Market in the PENDING_NEW state.
STOPMARKET and STOPLIMIT Orders remain in PENDING_NEW until the last traded price reaches or passes their Stop trigger price in the triggering direction. When that trigger condition is met, the Order is automatically converted to either a MARKET or LIMIT Order and given the status NEW.
Effective Orders wait for their time trigger to pass. When this time comes, the Order is automatically converted to either a MARKET, LIMIT, STOPMARKET or STOPLIMIT Order. If the Order becomes a STOPMARKET or STOPLIMIT Order, it remains in PENDING_NEW while its Stop trigger price is monitored. If the Order is MARKET or LIMIT, it is entered into the Market and given the status NEW.
NEW
MARKET and LIMIT Orders that are available to match have the status NEW.
Additionally, these Orders will not yet have had any executions. This is effectively the debutante stage of the Order life-cycle.
PARTIAL_FILL
When a MARKET or LIMIT Order is working, and has one or more executions, but has not yet completed, it will have status PARTIAL_FILL.
Orders in PARTIAL_FILL state are available for matching, but their remaining quantity is reduced to reflect the quantity already executed.
FILLED
MARKET and LIMIT Orders that fully execute their requested quantity are given the status FILLED.
These Orders are removed from the Market and play no further active part in the Market. This is the successful conclusion of the Order life-cycle.
The next step is that an Owner of the Market can poll for Fill data and begin the settlement and fulfilment process in the calling application.
CANCELED
Orders can be removed voluntarily from the Market before completion, and are given the CANCELED status.
The trader that entered the Order can cancel it at any point in the life-cycle, before it is fully FILLED. A FILLED Order is completed and does not need to be canceled.
Markets can have automatic expiry dates, to close them at a configured point in time. For example, a Market for tickets would not want to be open after the event that the tickets are for has occurred. When the Market expires, all working Orders are removed, and given the CANCELED status.
Orders with a TimeInForce setting of DAY are automatically canceled when a Market changes to CLOSE state.
EXPIRED
Orders can have a TimeInForce setting of GTD, and that will mean they are configured with an expiry date. The matching process reviews all Orders before attempting to match them, and automatically removes Orders from the Market once their GTD time has passed.
Order Lifespan
Orders can be created such that they cancel themselves automatically. This is done using a setting called TimeInForce.
TimeInForce: GTC
GTC stands for Good Til Canceled. This is the default setting for an Order. It means that the Order will continue working indefinitely, until the trader that submitted the Order cancels it. The Order can be canceled if the Market expires, as all working Orders are canceled on Market expiry. If the Market moves to CLOSE state, the Order will work when the Market moves back to OPEN state again.
TimeInForce: DAY
DAY Orders work until the current session of the Market moves to CLOSE state. The name comes from the common practice of financial exchanges, where they run one trading session per day. A broker would ensure that they control their orders by setting their orders to expire when the market closes, and thereby the broker can be sure that they have full control of their order book.
An Owner of a Market controls how the Market changes state, so they may open and close their Markets multiple times in one day, or close their Markets very irregularly. The basic rule still applies, Orders with a TimeInForce setting of DAY will be removed from the Market when the Market moves to CLOSE state.
TimeInForce: GTD
GTD stands for Good Til Date. When an Order is set to GTD, a UTC date and time is required, which sets the point in time after which the Order will be automatically expired and removed from the Market.
If the Market is in OPEN or ACCEPT state, the matching loop will scan the available Orders and find Orders whose GTD time has passed, and remove those Orders.
If the Market is in CLOSE, HALT or BLOCKED state, the lapsed GTD Orders persist until the Market moves to either OPEN or ACCEPT. On the first pass of the matching loop, the Orders will be found to be lapsed and will be removed before any matching occurs.
Order Routing
Orders may originate on external websites or applications, and be forwarded to the Market by a single User. This is termed Order Routing.