Documentation Index
Fetch the complete documentation index at: https://mintlify.com/hummingbot/hummingbot/llms.txt
Use this file to discover all available pages before exploring further.
OrderTracker is a Cython class that manages order tracking for Hummingbot strategies. It maintains state for both active orders and shadow orders (recently completed orders kept for reconciliation).
Class Definition
class OrderTracker(TimeIterator):
SHADOW_MAKER_ORDER_KEEP_ALIVE_DURATION = 60.0 * 3 # 3 minutes
CANCEL_EXPIRY_DURATION = 60.0 # 1 minute
def __init__(self):
super().__init__()
self._tracked_limit_orders = {} # Active limit orders
self._tracked_market_orders = {} # Active market orders
self._order_id_to_market_pair = {} # Order ID mapping
self._shadow_tracked_limit_orders = {} # Shadow limit orders
self._in_flight_cancels = OrderedDict() # Pending cancellations
Core Properties
active_limit_orders
List[Tuple[ConnectorBase, LimitOrder]]
Returns a list of all active limit orders (excluding those with in-flight cancels).
shadow_limit_orders
List[Tuple[ConnectorBase, LimitOrder]]
Returns a list of shadow limit orders kept for reconciliation.
active_bids
List[Tuple[ConnectorBase, LimitOrder]]
Returns all active buy limit orders.
active_asks
List[Tuple[ConnectorBase, LimitOrder]]
Returns all active sell limit orders.
market_pair_to_active_orders
Dict[MarketTradingPairTuple, List[LimitOrder]]
Returns a dictionary mapping market pairs to their active limit orders.
tracked_limit_orders
List[Tuple[ConnectorBase, LimitOrder]]
Returns all tracked limit orders (active and shadow).
tracked_market_orders
List[Tuple[ConnectorBase, MarketOrder]]
Returns all tracked market orders.
Returns a dictionary of order IDs with pending cancel requests and their timestamps.
in_flight_pending_created
Returns a set of order IDs that are pending creation confirmation.
DataFrames
tracked_limit_orders_data_frame
@property
def tracked_limit_orders_data_frame(self) -> pd.DataFrame:
"""
Returns a DataFrame with columns: market, trading_pair, order_id, quantity, timestamp
"""
DataFrame containing all tracked limit orders with their details.
tracked_market_orders_data_frame
@property
def tracked_market_orders_data_frame(self) -> pd.DataFrame:
"""
Returns a DataFrame with columns: market, trading_pair, order_id, quantity, timestamp
"""
DataFrame containing all tracked market orders with their details.
Order Tracking Methods
start_tracking_limit_order
def start_tracking_limit_order(
self,
market_pair: MarketTradingPairTuple,
order_id: str,
is_buy: bool,
price: Decimal,
quantity: Decimal
):
"""
Starts tracking a limit order. Creates both active and shadow tracking entries.
"""
The market and trading pair for this order.
The unique order identifier (client_order_id).
True for buy orders, False for sell orders.
The order quantity in base asset.
stop_tracking_limit_order
def stop_tracking_limit_order(
self,
market_pair: MarketTradingPairTuple,
order_id: str
):
"""
Stops tracking an active limit order. Moves it to shadow tracking for
SHADOW_MAKER_ORDER_KEEP_ALIVE_DURATION (3 minutes).
"""
The market and trading pair for this order.
The order identifier to stop tracking.
start_tracking_market_order
def start_tracking_market_order(
self,
market_pair: MarketTradingPairTuple,
order_id: str,
is_buy: bool,
quantity: Decimal
):
"""
Starts tracking a market order.
"""
The market and trading pair for this order.
The unique order identifier.
True for buy orders, False for sell orders.
The order quantity in base asset.
stop_tracking_market_order
def stop_tracking_market_order(
self,
market_pair: MarketTradingPairTuple,
order_id: str
):
"""
Stops tracking a market order.
"""
The market and trading pair for this order.
The order identifier to stop tracking.
Order Retrieval
get_limit_order
def get_limit_order(
self,
market_pair: MarketTradingPairTuple,
order_id: str
) -> LimitOrder:
"""
Retrieves a tracked limit order.
"""
The market and trading pair.
The LimitOrder object if found, None otherwise.
get_shadow_limit_order
def get_shadow_limit_order(self, order_id: str) -> LimitOrder:
"""
Retrieves a shadow limit order by order ID.
"""
The shadow LimitOrder object if found, None otherwise.
get_market_order
def get_market_order(
self,
market_pair: MarketTradingPairTuple,
order_id: str
) -> MarketOrder:
"""
Retrieves a tracked market order.
"""
The market and trading pair.
The MarketOrder object if found, None otherwise.
get_market_pair_from_order_id
def get_market_pair_from_order_id(self, order_id: str) -> MarketTradingPairTuple:
"""
Gets the market trading pair associated with an order ID.
"""
The MarketTradingPairTuple for this order, or None if not found.
Cancel Management
check_and_track_cancel
def check_and_track_cancel(self, order_id: str) -> bool:
"""
Checks if an order can be cancelled and tracks the cancel request.
Returns False if there's already an in-flight cancel or the order is pending creation.
"""
True if the cancel can proceed, False if there’s already a pending cancel or the order is pending creation.
has_in_flight_cancel
def has_in_flight_cancel(self, order_id: str) -> bool:
"""
Checks if an order has a pending cancel request.
"""
True if there’s a pending cancel request for this order.
Shadow Order Management
check_and_cleanup_shadow_records
def check_and_cleanup_shadow_records(self):
"""
Removes shadow orders that have exceeded the SHADOW_MAKER_ORDER_KEEP_ALIVE_DURATION.
Called automatically on each tick.
"""
Pending Creation Tracking
add_create_order_pending
def add_create_order_pending(self, order_id: str):
"""
Marks an order as pending creation confirmation.
"""
remove_create_order_pending
def remove_create_order_pending(self, order_id: str):
"""
Removes an order from the pending creation set.
"""
Usage Examples
Basic Order Tracking
from hummingbot.strategy.order_tracker import OrderTracker
from decimal import Decimal
# Initialize order tracker
order_tracker = OrderTracker()
# Track a limit buy order
order_tracker.start_tracking_limit_order(
market_pair=market_trading_pair_tuple,
order_id="buy_order_123",
is_buy=True,
price=Decimal("50000"),
quantity=Decimal("0.1")
)
# Track a market sell order
order_tracker.start_tracking_market_order(
market_pair=market_trading_pair_tuple,
order_id="sell_order_456",
is_buy=False,
quantity=Decimal("0.05")
)
# Get active limit orders
active_orders = order_tracker.active_limit_orders
for market, order in active_orders:
print(f"Order: {order.client_order_id}, Price: {order.price}, Qty: {order.quantity}")
Using in a Strategy
from hummingbot.strategy.strategy_base import StrategyBase
class MyStrategy(StrategyBase):
def __init__(self):
super().__init__()
# Order tracker is automatically initialized in StrategyBase
# as self._sb_order_tracker
cdef c_tick(self, double timestamp):
StrategyBase.c_tick(self, timestamp)
# Place a limit order
order_id = self.c_buy_with_specific_market(
market_pair,
Decimal("0.1"),
OrderType.LIMIT,
Decimal("50000")
)
# Order is automatically tracked by StrategyBase
cdef c_did_complete_buy_order(self, object order_completed_event):
# When order completes, it's automatically removed from active tracking
# and moved to shadow tracking
order_id = order_completed_event.order_id
# You can still access it from shadow orders for 3 minutes
shadow_order = self._sb_order_tracker.get_shadow_limit_order(order_id)
if shadow_order:
self.logger().info(f"Completed order: {shadow_order.client_order_id}")
Checking Order Status
# Get all active bids and asks
bids = order_tracker.active_bids
asks = order_tracker.active_asks
print(f"Active buy orders: {len(bids)}")
print(f"Active sell orders: {len(asks)}")
# Get orders for a specific market pair
market_orders = order_tracker.market_pair_to_active_orders
for market_pair, orders in market_orders.items():
print(f"Market: {market_pair.trading_pair}")
for order in orders:
print(f" Order: {order.client_order_id}, Price: {order.price}")
Cancel Management Example
def cancel_order_safely(order_tracker: OrderTracker, market_pair, order_id: str):
"""Safely cancel an order with duplicate prevention."""
# Check if cancel is already in flight
if order_tracker.has_in_flight_cancel(order_id):
print(f"Cancel already pending for {order_id}")
return False
# Track the cancel request
if order_tracker.check_and_track_cancel(order_id):
# Proceed with cancel
market_pair.market.cancel(market_pair.trading_pair, order_id)
return True
else:
print(f"Cannot cancel {order_id} - already pending or in creation")
return False
DataFrame Export
import pandas as pd
# Get limit orders as DataFrame
limit_df = order_tracker.tracked_limit_orders_data_frame
print(limit_df)
# Output:
# market trading_pair order_id quantity timestamp
# 0 binance BTC-USDT buy_order_123 0.10 2024-03-02 10:30:00
# 1 binance ETH-USDT sell_order_456 1.50 2024-03-02 10:31:00
# Get market orders as DataFrame
market_df = order_tracker.tracked_market_orders_data_frame
print(market_df)
# Export to CSV
limit_df.to_csv("active_orders.csv", index=False)
Shadow Order Cleanup
# Shadow orders are automatically cleaned up after 3 minutes
# This happens automatically on each tick
# Manually trigger cleanup (usually not needed)
order_tracker.check_and_cleanup_shadow_records()
# Access shadow orders (useful for reconciliation)
shadow_orders = order_tracker.shadow_limit_orders
for market, order in shadow_orders:
# These are recently completed/cancelled orders
# Kept for up to 3 minutes for reconciliation
print(f"Shadow order: {order.client_order_id}")
Integration with StrategyBase
The OrderTracker is automatically integrated into StrategyBase:
class StrategyBase(TimeIterator):
def __init__(self):
super().__init__()
self._sb_order_tracker = OrderTracker() # Automatically created
@property
def order_tracker(self) -> OrderTracker:
return self._sb_order_tracker
- When you call
buy_with_specific_market() or sell_with_specific_market(), orders are automatically tracked
- When orders complete, fail, or are cancelled, they’re automatically removed from active tracking
- Shadow tracking is maintained automatically for reconciliation
Constants
SHADOW_MAKER_ORDER_KEEP_ALIVE_DURATION
Duration (in seconds) to keep shadow orders before cleanup. Default is 3 minutes.
Duration (in seconds) for cancel requests to expire. Default is 1 minute.