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

• 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 and exchange credentials through Telegram
• AI Assistant - Natural language queries via GPT-4o + MCP (coming soon)

Prerequisites: Python 3.12+, Conda, Hummingbot Backend API running, Telegram Bot Token

git clone https://github.com/hummingbot/condor.git
cd condor

# Option 1: Local Python
make install     # Interactive setup + conda environment
make run         # Start the bot

# Option 2: Docker
make setup       # Interactive configuration
make deploy      # Start with Docker Compose

Telegram → Condor Bot → Hummingbot Backend 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 (/config)
│   │   ├── __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 (via /config)
├── 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 - Add, modify, delete Hummingbot Backend API servers
  • Real-time status checking (online/offline/auth error)
  • Set default server
  • Progressive form for adding servers
• API Keys - Manage exchange credentials per account
  • View connected exchanges
  • Add new credentials (field-by-field input)
  • Delete credentials with confirmation

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

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

# Setup and run with Docker
make setup       # Interactive configuration
docker compose up -d

Volumes mounted:

• condor_bot_data.pickle - User preferences and state
• config.yml - Server and permission configuration
• routines/ - Custom automation scripts

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/

Built with python-telegram-bot and Hummingbot