Hummingbot API

A REST API for managing Hummingbot trading bots across multiple exchanges, with AI assistant integration via MCP.

Quick Start

git clone https://github.com/hummingbot/hummingbot-api.git
cd hummingbot-api
make setup    # Creates .env (prompts for passwords)
make deploy   # Starts all services

That's it! The API is now running at http://localhost:8000

Available Commands

Command	Description
make setup	Create .env file with configuration
make deploy	Start all services (API, PostgreSQL, EMQX)
make stop	Stop all services
make run	Run API locally in dev mode
make install	Install conda environment for development
make build	Build Docker image

Services

After make deploy, these services are available:

Service	URL	Description
API	http://localhost:8000	REST API
Swagger UI	http://localhost:8000/docs	Interactive API documentation
PostgreSQL	localhost:5432	Database
EMQX	localhost:1883	MQTT broker
EMQX Dashboard	http://localhost:18083	Broker admin (admin/public)

Connect AI Assistant (MCP)

Claude Code (CLI)

claude mcp add --transport stdio hummingbot -- \
  docker run --rm -i \
  -e HUMMINGBOT_API_URL=http://host.docker.internal:8000 \
  -v hummingbot_mcp:/root/.hummingbot_mcp \
  hummingbot/hummingbot-mcp:latest

Then use natural language:

• "Show my portfolio balances"
• "Set up my Binance account"
• "Create a market making strategy for ETH-USDT"

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hummingbot": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "HUMMINGBOT_API_URL=http://host.docker.internal:8000", "-v", "hummingbot_mcp:/root/.hummingbot_mcp", "hummingbot/hummingbot-mcp:latest"]
    }
  }
}

Restart Claude Desktop after adding.

Gateway (DEX Trading)

Gateway enables decentralized exchange trading. Start it via MCP:

"Start Gateway in development mode with passphrase 'admin'"

Or via API at http://localhost:8000/docs using the Gateway endpoints.

Once running, Gateway is available at http://localhost:15888

Configuration

The .env file contains all configuration. Key settings:

USERNAME=admin              # API username
PASSWORD=admin              # API password
CONFIG_PASSWORD=admin       # Encrypts bot credentials
DATABASE_URL=...            # PostgreSQL connection
GATEWAY_URL=...             # Gateway URL (for DEX)

Edit .env and restart with make deploy to apply changes.

API Features

• Portfolio: Balances, positions, P&L across all exchanges
• Trading: Place orders, manage positions, track history
• Bots: Deploy, monitor, and control trading bots
• Market Data: Prices, orderbooks, candles, funding rates
• Strategies: Create and manage trading strategies

Full API documentation at http://localhost:8000/docs

Development

make install              # Create conda environment
conda activate hummingbot-api
make run                  # Run with hot-reload

Troubleshooting

API won't start?

docker compose logs hummingbot-api

Database issues?

docker compose down -v    # Reset all data
make deploy               # Fresh start

Check service status:

docker ps | grep hummingbot

Support

• API Docs: http://localhost:8000/docs
• Issues: https://github.com/hummingbot/hummingbot-api/issues