# Hummingbot tutorial: Client, Condor, API, vs Freqtrade

URL: https://fincodelabs.com/en/blog/hummingbot-tutorial · Publisher: Fincode (Fincode Yazılım ve Teknoloji A.Ş.), Istanbul, Turkey · Category: Trading bots · Published: 2026-11-06 · Updated: 2026-11-06

Hummingbot tutorial and map, tested 6 November 2026: Client, Condor, API, Gateway, the unmaintained Dashboard, a paper order and facts against 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.

**Official pages and GitHub API, read 6 November 2026**

| Component | Purpose, per the project | License | Status |
| --- | --- | --- | --- |
| Client (`hbot` CLI, terminal client) | One bot per install | Apache-2.0 | v2.17.0, 22 September 2026 |
| Condor | AI agents and many bots, via Telegram or web | MIT | No release; last commit on `main` 30 October 2026 |
| Hummingbot API | REST backend for bots and portfolios, with PostgreSQL and an EMQX broker | MIT | Last commit 15 October 2026; last tagged release October 2024 |
| Gateway | Middleware for decentralized exchanges | Apache-2.0 | v2.17.0, 22 September 2026 |
| Dashboard | Graphical interface for many bots | Apache-2.0 | Page says no longer actively maintained and recommends Condor; last commit 27 October 2025 |

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.

```bash
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.

**What ran on 6 November 2026 (Windows 11, Docker 29.4.0)**

| Step | Result |
| --- | --- |
| Image | `version-2.17.0`, digest starting `sha256:dd6a85fc58c5`; `latest` was not pulled |
| Clone and `make` targets | Not run, as they expect Ubuntu under WSL2 on Windows; the image ran with `docker run --init` as an idle host, per the CLI guide |
| `hbot --version` | `hbot dev-2.18.0`, under the image tag `version-2.17.0`, on Python 3.13.16 |
| `hbot doctor` | Exit 0, all checks ok, clock skew about 1.5 s. Skew warns above 2 s and fails above 10 s, and a warning still exits 0, so read the table |

On [Docker Hub](https://hub.docker.com/r/hummingbot/hummingbot/tags) (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](https://hummingbot.org/client/global-configs/paper-trade/) 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:

```python
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 |
```

> **Reading the output (paper, not a result).** From the default 1.0 BTC and 100,000 USDT, BTC rose by 0.001 and USDT fell by 76.0812, the fill's quote amount. `hbot history` reported a fee of 0.304325 on that fill (0.4%), yet neither balance moved by it, so paper balances left the fee out. The amount also arrived as a long float-derived Decimal, so compare with a tolerance.

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](https://fincodelabs.com/en/blog/how-to-test-trading-bots). When you later add keys, [API key security](https://fincodelabs.com/en/blog/api-key-security-trading-bots) 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](https://hummingbot.org/client/global-configs/clock-tick/).

- **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](https://fincodelabs.com/en/blog/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.

**Reporting page and [collector source](https://github.com/hummingbot/hummingbot/blob/master/hummingbot/connector/connector_metrics_collector.py), read 6 November 2026**

| Item | Reporting page | Source in the image that ran |
| --- | --- | --- |
| Sent | Aggregated USD volume, connector ID, version, general system specs, a random instance UUID | `instance_id`, `exchange`, `version`, `system` (OS and platform strings), `value` |
| Not sent | Personal information, individual trades, wallet addresses, API keys | Not in the payload |
| Default | Instances report automatically every 15 minutes | Enabled; the 15 is labelled minutes but compared with clock seconds, so an offline test totalled fills every 15 seconds; sent only if USD volume is above zero |
| Destination | Foundation's servers; says never sold | `api.coinalpha.com/reporting-proxy-v2` |

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.

**Connector figures, read 6 November 2026**

| Where | Figure |
| --- | --- |
| Home page | 318 connectors, beside self-reported volume and instance totals |
| Exchanges page | 50+ exchanges |
| README | 44 table rows; its opening lines say users traded on 140+ venues in the past year |
| CLOB connectors page | 31 exchanges |
| Folders in the image that ran | 26 spot, 20 perpetual |

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](https://hummingbot.org/exchanges/) 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.

**From each project's own pages, read 6 November 2026**

| Item | Hummingbot | Freqtrade |
| --- | --- | --- |
| Own description | Open-source Python framework for agentic strategies on centralized and decentralized exchanges | Free, open-source crypto trading bot with backtesting and money management tools |
| Language | Python with Cython extensions; Gateway in TypeScript | Python, with strategies on pandas dataframes |
| Execution model | Clock tick, default 1 second, with prices and order books available in `on_tick` | Loop every few seconds; candle data refreshed once per candle |
| License | Apache-2.0 | GPL-3.0 |
| Install | Docker through `make`, or source with conda | Prebuilt Docker images (strongly recommended on Windows), or Python 3.12+ |
| Interface | `hbot` CLI, terminal client; Condor adds Telegram and web | FreqUI, Telegram, REST API |
| Stated minimum | 4 GB RAM, 5 GB disk, 1 vCPU per instance | 2 GB RAM, 1 GB disk, 2 vCPU |

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](https://fincodelabs.com/en/blog/freqtrade-tutorial), and more projects are in the [open-source crypto trading bot](https://fincodelabs.com/en/blog/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](https://fincodelabs.com/en/blog/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](https://fincodelabs.com/en/services/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](https://hummingbot.org/)
- [Hummingbot: Installation overview (Client, Condor, API, Gateway)](https://hummingbot.org/installation/)
- [Hummingbot: Client installation (requirements, Docker, source, exit commands)](https://hummingbot.org/client/installation/)
- [Freqtrade documentation: overview, hardware and software requirements](https://www.freqtrade.io/en/stable/)
- [Hummingbot: Dashboard (not actively maintained)](https://hummingbot.org/dashboard/)
- [Hummingbot: Reporting (anonymous data collection)](https://hummingbot.org/reporting/)
- [Hummingbot: Strategies overview](https://hummingbot.org/strategies/)
- [Hummingbot: CLOB connectors (31 listed, fix priority)](https://hummingbot.org/connectors/clob/)
- [Hummingbot on GitHub: README (license, install, connectors, Gateway modes)](https://github.com/hummingbot/hummingbot)
- [Hummingbot on GitHub: hbot CLI guide (commands, proposed commands, exit codes, passwords)](https://github.com/hummingbot/hummingbot/blob/master/hummingbot/cli/README.md)
- [Hummingbot docker-compose.yml, master branch](https://github.com/hummingbot/hummingbot/blob/master/docker-compose.yml)
- [Condor on GitHub: README (local mode, telemetry)](https://github.com/hummingbot/condor)
- [Hummingbot API on GitHub: README (services, credentials, port binding)](https://github.com/hummingbot/hummingbot-api)
- [SEC press release 2024-166 (9 October 2024): charges against three so-called market makers](https://www.sec.gov/newsroom/press-releases/2024-166)
- [Capital Markets Law No. 6362, Article 99/A (Turkish, consolidated text)](https://www.mevzuat.gov.tr/mevzuatmetin/1.5.6362.pdf)

> 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](https://fincodelabs.com/en/editorial-policy).

---

Published by Fincode (Fincode Yazılım ve Teknoloji A.Ş.), a software company in Istanbul, Turkey: https://fincodelabs.com/en/blog/hummingbot-tutorial

Cite as: Fincode, "Hummingbot tutorial: Client, Condor, API, vs Freqtrade", updated November 6, 2026, https://fincodelabs.com/en/blog/hummingbot-tutorial