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
The V2 framework uses several data models to represent executor states, actions, and performance metrics:
- ExecutorInfo - Complete information about an executor’s state
- ExecutorAction - Actions that controllers send to executors
- PerformanceReport - Performance metrics and statistics
- CloseType - Enum defining how executors close
- RunnableStatus - Enum defining component status
- TrackedOrder - Order tracking model
ExecutorInfo
Complete information object about an executor’s current state and performance.
Model Definition
class ExecutorInfo(BaseModel):
id: str
timestamp: float
type: str
status: RunnableStatus
config: AnyExecutorConfig
net_pnl_pct: Decimal
net_pnl_quote: Decimal
cum_fees_quote: Decimal
filled_amount_quote: Decimal
is_active: bool
is_trading: bool
custom_info: Dict
close_timestamp: Optional[float] = None
close_type: Optional[CloseType] = None
controller_id: Optional[str] = None
hummingbot/strategy_v2/models/executors_info.py:21
Fields
Unique identifier for the executor
Unix timestamp when executor was created
Executor type (e.g., “PositionExecutor”, “DCAExecutor”)
Current status (NOT_STARTED, RUNNING, SHUTTING_DOWN, TERMINATED)
The executor’s configuration object (polymorphic based on type)
Net profit/loss as a percentage
Net profit/loss in quote currency
Cumulative fees paid in quote currency
Total filled amount in quote currency
True if executor is currently active (NOT_STARTED or RUNNING)
True if executor is active and has filled orders
Executor-specific custom information (e.g., order IDs, level info)
Unix timestamp when executor was closed (None if still active)
How the executor was closed (None if still active)
ID of the controller that created this executor
Properties
@property
def is_done(self) -> bool:
return self.status == RunnableStatus.TERMINATED
@property
def side(self) -> Optional[TradeType]:
return self.custom_info.get("side", None)
@property
def trading_pair(self) -> Optional[str]:
return self.config.trading_pair
@property
def connector_name(self) -> Optional[str]:
return self.config.connector_name
ExecutorAction
Base class for actions that controllers send to the executor orchestrator.
Base Action
class ExecutorAction(BaseModel):
controller_id: Optional[str] = "main"
hummingbot/strategy_v2/models/executor_actions.py:10
CreateExecutorAction
Action to create and start a new executor.
class CreateExecutorAction(ExecutorAction):
executor_config: ExecutorConfigType
executor_actions.py:17
executor_config
ExecutorConfigBase
required
Configuration for the executor to create (e.g., PositionExecutorConfig, DCAExecutorConfig)
StopExecutorAction
Action to stop an existing executor.
class StopExecutorAction(ExecutorAction):
executor_id: str
keep_position: Optional[bool] = False
executor_actions.py:24
ID of the executor to stop
If True, keeps the position open instead of closing it
StoreExecutorAction
Action to store executor state (for persistence).
class StoreExecutorAction(ExecutorAction):
executor_id: str
executor_actions.py:32
Aggregated performance metrics for a controller’s executors.
Model Definition
class PerformanceReport(BaseModel):
realized_pnl_quote: Decimal = Decimal("0")
unrealized_pnl_quote: Decimal = Decimal("0")
unrealized_pnl_pct: Decimal = Decimal("0")
realized_pnl_pct: Decimal = Decimal("0")
global_pnl_quote: Decimal = Decimal("0")
global_pnl_pct: Decimal = Decimal("0")
volume_traded: Decimal = Decimal("0")
positions_summary: List = []
close_type_counts: Dict[CloseType, int] = {}
hummingbot/strategy_v2/models/executors_info.py:61
Fields
Realized profit/loss from closed positions in quote currency
Unrealized profit/loss from open positions in quote currency
Unrealized profit/loss as percentage
Realized profit/loss as percentage
Total PnL (realized + unrealized) in quote currency
Total trading volume in quote currency
List of position summaries
close_type_counts
Dict[CloseType, int]
default:"{}"
Count of executors by close type (e.g., how many hit stop loss vs take profit)
CloseType Enum
Defines the various ways an executor can be closed.
class CloseType(Enum):
TIME_LIMIT = 1
STOP_LOSS = 2
TAKE_PROFIT = 3
EXPIRED = 4
EARLY_STOP = 5
TRAILING_STOP = 6
INSUFFICIENT_BALANCE = 7
FAILED = 8
COMPLETED = 9
POSITION_HOLD = 10
hummingbot/strategy_v2/models/executors.py:8
Position closed because time limit was reached
Position closed by stop loss trigger
Position closed by take profit trigger
Executor expired (alternative to time limit)
Manually stopped by controller before completion
Position closed by trailing stop trigger
Executor closed due to insufficient balance
Executor failed (e.g., validation error, order failure)
Executor completed successfully
Position is being held (keep_position=True)
RunnableStatus Enum
Defines the lifecycle status of runnable components (executors and controllers).
class RunnableStatus(Enum):
NOT_STARTED = 1
RUNNING = 2
SHUTTING_DOWN = 3
TERMINATED = 4
hummingbot/strategy_v2/models/base.py:4
Component created but not yet started
Component is actively running
Component is in the process of shutting down
Component has completely stopped
TrackedOrder
Wrapper for tracking in-flight orders within executors.
Model Definition
class TrackedOrder:
def __init__(self, order_id: Optional[str] = None)
hummingbot/strategy_v2/models/executors.py:21
Properties
Client order ID for the tracked order
Reference to the actual in-flight order object
Order price (from in-flight order)
Average price at which order was executed
Amount executed in base asset
Amount executed in quote asset
Cumulative fees in base asset
Cumulative fees in quote asset
True if order is completely filled or cancelled
True if order is still open
True if order is completely filled
Usage Examples
Working with ExecutorInfo
from hummingbot.strategy_v2.models.executors_info import ExecutorInfo
from hummingbot.strategy_v2.models.base import RunnableStatus
# Get executor info from controller
executor_infos = controller.executors_info
for info in executor_infos:
print(f"Executor {info.id}:")
print(f" Type: {info.type}")
print(f" Status: {info.status.name}")
print(f" Trading Pair: {info.trading_pair}")
print(f" Side: {info.side}")
print(f" PnL %: {info.net_pnl_pct * 100:.2f}%")
print(f" PnL Quote: {info.net_pnl_quote}")
print(f" Fees: {info.cum_fees_quote}")
if info.is_done:
print(f" Closed: {info.close_type.name}")
print(f" Duration: {info.close_timestamp - info.timestamp:.0f}s")
Creating Executor Actions
from hummingbot.strategy_v2.models.executor_actions import (
CreateExecutorAction,
StopExecutorAction
)
from hummingbot.strategy_v2.executors.position_executor.data_types import (
PositionExecutorConfig
)
# Create action to start new executor
create_action = CreateExecutorAction(
controller_id="my_controller",
executor_config=PositionExecutorConfig(
timestamp=time.time(),
connector_name="binance",
trading_pair="BTC-USDT",
side=TradeType.BUY,
amount=Decimal("0.01"),
# ... other config
)
)
# Create action to stop executor
stop_action = StopExecutorAction(
controller_id="my_controller",
executor_id="executor_123",
keep_position=False # Close the position
)
# Send actions to queue
await actions_queue.put([create_action, stop_action])
from hummingbot.strategy_v2.models.executors_info import PerformanceReport
from hummingbot.strategy_v2.models.executors import CloseType
report: PerformanceReport = controller.performance_report
print(f"Overall Performance:")
print(f" Realized PnL: {report.realized_pnl_quote} ({report.realized_pnl_pct * 100:.2f}%)")
print(f" Unrealized PnL: {report.unrealized_pnl_quote} ({report.unrealized_pnl_pct * 100:.2f}%)")
print(f" Global PnL: {report.global_pnl_quote} ({report.global_pnl_pct * 100:.2f}%)")
print(f" Volume Traded: {report.volume_traded}")
print(f"\nClose Type Breakdown:")
for close_type, count in report.close_type_counts.items():
print(f" {close_type.name}: {count}")
# Calculate win rate
take_profits = report.close_type_counts.get(CloseType.TAKE_PROFIT, 0)
stop_losses = report.close_type_counts.get(CloseType.STOP_LOSS, 0)
total = take_profits + stop_losses
if total > 0:
win_rate = (take_profits / total) * 100
print(f"\nWin Rate: {win_rate:.1f}%")
Filtering by Status and Close Type
from hummingbot.strategy_v2.controllers.controller_base import ExecutorFilter
from hummingbot.strategy_v2.models.executors import CloseType
from hummingbot.strategy_v2.models.base import RunnableStatus
# Get all executors that hit stop loss
stop_loss_filter = ExecutorFilter(
statuses=[RunnableStatus.TERMINATED],
close_types=[CloseType.STOP_LOSS]
)
stop_loss_executors = controller.filter_executors(executor_filter=stop_loss_filter)
print(f"Total stop losses: {len(stop_loss_executors)}")
for executor in stop_loss_executors:
print(f" {executor.id}: Lost {executor.net_pnl_quote}")
# Get all take profits
tp_filter = ExecutorFilter(
statuses=[RunnableStatus.TERMINATED],
close_types=[CloseType.TAKE_PROFIT]
)
take_profit_executors = controller.filter_executors(executor_filter=tp_filter)
print(f"\nTotal take profits: {len(take_profit_executors)}")
for executor in take_profit_executors:
print(f" {executor.id}: Gained {executor.net_pnl_quote}")