Skip to content

Documentation

Hummingbot is an community-driven, open source Python framework for building automated market making and algorithmic trading bots, maintained by Hummingbot Foundation.

It is designed to be modular and extensible, allowing users to automate any trading strategy on any exchange and blockchain.

Getting Started

New here? Use the guide below to find the product, experience level, and reading order that matches what you're trying to do—rather than reading every page in order.

Which path is right for you?

Your situation Recommended path Why
New to algo trading, want AI to help build and run strategies Condor Guided setup, Telegram/web UI, AI does the strategy reasoning
Want full manual control, comfortable with CLI/YAML, no AI dependency Hummingbot Client Precise control, lighter footprint, proven V1/V2 strategies
Already running Client, want to add AI agents or manage many bots Condor (add Hummingbot API on top) Keep existing strategies, layer on multi-agent management
Building custom connectors or strategies Hummingbot Client from source + Strategies Dev-focused, upstream contribution path
Running as a team or fund managing many bots/agents Condor + Hummingbot API, deployed remotely Multi-agent orchestration, Tailscale-secured access

New here?

Start with Condor—the AI assistant handles most of the setup and strategy reasoning for you. You can always add the standalone Client later for manual control over a specific strategy.

By experience level

Condor track

Level Goal Reading path Time
Beginner Get Condor running and place your first AI-assisted trade Condor Quickstart → Telegram → First Agent ~30–45 min
Beginner, no Telegram Same, driven entirely from the browser dashboard Condor Quickstart (Local mode) → Web Dashboard → First Agent ~30–45 min
Intermediate Add real credentials, run Bots/Executors alongside Agents, track P&L Credentials → Web Dashboard → Bots vs. Executors vs. Routines → Sessions ~1–2 hrs
Advanced Deploy remotely/production, manage multiple agents, secure with Tailscale Tailscale setup → Trading Agents Architecture → Agent Builder ~2–4 hrs

For the full Condor-specific breakdown, see the Condor Learning Path.

Client track

Level Goal Reading path Time
Beginner Install the client and paper trade a strategy Client Quickstart → paper trade simple_pmm → hbot CLI ~30–45 min
Intermediate Go live with a strategy, use a Controller Connect Exchange → Controllers → Strategy V2 Walkthrough → Config Files ~1–2 hrs
Advanced Build custom scripts/connectors, contribute upstream Scripts Cheatsheet → Building CLOB Connectors → Building Gateway Connectors → Contribution Guidelines ~3+ hrs

By use case

  1. AI trades for me, starting today — Condor Quickstart → Telegram → First Agent
  2. Test everything locally before risking capital — Condor Quickstart (local, no Tailscale needed) or Client paper trading
  3. Use Condor without a Telegram account — Condor Quickstart → Local mode, then drive everything from the web dashboard
  4. Run a proven market-making strategy with full manual control — Hummingbot Client Quickstart → Strategies
  5. Deploy to a VPS/cloud server for 24/7 uptime — Hummingbot API Installation → Tailscale (required) → Securing Condor and Hummingbot API with Tailscale
  6. Manage multiple bots or agents across a team — Condor + Hummingbot API, remote/Tailscale deployment
  7. Build a custom strategy or connector — Strategies → Building CLOB Connectors → Building Gateway Connectors
  8. Automate alerts/reports without LLM or API cost — Routines (Condor) or Market Data Collector (Client)

Did it install correctly?

Both Condor and Hummingbot API ship a make doctor — a read-only check of dependencies, configuration, credentials, port exposure, Tailscale, and whether the two can actually reach and authenticate with each other. Run it from each repo's directory after installing, and any time something stops working.

Do I need Tailscale?

Situation Tailscale needed?
Testing locally, Condor and Hummingbot API on one machine No
Same VPS, both services together No — the API binds 127.0.0.1 by default; still worth it if anything needs off-box access
Different machines (for example, laptop + VPS) Yes
Team or multiple devices need access Yes

Installed before the API's port lockdown? Check it

Hummingbot API used to publish port 8000 on every interface, including a VPS's public IP. It now binds 127.0.0.1 by default, and so do Postgres and the EMQX broker — but an existing stack keeps its old bindings until the containers are recreated. Run make deploy, then make doctor, which flags any of those ports still on a public interface.

To widen it deliberately, set API_BIND in .env — prefer a specific interface over 0.0.0.0. Docker's published ports are not blocked by ufw: its rules are evaluated before ufw's, so ufw deny 8000 leaves a widened port reachable unless you write DOCKER-USER rules. Close it in your cloud provider's firewall instead.

See Tailscale for setup, or the full walkthrough for security context and screenshots.

Help shape Condor

What's working? What's confusing? What do you wish Condor could do? The survey takes 2 minutes, and every response goes to the Hummingbot Foundation team and directly shapes what we build next.

Take the 2-minute survey →

For Developers

If you're a developer looking to build custom strategies or exchange connectors, see Source Installation for Hummingbot Client or Hummingbot API Installation for the API.

Afterwards, check out the Academy category in the Hummingbot Blog for blog posts and step-by-step tutorials on how to use Hummingbot.

Strategies

A Hummingbot strategy automates an algorithmic trading strategy based on a configuration file, allowing the template containing the strategy logic to be defined publicly, while users can keep their configurations private.

As of the 2.0 release, the framework offers two ways to create Hummingbot strategies:

  • Scripts: Scripts are the entry point for all Hummingbot strategies. A script's on_tick method defines the actions taken each clock tick, and it provides access to core Hummingbot components like connectors. They can range in complexity from a simple Python file that contains all strategy logic to a launcher script launches multiple Controllers, each defining a separate sub-strategy.

  • Controllers: Controllers define a modularized strategy using components such as Executors, enabling backtesting and faciliates multi-bot deployment using Dashboard.

In the past, there were legacy strategy templates (V1 Strategies), the original Hummingbot strategies that are more rigid and less customizable than those built using the new Strategy V2 framework.

Connectors

Hummingbot connectors standardize trading logic and order types across different types of exchanges and blockchain networks, so that strategies can access standardized methods that work across all connectors of that type.

Each connector's code is contained in modularized folders in the Hummingbot and/or Gateway codebases:

  • CLOB Connectors: Connectors to central limit order book (CLOB) centralized and decentralized exchanges
  • AMM DEX Connectors: Connectors to automated market maker (AMM) decentralized exchanges and aggregators

Official Code Repositories

All Hummingbot Foundation code is maintained and stored in repositories in the official Github and DockerHub organization accounts. These are the only code repositories used to release official versions of Hummingbot. Please download Hummingbot and Hummingbot-related software from only these official sources.

The Hummingbot framework is comprised of multiple code repositories, hosted on the Hummingbot Foundation Github, that are maintained by the Foundation alongside individual community members. All code is open sourced under the Apache 2.0 or MIT licenses.

Hummingbot started as a command line interface (CLI) tool. The recommended entry point is now hbot for automation and scripts; the interactive client remains available for manual use and Gateway/DEX workflows.

Today, the framework comprises companion modules to assist with other aspects of crypto algorithmic trading:

  • Gateway: Middleware to interact with AMM connectors and other DeFi protocols on various blockchains
  • Dashboard: A web-based user interface for deploying multi-bot trading strategies
  • Hummingbot API: Comprehensive API that exposes trading and bot deployment endpoints for Dashboard and other clients
  • Hummingbot MCP: Model Context Protocol (MCP) server that lets you use AI assistants to interact with Hummingbot API
  • Quants Lab: A sandbox for users to conduct research and backtest trading strategies using Python notebooks

Getting Help

If you encounter issues or have questions, here’s how you can get assistance:

We pledge that we will not use the information/data your provide us for trading purposes nor share them with third parties.

Learn Market Making in Botcamp

To gain a deeper understanding of Hummingbot strategies along with access to the latest Hummingbot framework updates, check out Botcamp, the official training and certification program for Hummingbot.

Operated by the people behind Hummingbot Foundation, Botcamp offers bootcamps and courses that teach you how to design and deploy advanced algo trading and market making strategies using Hummingbot's Strategy V2 framework.