Hummingbot API

A comprehensive RESTful API framework for managing trading operations across multiple exchanges. The Hummingbot API provides a centralized platform to aggregate all your trading functionalities, from basic account management to sophisticated automated trading strategies.

What is Hummingbot API?

The Hummingbot API is designed to be your central hub for trading operations, offering:

• Multi-Exchange Account Management: Create and manage multiple trading accounts across different exchanges
• Portfolio Monitoring: Real-time balance tracking and portfolio distribution analysis
• Trade Execution: Execute trades, manage orders, and monitor positions across all your accounts
• Automated Trading: Deploy and control Hummingbot instances with automated strategies
• Strategy Management: Add, configure, and manage trading strategies in real-time
• Complete Flexibility: Build any trading product on top of this robust API framework

Whether you're building a trading dashboard, implementing algorithmic strategies, or creating a comprehensive trading platform, the Hummingbot API provides all the tools you need.

System Dependencies

The Hummingbot API requires two essential services to function properly:

1. PostgreSQL Database

Stores all trading data including:

• Orders and trade history
• Account states and balances
• Positions and funding payments
• Performance metrics

2. EMQX Message Broker

Enables real-time communication with trading bots:

• Receives live updates from running bots
• Sends commands to control bot execution
• Handles real-time data streaming

Installation & Setup

Prerequisites

• Docker and Docker Compose installed
• Git for cloning the repository

Quick Start

1. Clone the repository

   git clone https://github.com/hummingbot/hummingbot-api.git
   cd hummingbot-api

2. Make setup script executable and run it

   chmod +x setup.sh
   ./setup.sh

3. Configure your environment During setup, you'll configure several important variables:

   • Config Password: Used to encrypt and hash API keys and credentials for security
   • Username & Password: Basic authentication credentials for API access (used by dashboards and other systems)
   • Additional configurations: Available in the .env file including:
     • Broker configuration (EMQX settings)
     • Database URL
     • Market data cleanup settings
     • AWS S3 configuration (experimental)
     • Banned tokens list (for delisted tokens)

4. Set up monitoring (Production recommended) For production deployments, add observability through Logfire:

   export LOGFIRE_TOKEN=your_token_here

   Learn more: Logfire Documentation

After running setup.sh, the required Docker images (EMQX, PostgreSQL, and Hummingbot) will be running and ready.

Running the API

You have two deployment options depending on your use case:

For Users (Production/Simple Deployment)

./run.sh

This runs the API in a Docker container - simple and isolated.

For Developers (Development Environment)

1. Install Conda (if not already installed)

2. Set up the development environment

   make install

   This creates a Conda environment with all dependencies.

3. Run in development mode

   ./run.sh --dev

   This starts the API from source with hot-reloading enabled.

Getting Started

Once the API is running, you can access it at http://localhost:8000

First Steps

1. Visit the API Documentation: Go to http://localhost:8000/docs to explore the interactive Swagger documentation
2. Authenticate: Use the username and password you configured during setup
3. Test endpoints: Use the Swagger interface to test API functionality

API Overview

The Hummingbot API is organized into several functional routers:

🐳 Docker Management (/docker)

• Check Docker daemon status and health
• Pull new Docker images with async support
• Start, stop, and remove containers
• Monitor active and exited containers
• Clean up exited containers
• Archive container data locally or to S3
• Track image pull status and progress

💳 Account Management (/accounts)

• Create and delete trading accounts
• Add/remove exchange credentials
• List available credentials per account
• Basic account configuration

🔌 Connector Discovery (/connectors)

Provides exchange connector information and configuration

• List available exchange connectors
• Get connector configuration requirements
• Retrieve trading rules and constraints
• Query supported order types per connector

📊 Portfolio Management (/portfolio)

Centralized portfolio tracking and analytics

• Real-time Portfolio State: Current balances across all accounts
• Portfolio History: Time-series data with cursor-based pagination
• Token Distribution: Aggregate holdings by token across exchanges
• Account Distribution: Percentage-based portfolio allocation analysis
• Advanced Filtering: Filter by account names and connectors

💹 Trading Operations (/trading)

Enhanced with POST-based filtering and comprehensive order/trade management

• Order Placement: Execute trades with advanced order types
• Order Cancellation: Cancel specific orders by ID
• Position Tracking: Real-time perpetual positions with PnL data
• Active Orders: Live order monitoring from connector in-flight orders
• Order History: Paginated historical orders with advanced filtering
• Trade History: Complete execution records with filtering
• Funding Payments: Historical funding payment tracking for perpetuals
• Position Modes: Configure HEDGE/ONEWAY modes for perpetual trading
• Leverage Management: Set and adjust leverage per trading pair

🤖 Bot Orchestration (/bot-orchestration)

• Monitor bot status and MQTT connectivity
• Deploy V2 scripts and controllers
• Start/stop bots with configurable parameters
• Stop and archive bots with background task support
• Retrieve bot performance history
• Real-time bot status monitoring

📋 Strategy Management

• Controllers (/controllers): Manage V2 strategy controllers
  • CRUD operations on controller files
  • Controller configuration management
  • Bot-specific controller configurations
  • Template retrieval for new configs
• Scripts (/scripts): Handle traditional Hummingbot scripts
  • CRUD operations on script files
  • Script configuration management
  • Configuration templates

📊 Market Data (/market-data)

Professional market data analysis and real-time feeds

• Price Discovery: Real-time prices, funding rates, mark/index prices
• Candle Data: Real-time and historical candles with multiple intervals
• Order Book Analysis:
  • Live order book snapshots
  • Price impact calculations
  • Volume queries at specific price levels
  • VWAP (Volume-Weighted Average Price) calculations
• Feed Management: Active feed monitoring with automatic cleanup

🔄 Backtesting (/backtesting)

• Run strategy backtests against historical data
• Support for controller configurations
• Customizable trade costs and resolution

📈 Archived Bot Analytics (/archived-bots)

Comprehensive analysis of stopped bot performance

• List and discover archived bot databases
• Performance metrics and trade analysis
• Historical order and trade retrieval
• Position and executor data extraction
• Controller configuration recovery
• Support for both V1 and V2 bot architectures

Configuration

Environment Variables

Key configuration options available in .env:

• CONFIG_PASSWORD: Encrypts API keys and credentials
• USERNAME/PASSWORD: API authentication credentials
• BROKER_HOST/PORT: EMQX message broker settings
• DATABASE_URL: PostgreSQL connection string
• ACCOUNT_UPDATE_INTERVAL: Balance update frequency (minutes)
• AWS_API_KEY/AWS_SECRET_KEY: S3 archiving (optional)
• BANNED_TOKENS: Comma-separated list of tokens to exclude
• LOGFIRE_TOKEN: Observability and monitoring (production)

Bot Instance Structure

Each bot maintains its own isolated environment:

bots/instances/hummingbot-{name}/
├── conf/           # Configuration files
├── data/           # Bot databases and state
└── logs/           # Execution logs

Development

Code Quality Tools

# Install pre-commit hooks
make install-pre-commit

# Format code (runs automatically)
black --line-length 130 .
isort --line-length 130 --profile black .

Testing

The API includes comprehensive backtesting capabilities. Test using:

• Backtesting router for strategy validation
• Swagger UI at http://localhost:8000/docs
• Integration testing with live containers

Architecture

Core Components

1. FastAPI Application: HTTP API with Basic Auth
2. Docker Service: Container lifecycle management
3. Bot Orchestrator: Strategy deployment and monitoring
4. Accounts Service: Multi-exchange account management
5. Market Data Manager: Real-time feeds and historical data
6. MQTT Broker: Real-time bot communication

Data Models

• Orders and trades with multi-account support
• Portfolio states and balance tracking
• Position management for perpetual trading
• Historical performance analytics

Authentication

All API endpoints require HTTP Basic Authentication. Include your configured credentials in all requests:

curl -u username:password http://localhost:8000/endpoint

Support & Documentation

• API Documentation: Available at http://localhost:8000/docs when running
• Detailed Examples: Check the CLAUDE.md file for comprehensive API usage examples
• Issues: Report bugs and feature requests through the project's issue tracker

---

Ready to start trading? Deploy your first account and start exploring the powerful capabilities of the Hummingbot API!