A Telegram bot for monitoring and trading with Hummingbot via the Hummingbot API.

Why we recommend Tailscale for production

Condor controls real trading through Hummingbot API: orders, balances, bots, and stored exchange keys. That has always required strong passwords and careful configuration—but the risk surface has grown. Trading agents, MCP tools, and other AI assistants make powerful API actions easier to trigger, while cloud VPSes are constantly scanned for open ports like 8000.

Tailscale is one safeguard you can add: it puts the API on a private encrypted network so only your devices can reach it, without publishing port 8000 to the internet. It does not replace proper security—use strong API and config passwords, and avoid exposing sensitive services publicly. Tailscale also works when Condor and the API run on the same machine.

Full walkthrough: Securing Condor and Hummingbot API with Tailscale · Hummingbot API Tailscale guide

• Portfolio Dashboard - Comprehensive portfolio view with PNL tracking, 24h changes, and graphical analysis
• Bot Monitoring - Track active Hummingbot trading bots with real-time status and metrics
• CLOB Trading - Place orders on centralized exchanges (Binance, Bybit, etc.) with interactive menus
• DEX Trading - Swap tokens and manage CLMM liquidity positions via Gateway
• Configuration - Manage API servers, exchange credentials, and Gateway through Telegram (/servers, /keys, /gateway)
• AI Assistant - Natural language trading help via /agent (optional OpenAI or OpenRouter keys; MCP tools when configured)

• A Mac or Linux computer (Windows users: install WSL2 with Ubuntu, then use Terminal inside Ubuntu).
• The Terminal app open.
• A stable internet connection.
• For Hummingbot API (the API-only install below, or if you choose to add the API during Condor setup): Docker Desktop (Mac/Windows) or Docker on Linux, installed and running on that machine before you run the command.
• Tailscale account (free tier is enough) — recommended for production, especially when Condor and the API run on different machines. Create a reusable auth key and enable MagicDNS before you install.

1. Create a free account at tailscale.com
2. Generate a reusable auth key at Settings → Keys (starts with tskey-auth-)
3. Enable MagicDNS in the Tailscale admin console

Open Terminal, go to an empty folder where you are happy to create files (for example your home folder, or cd Desktop first), then paste:

curl -fsSL https://raw.githubusercontent.com/hummingbot/deploy/main/setup.sh | bash

The installer walks you through setup—for example your Telegram bot token and your Telegram user id—and can also install Hummingbot API on the same machine if you choose that when it asks.

When installing Hummingbot API, answer y when asked to enable Tailscale and paste your auth key. When it finishes, continue to After installation below.

Use this when you are deploying Hummingbot API on its own machine (for example a VPS or another remote server), or any time you only need the API and database stack and not Condor. Docker must be installed and running on that server before you run the command:

curl -fsSL https://raw.githubusercontent.com/hummingbot/deploy/main/setup.sh | bash -s -- --hummingbot-api

Enable Tailscale when prompted (answer y) so Condor and other clients can reach the API at http://hummingbot-api:8000 on your private tailnet—without opening port 8000 on a public IP.

If the script finishes but services did not start:

cd hummingbot-api
make setup
make deploy

The following applies after Install Condor. If you used Install only Hummingbot API, use your API host's health checks and client docs instead; point Condor (or other clients) at that API when you connect them.

• Open the Telegram chat with your Condor bot. When startup succeeds, admins receive a message such as "Condor is online and ready."
• Logs: Condor runs in a tmux session named condor. Attach with tmux attach -t condor. Detach without stopping the bot: Ctrl+B, then D. To stop Condor completely: tmux kill-session -t condor.
• In Telegram, use /servers for Hummingbot API URLs and auth, /keys for exchange credentials, and /gateway for DEX setup (or /start for the setup shortcuts) so commands like /portfolio and /trade can reach your stack.
• If Condor and the API are on different machines, install Tailscale on the Condor host and add the API in /servers with host hummingbot-api (not a public IP). See Secure Connection via Tailscale below.
• If something fails, see Troubleshooting below.

Telegram → Condor Bot → Hummingbot API → Trading Bots
                     ↘ Gateway → DEX Protocols

All commands use direct API calls via hummingbot_api_client with interactive button menus.

condor/
├── handlers/                    # Telegram command handlers
│   ├── portfolio.py            # /portfolio command with dashboard
│   ├── bots/                   # Bot monitoring module
│   │   ├── __init__.py         # /bots command
│   │   ├── menu.py             # Bot status display
│   │   └── controllers/        # Bot controller configs
│   ├── cex/                    # CEX trading module (/trade)
│   │   ├── __init__.py         # Main command, callback router
│   │   ├── trade.py            # Order placement
│   │   ├── orders.py           # Order management
│   │   └── positions.py        # Position tracking
│   ├── dex/                    # DEX trading module (/swap, /lp)
│   │   ├── __init__.py         # Main commands, callback router
│   │   ├── swap.py             # Quote, execute, history
│   │   ├── liquidity.py        # LP positions management
│   │   └── pools.py            # Pool info and discovery
│   ├── config/                 # Configuration module (/servers, /keys, /gateway)
│   │   ├── __init__.py         # Main command
│   │   ├── servers.py          # API server management
│   │   ├── api_keys.py         # Exchange credentials
│   │   └── gateway/            # Gateway configuration
│   ├── routines/               # Routines module (/routines)
│   │   └── __init__.py         # Script discovery and execution
│   └── admin/                  # Admin panel (/admin)
├── routines/                   # User-defined automation scripts
├── utils/                      # Utilities
│   ├── auth.py                 # @restricted, @admin_required decorators
│   └── telegram_formatters.py  # Message formatting
├── config_manager.py           # Unified config (servers, users, permissions)
├── hummingbot_api_client/      # API client library
└── main.py                     # Entry point

• PNL Indicators - 24h, 7d, 30d with deposit/withdrawal detection
• Token Holdings - Balances with 24h price changes
• Positions - Perpetual positions with unrealized PnL
• LP Positions - CLMM positions with in-range status
• Active Orders - Open order summary
• Dashboard - Combined chart with value history, token distribution, account breakdown
• Settings - Configure time period (1d, 3d, 7d, 14d, 30d)

• Overview - Account balances, positions, orders at a glance
• Place Orders - Interactive menu with dual input (buttons + direct text)
  • Toggle: side, order type, position mode
  • Input: connector, pair, amount, price
  • USD notation: $100 auto-converts to token units
• Set Leverage - Configure leverage and position mode per connector
• Search Orders - View/filter/cancel orders
• Manage Positions - View, trade, close positions with confirmation

• Gateway Balances - Token balances across DEX wallets
• Swap Quote - Get quotes before executing
• Execute Swap - Perform swaps with slippage control
• Quick Swap - Repeat last swap with minimal input

• Pool Discovery - Search pools by connector and token
• Pool Info - Detailed pool stats with liquidity charts
• LP Positions - Manage CLMM positions (add, close, collect fees)

• Auto-Discovery - Python scripts auto-discovered from routines/ folder
• Pydantic Config - Type-safe configuration with descriptions
• One-shot Scripts - Run once, optionally schedule (interval or daily)
• Continuous Scripts - Long-running tasks with start/stop control
• Multi-instance - Run multiple instances with different configs

• API Servers (/servers) - Add, modify, delete Hummingbot API servers
  • Real-time status checking (online/offline/auth error)
  • Set default server
  • Progressive form for adding servers
• API Keys (/keys) - Manage exchange credentials per account
  • View connected exchanges
  • Add new credentials (field-by-field input)
  • Delete credentials with confirmation
• Gateway (/gateway) - DEX connector settings and Gateway status

Preferences are automatically saved and persist across sessions:

• Portfolio - Graph time period (days, interval)
• CEX - Active account, last order parameters
• DEX - Default network/connector, last swap parameters
• General - Active server

• Admin Whitelist - Only ADMIN_USER_ID has initial access
• Role-Based Access - Admin, User, Pending, Blocked roles
• @restricted Decorator - Applied to all command handlers
• Secret Masking - Passwords hidden in UI

TELEGRAM_TOKEN=your_bot_token
ADMIN_USER_ID=123456789
OPENAI_API_KEY=sk-...                    # Optional, for AI features
OPENROUTER_API_KEY=sk-or-...             # Optional, unlocks the OpenRouter LLM picker

OpenRouter: Add OPENROUTER_API_KEY to .env, then in /agent → Change LLM select OpenRouter — Pick Model. The picker fetches the live catalog and shows only models that support tool-calling. Get a key at openrouter.ai/keys.

servers:
  main:
    host: localhost
    port: 8000
    username: admin
    password: admin
default_server: main
admin_id: 123456789
users: {}
server_access: {}
chat_defaults: {}
audit_log: []

Tailscale creates a private WireGuard network (tailnet) so Condor can reach Hummingbot API securely without exposing port 8000 publicly.

Use this when:

• Hummingbot API is running on a remote server or VPS
• You want an encrypted private connection without opening firewall ports
• Condor runs on your laptop and the API runs in the cloud (most common production layout)

Tailscale also works when Condor and the API run on the same machine—you still get a stable hostname and avoid publishing port 8000 publicly.

1. Create a free account at tailscale.com
2. Go to Settings → Keys: tailscale.com/admin/settings/keys
3. Click Generate auth key — check Reusable for multiple deployments
4. Copy the key (starts with tskey-auth-)
5. Enable MagicDNS in the Tailscale admin console

1. Run the Install only Hummingbot API command (or Quick Start with API enabled)
2. When asked Use Tailscale for secure private networking?, answer y
3. Paste your auth key and deploy:

cd hummingbot-api
make deploy
make tailscale-status   # confirm hummingbot-api appears on your tailnet

1. Install Tailscale and sign in to the same account
2. In Telegram, open /servers and add the API with:
   • Host: hummingbot-api (MagicDNS name, not a public IP)
   • Port: 8000
   • Username / Password: same as the API .env

Test from the Condor host:

curl -u YOUR_USERNAME:YOUR_PASSWORD http://hummingbot-api:8000/health

Run make setup — the wizard supports two Tailscale scenarios:

Scenario A — Deploy Hummingbot API locally with Tailscale

Choose Y to deploy Hummingbot API locally, then y when asked about Tailscale. The wizard will:

• Clone and start hummingbot-api with a Tailscale sidecar container
• Install Tailscale on this machine and connect with hostname condor
• Update config.yml to reach the API at http://hummingbot-api:8000

Scenario B — Connect to a remote Hummingbot API via Tailscale

Choose N to skip local deployment, enter the remote API URL, then y when asked about Tailscale. The wizard will:

• Install Tailscale on this machine and connect with hostname condor
• Update config.yml to use the Tailscale MagicDNS hostname of the remote API

The remote machine must be running hummingbot-api with Tailscale enabled on the same tailnet.

[Condor]  tailnet: condor  ──WireGuard──►  [API]  tailnet: hummingbot-api
                           http://hummingbot-api:8000

Both machines must be on the same Tailscale account.

tailscale status

Both condor and hummingbot-api should appear as connected peers.

Do not open port 8000 on your public firewall when Tailscale is enabled. Allow SSH (port 22) for server administration only.

For local development or manual setup without the deploy installer:

git clone https://github.com/hummingbot/condor.git
cd condor
make install     # Interactive setup + uv deps + AI CLI tools
make run         # Start the bot

To run Hummingbot API locally with Docker (for example from a sibling clone of hummingbot-api):

cd ../hummingbot-api
make setup    # answer y for Tailscale on production/VPS setups
make deploy

See flows/ directory for detailed command flow documentation:

• Each handler has a corresponding *_flow.txt file
• common_patterns.txt documents shared patterns across handlers

1. Create handler in handlers/ (or subdirectory for complex features)
2. Register in main.py
3. Follow patterns in flows/common_patterns.txt
4. Document flow in flows/

• Docs: https://condor.hummingbot.org
• Installation guide: https://condor.hummingbot.org/getting-started/installing
• Tailscale guide: https://hummingbot.org/hummingbot-api/tailscale/
• Issues: https://github.com/hummingbot/condor/issues

Built with python-telegram-bot and Hummingbot