Skip to main content
Controllers are V2 strategy components that implement algorithmic trading logic. They run inside bot containers and manage complex, multi-step trading strategies by creating and supervising executors.

What Are Controllers?

Controllers are Python classes that:
  • Define trading strategy logic
  • Process market data into a signal
  • Create and manage executors
  • Expose status and custom metrics
A single bot can run multiple controllers at once — each targeting a different market — within one container.

Built-in Controllers

Controllers ship under three controller_type categories. A selection of the built-ins:
directional_trading, market_making, and generic are controller types, not controller names. The exact set of built-ins tracks the Hummingbot repository — browse controllers/ for the current list.

Controller Structure

A controller overrides two core methods from ControllerBase:
  • update_processed_data() — pull market data and compute a signal into self.processed_data
  • determine_executor_actions() — decide which executors to create or stop
The specialized base classes DirectionalTradingControllerBase and MarketMakingControllerBase already implement determine_executor_actions() for you, so trend and market-making controllers typically only implement update_processed_data() and get_candles_config(). This is the actual bollinger_v1 directional controller:
Market data comes from self.market_data_provider (e.g. get_candles_df(...), get_price_by_type(...)), not from ad-hoc fetches.

Controller Configuration

Each controller instance is configured by a YAML file. This is a real pmm_simple config:

Deploying a Controller

The usual flow is: create one or more controller configs (in the dashboard Editor, in Telegram, or via the API), then deploy a bot that runs them.

Via Telegram

Via API

Deploy a bot from existing controller config files (without the .yml extension). You can pass several configs to run multiple controllers in one bot:

Updating a Running Controller

Controllers can be reconfigured while running — no restart required. Only fields a controller marks as updatable are applied; everything else (for example, the connector name) is ignored on update. A config field is made updatable with json_schema_extra:
At runtime, ControllerBase.update_config(new_config) copies over only the fields flagged is_updatable. In Condor, push a live update from the dashboard Bots → Active tab by editing the config and saving.

Custom Controller Metrics

Override get_custom_info() to publish controller-specific fields alongside the standard performance report. The payload is sent over MQTT to the Hummingbot API, so keep it small (recommended < 1 KB):
These fields are stored with each controller snapshot and surfaced per controller in the dashboard.

Creating Custom Controllers

  1. Create a new Python file under controllers/ (in the matching controller_type subfolder)
  2. Subclass the appropriate base — ControllerBase, DirectionalTradingControllerBase, or MarketMakingControllerBase
  3. Implement update_processed_data() (and determine_executor_actions() if you subclass ControllerBase directly)
  4. Add a config file and deploy it
Custom controllers run in stock Hummingbot too, and can be uploaded directly from the dashboard Editor.

Monitoring Controllers

The Hummingbot API records a snapshot of every running controller every 5 minutes, giving you a time series of P&L and volume rather than a single point in time.
In Condor, view this history under Bots → Runs, and the combined P&L across a bot’s controllers under Bots → Active.