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.
Overview
Executors are responsible for executing trading orders and managing positions. The V2 framework provides a base ExecutorBase class and several specialized executor types:
- PositionExecutor - Manages single positions with triple barrier risk management
- DCAExecutor - Dollar-cost averaging with multiple entry levels
- OrderExecutor - Simple order execution with various strategies
- GridExecutor - Grid trading executor
- TWAPExecutor - Time-weighted average price execution
- ArbitrageExecutor - Cross-exchange arbitrage
- XEMMExecutor - Cross-exchange market making
- LPExecutor - Liquidity pool executor for AMMs
ExecutorBase
Base class for all executors in the V2 framework.
Class Definition
class ExecutorBase(RunnableBase):
def __init__(
self,
strategy: StrategyV2Base,
connectors: List[str],
config: ExecutorConfigBase,
update_interval: float = 0.5
)
hummingbot/strategy_v2/executors/executor_base.py:29
Parameters
The strategy instance that owns this executor
List of connector names to be used by the executor
config
ExecutorConfigBase
required
Configuration object for the executor
Update interval for the executor in seconds
Properties
Current status of the executor (NOT_STARTED, RUNNING, TERMINATED)
Returns True if executor is open or trading
Returns True if executor is active and has non-zero PnL
Returns True if executor status is TERMINATED
Net profit or loss in quote currency
Net profit or loss as percentage
Cumulative fees paid in quote currency
Filled amount in quote currency
Complete information object about the executor
Core Methods
place_order()
def place_order(
self,
connector_name: str,
trading_pair: str,
order_type: OrderType,
side: TradeType,
amount: Decimal,
position_action: PositionAction = PositionAction.NIL,
price: Decimal = Decimal("NaN")
)
executor_base.py:268
get_price()
def get_price(
self,
connector_name: str,
trading_pair: str,
price_type: PriceType = PriceType.MidPrice
) -> Decimal
executor_base.py:294
get_balance()
def get_balance(self, connector_name: str, asset: str) -> Decimal
executor_base.py:325
early_stop()
def early_stop(self, keep_position: bool = False)
executor_base.py:185
Event Handlers
Executors automatically listen to order events and process them:
def process_order_created_event(self, event_tag: int, market: ConnectorBase, event)
def process_order_filled_event(self, event_tag: int, market: ConnectorBase, event)
def process_order_completed_event(self, event_tag: int, market: ConnectorBase, event)
def process_order_canceled_event(self, event_tag: int, market: ConnectorBase, event)
def process_order_failed_event(self, event_tag: int, market: ConnectorBase, event)
PositionExecutor
Manages single positions with triple barrier risk management (stop loss, take profit, time limit).
Class Definition
class PositionExecutor(ExecutorBase):
def __init__(
self,
strategy: StrategyV2Base,
config: PositionExecutorConfig,
update_interval: float = 1.0,
max_retries: int = 10
)
hummingbot/strategy_v2/executors/position_executor/position_executor.py:26
Configuration
Trading pair to execute on
Amount to trade in base asset
Entry price for the position (calculated if not provided)
triple_barrier_config
TripleBarrierConfig
required
Configuration for stop loss, take profit, and time limit
Leverage for perpetual trading
Triple Barrier Config
class TripleBarrierConfig:
stop_loss: Optional[Decimal] # Stop loss as percentage (e.g., 0.03 = 3%)
take_profit: Optional[Decimal] # Take profit as percentage
time_limit: Optional[int] # Time limit in seconds
trailing_stop: Optional[TrailingStop] # Trailing stop config
open_order_type: OrderType # Order type for opening
take_profit_order_type: OrderType # Order type for take profit
stop_loss_order_type: OrderType # Order type for stop loss
time_limit_order_type: OrderType # Order type for time limit
Key Properties
True if using a perpetual exchange connector
Filled amount of the open order
Filled amount of the close order
Average executed entry price
Average executed close price or current market price
True if position has exceeded time limit
DCAExecutor
Dollar-cost averaging executor that places multiple orders at different price levels.
Class Definition
class DCAExecutor(ExecutorBase):
def __init__(
self,
strategy: StrategyV2Base,
config: DCAExecutorConfig,
update_interval: float = 1.0,
max_retries: int = 15
)
hummingbot/strategy_v2/executors/dca_executor/dca_executor.py:24
Configuration
Trading pair to execute on
List of amounts in quote currency for each level
List of prices for each DCA level
mode
DCAMode
default:"DCAMode.MAKER"
MAKER (limit orders) or TAKER (market orders)
Take profit as percentage
Activation bounds for TAKER mode [min, max]
Key Properties
Total filled amount across all open orders
current_position_average_price
Weighted average price of filled orders
target_position_average_price
Target average price if all levels are filled
Total amount in quote currency across all levels
True if executor has exceeded time limit
CloseType Enum
Defines how an executor was closed:
Closed due to time limit being reached
Closed due to stop loss being triggered
Closed due to take profit being reached
Manually stopped early by controller
Closed due to trailing stop
Closed due to insufficient balance
Executor completed successfully
Position is being held (not closed)
Usage Examples
PositionExecutor with Triple Barrier
from hummingbot.strategy_v2.executors.position_executor.data_types import (
PositionExecutorConfig,
TripleBarrierConfig
)
from decimal import Decimal
# Configure triple barrier
triple_barrier = TripleBarrierConfig(
stop_loss=Decimal("0.02"), # 2% stop loss
take_profit=Decimal("0.03"), # 3% take profit
time_limit=60 * 30, # 30 minutes
open_order_type=OrderType.MARKET,
take_profit_order_type=OrderType.LIMIT,
stop_loss_order_type=OrderType.MARKET,
time_limit_order_type=OrderType.MARKET
)
# Create position config
config = PositionExecutorConfig(
timestamp=time.time(),
connector_name="binance_perpetual",
trading_pair="BTC-USDT",
side=TradeType.BUY,
amount=Decimal("0.01"),
entry_price=Decimal("50000"),
triple_barrier_config=triple_barrier,
leverage=10
)
# Create and start executor
executor = PositionExecutor(strategy, config)
executor.start()
DCAExecutor Example
from hummingbot.strategy_v2.executors.dca_executor.data_types import (
DCAExecutorConfig,
DCAMode
)
# Configure DCA with 3 levels
config = DCAExecutorConfig(
timestamp=time.time(),
connector_name="binance",
trading_pair="ETH-USDT",
side=TradeType.BUY,
amounts_quote=[Decimal("100"), Decimal("150"), Decimal("200")],
prices=[Decimal("3000"), Decimal("2950"), Decimal("2900")],
mode=DCAMode.MAKER,
take_profit=Decimal("0.05"), # 5% take profit
stop_loss=Decimal("0.03"), # 3% stop loss
time_limit=60 * 60 * 24 # 24 hours
)
executor = DCAExecutor(strategy, config)
executor.start()
# Check position average
print(f"Current avg price: {executor.current_position_average_price}")
print(f"Target avg price: {executor.target_position_average_price}")
Checking Executor Status
# Get executor info
info = executor.executor_info
print(f"Status: {info.status}")
print(f"PnL %: {info.net_pnl_pct}")
print(f"PnL Quote: {info.net_pnl_quote}")
print(f"Is Active: {info.is_active}")
print(f"Is Trading: {info.is_trading}")
if info.close_type:
print(f"Close Type: {info.close_type}")