Controllers - Hummingbot

Overview

Controllers are the brain of V2 strategies, responsible for analyzing market data and determining what actions executors should take. The V2 framework provides three controller base classes:

ControllerBase - Generic controller with advanced filtering capabilities
MarketMakingControllerBase - Specialized for market making strategies
DirectionalTradingControllerBase - Specialized for directional trading strategies

ControllerBase

The base controller class that provides comprehensive executor management and filtering capabilities.

Class Definition

class ControllerBase(RunnableBase):
    def __init__(
        self,
        config: ControllerConfigBase,
        market_data_provider: MarketDataProvider,
        actions_queue: asyncio.Queue,
        update_interval: float = 1.0
    )

Location: hummingbot/strategy_v2/controllers/controller_base.py:127

Parameters

config

ControllerConfigBase

required

The configuration object for the controller

market_data_provider

MarketDataProvider

required

Provider for accessing market data and prices

actions_queue

asyncio.Queue

required

Queue for sending executor actions to the orchestrator

update_interval

float

default:"1.0"

Interval in seconds for the control loop

Key Properties

executors_info

List[ExecutorInfo]

List of all executor information objects managed by this controller

positions_held

List[PositionSummary]

List of positions currently held by executors

performance_report

Optional[PerformanceReport]

Performance metrics for the controller

Core Methods

determine_executor_actions()

def determine_executor_actions(self) -> List[ExecutorAction]

Determines what actions executors should take based on current market conditions. Must be overridden in subclasses. Returns: List of executor actions (CreateExecutorAction or StopExecutorAction) Location: controller_base.py:456

update_processed_data()

async def update_processed_data(self)

Updates market data used by the controller for decision making. Must be overridden in subclasses. Location: controller_base.py:448

get_candles_config()

def get_candles_config(self) -> List[CandlesConfig]

Returns candles configuration needed by the controller. Override to specify required candle data. Returns: List of CandlesConfig objects Location: controller_base.py:228

Executor Filtering

The controller provides powerful filtering capabilities through the ExecutorFilter system.

filter_executors()

def filter_executors(
    self,
    executors: List[ExecutorInfo] = None,
    executor_filter: ExecutorFilter = None,
    filter_func: Callable[[ExecutorInfo], bool] = None
) -> List[ExecutorInfo]

Filters executors using ExecutorFilter criteria or a custom filter function.

executors

List[ExecutorInfo]

Optional list of executors to filter. If None, uses self.executors_info

executor_filter

ExecutorFilter

ExecutorFilter instance with filtering criteria

filter_func

Callable

Optional custom filter function for backward compatibility

Location: controller_base.py:272

get_active_executors()

def get_active_executors(
    self,
    connector_names: Optional[List[str]] = None,
    trading_pairs: Optional[List[str]] = None,
    executor_types: Optional[List[str]] = None
) -> List[ExecutorInfo]

Returns all active executors with optional filtering. Location: controller_base.py:372

get_completed_executors()

def get_completed_executors(
    self,
    connector_names: Optional[List[str]] = None,
    trading_pairs: Optional[List[str]] = None,
    executor_types: Optional[List[str]] = None
) -> List[ExecutorInfo]

Returns all completed (terminated) executors with optional filtering. Location: controller_base.py:392

Trading API Methods

buy()

def buy(
    self,
    connector_name: str,
    trading_pair: str,
    amount: Decimal,
    price: Optional[Decimal] = None,
    execution_strategy: ExecutionStrategy = ExecutionStrategy.MARKET,
    chaser_config: Optional[LimitChaserConfig] = None,
    triple_barrier_config: Optional[TripleBarrierConfig] = None,
    leverage: int = 1,
    keep_position: bool = True
) -> str

Creates a buy order using the unified PositionExecutor. Returns: Executor ID for tracking the order Location: controller_base.py:485

sell()

def sell(
    self,
    connector_name: str,
    trading_pair: str,
    amount: Decimal,
    price: Optional[Decimal] = None,
    execution_strategy: ExecutionStrategy = ExecutionStrategy.MARKET,
    chaser_config: Optional[LimitChaserConfig] = None,
    triple_barrier_config: Optional[TripleBarrierConfig] = None,
    leverage: int = 1,
    keep_position: bool = True
) -> str

Creates a sell order using the unified PositionExecutor. Returns: Executor ID for tracking the order Location: controller_base.py:522

cancel()

def cancel(self, executor_id: str) -> bool

Cancels an active executor (order) by its ID. Returns: True if cancellation request was sent, False otherwise Location: controller_base.py:617

cancel_all()

def cancel_all(
    self,
    connector_name: Optional[str] = None,
    trading_pair: Optional[str] = None,
    executor_filter: Optional[ExecutorFilter] = None
) -> List[str]

Cancels all active orders with optional filtering. Returns: List of executor IDs that were cancelled Location: controller_base.py:643

open_orders()

def open_orders(
    self,
    connector_name: Optional[str] = None,
    trading_pair: Optional[str] = None,
    executor_filter: Optional[ExecutorFilter] = None
) -> List[Dict]

Gets all open orders from active executors. Returns: List of open order dictionaries Location: controller_base.py:697

open_positions()

def open_positions(
    self,
    connector_name: Optional[str] = None,
    trading_pair: Optional[str] = None,
    executor_filter: Optional[ExecutorFilter] = None
) -> List[Dict]

Gets all held positions from completed executors. Returns: List of position dictionaries Location: controller_base.py:764

get_current_price()

def get_current_price(
    self,
    connector_name: str,
    trading_pair: str,
    price_type: PriceType = PriceType.MidPrice
) -> Decimal

Gets current market price for a trading pair. Location: controller_base.py:839

MarketMakingControllerBase

Specialized controller for market making strategies that places orders on both bid and ask sides.

Class Definition

class MarketMakingControllerBase(ControllerBase):
    def __init__(self, config: MarketMakingControllerConfigBase, *args, **kwargs)

Location: hummingbot/strategy_v2/controllers/market_making_controller_base.py:212

Configuration Fields

connector_name

str

default:"binance_perpetual"

Exchange connector name (e.g., binance_perpetual)

trading_pair

str

default:"WLD-USDT"

Trading pair to trade on

buy_spreads

List[float]

default:"[0.01, 0.02]"

Comma-separated list of buy spreads

sell_spreads

List[float]

default:"[0.01, 0.02]"

Comma-separated list of sell spreads

executor_refresh_time

int

default:"300"

Refresh time in seconds for executors (5 minutes)

leverage

int

default:"20"

Leverage for perpetual trading (set to 1 for spot)

stop_loss

Decimal

default:"0.03"

Stop loss as decimal (e.g., 0.03 for 3%)

take_profit

Decimal

default:"0.02"

Take profit as decimal (e.g., 0.02 for 2%)

Key Methods

create_actions_proposal()

def create_actions_proposal(self) -> List[ExecutorAction]

Creates actions proposal based on current controller state, including position rebalancing and market making levels. Location: market_making_controller_base.py:232

get_price_and_amount()

def get_price_and_amount(self, level_id: str) -> Tuple[Decimal, Decimal]

Calculates the price and amount for a given market making level. Returns: Tuple of (price, amount) Location: market_making_controller_base.py:304

DirectionalTradingControllerBase

Specialized controller for directional trading strategies based on signals.

Class Definition

class DirectionalTradingControllerBase(ControllerBase):
    def __init__(self, config: DirectionalTradingControllerConfigBase, *args, **kwargs)

Location: hummingbot/strategy_v2/controllers/directional_trading_controller_base.py:141

Configuration Fields

connector_name

str

default:"binance_perpetual"

Exchange connector name

trading_pair

str

default:"WLD-USDT"

Trading pair to trade on

max_executors_per_side

int

default:"2"

Maximum number of executors per side (buy/sell)

cooldown_time

int

default:"300"

Cooldown time in seconds after executing a signal (5 minutes)

leverage

int

default:"20"

Leverage for perpetual trading

Key Methods

can_create_executor()

def can_create_executor(self, signal: int) -> bool

Checks if an executor can be created based on the signal, quantity of active executors, and cooldown time. Location: directional_trading_controller_base.py:185

get_executor_config()

def get_executor_config(
    self,
    trade_type: TradeType,
    price: Decimal,
    amount: Decimal
) -> PositionExecutorConfig

Gets the executor configuration based on trade type, price, and amount. Location: directional_trading_controller_base.py:204

ExecutorFilter

Powerful filtering system for querying executors.

@dataclass
class ExecutorFilter:
    executor_ids: Optional[List[str]] = None
    connector_names: Optional[List[str]] = None
    trading_pairs: Optional[List[str]] = None
    executor_types: Optional[List[str]] = None
    statuses: Optional[List[RunnableStatus]] = None
    sides: Optional[List[TradeType]] = None
    is_active: Optional[bool] = None
    is_trading: Optional[bool] = None
    close_types: Optional[List[CloseType]] = None
    controller_ids: Optional[List[str]] = None
    min_pnl_pct: Optional[Decimal] = None
    max_pnl_pct: Optional[Decimal] = None
    min_pnl_quote: Optional[Decimal] = None
    max_pnl_quote: Optional[Decimal] = None
    min_timestamp: Optional[float] = None
    max_timestamp: Optional[float] = None

Location: controller_base.py:32

Usage Examples

Basic Controller

from hummingbot.strategy_v2.controllers.controller_base import ControllerBase, ExecutorFilter
from decimal import Decimal

class MyController(ControllerBase):
    async def update_processed_data(self):
        # Update market data
        self.processed_data["price"] = self.get_current_price(
            "binance", "BTC-USDT"
        )
    
    def determine_executor_actions(self):
        # Get active executors for BTC-USDT
        active = self.get_active_executors(
            connector_names=["binance"],
            trading_pairs=["BTC-USDT"]
        )
        
        # Create buy order if no active executors
        if len(active) == 0:
            executor_id = self.buy(
                connector_name="binance",
                trading_pair="BTC-USDT",
                amount=Decimal("0.001")
            )
        
        return []

Advanced Filtering

# Get profitable completed executors from last hour
filter = ExecutorFilter(
    statuses=[RunnableStatus.TERMINATED],
    min_pnl_pct=Decimal("0.01"),  # At least 1% profit
    min_timestamp=time.time() - 3600  # Last hour
)
profit_executors = controller.filter_executors(executor_filter=filter)

# Cancel losing positions
losing_filter = ExecutorFilter(
    is_active=True,
    max_pnl_pct=Decimal("-0.02")  # More than 2% loss
)
controller.cancel_all(executor_filter=losing_filter)

Core

Strategy V2

Data Types

Documentation Index

​Overview

​ControllerBase

​Class Definition

​Parameters

​Key Properties

​Core Methods

​determine_executor_actions()

​update_processed_data()

​get_candles_config()

​Executor Filtering

​filter_executors()

​get_active_executors()

​get_completed_executors()

​Trading API Methods

​buy()

​sell()

​cancel()

​cancel_all()

​open_orders()

​open_positions()

​get_current_price()

​MarketMakingControllerBase

​Class Definition

​Configuration Fields

​Key Methods

​create_actions_proposal()

​get_price_and_amount()

​DirectionalTradingControllerBase

​Class Definition

​Configuration Fields

​Key Methods

​can_create_executor()

​get_executor_config()

​ExecutorFilter

​Usage Examples

​Basic Controller

​Advanced Filtering

Overview

ControllerBase

Class Definition

Parameters

Key Properties

Core Methods

determine_executor_actions()

update_processed_data()

get_candles_config()

Executor Filtering

filter_executors()

get_active_executors()

get_completed_executors()

Trading API Methods

buy()

sell()

cancel()

cancel_all()

open_orders()

open_positions()

get_current_price()

MarketMakingControllerBase

Class Definition

Configuration Fields

Key Methods

create_actions_proposal()

get_price_and_amount()

DirectionalTradingControllerBase

Class Definition

Configuration Fields

Key Methods

can_create_executor()

get_executor_config()

ExecutorFilter

Usage Examples

Basic Controller

Advanced Filtering