Hummingbot tutorial: Client, Condor, API, vs Freqtrade

Short answer: This Hummingbot tutorial maps the project as read on 6 November 2026. Hummingbot (Apache-2.0, v2.17.0 of 22 September 2026) has a Python client with the hbot CLI, Condor for AI agents and many instances, the Hummingbot API and Gateway; its Dashboard is no longer actively maintained. For one bot, run the client in Docker with a connector ending in _paper_trade, tested here with no keys; against Freqtrade there is no overall winner.

Older tutorials often stop at the Dashboard or at replaced commands; this one dates each official page and reports what ran.

The project serves market makers among others, and its README's paper example is a market-making script. This guide uses no such script or setting, recommends no exchange and implies no profit. Automated trading can lose money.

Hummingbot tutorial: which part do you install?

Start with the client for one bot; the other components manage many bots or reach decentralized venues.

The pages disagree on one label: the installation page, dated 23 October 2026, calls the client legacy and recommends Condor for many instances and cloud production, while the README calls the hbot CLI the recommended way to run the client directly.

Condor was not installed here. Its README warns that local mode has no login, so anyone reaching the port has full trading control, and that it sends anonymous usage statistics unless CONDOR_TELEMETRY=off is set. Agentic implies nothing about results.

Hummingbot install: the documented commands and what ran

The documented Docker route is a clone plus three make targets, and on Windows the project says to run everything in an Ubuntu terminal under WSL2.

git clone https://github.com/hummingbot/hummingbot.git
cd hummingbot
make setup      # asks whether to include Gateway
make deploy     # interactive client by default
make link-cli
hbot doctor

The shipped docker-compose.yml sets network_mode: host and mounts conf, logs, data, scripts and controllers from the host, so back those up. Keys are encrypted with a keystore password, which the CLI guide says to pass through HBOT_PASSWORD or --password-stdin, never as an argument.

On Docker Hub (opens in a new tab) (read 6 November 2026), latest was pushed on 22 September 2026, the release date, and version-2.17.0 on 7 October. The tag name did not identify the release, so check hbot --version after any pull and pin by digest.

Hummingbot paper trading: one fixed order, no keys

Paper mode is a connector rather than a flag: pick a name ending in _paper_trade, and the bot reads public market data and simulates the order.

The CLI guide lists start --paper only as a proposed command, and hbot start --help showed no such flag. The paper trade page (opens in a new tab) enables paper connectors for four exchanges by default, with kraken_paper_trade as its example; that name and the pair are placeholders, not suggestions. This stub places one fixed order. Save it as scripts/one_paper_order.py, set HBOT_PASSWORD and run:

import os
from decimal import Decimal

from hummingbot.core.data_type.common import MarketDict, OrderType
from hummingbot.strategy.strategy_v2_base import StrategyV2Base, StrategyV2ConfigBase


class OnePaperOrderConfig(StrategyV2ConfigBase):
    script_file_name: str = os.path.basename(__file__)
    exchange: str = "kraken_paper_trade"
    trading_pair: str = "BTC-USDT"

    def update_markets(self, markets: MarketDict) -> MarketDict:
        markets[self.exchange] = markets.get(self.exchange, set()) | {self.trading_pair}
        return markets


class OnePaperOrder(StrategyV2Base):       # one fixed order, not a trading rule
    sent = False

    def on_tick(self):
        if not self.sent:
            self.sent = True
            self.buy(self.config.exchange, self.config.trading_pair, Decimal("0.001"), OrderType.MARKET)

    def did_fill_order(self, event):
        self.logger().info(f"FILLED {event.trade_type.name} {event.amount} {event.trading_pair}")

    def did_fail_order(self, event):
        self.logger().warning(f"FAILED {event.order_id}: {event.error_message}")

hbot create one_paper_order --name conf_one_order.yml \
     --set exchange=kraken_paper_trade --set trading_pair=BTC-USDT
hbot start conf_one_order.yml --timeout 280
hbot status; hbot logs; hbot history; hbot stop

Trimmed output of hbot logs, status and history:

FILLED BUY 0.001000000000000000020816681711721685132943093776702880859375 BTC-USDT
kraken_paper_trade   BTC          1.001              1.001
kraken_paper_trade  USDT     99923.9188         99923.9188
| market            | pair     | trades | quote_vol | fees     | total_pnl |
| kraken_PaperTrade | BTC-USDT | 1      | -76.0812  | 0.304325 | -0.307875 |

With 1000 in place of 0.001, the handler logged FAILED with the reason None, while the log had no ERROR line and hbot status showed 0 errors: without did_fail_order, a rejected order leaves no sign there.

The paper page does not list what the simulation leaves out, so a clean run proves the plumbing, not future fills; see how to test trading bots. When you later add keys, API key security applies: read and trade only, never withdrawal.

How a Hummingbot bot is structured

A bot is a config plus Python code run by a clock, 1 second per tick by default per the clock page (opens in a new tab).

• Scripts. Single Python files for learning and prototyping, per the strategies page.
• Controllers. Reusable modules tunable while running; one bot can run several.
• Executors. Start and finish one workflow and manage its orders.
• Connectors. Centralized exchanges with API keys, on-chain order books with wallet keys, AMM venues through Gateway.

The CLI runs one bot per install, with stable exit codes, and hbot status --json returned run state, uptime, an error count and balances, so a monitor can read it. What production needs beyond this is in trading bot development.

Anonymous data collection: what Hummingbot sends

By default Hummingbot totals your fill volume and reports it when the total is above zero; you can switch this off, though the obvious hbot command for that fails.

The page's opt-out sets anonymized_metrics_mode to anonymized_metrics_disabled, but hbot config anonymized_metrics_mode anonymized_metrics_disabled stopped with exit code 4, saying the key is a section, not a value; the interactive client was not tried. The project's own config writer saves the disabled mode as anonymized_metrics_mode: {} in conf/conf_client.yml, and its loader read that back as disabled, so write that line with the bot stopped, as the runs here did. Each report also shows your IP address, as any request does. This comes from the page and source, not a traffic capture.

Connectors: why the official counts differ

Official figures differ on the same day, so treat each as self-reported and check the venue you need.

The pages do not reconcile these scopes. Maintenance matters more than the count: the CLOB page says the Foundation prioritizes fixes for sponsor or partner exchanges. For a missing connector, the exchanges page (opens in a new tab) lists governance, a bounty from $10,000 or sponsorship from $50,000.

Which venues you may use depends on your jurisdiction and their terms, and perpetual futures are a separate regulated question. For readers in Turkey, Article 99/A of Capital Markets Law No. 6362 treats activity by foreign crypto-asset platforms directed at Turkish residents as unauthorized.

Hummingbot vs Freqtrade: the facts side by side

Neither is better overall; they are built around different loops.

These questions decide it:

1. Does your logic react to candles or to order book changes?
2. Do you need decentralized venues through one interface?
3. Would GPL-3.0 or Apache-2.0 fit a product you might distribute? Ask a lawyer.
4. Does the connector you need have an active maintainer?

A walk-through is in the Freqtrade tutorial, and more projects are in the open-source crypto trading bot reference.

Market making, wash trading and paid volume: the warning

Bots that place both sides of a market can cross into manipulation, depending on what they do and why.

The SEC's press release 2024-166 of 9 October 2024 announced charges against three so-called market makers and nine individuals. It alleged that promoters hired firms for market manipulation as a service, including self-trading, known as wash trading, and that bots at times generated billions of dollars of artificial trading volume each day. Rules vary by jurisdiction, but purpose and pattern matter whatever the tool:

• Never trade with yourself or between your own accounts to show activity.
• Treat any offer of or request for paid volume as a red flag, and take legal advice before token-project work.
• Check whether exchange terms and local rules cover providing liquidity, even on your own account.

Limits outside the strategy code are covered in trading bot risk management.

Where Hummingbot setups fail, and where developers come in

Check control surfaces and networks before writing any logic.

• Open ports. The Hummingbot API binds port 8000 to 127.0.0.1 by default, and its README warns that cloud servers are constantly scanned for such ports. Its documented .env shows admin for username and passwords; change them.
• Running is not ready. With networking off (docker run --network none), hbot start still exited 0 with status running and no order went out; hbot status showed 8 errors in its last 600 log lines and Market connectors are not ready, and the log showed DNS failures. start waits up to 120 s by default; raise --timeout on a slow host.
• Extra calls. The default rate_oracle_source is Gate.io, and in that run the rate oracle tried Gate.io although only a Kraken paper connector was selected; check it against your firewall and rules.

Developer work here usually means scripts or controllers from rules you wrote, connector fixes and monitoring on the CLI's exit codes and JSON. For integration work in general, see Fincode's exchange API integration page; naming Hummingbot or Kraken here does not mean Fincode integrates them or has built on them, and Fincode does not supply strategies.

Frequently asked questions

Is Hummingbot free and open source on GitHub?

Yes. hummingbot/hummingbot is Apache-2.0, and Condor and the Hummingbot API are MIT. You still pay for your server and any exchange fees.

Is the Hummingbot Dashboard still maintained?

Its official page says it is no longer actively maintained and recommends Condor; the repository, last committed to on 27 October 2025, stays available.

Is Hummingbot better than Freqtrade?

Neither is better overall. Decide by whether your logic follows candles or order books, which venues you need and the license.

Do I need API keys to try Hummingbot?

Not for a paper connector. The test on 6 November 2026 used no keys and read only public market data, though a keystore password is still set on first use.

Sources

• Hummingbot: Home page (opens in a new tab)
• Hummingbot: Installation overview (Client, Condor, API, Gateway) (opens in a new tab)
• Hummingbot: Client installation (requirements, Docker, source, exit commands) (opens in a new tab)
• Freqtrade documentation: overview, hardware and software requirements (opens in a new tab)
• Hummingbot: Dashboard (not actively maintained) (opens in a new tab)
• Hummingbot: Reporting (anonymous data collection) (opens in a new tab)
• Hummingbot: Strategies overview (opens in a new tab)
• Hummingbot: CLOB connectors (31 listed, fix priority) (opens in a new tab)
• Hummingbot on GitHub: README (license, install, connectors, Gateway modes) (opens in a new tab)
• Hummingbot on GitHub: hbot CLI guide (commands, proposed commands, exit codes, passwords) (opens in a new tab)
• Hummingbot docker-compose.yml, master branch (opens in a new tab)
• Condor on GitHub: README (local mode, telemetry) (opens in a new tab)
• Hummingbot API on GitHub: README (services, credentials, port binding) (opens in a new tab)
• SEC press release 2024-166 (9 October 2024): charges against three so-called market makers (opens in a new tab)
• Capital Markets Law No. 6362, Article 99/A (Turkish, consolidated text) (opens in a new tab)

This guide is general information about software and markets, not investment, legal or tax advice. Automated trading can lose money, past or backtested performance does not guarantee future results, and the rules that apply depend on your jurisdiction and your exchange's terms. Sources, checks and corrections: see the editorial policy.