Order State Tracking and Events in Exchange Connectors
Summary
This developer guide explains how an exchange connector tracks orders and reports their state changes to trading strategies. A buy or sell request returns a client-side identifier promptly while submission proceeds asynchronously. Tracking should begin before the exchange placement request, and continue until the order is completed, canceled, expired, or rejected. The connector also checks trading rules before submission and emits a creation or failure event based on the response.
As fills arrive, including partial fills, the connector reports each one; a completed event follows the final fill event, after which tracking ends. Cancellations and expirations have their own events. For centralized exchanges, tracking generally stops after those events, while decentralized exchanges may continue tracking because delayed blocks can allow fills after cancellation or expiry. The guide defines event ordering and lifecycle semantics for connector developers, rather than presenting a trading strategy or empirical results. Its scope is integration behavior for spot and perpetual exchange connectors within the client.
Key ideas
- Order tracking should start before the exchange request is sent.
- Connectors report each partial or complete fill through a fill event.
- A completion event must follow the final fill event, after which tracking stops.
- Cancellation, expiry, and other failures use distinct event types.
- Decentralized exchange connectors may need to keep tracking after cancellation or expiry because delayed fills can occur.
Tags
Full text
# Order Lifecycle Flowchart
!!! note
The information below are for developers building `spot` and `perp` connectors that integrate directly into the Hummingbot client. For information on developing `gateway` connectors that use [Gateway](../../../gateway/index.md), see [Building Gateway Connectors](../../../gateway/connectors.md).
Exchange connectors track status updates of all orders created in Hummingbot and emit events on status updates of its orders for the strategy modules. Be careful when implementing a new exchange connector to ensure all the status updates and emitted events adhere to the semantics defined by Hummingbot.
## Order Lifecycle Flowchart
[](../../../assets/img/connector-order-lifecycle.svg)
## Creating an Order
An order is created when a script or strategy invokes the `buy()` or `sell()` method in an exchange connector.
`buy()` and `sell()` would return immediately with a client-side order ID that Hummingbot uses to track the order's status.
They would schedule the order to be submitted to the exchange as soon as possible but would not wait for the reply from the exchange before returning.
## Order Tracking
Order tracking starts when `_create_order()` is called. It is called from within the `buy()` and `sell()` functions.
An exchange connector should keep tracking the order's status and emit events for any change of states until the order is completed, cancelled, expired, or failed.
This is done by calling `start_tracking_order()` method in the `Exchange` class. `start_tracking_order()` should be called before the API request for placing the order is executed.
## Submitting an Order
In most of our built-in exchange connectors, order submission occurs in the `_create_order()` function - although it may be different for some decentralized exchange connectors.
The `_create_order()` method is responsible for performing the necessary trading rule checks before submitting the order via the REST API.
Upon receiving a successful response, a `BuyOrderCreatedEvent` or `SellOrderCreatedEvent` would be emitted. Otherwise, a `MarketOrderFailureEvent` would be emitted. Note that despite the naming, `MarketOrderFailureEvent` is emitted even for limit orders.
## Order Being Filled
Other market participants could fill an order over time once it's live on an exchange.
Depending on the order types, i.e. limit or market, the order could be filled either immediately or after another market participant fulfils it.
For every order fill on our orders, whether partially or entirely, the exchange connector must emit an `OrderFilledEvent`, to notify the strategy modules about the order's progress.
## Order Completion
Once an order has been completely filled, the exchange connector must emit a `BuyOrderCompletedEvent` or `SellOrderCompletedEvent`.
The exchange connector would stop tracking the order afterward.
`BuyOrderCompletedEvent` or `SellOrderCompletedEvent` should always come **after** an `OrderFilledEvent` has been emitted.
## Order Cancellation or Expiry
If an order is canceled or expired before it has been completely filled, an `OrderCancelledEvent` or an `OrderExpiredEvent` should be emitted.
For centralized exchanges, order tracking should end after emitting an `OrderCancelledEvent` or `OrderExpiredEvent`.
On decentralized exchanges - since it's possible for orders to be filled after cancellation or even expiry, due to block delays - the exchange connector may keep tracking the order for a certain amount of time afterwards.
## Order Failure
If a failed order has been rejected for any reason other than cancellation or expiry, `MarketOrderFailureEvent` must be emitted.Shown in full with attribution under the source's licence. Licence: Apache-2.0
This summary was written by Stratmill's research agent from the original; it is not a copy of the source.