diff --git a/.gitignore b/.gitignore index 7856a1df..648d894d 100644 --- a/.gitignore +++ b/.gitignore @@ -161,3 +161,14 @@ cython_debug/ # Hummingbot Gateway files gateway-files/ + +# Hummingbot credentials and local data +bots/credentials/ +bots/instances/ + +# Local MCP configuration (project-specific overrides) +.mcp.json + +# IDE files +.vscode/ +.idea/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..c606bed1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,568 @@ +# Using Hummingbot API with AI Agents + +This guide shows you how to interact with the Hummingbot API using various AI agents including ChatGPT, custom agents, and other MCP-compatible assistants. + +## 🤖 Method 1: MCP Server (Recommended) + +The Hummingbot MCP server provides natural language access to all API functionality through MCP-compatible AI clients. + +### OpenAI ChatGPT (Desktop App) + +If OpenAI releases an MCP-compatible desktop client, you can configure it similar to Claude: + +1. **Enable MCP during Hummingbot API setup**: + ```bash + ./setup.sh # Answer "y" to "Enable MCP server for AI assistant usage?" + ``` + +2. **Configure the MCP server**: + Add to your ChatGPT configuration file (location may vary): + ```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"] + } + } + } + ``` + +3. **Start using natural language**: + - "Show me my portfolio across all exchanges" + - "What bots are currently running?" + - "Create a grid trading strategy for BTC-USDT" + - "Analyze my trading performance this month" + +### Custom MCP Clients + +For custom implementations, connect to the MCP server using stdio transport: + +**Python Example**: +```python +import subprocess +import json + +# Start the MCP server process +process = subprocess.Popen([ + "docker", "run", "--rm", "-i", "-e", "HUMMINGBOT_API_URL=http://host.docker.internal:8000", "-v", "hummingbot_mcp:/root/.hummingbot_mcp", "hummingbot/hummingbot-mcp:latest" +], + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + text=True +) + +# Send JSON-RPC request +request = { + "jsonrpc": "2.0", + "id": 1, + "method": "tools/list", + "params": {} +} +process.stdin.write(json.dumps(request) + "\n") +process.stdin.flush() + +# Read response +response = process.stdout.readline() +print(json.loads(response)) +``` + +**Node.js Example**: +```javascript +const { spawn } = require('child_process'); + +// Start MCP server +const mcp = spawn('docker', ['run', '--rm', '-i', '-e', 'HUMMINGBOT_API_URL=http://host.docker.internal:8000', '-v', 'hummingbot_mcp:/root/.hummingbot_mcp', 'hummingbot/hummingbot-mcp:latest']); + +// Send request +const request = { + jsonrpc: '2.0', + id: 1, + method: 'tools/list', + params: {} +}; + +mcp.stdin.write(JSON.stringify(request) + '\n'); + +// Handle response +mcp.stdout.on('data', (data) => { + console.log(JSON.parse(data.toString())); +}); +``` + +### Available MCP Tools + +The Hummingbot MCP server provides these tools: + +- **Portfolio Management**: `get_portfolio_balances`, `get_portfolio_distribution` +- **Bot Operations**: `list_bots`, `start_bot`, `stop_bot`, `get_bot_status` +- **Market Data**: `get_prices`, `get_order_book`, `get_candles` +- **Order Management**: `place_order`, `cancel_order`, `get_active_orders` +- **Account Management**: `list_accounts`, `add_credentials` +- **Strategy Management**: `list_strategies`, `get_strategy_template` + +For a complete list, use the `tools/list` MCP method. + +## 🔧 Method 2: Direct API Access (Standard HTTP) + +All AI agents can interact with the API using standard HTTP requests. + +### API Endpoints + +The API is accessible at `http://localhost:8000` with interactive Swagger docs at `http://localhost:8000/docs`. + +See @API_REFERENCE.md for the complete endpoint reference. + +### Authentication + +All endpoints require HTTP Basic Authentication: + +```bash +curl -u username:password http://localhost:8000/endpoint +``` + +Use the username and password you configured during setup (stored in `.env`). + +### Common API Operations + +**1. Get Portfolio Balances**: +```bash +curl -u admin:admin -X POST http://localhost:8000/portfolio/state \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +**2. List Active Bots**: +```bash +curl -u admin:admin http://localhost:8000/bot-orchestration/status +``` + +**3. Get Market Prices**: +```bash +curl -u admin:admin -X POST http://localhost:8000/market-data/prices \ + -H "Content-Type: application/json" \ + -d '{ + "connector_name": "binance", + "trading_pairs": ["BTC-USDT", "ETH-USDT"] + }' +``` + +**4. Place an Order**: +```bash +curl -u admin:admin -X POST http://localhost:8000/trading/orders \ + -H "Content-Type: application/json" \ + -d '{ + "account_name": "master_account", + "connector_name": "binance", + "trading_pair": "BTC-USDT", + "order_type": "limit", + "trade_type": "buy", + "price": 50000, + "amount": 0.001 + }' +``` + +**5. Start a Trading Bot**: +```bash +curl -u admin:admin -X POST http://localhost:8000/bot-orchestration/deploy-v2-script \ + -H "Content-Type: application/json" \ + -d '{ + "bot_name": "my_pmm_bot", + "script": "v2_with_controllers", + "config": { + "connector": "binance", + "trading_pair": "ETH-USDT", + "total_amount_quote": 100 + } + }' +``` + +### Integration Examples + +**Python with requests**: +```python +import requests +from requests.auth import HTTPBasicAuth + +auth = HTTPBasicAuth('admin', 'admin') +base_url = 'http://localhost:8000' + +# Get portfolio state +response = requests.post( + f'{base_url}/portfolio/state', + json={}, + auth=auth +) +print(response.json()) +``` + +**JavaScript with fetch**: +```javascript +const username = 'admin'; +const password = 'admin'; +const baseURL = 'http://localhost:8000'; + +const headers = { + 'Content-Type': 'application/json', + 'Authorization': 'Basic ' + btoa(`${username}:${password}`) +}; + +// Get portfolio state +fetch(`${baseURL}/portfolio/state`, { + method: 'POST', + headers: headers, + body: JSON.stringify({}) +}) +.then(res => res.json()) +.then(data => console.log(data)); +``` + +## 🌐 Common Workflows + +### Managing Gateway Container (For DEX Trading) + +Gateway is required for decentralized exchange (DEX) trading. The `manage_gateway_container` MCP tool provides full lifecycle management. + +#### Using Natural Language (MCP-Compatible Assistants) + +If you're using Claude, ChatGPT, or other MCP-compatible AI assistants, you can manage Gateway with simple commands: + +- **"Start Gateway in development mode with passphrase 'admin'"** +- **"Check Gateway status"** +- **"Restart the Gateway container"** +- **"Stop Gateway"** + +#### Using MCP Tool Programmatically + +For custom integrations, call the `manage_gateway_container` tool via MCP: + +**Python Example**: +```python +import subprocess +import json + +# Start MCP server +process = subprocess.Popen([ + "docker", "run", "--rm", "-i", "-e", "HUMMINGBOT_API_URL=http://host.docker.internal:8000", + "-v", "hummingbot_mcp:/root/.hummingbot_mcp", "hummingbot/hummingbot-mcp:latest" +], + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + text=True +) + +def send_request(req): + process.stdin.write(json.dumps(req) + "\n") + process.stdin.flush() + return json.loads(process.stdout.readline()) + +# 1. Configure API connection (first time only) +send_request({ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "configure_api_servers", + "arguments": { + "api_url": "http://host.docker.internal:8000", + "username": "admin", + "password": "admin" + } + } +}) + +# 2. Start Gateway container +gateway_response = send_request({ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "start", + "config": { + "passphrase": "admin", + "dev_mode": True, + "image": "hummingbot/gateway:latest", + "port": 15888 + } + } + } +}) +print(gateway_response) + +# 3. Check Gateway status +status = send_request({ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "get_status" + } + } +}) +print(status) + +# 4. Restart Gateway (if needed) +send_request({ + "jsonrpc": "2.0", + "id": 4, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "restart" + } + } +}) + +# 5. Stop Gateway +send_request({ + "jsonrpc": "2.0", + "id": 5, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "stop" + } + } +}) +``` + +**Node.js Example**: +```javascript +const { spawn } = require('child_process'); + +// Start MCP server +const mcp = spawn('docker', ['run', '--rm', '-i', '-e', 'HUMMINGBOT_API_URL=http://host.docker.internal:8000', '-v', 'hummingbot_mcp:/root/.hummingbot_mcp', 'hummingbot/hummingbot-mcp:latest']); + +let buffer = ''; +mcp.stdout.on('data', (data) => { + buffer += data.toString(); + const lines = buffer.split('\n'); + buffer = lines.pop(); + lines.forEach(line => { + if (line.trim()) { + console.log(JSON.parse(line)); + } + }); +}); + +function sendRequest(req) { + mcp.stdin.write(JSON.stringify(req) + '\n'); +} + +// 1. Configure API connection +sendRequest({ + jsonrpc: '2.0', + id: 1, + method: 'tools/call', + params: { + name: 'configure_api_servers', + arguments: { + api_url: 'http://host.docker.internal:8000', + username: 'admin', + password: 'admin' + } + } +}); + +// 2. Start Gateway container +sendRequest({ + jsonrpc: '2.0', + id: 2, + method: 'tools/call', + params: { + name: 'manage_gateway_container', + arguments: { + action: 'start', + config: { + passphrase: 'admin', + dev_mode: true, + image: 'hummingbot/gateway:latest', + port: 15888 + } + } + } +}); + +// 3. Check Gateway status +sendRequest({ + jsonrpc: '2.0', + id: 3, + method: 'tools/call', + params: { + name: 'manage_gateway_container', + arguments: { + action: 'get_status' + } + } +}); +``` + +#### Using Direct API Access (Alternative) + +If MCP is not available, you can manage Gateway through the API directly: + +```bash +# Start Gateway (via Swagger UI or curl) +curl -u admin:admin -X POST http://localhost:8000/manage-gateway \ + -H "Content-Type: application/json" \ + -d '{ + "action": "start", + "passphrase": "admin", + "dev_mode": true + }' + +# Check Gateway status +curl -u admin:admin http://localhost:8000/manage-gateway/status +``` + +#### Important Notes +- **Development mode** (`dev_mode: true`): HTTP access on port 15888, Swagger UI at `http://localhost:15888/docs` +- **Production mode** (`dev_mode: false`): HTTPS with certificates, more secure +- **Passphrase**: Encrypts/decrypts DEX wallet keys - store securely +- **Port**: Default is 15888, must be available on your system +- **Gateway URL**: `http://localhost:15888` (dev) or `https://localhost:15888` (prod) + +## 📚 API Reference + +For complete API documentation, see: +- **@API_REFERENCE.md**: Full endpoint reference with request/response examples +- **Swagger UI**: http://localhost:8000/docs (interactive documentation) +- **@README.md**: Setup instructions and architecture overview + +## 🆘 Troubleshooting + +**MCP Server Issues**: +```bash +# Check if MCP container is running +docker ps | grep hummingbot-mcp + +# View MCP logs +docker logs hummingbot-mcp + +# Restart MCP +docker compose restart hummingbot-mcp +``` + +**API Connection Issues**: +```bash +# Check if API is running +docker ps | grep hummingbot-api + +# View API logs +docker logs hummingbot-api + +# Test API connectivity +curl -u admin:admin http://localhost:8000/ +``` + +**Authentication Errors**: +- Verify credentials in `.env` file +- Ensure you're using the correct username and password +- Check that the API container is running + +**Docker Issues**: +```bash +# Ensure Docker is running +docker ps + +# Restart all services +docker compose restart + +# View all logs +docker compose logs -f +``` + +## 🚀 Next Steps + +1. **Explore the API**: Visit http://localhost:8000/docs +2. **Read API Reference**: See @API_REFERENCE.md for all endpoints +3. **Set up credentials**: Add exchange API keys via `/accounts/add-credential` +4. **Deploy a bot**: Start with a simple PMM or DCA strategy +5. **Monitor performance**: Use portfolio and bot status endpoints + +## 💡 Tips for AI Agent Integration + +1. **Use MCP when possible**: More natural language interface, automatic tool discovery +2. **Handle authentication**: Store credentials securely in your agent's configuration +3. **Implement retry logic**: API calls may timeout, implement exponential backoff +4. **Parse responses carefully**: All responses are JSON, handle errors appropriately +5. **Use Swagger UI**: Test endpoints manually before integrating into your agent + +## MCP Tools Best Practices + +### Using `configure_api_servers` for Connection Management + +**Before using any MCP tools**, always ensure the API server is properly configured: + +```python +# Check if connection is working - if any MCP tool fails, reconnect: +configure_api_servers(action="add", name="local", host="localhost", port=8000, username="admin", password="admin") +configure_api_servers(action="set_default", name="local") +``` + +### Using `get_portfolio_overview` for Token Balances + +**Preferred method for checking balances**: +- Use `get_portfolio_overview()` instead of direct API calls +- Includes CEX balances, DEX balances, LP positions, and active orders in one call +- Automatically handles all account types (Hyperliquid, Solana, Ethereum, etc.) + +```python +# Get complete portfolio overview +get_portfolio_overview( + include_balances=True, + include_perp_positions=False, + include_lp_positions=True, + include_active_orders=True, + as_distribution=False +) +``` + +### Common MCP Connection Issue + +**Error**: +``` +Error executing tool get_portfolio_overview: ❌ Failed to connect to Hummingbot API at http://docker.host.internal:8000 + +Connection failed after 3 attempts. + +💡 Solutions: + 1. Check if the API is running and accessible + 2. Verify your credentials are correct + 3. Use 'configure_api_servers' tool for setup + +Original error: Cannot connect to host docker.host.internal:8000 ssl:default [Name or service not known] +``` + +**Root Cause**: The MCP tool loses connection to the API server. This happens when: +- MCP server reconnects/restarts +- API credentials are not cached +- Network configuration changes + +**Solution**: Reconfigure the API server connection before retrying: + +```python +# Step 1: Add server configuration +configure_api_servers( + action="add", + name="local", + host="localhost", + port=8000, + username="admin", + password="admin" +) + +# Step 2: Set as default +configure_api_servers(action="set_default", name="local") + +# Step 3: Retry the operation +get_portfolio_overview(include_balances=True) +``` + +**Prevention**: Always check connection before using other MCP tools. If you see any connection error, immediately run `configure_api_servers` to restore the connection. diff --git a/API_REFERENCE.md b/API_REFERENCE.md new file mode 100644 index 00000000..ca1106fd --- /dev/null +++ b/API_REFERENCE.md @@ -0,0 +1,1080 @@ +# Hummingbot API Reference for AI Assistants + +**Quick Start:** This API is accessible at `http://localhost:8000` with interactive docs at `http://localhost:8000/docs`. + +## 🤖 MCP Tools (Recommended - Use These First!) + +**For AI Assistants:** Before making direct API calls, check if an MCP tool exists for your task. MCP tools provide simplified, high-level access to common operations. + +### Essential Setup & Connection + +#### `configure_api_servers` - **ALWAYS RUN FIRST** +Configure connection to the Hummingbot API. Run this before using any other MCP tool. + +```python +configure_api_servers( + action="add", + name="local", + host="localhost", + port=8000, + username="admin", + password="admin" +) +configure_api_servers(action="set_default", name="local") +``` + +**When to use:** +- Before any other MCP tool +- When you get connection errors +- After MCP server restarts + +--- + +### Portfolio & Trading + +#### `get_portfolio_overview` - **Unified Portfolio View** +Get complete portfolio across CEX, DEX, LP positions, and orders in one call. + +```python +get_portfolio_overview( + account_names=["master_account"], # Optional filter + connector_names=["binance", "solana-mainnet-beta"], # Optional filter + include_balances=True, + include_perp_positions=True, + include_lp_positions=True, + include_active_orders=True, + as_distribution=False # Set True for percentage breakdown +) +``` + +**Use instead of:** +- `POST /portfolio/state` +- `POST /portfolio/distribution` +- `POST /trading/positions` +- `POST /trading/orders/active` + +**When to use:** +- "Show me my portfolio" +- "What are my balances?" +- "Do I have any open positions?" + +--- + +#### `place_order` - Place Exchange Orders +Execute buy/sell orders on CEX exchanges. + +```python +place_order( + connector_name="binance", + trading_pair="BTC-USDT", + trade_type="BUY", # or "SELL" + amount="$100", # Use $ prefix for USD value, or specify base amount "0.001" + order_type="MARKET", # or "LIMIT" + price="50000", # Required for LIMIT orders + account_name="master_account" +) +``` + +**Use instead of:** `POST /trading/orders` + +--- + +#### `search_history` - Search Trading History +Search orders, perpetual positions, or CLMM positions. + +```python +search_history( + data_type="orders", # or "perp_positions", "clmm_positions" + account_names=["master_account"], + connector_names=["binance"], + trading_pairs=["BTC-USDT"], + status="FILLED", # Optional: OPEN, CLOSED, FILLED, CANCELED + start_time=1609459200, # Unix timestamp + end_time=1609545600, + limit=50 +) +``` + +**Use instead of:** +- `POST /trading/orders/search` +- `POST /trading/positions` +- `POST /gateway/clmm/positions/search` + +--- + +#### `set_account_position_mode_and_leverage` - Configure Perpetuals +Set position mode and leverage for perpetual trading. + +```python +set_account_position_mode_and_leverage( + account_name="master_account", + connector_name="binance_perpetual", + trading_pair="BTC-USDT", # Required for leverage + position_mode="HEDGE", # or "ONE-WAY" + leverage=10 # Optional +) +``` + +**Use instead of:** +- `POST /trading/{account_name}/{connector_name}/position-mode` +- `POST /trading/{account_name}/{connector_name}/leverage` + +--- + +### Exchange Credentials & Setup + +#### `setup_connector` - Add Exchange Credentials +Progressive setup flow for adding exchange API keys. + +```python +# Step 1: List available exchanges +setup_connector() + +# Step 2: Get required fields for specific exchange +setup_connector(connector="binance") + +# Step 3: Select account (if needed) +# Step 4: Add credentials +setup_connector( + connector="binance", + credentials={ + "binance_api_key": "your_key", + "binance_api_secret": "your_secret" + }, + account="master_account" +) +``` + +**Use instead of:** +- `GET /connectors/` +- `GET /connectors/{connector_name}/config-map` +- `POST /accounts/add-credential/{account_name}/{connector_name}` + +--- + +### Market Data + +#### `get_prices` - Latest Market Prices +Get current prices for multiple trading pairs. + +```python +get_prices( + connector_name="binance", + trading_pairs=["BTC-USDT", "ETH-USDT", "SOL-USDT"] +) +``` + +**Use instead of:** `POST /market-data/prices` + +--- + +#### `get_candles` - Price History (OHLCV) +Get candlestick data for technical analysis. + +```python +get_candles( + connector_name="binance", + trading_pair="BTC-USDT", + interval="1h", # "1m", "5m", "15m", "30m", "1h", "4h", "1d" + days=30 # Days of history +) +``` + +**Use instead of:** `POST /market-data/historical-candles` + +--- + +#### `get_funding_rate` - Perpetual Funding Rates +Get funding rates for perpetual contracts. + +```python +get_funding_rate( + connector_name="binance_perpetual", + trading_pair="BTC-USDT" +) +``` + +**Use instead of:** `POST /market-data/funding-info` + +--- + +#### `get_order_book` - Order Book Analysis +Get order book data with advanced queries. + +```python +get_order_book( + connector_name="binance", + trading_pair="BTC-USDT", + query_type="snapshot", # "volume_for_price", "price_for_volume", etc. + query_value=50000, # Required for non-snapshot queries + is_buy=True # Required for non-snapshot queries +) +``` + +**Use instead of:** +- `POST /market-data/order-book` +- `POST /market-data/order-book/price-for-volume` +- `POST /market-data/order-book/volume-for-price` +- `POST /market-data/order-book/vwap-for-volume` + +--- + +### Gateway (DEX Trading) + +#### `manage_gateway_container` - Gateway Lifecycle +Start, stop, or check Gateway container status. + +```python +# Start Gateway +manage_gateway_container( + action="start", + config={ + "passphrase": "admin", + "image": "hummingbot/gateway:latest", + "port": 15888 + } +) + +# Check status +manage_gateway_container(action="get_status") + +# View logs +manage_gateway_container(action="get_logs", tail=100) + +# Restart +manage_gateway_container(action="restart") + +# Stop +manage_gateway_container(action="stop") +``` + +**Use instead of:** +- `POST /gateway/start` +- `GET /gateway/status` +- `POST /gateway/stop` +- `POST /gateway/restart` +- `GET /gateway/logs` + +--- + +#### `manage_gateway_config` - Configure DEX Resources +Manage chains, networks, tokens, connectors, pools, and wallets. + +```python +# List supported chains +manage_gateway_config(resource_type="chains", action="list") + +# List networks +manage_gateway_config(resource_type="networks", action="list") + +# Get specific network +manage_gateway_config( + resource_type="networks", + action="get", + network_id="solana-mainnet-beta" +) + +# List tokens on network +manage_gateway_config( + resource_type="tokens", + action="list", + network_id="solana-mainnet-beta", + search="USDC" # Optional search filter +) + +# Add token +manage_gateway_config( + resource_type="tokens", + action="add", + network_id="solana-mainnet-beta", + token_address="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", + token_symbol="USDC", + token_decimals=6, + token_name="USD Coin" +) + +# Add wallet +manage_gateway_config( + resource_type="wallets", + action="add", + chain="solana", + private_key="your_private_key" +) + +# List DEX connectors +manage_gateway_config(resource_type="connectors", action="list") + +# List pools +manage_gateway_config( + resource_type="pools", + action="list", + connector_name="meteora", + network="mainnet-beta" +) +``` + +**Use instead of:** +- `GET /gateway/chains` +- `GET /gateway/networks` +- `GET /gateway/networks/{network_id}` +- `GET /gateway/networks/{network_id}/tokens` +- `POST /gateway/networks/{network_id}/tokens` +- `POST /accounts/gateway/add-wallet` +- `GET /gateway/connectors` +- `GET /gateway/pools` + +--- + +#### `manage_gateway_swaps` - DEX Swaps +Quote and execute swaps on DEX routers (Jupiter, 0x). + +```python +# Get quote +manage_gateway_swaps( + action="quote", + connector="jupiter", + network="solana-mainnet-beta", + trading_pair="SOL-USDC", + side="BUY", # or "SELL" + amount="1.0", # Amount of base token + slippage_pct="1.0" +) + +# Execute swap +manage_gateway_swaps( + action="execute", + connector="jupiter", + network="solana-mainnet-beta", + trading_pair="SOL-USDC", + side="BUY", + amount="1.0", + slippage_pct="1.0", + wallet_address="your_wallet_address" # Optional +) + +# Search swap history +manage_gateway_swaps( + action="search", + search_connector="jupiter", + search_network="solana-mainnet-beta", + status="CONFIRMED", # SUBMITTED, CONFIRMED, FAILED + limit=50 +) + +# Check transaction status +manage_gateway_swaps( + action="get_status", + transaction_hash="your_tx_hash" +) +``` + +**Use instead of:** +- `POST /gateway/swap/quote` +- `POST /gateway/swap/execute` +- `POST /gateway/swaps/search` +- `GET /gateway/swaps/{transaction_hash}/status` + +--- + +#### `explore_gateway_clmm_pools` - Discover CLMM Pools +Browse concentrated liquidity pools. + +```python +# List pools +explore_gateway_clmm_pools( + action="list_pools", + connector="meteora", + page=0, + limit=50, + search_term="SOL", # Optional filter + sort_key="volume", # volume, tvl, feetvlratio + order_by="desc", + include_unknown=True, + detailed=False # Set True for more columns +) + +# Get specific pool info +explore_gateway_clmm_pools( + action="get_pool_info", + connector="meteora", + network="solana-mainnet-beta", + pool_address="pool_address_here" +) +``` + +**Use instead of:** +- `GET /gateway/clmm/pools` +- `GET /gateway/clmm/pool-info` + +--- + +#### `manage_gateway_clmm_positions` - CLMM Liquidity Positions +Open, close, collect fees from concentrated liquidity positions. + +```python +# Open position +manage_gateway_clmm_positions( + action="open_position", + connector="meteora", + network="solana-mainnet-beta", + pool_address="pool_address", + lower_price="150", + upper_price="250", + base_token_amount="1.0", # Optional + quote_token_amount="200", # Optional + slippage_pct="1.0", + wallet_address="your_wallet", # Optional + extra_params={"strategyType": 0} # Connector-specific +) + +# Get positions for wallet/pool +manage_gateway_clmm_positions( + action="get_positions", + connector="meteora", + network="solana-mainnet-beta", + pool_address="pool_address", + wallet_address="your_wallet" +) + +# Collect fees +manage_gateway_clmm_positions( + action="collect_fees", + connector="meteora", + network="solana-mainnet-beta", + position_address="position_nft_address", + wallet_address="your_wallet" +) + +# Close position +manage_gateway_clmm_positions( + action="close_position", + connector="meteora", + network="solana-mainnet-beta", + position_address="position_nft_address", + wallet_address="your_wallet" +) +``` + +**Use instead of:** +- `POST /gateway/clmm/open` +- `POST /gateway/clmm/positions_owned` +- `POST /gateway/clmm/collect-fees` +- `POST /gateway/clmm/close` + +--- + +### Bot Management + +#### `explore_controllers` - Discover Trading Strategies +List and understand available trading controllers (strategies). + +```python +# List all controllers +explore_controllers(action="list") + +# List by type +explore_controllers( + action="list", + controller_type="directional_trading" # or "market_making", "generic" +) + +# Describe specific controller +explore_controllers( + action="describe", + controller_name="macd_bb_v1" +) + +# Describe specific config +explore_controllers( + action="describe", + config_name="my_strategy_config" +) +``` + +**Use instead of:** +- `GET /controllers/` +- `GET /controllers/{controller_type}/{controller_name}` +- `GET /controllers/configs/` + +--- + +#### `modify_controllers` - Create/Update Strategies +Create, update, or delete controller templates and configs. + +```python +# Create controller config +modify_controllers( + action="upsert", + target="config", + config_name="my_pmm_strategy", + config_data={ + "controller_name": "macd_bb_v1", + "controller_type": "directional_trading", + # ... other config parameters + } +) + +# Update bot-specific config +modify_controllers( + action="upsert", + target="config", + config_name="my_pmm_strategy", + config_data={...}, + bot_name="my_bot", + confirm_override=True +) + +# Delete config +modify_controllers( + action="delete", + target="config", + config_name="old_strategy" +) +``` + +**Use instead of:** +- `POST /controllers/configs/{config_name}` +- `PUT /controllers/configs/{config_name}` +- `DELETE /controllers/configs/{config_name}` +- `POST /controllers/{controller_type}/{controller_name}` + +--- + +#### `deploy_bot_with_controllers` - Deploy Trading Bot +Deploy a bot with controller configurations. + +```python +deploy_bot_with_controllers( + bot_name="my_trading_bot", + controllers_config=["strategy_config_1", "strategy_config_2"], + account_name="master_account", + max_global_drawdown_quote=1000, # Optional stop-loss + max_controller_drawdown_quote=500, # Optional per-strategy stop + image="hummingbot/hummingbot:latest" +) +``` + +**Use instead of:** `POST /bot-orchestration/deploy-v2-controllers` + +--- + +#### `get_active_bots_status` - Monitor Running Bots +Get status of all active trading bots. + +```python +get_active_bots_status() +``` + +**Returns:** Bot status, PnL, volume, latest logs, errors + +**Use instead of:** `GET /bot-orchestration/status` + +--- + +#### `get_bot_logs` - Detailed Bot Logs +Search and filter bot logs. + +```python +get_bot_logs( + bot_name="my_trading_bot", + log_type="error", # "error", "general", "all" + limit=50, + search_term="connection" # Optional filter +) +``` + +**Use instead of:** `GET /bot-orchestration/{bot_name}/status` (for logs) + +--- + +#### `manage_bot_execution` - Start/Stop Bots +Control bot and controller execution. + +```python +# Stop entire bot permanently +manage_bot_execution( + bot_name="my_trading_bot", + action="stop_bot" +) + +# Stop specific controllers +manage_bot_execution( + bot_name="my_trading_bot", + action="stop_controllers", + controller_names=["strategy_1", "strategy_2"] +) + +# Start/resume controllers +manage_bot_execution( + bot_name="my_trading_bot", + action="start_controllers", + controller_names=["strategy_1"] +) +``` + +**Use instead of:** +- `POST /bot-orchestration/stop-bot` +- `POST /bot-orchestration/stop-and-archive-bot/{bot_name}` + +--- + +## 📋 Direct API Endpoints (Use When MCP Tools Don't Exist) + +**Authentication:** All endpoints require HTTP Basic Auth. + +```bash +curl -u username:password http://localhost:8000/endpoint +``` + +--- + +### 🐳 Docker Management (`/docker`) + +``` +GET /docker/running +GET /docker/available-images/ +GET /docker/active-containers +GET /docker/exited-containers +POST /docker/pull-image/ +GET /docker/pull-status/ +POST /docker/clean-exited-containers +POST /docker/start-container/{container_name} +POST /docker/stop-container/{container_name} +POST /docker/remove-container/{container_name} +``` + +**Use Cases:** +- Check if Docker daemon is running +- Pull latest Hummingbot images +- Manage container lifecycle +- Clean up exited containers + +--- + +### 💳 Account Management (`/accounts`) + +**MCP tools exist** for most operations. Use direct API only for: + +``` +GET /accounts/ # List all accounts +POST /accounts/add-account # Create new account +POST /accounts/delete-account # Remove account +GET /accounts/{account_name}/credentials # List credentials +``` + +**Note:** Use `setup_connector` MCP tool for adding credentials instead of: +- `POST /accounts/add-credential/{account_name}/{connector_name}` +- `POST /accounts/delete-credential/{account_name}/{connector_name}` + +--- + +### 🔌 Connector Information (`/connectors`) + +**MCP tool exists:** Use `setup_connector()` for progressive flow. + +Direct API endpoints: +``` +GET /connectors/ # List all exchanges +GET /connectors/{connector_name}/config-map # Get required credentials +GET /connectors/{connector_name}/order-types # Supported order types +GET /connectors/{connector_name}/trading-rules # Min/max amounts, tick sizes +``` + +**Example:** +```bash +# Get Binance trading rules +curl -u admin:admin "http://localhost:8000/connectors/binance/trading-rules?trading_pairs=BTC-USDT,ETH-USDT" +``` + +--- + +### 📊 Portfolio Management (`/portfolio`) + +**MCP tool exists:** Use `get_portfolio_overview()` instead of these: + +``` +POST /portfolio/state # Current balances (use MCP tool!) +POST /portfolio/distribution # Token breakdown (use MCP tool!) +POST /portfolio/accounts-distribution # Account allocation (use MCP tool!) +POST /portfolio/history # Historical portfolio values +``` + +**When to use direct API:** +- Need cursor-based pagination for portfolio history +- Building custom portfolio analytics + +--- + +### 💹 Trading Operations (`/trading`) + +**MCP tools exist** for most operations: +- `place_order()` for placing orders +- `search_history()` for order/trade history +- `get_portfolio_overview()` for active orders and positions +- `set_account_position_mode_and_leverage()` for perpetual settings + +**Direct API only needed for:** + +``` +GET /trading/{account_name}/{connector_name}/position-mode + # Get current position mode (HEDGE/ONEWAY) +``` + +--- + +### 🤖 Bot Orchestration (`/bot-orchestration`) + +**MCP tools exist:** +- `deploy_bot_with_controllers()` - Deploy bots +- `get_active_bots_status()` - Monitor bots +- `get_bot_logs()` - View logs +- `manage_bot_execution()` - Start/stop + +**Direct API for advanced use:** + +``` +GET /bot-orchestration/bot-runs # Bot run history +GET /bot-orchestration/bot-runs/stats # Aggregate stats +GET /bot-orchestration/bot-runs/{bot_run_id} # Specific run details +POST /bot-orchestration/deploy-v2-script # Deploy V2 scripts +POST /bot-orchestration/start-bot # Start V1 bots +GET /bot-orchestration/mqtt # MQTT status +GET /bot-orchestration/{bot_name}/history # Bot performance history +``` + +--- + +### 📋 Strategy Management + +#### Controllers (`/controllers`) + +**MCP tools:** `explore_controllers()`, `modify_controllers()` + +**Direct API for:** +``` +GET /controllers/{controller_type}/{controller_name}/config/template + # Get JSON template for config +POST /controllers/{controller_type}/{controller_name}/config/validate + # Validate config before deploying +``` + +#### Scripts (`/scripts`) + +``` +GET /scripts/ # List available scripts +GET /scripts/{script_name} # Get script code +POST /scripts/{script_name} # Upload custom script +DELETE /scripts/{script_name} # Remove script +GET /scripts/{script_name}/config/template # Get config template +GET /scripts/configs/ # List script configs +POST /scripts/configs/{config_name} # Create config +DELETE /scripts/configs/{config_name} # Delete config +``` + +--- + +### 📊 Market Data (`/market-data`) + +**MCP tools exist:** +- `get_prices()` - Current prices +- `get_candles()` - OHLCV data +- `get_funding_rate()` - Funding rates +- `get_order_book()` - Order book analysis + +**Direct API for real-time feeds:** + +``` +POST /market-data/candles + # Start persistent candle feed (WebSocket-like) + Body: { + "connector_name": "binance", + "trading_pairs": ["BTC-USDT"], + "intervals": ["1m", "5m"], + "max_records": 1000 + } + +GET /market-data/active-feeds + # List active real-time feeds + +GET /market-data/settings + # Get market data configuration +``` + +--- + +### 🔄 Backtesting (`/backtesting`) + +**No MCP tool.** Use direct API: + +``` +POST /backtesting/run-backtesting + Body: { + "config": { + "controller_name": "directional_trading.macd_bb_v1", + "controller_type": "directional_trading", + "controller_config": [...], + "start_time": 1609459200, + "end_time": 1609545600, + "backtesting_resolution": "1m", + "trade_cost": 0.0006 + } + } +``` + +--- + +### 📈 Archived Bot Analytics (`/archived-bots`) + +**No MCP tool.** Use direct API for analyzing stopped bots: + +``` +GET /archived-bots/ # List archived databases +GET /archived-bots/{db_path}/status # Bot configuration +GET /archived-bots/{db_path}/summary # Performance summary +GET /archived-bots/{db_path}/performance # Detailed metrics +GET /archived-bots/{db_path}/orders # Historical orders +GET /archived-bots/{db_path}/trades # Trade history +GET /archived-bots/{db_path}/positions # Position history +GET /archived-bots/{db_path}/controllers # Controller configs +GET /archived-bots/{db_path}/executors # Executor data +``` + +--- + +### 🌐 Gateway Endpoints (DEX & Blockchain Operations) + +**MCP tools exist** for most Gateway operations. Use direct API only for specific needs. + +#### Gateway Lifecycle (`/gateway`) + +``` +GET /gateway/status # Get Gateway status +POST /gateway/start # Start Gateway container +POST /gateway/stop # Stop Gateway container +POST /gateway/restart # Restart Gateway container +GET /gateway/logs # Get Gateway logs +``` + +**Note:** Use `manage_gateway_container` MCP tool instead of these endpoints. + +--- + +#### Gateway Configuration (`/gateway`) + +``` +GET /gateway/chains # List supported blockchain chains +GET /gateway/connectors # List available DEX connectors +GET /gateway/connectors/{connector_name} + # Get specific connector configuration +POST /gateway/connectors/{connector_name} + # Update connector configuration + +GET /gateway/networks # List all networks +GET /gateway/networks/{network_id} + # Get specific network config (e.g., "solana-mainnet-beta") +POST /gateway/networks/{network_id} + # Update network configuration + +GET /gateway/networks/{network_id}/tokens + # List tokens available on network +POST /gateway/networks/{network_id}/tokens + # Add custom token to network + Body: { + "token_address": "token_contract_address", + "token_symbol": "SYMBOL", + "token_decimals": 18, + "token_name": "Token Name" + } +DELETE /gateway/networks/{network_id}/tokens/{token_address} + # Remove token from network + +GET /gateway/pools # List liquidity pools +POST /gateway/pools # Add custom pool +``` + +**Note:** Use `manage_gateway_config` MCP tool for easier configuration management. + +--- + +### 💱 Gateway Swaps (`/gateway/swap`) + +**MCP tool exists:** Use `manage_gateway_swaps()` for DEX trading. + +``` +POST /gateway/swap/quote + # Get swap quote with pricing and gas estimates + Body: { + "chain": "solana", + "network": "mainnet-beta", + "connector": "jupiter", + "base": "SOL", + "quote": "USDC", + "amount": "1.0", + "side": "BUY", + "allowedSlippage": "1.0" + } + +POST /gateway/swap/execute + # Execute the swap transaction + Body: { + "chain": "solana", + "network": "mainnet-beta", + "connector": "jupiter", + "address": "wallet_address", + "base": "SOL", + "quote": "USDC", + "amount": "1.0", + "side": "BUY", + "allowedSlippage": "1.0" + } + +GET /gateway/swaps/{transaction_hash}/status + # Check transaction status + +POST /gateway/swaps/search + # Search swap transaction history + Body: { + "chain": "solana", + "network": "mainnet-beta", + "connector": "jupiter", + "address": "wallet_address", + "status": "CONFIRMED", # SUBMITTED, CONFIRMED, FAILED + "start_time": 1609459200, + "end_time": 1609545600, + "limit": 50 + } + +GET /gateway/swaps/summary + # Get aggregated swap statistics +``` + +--- + +### 🏊 Gateway CLMM (`/gateway/clmm`) + +**MCP tools exist:** +- `explore_gateway_clmm_pools()` - Pool discovery +- `manage_gateway_clmm_positions()` - Position management + +``` +GET /gateway/clmm/pools + # List CLMM pools with filtering and sorting + Query params: connector, page, limit, search, sort_key, order_by + +GET /gateway/clmm/pool-info + # Get detailed info for specific pool + Query params: chain, network, connector, token0, token1, fee + +POST /gateway/clmm/open + # Open new concentrated liquidity position + Body: { + "chain": "solana", + "network": "mainnet-beta", + "connector": "meteora", + "address": "wallet_address", + "pool_address": "pool_address", + "lower_price": "150.0", + "upper_price": "250.0", + "base_token_amount": "1.0", + "quote_token_amount": "200.0", + "slippage": "1.0" + } + +POST /gateway/clmm/close + # Close CLMM position (remove all liquidity) + Body: { + "chain": "solana", + "network": "mainnet-beta", + "connector": "meteora", + "address": "wallet_address", + "position_address": "position_nft_address" + } + +POST /gateway/clmm/collect-fees + # Collect accumulated fees from position + Body: { + "chain": "solana", + "network": "mainnet-beta", + "connector": "meteora", + "address": "wallet_address", + "position_address": "position_nft_address" + } + +POST /gateway/clmm/positions_owned + # Get all positions owned by wallet in specific pool + Body: { + "chain": "solana", + "network": "mainnet-beta", + "connector": "meteora", + "address": "wallet_address", + "pool_address": "pool_address" + } + +GET /gateway/clmm/positions/{position_address}/events + # Get event history for specific position + +POST /gateway/clmm/positions/search + # Search CLMM positions with filters + Body: { + "chain": "solana", + "network": "mainnet-beta", + "connector": "meteora", + "address": "wallet_address", + "status": "OPEN", # OPEN, CLOSED + "start_time": 1609459200, + "end_time": 1609545600 + } +``` + +--- + +## 🆘 Common Error Handling + +### MCP Connection Lost + +**Error:** +``` +Error executing tool: ❌ Failed to connect to Hummingbot API +Connection failed after 3 attempts. +``` + +**Solution:** Reconnect immediately: +```python +configure_api_servers(action="add", name="local", host="localhost", port=8000, username="admin", password="admin") +configure_api_servers(action="set_default", name="local") +# Retry your operation +``` + +### Authentication Errors (401) + +Check credentials in `.env` file match what you're using. + +### Validation Errors (422) + +Read the error detail - usually missing required parameters or invalid values. + +### Resource Not Found (404) + +- Bot doesn't exist +- Connector name misspelled +- Database path incorrect + +--- + +## 💡 AI Assistant Tips + +1. **Always use MCP tools first** - They handle complexity for you +2. **Start with `configure_api_servers`** - Establishes connection +3. **Use `get_portfolio_overview`** - Single call for complete portfolio +4. **Progressive disclosure** - Tools like `setup_connector` guide you step-by-step +5. **Check MCP tool errors** - Reconnect immediately if connection fails +6. **Read error messages** - They usually tell you exactly what's wrong + +--- + +## 📚 Additional Resources + +- **Interactive API Docs**: http://localhost:8000/docs (Swagger UI) +- **Setup Guides**: See CLAUDE.md, AGENTS.md, GEMINI.md +- **Architecture**: See README.md +- **Troubleshooting**: See README.md Troubleshooting section diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..8011ce58 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,726 @@ +# Using Hummingbot API with Claude + +This guide shows you how to interact with the Hummingbot API using Claude (claude.ai) and Claude Code (CLI). + +## 🤖 Method 1: MCP Server (Recommended) + +The Hummingbot MCP server provides natural language access to all API functionality through Claude Desktop or Claude Code. + +### Claude Desktop Setup + +1. **Enable MCP during Hummingbot API setup**: + ```bash + ./setup.sh # Answer "y" to "Enable MCP server for AI assistant usage?" + ``` + +2. **Configure Claude Desktop**: + - Open (or create) `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) + - Or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) + + Add this configuration: + ```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"] + } + } + } + ``` + +3. **Restart Claude Desktop** + +4. **Start using natural language**: + - "What are my current portfolio balances?" + - "Show me active trading bots" + - "Create a new PMM strategy for ETH-USDT on Binance" + - "What's the performance of my bots this week?" + +### Claude Code (CLI) Setup + +1. **Add the MCP server**: + ```bash + 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 + ``` + +2. **Use in your terminal**: + ```bash + # Claude Code automatically uses the MCP server + # Just ask questions naturally in your terminal + ``` + +3. **Manage the connection**: + ```bash + claude mcp list # List configured servers + claude mcp get hummingbot # View server details + claude mcp remove hummingbot # Remove server + ``` + +## 🔧 Method 2: Direct API Access (Fallback) + +If MCP is unavailable, you can interact with the API directly. See @API_REFERENCE.md for the full endpoint list. + +## API Reference + +The API is accessible at `http://localhost:8000` with interactive Swagger docs at `http://localhost:8000/docs`. + +Refer to @API_REFERENCE.md for the full set of endpoints. + +### Authentication + +All endpoints require HTTP Basic Authentication. Use the username and password configured during setup. + +See @env for the current environment variables. + +Example: +```bash +curl -u username:password http://localhost:8000/endpoint +``` + +## Common Development Commands + +Refer to the Installation & Setup section in @README.md for more information. + +### Environment Setup +```bash +# First-time setup - creates Docker services and environment +chmod +x setup.sh +./setup.sh + +# Install development environment (requires Conda) +make install + +# Run in development mode with hot-reloading +./run.sh --dev + +# Run in production mode (Docker container) +./run.sh +``` + +### Code Quality & Testing +```bash +# Format code (automatically enforced by pre-commit hooks) +black --line-length 130 . +isort --line-length 130 --profile black . + +# Install pre-commit hooks +make install-pre-commit + +# Access API documentation +# Visit http://localhost:8000/docs after starting the API +``` + +### Docker Operations +```bash +# Build Docker image +make build + +# Deploy with Docker Compose +make deploy + +# Check running containers +docker ps + +# View container logs +docker logs hummingbot-api +``` + +## High-Level Architecture + +### Core Service Architecture +The API follows a microservice pattern where each trading bot runs in its own Docker container, communicating through MQTT with the main API service. + +**Key Components:** +1. **FastAPI Application** (`main.py`): Central API with lifespan management for background services +2. **Bot Orchestrator** (`services/bots_orchestrator.py`): Manages bot lifecycle - deployment, monitoring, and archival +3. **Docker Service** (`services/docker_service.py`): Wrapper around Docker SDK for container operations +4. **MQTT Manager** (`utils/mqtt_manager.py`): Handles real-time communication with bot instances +5. **Repository Pattern** (`database/`): Clean data access layer with async PostgreSQL operations + +### Request Flow Example +1. User sends authenticated request to API endpoint +2. Router validates request and calls appropriate service +3. Service orchestrates operations (e.g., starting a bot involves Docker service + MQTT setup) +4. Bot containers publish updates via MQTT +5. API aggregates real-time data from MQTT and database + +### Bot Instance Management +Each bot maintains isolated state in `/bots/instances/hummingbot-{name}/`: +- Configuration files in `conf/` +- SQLite database in `data/` +- Execution logs in `logs/` + +The API never directly modifies bot files - all communication happens through MQTT commands. + +### Authentication & Security +- HTTP Basic Auth for API access (configured in `.env`) +- Config password encrypts exchange credentials using Fernet +- Credentials stored encrypted in `/bots/credentials/` + +### Database Schema +PostgreSQL stores aggregated data from all bots: +- `orders`: All order history with exchange info +- `trades`: Executed trades with fees +- `account_balances`: Periodic balance snapshots +- `positions`: Perpetual contract positions +- `funding_payments`: Funding payment history + +### Real-time Data Flow +1. Bots publish state updates to MQTT topics +2. API subscribes to relevant topics +3. Services process updates and store in PostgreSQL +4. Clients can query aggregated data via REST endpoints + +## Key Development Patterns + +### Async-First Design +All database operations and external calls use async/await. When adding new features: +```python +async def your_function(): + async with get_db_session() as session: + # Database operations +``` + +### Service Layer Pattern +Business logic lives in `/services`, not in routers. Routers should only handle HTTP concerns. + +### Error Handling +The API uses FastAPI's exception handling. Services should raise clear exceptions that routers can catch. + +### Configuration Management +All configuration uses Pydantic Settings (`config.py`). Environment variables override defaults. + +## Important Considerations + +### Bot State Synchronization +- Account balances update every `ACCOUNT_UPDATE_INTERVAL` minutes +- Real-time updates come from MQTT, historical data from database +- Always check both sources for complete picture + +### Docker Container Lifecycle +- Starting a bot: Creates container, waits for MQTT connection +- Stopping a bot: Graceful shutdown, optional archival to S3/local +- Failed containers remain for debugging (clean with `/docker/clean-exited`) + +### Market Data Feeds +- Feeds auto-cleanup after inactivity +- Each feed runs in a background task +- Memory management crucial for long-running feeds + +### Performance Optimization +- Use pagination for large datasets +- Cursor-based pagination preferred over offset +- Background tasks for long operations (archival, bulk updates) + +## Troubleshooting + +### Common Errors + +#### Password Verification File Missing +**Error**: `[Errno 2] No such file or directory: 'bots/credentials/master_account/.password_verification'` + +**Cause**: This error occurs when trying to add credentials before running the initial setup. + +**Solution**: Run `./setup.sh` to initialize the environment. This script: +- Creates necessary directory structures +- Sets up Docker services (PostgreSQL, MQTT broker) +- Initializes the master_account with required configuration files +- Creates the `.password_verification` file needed for credential encryption + +**Prevention**: Always run `./setup.sh` before attempting to add exchange credentials or perform account operations. + +## Common Workflows + +### 1. Adding Exchange Credentials +1. List available connectors: `GET /connectors/` + - Returns all supported exchanges (binance, coinbase, kraken, etc.) +2. Get required configuration fields: `GET /connectors/{connector_name}/config-map` + - Returns which fields are needed (api_key, api_secret, etc.) + - Shows field types and whether they're required +3. Gather credential values from the user + - Ask the user to provide values for each required field + - Ensure all required fields from step 2 are collected +4. Add credentials: `POST /accounts/add-credential/{account_name}/{connector_name}` + - Provide the required fields from config-map + - Credentials are encrypted and stored securely + +Example workflow: +```bash +# 1. Check what connectors are available +# Why: First, I need to see which exchanges are supported by the API +GET /connectors/ + +# 2. Get config requirements for Binance +# Why: I need to know what credentials Binance requires so I can ask you for the right information +GET /connectors/binance/config-map +# Returns: {"binance_api_key": {"prompt": "Enter your Binance API key", "is_secure": true, "is_connect_key": true}, +# "binance_api_secret": {"prompt": "Enter your Binance API secret", "is_secure": true}} + +# 3. Gather credentials from user +# Why: I need to collect your API credentials to connect to your Binance account +# Ask user: "Please provide your Binance API key" +# Ask user: "Please provide your Binance API secret" + +# 4. Add credentials +# Why: Now I will securely store your credentials encrypted with your config password +POST /accounts/add-credential/my_account/binance +Body: { + "binance_api_key": "your_api_key_here", + "binance_api_secret": "your_api_secret_here" +} +``` + +#### XRPL Example: +```bash +# 1. Get XRPL config requirements +# Why: I need to check what configuration XRPL connector requires +GET /connectors/xrpl/config-map +# Returns: ["xrpl_secret_key", "wss_node_urls", "custom_markets", "max_request_per_minute"] + +# 2. Gather XRPL credentials from user +# Why: I need to collect your XRPL wallet credentials and optional configuration +# Ask user: "Please provide your XRPL secret key" +# Ask user: "Please provide WebSocket node URLs (optional, defaults to public nodes)" +# Ask user: "Please provide custom markets configuration (optional)" +# Ask user: "Please provide max requests per minute (optional)" + +# 3. Add XRPL credentials +# Why: Now I will securely store your XRPL credentials encrypted with your config password +POST /accounts/add-credential/my_account/xrpl +Body: { + "xrpl_secret_key": "your_xrpl_secret_key_here", + "wss_node_urls": ["wss://s1.ripple.com", "wss://s2.ripple.com"], // optional + "custom_markets": {}, // optional + "max_request_per_minute": 300 // optional +} +``` + +### 2. Analyzing Portfolio +1. Get current portfolio state: `POST /portfolio/state` + - Returns real-time balances across all accounts + - Can filter by specific accounts or connectors +2. Retrieve historical data: `POST /portfolio/history` + - Returns time-series portfolio values + - Supports cursor-based pagination for large datasets +3. Analyze token distribution: `POST /portfolio/distribution` + - Shows percentage allocation by token + - Aggregates across all exchanges +4. Review account distribution: `POST /portfolio/accounts-distribution` + - Shows percentage allocation by account + - Useful for risk management + +Example workflow: +```bash +# 1. Get current portfolio snapshot +# Why: I'm checking your current balances across selected accounts and exchanges +POST /portfolio/state +Body: { + "account_names": ["trading_account", "savings_account"], + "connectors": ["binance", "coinbase"] +} +# Returns: {"balances": [{"token": "BTC", "total": 0.5, "available": 0.4, "locked": 0.1, "usd_value": 25000}...]} + +# 2. Get historical portfolio performance +# Why: I'm retrieving your portfolio history to analyze performance over time +POST /portfolio/history +Body: { + "account_names": ["trading_account"], + "limit": 100, + "cursor": null +} +# Returns: {"data": [{"timestamp": 1234567890, "total_usd_value": 50000, "balances": {...}}...], "next_cursor": "..."} + +# 3. Analyze token distribution +# Why: I'm calculating how your portfolio is distributed across different tokens +POST /portfolio/distribution +Body: { + "account_names": ["trading_account", "savings_account"] +} +# Returns: {"BTC": {"amount": 0.5, "usd_value": 25000, "percentage": 50.0}, +# "ETH": {"amount": 10, "usd_value": 20000, "percentage": 40.0}...} + +# 4. Check account distribution +# Why: I'm analyzing how your total portfolio value is spread across your different accounts +POST /portfolio/accounts-distribution +Body: {} # No filter returns all accounts +# Returns: {"trading_account": {"usd_value": 40000, "percentage": 80.0}, +# "savings_account": {"usd_value": 10000, "percentage": 20.0}} +``` + +### 3. Fetching Market Data +1. Start real-time candle feed: `POST /market-data/candles` + - Creates persistent websocket connection + - Auto-cleanup after inactivity +2. Get current prices: `POST /market-data/prices` + - Returns spot prices for multiple pairs +3. Analyze order book: `POST /market-data/order-book` + - Returns bid/ask levels with depth +4. Calculate market metrics: Various order book analytics endpoints + - Price impact for volume + - VWAP calculations + - Volume at price levels + +Example workflow: +```bash +# 1. Start real-time candle feed +# Why: I'm establishing a real-time data feed to monitor price movements +POST /market-data/candles +Body: { + "connector_name": "binance", + "trading_pairs": ["BTC-USDT", "ETH-USDT"], + "intervals": ["1m", "5m"], + "max_records": 1000 +} +# Returns: {"feed_id": "candles_binance_123", "status": "running"} + +# 2. Get current prices +# Why: I need to check the current market prices before placing any orders +POST /market-data/prices +Body: { + "connector_name": "binance", + "trading_pairs": ["BTC-USDT", "ETH-USDT"] +} +# Returns: {"BTC-USDT": {"price": 50000.00, "timestamp": 1234567890}, +# "ETH-USDT": {"price": 3000.00, "timestamp": 1234567890}} + +# 3. Get order book snapshot +# Why: I'm analyzing market depth to understand liquidity and potential price impact +POST /market-data/order-book +Body: { + "connector_name": "binance", + "trading_pair": "BTC-USDT", + "depth": 20 +} +# Returns: {"timestamp": 1234567890, +# "bids": [[49999.00, 0.5], [49998.00, 1.0]...], +# "asks": [[50001.00, 0.3], [50002.00, 0.8]...]} + +# 4. Calculate VWAP for large order +# Why: I'm calculating the average price you would pay if you execute a large order +POST /market-data/order-book/vwap-for-volume +Body: { + "connector_name": "binance", + "trading_pair": "BTC-USDT", + "volume": 10, + "side": "buy" +} +# Returns: {"vwap": 50015.50, "avg_price": 50015.50} +``` + +### 4. Executing Trades +1. Check connector capabilities: `GET /connectors/{connector_name}/order-types` + - Returns supported order types (limit, market, stop-loss, etc.) +2. Get trading rules: `GET /connectors/{connector_name}/trading-rules` + - Returns min/max order amounts, tick sizes, minimum notional values +3. Verify current price: `POST /market-data/prices` + - Ensures order price is reasonable +4. Place order: `POST /trading/orders` + - Must respect trading rules constraints +5. Monitor order status: `POST /trading/orders/active` + - Track order execution progress +6. Cancel if needed: `POST /trading/{account_name}/{connector_name}/orders/{order_id}/cancel` + +Example workflow: +```bash +# 1. Check supported order types +# Why: I need to verify what order types Binance supports before placing orders +GET /connectors/binance/order-types +# Returns: ["limit", "limit_maker", "market", "stop_loss_limit"] + +# 2. Get trading rules for BTC-USDT +# Why: I'm checking minimum order sizes and price increments to ensure your order is valid +GET /connectors/binance/trading-rules?trading_pairs=BTC-USDT +# Returns: {"BTC-USDT": {"min_order_size": 0.00001, "max_order_size": 9000, +# "min_price_increment": 0.01, "min_base_amount_increment": 0.00001, +# "min_notional_size": 5.0}} + +# 3. Check current market price +# Why: I need to know the current price to place a competitive limit order +POST /market-data/prices +Body: {"connector_name": "binance", "trading_pairs": ["BTC-USDT"]} +# Returns: {"BTC-USDT": {"price": 50000.00, "timestamp": 1234567890}} + +# 4. Place limit order +# Why: I'm placing your buy order slightly below market price to get a better fill +POST /trading/orders +Body: { + "account_name": "trading_account", + "connector_name": "binance", + "trading_pair": "BTC-USDT", + "order_type": "limit", + "trade_type": "buy", + "price": 49900.00, # Below market for limit buy + "amount": 0.001 # Total value: 49.90 USD (above min_notional_size) +} +# Returns: {"client_order_id": "HMBot-123456", "exchange_order_id": "BIN-789", "status": "open"} + +# 5. Monitor active orders +# Why: I'm checking the status of your order to see if it has been filled +POST /trading/orders/active +Body: { + "account_names": ["trading_account"], + "connectors": ["binance"] +} +# Returns: {"data": [{"client_order_id": "HMBot-123456", "status": "open", "filled_amount": 0}...]} + +# 6. Cancel order if needed +# Why: If the order hasn't filled and you want to cancel it, I can do that now +POST /trading/trading_account/binance/orders/HMBot-123456/cancel +# Returns: {"success": true, "exchange_order_id": "BIN-789"} +``` + +### 5. Orchestrating Bots +1. Create account and add credentials: See workflow 1 +2. Choose strategy type: + - V1 Scripts: Traditional Hummingbot scripts + - V2 Scripts: Next-gen scripts with enhanced features + - V2 Controllers: Advanced multi-strategy controllers +3. Get strategy configuration template: `GET /scripts/{script_name}/config-template` +4. Deploy bot with configuration: `POST /bot-orchestration/start-bot` or `POST /bot-orchestration/deploy-v2-script` +5. Monitor bot status: `GET /bot-orchestration/{bot_name}/status` +6. Review performance: `GET /bot-orchestration/{bot_name}/history` +7. Stop and archive when done: `POST /bot-orchestration/stop-and-archive-bot/{bot_name}` + +Example workflow: +```bash +# 1. List available V2 scripts +# Why: I need to see what automated trading strategies are available +GET /scripts/ +# Returns: ["v2_directional_rsi", "v2_bollinger_dca", "v2_macd_bb_v1"...] + +# 2. Get configuration template +# Why: I'm checking what parameters the RSI strategy needs so I can configure it properly +GET /scripts/v2_directional_rsi/config-template +# Returns: {"script_name": "v2_directional_rsi", "config": {"connector": "", "trading_pair": "", "rsi_period": 14...}} + +# 3. Deploy V2 script bot +# Why: I'm launching your automated RSI trading bot with your specified configuration +POST /bot-orchestration/deploy-v2-script +Body: { + "bot_name": "rsi_bot_btc", + "script": "v2_directional_rsi", + "config": { + "connector": "binance", + "trading_pair": "BTC-USDT", + "rsi_period": 14, + "rsi_oversold": 30, + "rsi_overbought": 70, + "order_amount": 0.001 + } +} +# Returns: {"bot_name": "rsi_bot_btc", "status": "starting", "container_name": "hummingbot-rsi_bot_btc"} + +# 4. Check bot status +# Why: I'm verifying that your bot is running properly and connected to the exchange +GET /bot-orchestration/rsi_bot_btc/status +# Returns: {"bot_name": "rsi_bot_btc", "status": "running", "mqtt_connected": true, +# "last_update": 1234567890, "active_orders": 1} + +# 5. Get bot performance history +# Why: I'm retrieving your bot's trading performance to analyze its effectiveness +GET /bot-orchestration/rsi_bot_btc/history?start_time=1234567800&end_time=1234567890 +# Returns: {"orders": [...], "trades": [...], "performance": {"total_pnl": 150.50, "win_rate": 0.65}} + +# 6. Stop and archive bot +# Why: I'm stopping your bot and archiving its data for future analysis +POST /bot-orchestration/stop-and-archive-bot/rsi_bot_btc +# Returns: {"status": "stopped", "archive_path": "/bots/archived/rsi_bot_btc_20240704.tar.gz"} +``` + +### 6. Managing Gateway Container (For DEX Trading) +Gateway is required for decentralized exchange (DEX) trading. Use the `manage_gateway_container` MCP tool to control Gateway lifecycle. + +1. Configure API connection (one-time setup) +2. Start Gateway with configuration +3. Verify Gateway status +4. Manage Gateway lifecycle (restart/stop as needed) + +Example workflow using MCP: +```python +# 1. Configure API connection (first time only) +# Why: I need to authenticate with the Hummingbot API to manage Gateway +send_request({ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "configure_api_servers", + "arguments": { + "api_url": "http://host.docker.internal:8000", + "username": "admin", + "password": "admin" + } + } +}) +# Returns: {"result": {"content": [{"type": "text", "text": "API configuration saved successfully"}]}} + +# 2. Start Gateway container +# Why: I'm launching the Gateway service for DEX trading with your specified passphrase +send_request({ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "start", + "config": { + "passphrase": "admin", + "dev_mode": true, + "image": "hummingbot/gateway:latest", + "port": 15888 + } + } + } +}) +# Returns: Gateway container started successfully at http://localhost:15888 + +# 3. Check Gateway status +# Why: I'm verifying that Gateway is running and accessible +send_request({ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "get_status" + } + } +}) +# Returns: {"status": "running", "container_id": "abc123...", "port": 15888, "dev_mode": true} + +# 4. Restart Gateway (if needed) +# Why: If Gateway becomes unresponsive, I can restart it to restore functionality +send_request({ + "jsonrpc": "2.0", + "id": 4, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "restart" + } + } +}) +# Returns: Gateway container restarted successfully + +# 5. Stop Gateway (when done with DEX trading) +# Why: I'm shutting down Gateway to free up resources when you're not using DEX features +send_request({ + "jsonrpc": "2.0", + "id": 5, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "stop" + } + } +}) +# Returns: Gateway container stopped successfully +``` + +#### Natural Language Examples (Claude Code) +If you're using Claude Code CLI, you can use natural language: +- "Start Gateway in development mode with passphrase 'admin'" +- "Check if Gateway is running" +- "Restart the Gateway container" +- "Stop Gateway" + +#### Important Notes +- **Development mode** (`dev_mode: true`): HTTP access on port 15888, Swagger UI available +- **Production mode** (`dev_mode: false`): HTTPS with certificates required, more secure +- **Passphrase**: Used to encrypt/decrypt DEX wallet keys, store it securely +- **Port**: Default is 15888, must be available on your system +- Gateway URL will be: `http://localhost:15888` (dev) or `https://localhost:15888` (prod) + +## MCP Tools Best Practices + +### Using `configure_api_servers` for Connection Management + +**Before using any MCP tools**, always ensure the API server is properly configured: + +```python +# Check if connection is working - if any MCP tool fails, reconnect: +configure_api_servers(action="add", name="local", host="localhost", port=8000, username="admin", password="admin") +configure_api_servers(action="set_default", name="local") +``` + +### Using `get_portfolio_overview` for Token Balances + +**Preferred method for checking balances**: +- Use `get_portfolio_overview()` instead of direct API calls +- Includes CEX balances, DEX balances, LP positions, and active orders in one call +- Automatically handles all account types (Hyperliquid, Solana, Ethereum, etc.) + +```python +# Get complete portfolio overview +get_portfolio_overview( + include_balances=True, + include_perp_positions=False, + include_lp_positions=True, + include_active_orders=True, + as_distribution=False +) +``` + +### Common MCP Connection Issue + +**Error**: +``` +Error executing tool get_portfolio_overview: ❌ Failed to connect to Hummingbot API at http://docker.host.internal:8000 + +Connection failed after 3 attempts. + +💡 Solutions: + 1. Check if the API is running and accessible + 2. Verify your credentials are correct + 3. Use 'configure_api_servers' tool for setup + +Original error: Cannot connect to host docker.host.internal:8000 ssl:default [Name or service not known] +``` + +**Root Cause**: The MCP tool loses connection to the API server. This happens when: +- MCP server reconnects/restarts +- API credentials are not cached +- Network configuration changes + +**Solution**: Reconfigure the API server connection before retrying: + +```python +# Step 1: Add server configuration +configure_api_servers( + action="add", + name="local", + host="localhost", + port=8000, + username="admin", + password="admin" +) + +# Step 2: Set as default +configure_api_servers(action="set_default", name="local") + +# Step 3: Retry the operation +get_portfolio_overview(include_balances=True) +``` + +**Prevention**: Always check connection before using other MCP tools. If you see any connection error, immediately run `configure_api_servers` to restore the connection. + +## Error Codes + +- `400`: Bad Request - Invalid parameters +- `401`: Unauthorized - Authentication required +- `404`: Not Found - Resource doesn't exist +- `422`: Unprocessable Entity - Validation error +- `500`: Internal Server Error - Server issue + +## Rate Limiting + +No built-in rate limiting. Consider implementing client-side throttling for production use. + +## WebSocket Support + +Not available. Use polling for real-time updates or integrate with MQTT broker directly for bot events. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..24acfa60 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,348 @@ +# Using Hummingbot API with Gemini + +This guide shows you how to interact with the Hummingbot API using Google Gemini. + +## 🤖 Method 1: MCP Server (Recommended) + +The Hummingbot MCP server provides natural language access to all API functionality through Gemini. + +### Setup via Gemini CLI + +1. **Enable MCP during Hummingbot API setup**: + ```bash + ./setup.sh # Answer "y" to "Enable MCP server for AI assistant usage?" + ``` + +2. **Add the MCP server using Gemini CLI**: + ```bash + gemini mcp add 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" \ + --protocol stdio + ``` + +3. **Verify the server was added**: + ```bash + gemini mcp list + ``` + +4. **Start using natural language**: + - "What are my current portfolio balances?" + - "Show me active trading bots" + - "Create a new market making strategy for SOL-USDT" + - "What's the performance of my bots today?" + +### Manual Configuration (Alternative) + +#### For Gemini CLI (Global Configuration) + +Create or edit `~/.gemini/settings.json`: + +```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"], + "protocol": "stdio" + } + } +} +``` + +#### For Project-Specific Configuration + +Create `.gemini/settings.json` in your project root: + +```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"], + "protocol": "stdio" + } + } +} +``` + +#### For IDE Integration + +Create `mcp.json` in your IDE's configuration directory: + +```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"], + "protocol": "stdio" + } + } +} +``` + +### Managing the Connection + +```bash +# List all configured MCP servers +gemini mcp list + +# View details of the Hummingbot server +gemini mcp get hummingbot + +# Remove the server +gemini mcp remove hummingbot +``` + +## 🔧 Method 2: Direct API Access (Fallback) + +If MCP is unavailable, you can interact with the API directly using HTTP requests. + +### API Endpoints + +The API is accessible at `http://localhost:8000` with interactive Swagger docs at `http://localhost:8000/docs`. + +See @API_REFERENCE.md for the complete endpoint reference. + +### Authentication + +All endpoints require HTTP Basic Authentication: + +```bash +curl -u username:password http://localhost:8000/endpoint +``` + +### Example API Calls + +**Get Portfolio State**: +```bash +curl -u admin:admin -X POST http://localhost:8000/portfolio/state \ + -H "Content-Type: application/json" \ + -d '{"account_names": ["master_account"]}' +``` + +**List Active Bots**: +```bash +curl -u admin:admin http://localhost:8000/bot-orchestration/status +``` + +**Get Market Prices**: +```bash +curl -u admin:admin -X POST http://localhost:8000/market-data/prices \ + -H "Content-Type: application/json" \ + -d '{ + "connector_name": "binance", + "trading_pairs": ["BTC-USDT", "ETH-USDT"] + }' +``` + +## 🌐 Common Workflows + +### Managing Gateway Container (For DEX Trading) + +Gateway is required for decentralized exchange (DEX) trading. Use the `manage_gateway_container` MCP tool through natural language commands. + +#### Using Natural Language (Recommended) + +Once you've configured Gemini with the Hummingbot MCP server, you can manage Gateway using simple commands: + +- **"Start Gateway in development mode with passphrase 'admin'"** + - Launches Gateway container for DEX trading + - Development mode enables HTTP access and Swagger UI + +- **"Check Gateway status"** + - Verifies if Gateway is running + - Shows container details, port, and mode + +- **"Restart the Gateway container"** + - Restarts Gateway if it becomes unresponsive + - Useful for applying configuration changes + +- **"Stop Gateway"** + - Shuts down Gateway when not needed + - Frees up system resources + +#### Using MCP Tool Directly + +If you're building custom integrations, you can call the `manage_gateway_container` tool directly: + +```python +# 1. Configure API connection (first time only) +send_request({ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "configure_api_servers", + "arguments": { + "api_url": "http://host.docker.internal:8000", + "username": "admin", + "password": "admin" + } + } +}) + +# 2. Start Gateway container +send_request({ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "start", + "config": { + "passphrase": "admin", + "dev_mode": true, + "image": "hummingbot/gateway:latest", + "port": 15888 + } + } + } +}) + +# 3. Check Gateway status +send_request({ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "get_status" + } + } +}) + +# 4. Restart Gateway (if needed) +send_request({ + "jsonrpc": "2.0", + "id": 4, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "restart" + } + } +}) + +# 5. Stop Gateway +send_request({ + "jsonrpc": "2.0", + "id": 5, + "method": "tools/call", + "params": { + "name": "manage_gateway_container", + "arguments": { + "action": "stop" + } + } +}) +``` + +#### Important Notes +- **Development mode** (`dev_mode: true`): HTTP access on port 15888, Swagger UI available at `http://localhost:15888/docs` +- **Production mode** (`dev_mode: false`): HTTPS with certificates required, more secure for production use +- **Passphrase**: Used to encrypt/decrypt DEX wallet keys - store it securely +- **Port**: Default is 15888, ensure it's available on your system + +## 📚 Additional Resources + +- **API Reference**: See @API_REFERENCE.md for all available endpoints +- **README**: See @README.md for complete setup instructions +- **Swagger UI**: http://localhost:8000/docs (interactive API documentation) + +## 🆘 Troubleshooting + +**MCP server not responding**: +```bash +# Check if MCP container is running +docker ps | grep hummingbot-mcp + +# If not, re-enable during setup +./setup.sh # Answer "y" to MCP prompt +``` + +**Configuration not loading**: +- Verify the JSON syntax in your configuration file +- Ensure Docker is running +- Check that the hummingbot-mcp container exists + +**Authentication errors**: +- Verify username and password in `.env` file +- Ensure the API is running: `docker ps | grep hummingbot-api` + +## MCP Tools Best Practices + +### Using `configure_api_servers` for Connection Management + +**Before using any MCP tools**, always ensure the API server is properly configured: + +```python +# Check if connection is working - if any MCP tool fails, reconnect: +configure_api_servers(action="add", name="local", host="localhost", port=8000, username="admin", password="admin") +configure_api_servers(action="set_default", name="local") +``` + +### Using `get_portfolio_overview` for Token Balances + +**Preferred method for checking balances**: +- Use `get_portfolio_overview()` instead of direct API calls +- Includes CEX balances, DEX balances, LP positions, and active orders in one call +- Automatically handles all account types (Hyperliquid, Solana, Ethereum, etc.) + +```python +# Get complete portfolio overview +get_portfolio_overview( + include_balances=True, + include_perp_positions=False, + include_lp_positions=True, + include_active_orders=True, + as_distribution=False +) +``` + +### Common MCP Connection Issue + +**Error**: +``` +Error executing tool get_portfolio_overview: ❌ Failed to connect to Hummingbot API at http://docker.host.internal:8000 + +Connection failed after 3 attempts. + +💡 Solutions: + 1. Check if the API is running and accessible + 2. Verify your credentials are correct + 3. Use 'configure_api_servers' tool for setup + +Original error: Cannot connect to host docker.host.internal:8000 ssl:default [Name or service not known] +``` + +**Root Cause**: The MCP tool loses connection to the API server. This happens when: +- MCP server reconnects/restarts +- API credentials are not cached +- Network configuration changes + +**Solution**: Reconfigure the API server connection before retrying: + +```python +# Step 1: Add server configuration +configure_api_servers( + action="add", + name="local", + host="localhost", + port=8000, + username="admin", + password="admin" +) + +# Step 2: Set as default +configure_api_servers(action="set_default", name="local") + +# Step 3: Retry the operation +get_portfolio_overview(include_balances=True) +``` + +**Prevention**: Always check connection before using other MCP tools. If you see any connection error, immediately run `configure_api_servers` to restore the connection. diff --git a/README.md b/README.md index b1072c92..7bd41373 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,94 @@ # Hummingbot API +**The central hub for running Hummingbot trading bots - now with AI assistant integration via MCP (Model Context Protocol).** + 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. +## 🚀 Quick Start + +Run the setup script to deploy the Hummingbot API platform: + +```bash +git clone https://github.com/hummingbot/hummingbot-api.git +cd hummingbot-api +chmod +x setup.sh +./setup.sh +``` + +### Setup Process + +The script will prompt you for: + +1. **Credentials** (required): + - Config password (for encrypting bot credentials) + - API username and password + +2. **Optional Services**: + - **Dashboard**: For web-based visual interface + +3. **Gateway**: Optional passphrase for DEX trading + +### What Gets Installed + +**Core services** (always installed): +- ✅ **Hummingbot API** (port 8000) - REST API backend +- ✅ **PostgreSQL** - Database for trading data +- ✅ **EMQX** - Message broker for real-time communication +- ✅ **Swagger UI** (port 8000/docs) - API documentation + +**Optional service** (enable during setup): +- 📊 **Dashboard** (port 8501) - Web interface + +**Note**: MCP (AI assistant integration) is configured separately - see below + +### After Setup + +**1. Access Swagger UI (Default)** + +The API documentation is immediately available: +- URL: http://localhost:8000/docs +- Use the username/password you configured +- Test all API endpoints directly + +**2. Connect AI Assistant (Optional)** + +To connect an AI assistant via MCP: + +**Claude Desktop:** +1. Install from [https://claude.ai/download](https://claude.ai/download) +2. Add to your config file: + - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` + - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + + ```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"] + } + } + } + ``` +3. Restart Claude Desktop +4. **First-time setup - Add exchange credentials:** + - "Set up my Solana wallet" → Uses `setup_connector` tool for progressive credential setup + - Or for CEX: "Set up my Binance account" → Guides you through API key setup +5. **Try trading operations:** + - "What's the current price for swapping SOL to USDC?" + - "Execute a swap: sell 0.01 SOL for USDC with 1% slippage" + +**3. Access Dashboard (If Enabled)** + +If you enabled Dashboard during setup: +- URL: http://localhost:8501 +- Use the same username/password from setup + ## What is Hummingbot API? The Hummingbot API is designed to be your central hub for trading operations, offering: +- **🤖 AI Assistant Integration**: Control your trading with natural language via MCP (Claude, ChatGPT, Gemini) - **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 @@ -13,11 +96,264 @@ The Hummingbot API is designed to be your central hub for trading operations, of - **Strategy Management**: Add, configure, and manage trading strategies in real-time - **Complete Flexibility**: Build any trading product on top of this robust API framework +## 🎯 Ways to Interact with Hummingbot API + +Choose the method that best fits your workflow: + +### 1. 🔧 Swagger UI - API Documentation (Default) +**Interactive REST API documentation and testing** + +- **Best for**: Developers and power users who want full control +- **Advantages**: + - Complete API access - all endpoints available + - Direct endpoint testing + - Integration development + - No additional setup required +- **Setup**: Automatically available after running setup +- **Access**: http://localhost:8000/docs + +### 2. 🤖 MCP - AI Assistant (Optional) +**Natural language trading commands through Claude, ChatGPT, or Gemini** + +- **Best for**: Users who prefer conversational interaction +- **Advantages**: + - Natural language commands + - Full access to all API features + - Contextual help and explanations + - Complex multi-step operations made simple + - Progressive credential setup with `setup_connector` tool +- **Setup**: Answer "y" when prompted during setup, then connect your AI assistant +- **Examples**: + - First-time: "Set up my Solana wallet" → Guides through credential setup + - Trading: "What's the price to swap 0.01 SOL for USDC? Execute the trade" + +### 3. 📊 Dashboard - Web Interface (Optional) +**Visual interface for common operations** + +- **Best for**: Users who prefer graphical interfaces +- **Advantages**: + - Intuitive visual workflows + - Real-time charts and graphs + - Quick access to common tasks +- **Limitations**: Not all API functions available (focused on core features) +- **Setup**: Answer "y" when prompted during setup +- **Access**: http://localhost:8501 + 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. +## 🔌 Setting Up MCP with Claude Code + +If you're using Claude Code (the CLI tool), you can connect to the Hummingbot MCP server directly from your development environment. + +### Quick Setup + +1. **Enable MCP during setup** (if not already done): + ```bash + ./setup.sh # Answer "y" to "Enable MCP server for AI assistant usage?" + ``` + +2. **Add the MCP server to Claude Code**: + ```bash + 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 + ``` + + This configures Claude Code to communicate with the Hummingbot MCP server. + +3. **Start using Hummingbot in Claude Code**: + - Open your terminal with Claude Code + - Use natural language commands to interact with your trading operations: + ``` + "What are my current portfolio balances?" + "Show me active trading bots" + "Create a new market making strategy for ETH-USDT" + ``` + +### Configuration File + +The command above automatically creates/updates `.mcp.json` in your project root: + +```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"] + } + } +} +``` + +### Managing the Connection + +**List configured MCP servers:** +```bash +claude mcp list +``` + +**View server details:** +```bash +claude mcp get hummingbot +``` + +**Remove the server:** +```bash +claude mcp remove hummingbot +``` + +### Prerequisites + +- Claude Code CLI installed (see [Claude Code documentation](https://docs.claude.com/en/docs/claude-code)) +- MCP service enabled during Hummingbot API setup +- Docker running with `hummingbot-mcp` container active + +### Verify Setup + +Check that the MCP container is running: +```bash +docker ps | grep hummingbot-mcp +``` + +If the container isn't running, re-run setup with MCP enabled: +```bash +./setup.sh # Answer "y" to MCP prompt +``` + +## 🌐 Gateway Setup (For DEX Trading) + +Gateway is required for decentralized exchange (DEX) trading. The Hummingbot API can manage Gateway containers for you - no separate installation needed! + +### Option 1: Using Swagger UI (API) + +1. **Access Swagger UI**: http://localhost:8000/docs +2. **Navigate to Gateway endpoints**: Look for `/manage-gateway` or similar endpoints +3. **Start Gateway**: + ```json + POST /manage-gateway + { + "action": "start", + "passphrase": "your-secure-passphrase", + "dev_mode": true + } + ``` + +The API automatically handles OS-specific networking: +- **macOS/Windows**: Uses `host.docker.internal` to connect to the API +- **Linux**: Uses appropriate network configuration + +### Option 2: Using MCP AI Assistant + +If you enabled MCP during setup, you can manage Gateway with natural language: + +**Example commands:** +- "Start Gateway in development mode with passphrase 'admin'" +- "Check Gateway status" +- "Stop the Gateway container" +- "Restart Gateway with a new passphrase" + +The `manage_gateway_container` MCP tool will: +- Pull the Gateway Docker image if needed +- Start the container with proper configuration +- Configure networking based on your OS +- Report Gateway status and connection info + +### Verify Gateway is Running + +**Check container status:** +```bash +docker ps | grep gateway +``` + +**View Gateway logs:** +```bash +docker logs gateway -f +``` + +**Test Gateway API** (dev mode only): +```bash +curl http://localhost:15888/ +``` + +### Gateway Access + +Once running, Gateway will be available at: +- **Development mode**: `http://localhost:15888` +- **Production mode**: `https://localhost:15888` (requires certificates) +- **API Documentation**: `http://localhost:15888/docs` (dev mode only) + +### Troubleshooting + +**Gateway won't start:** +- Ensure Docker is running +- Check if port 15888 is available +- Review logs: `docker logs gateway` + +**Multiple Gateway containers running:** +If you have multiple Gateway containers (e.g., from previous setups), you may experience connection issues or unexpected behavior. + +```bash +# Check for multiple Gateway containers +docker ps -a | grep gateway + +# If you see multiple containers, stop and remove old ones +docker stop gateway-old-name +docker rm gateway-old-name + +# Keep only the one you want to use +# The Hummingbot API expects the container to be named 'gateway' +docker rename your-container-name gateway +``` + +**Connection issues:** +- Verify Gateway URL in your `.env` file and `docker-compose.yml` +- The API uses `GATEWAY_URL=http://host.docker.internal:15888` (configured in docker-compose.yml) +- Ensure Gateway container is on the same Docker network: `docker network inspect hummingbot-api_emqx-bridge` +- macOS/Windows users: `host.docker.internal` should work automatically +- Linux users: Check that `extra_hosts` is properly configured in docker-compose.yml + +## 🐳 Docker Compose Architecture + +The Hummingbot API uses Docker Compose to orchestrate multiple services into a complete trading platform: + +### Services Overview + +```yaml +services: + # dashboard: # Optional - Web UI (enable during setup or uncomment manually) + hummingbot-api: # Core FastAPI backend (port 8000) - Always installed + emqx: # MQTT message broker (port 1883) - Always installed + postgres: # PostgreSQL database (port 5432) - Always installed +``` + +### Network Configuration + +All services communicate via the `emqx-bridge` Docker network: +- **Internal communication**: Services reference each other by container name (e.g., `hummingbot-api:8000`) +- **External access**: Exposed ports allow access from your host machine + +### Environment Variables + +The setup script creates a `.env` file with all necessary configuration: + +```bash +# Security +USERNAME=admin # API authentication username +PASSWORD=admin # API authentication password +CONFIG_PASSWORD=admin # Bot credentials encryption key + +# Services (auto-configured) +BROKER_HOST=emqx +DATABASE_URL=postgresql+asyncpg://hbot:hummingbot-api@postgres:5432/hummingbot_api +``` + +### Persistent Storage + +Docker volumes ensure data persistence: +- `postgres-data`: Trading data and bot performance +- `emqx-data`, `emqx-log`, `emqx-etc`: Message broker state + ## System Dependencies -The Hummingbot API requires two essential services to function properly: +The platform includes these essential services: ### 1. PostgreSQL Database Stores all trading data including: @@ -26,7 +362,7 @@ Stores all trading data including: - Positions and funding payments - Performance metrics -**Note:** The database is automatically initialized using environment variables (`POSTGRES_USER`, `POSTGRES_DB`, `POSTGRES_PASSWORD`). The included `init-db.sql` script serves as a safety net for edge cases where automatic initialization doesn't complete properly. +**Note:** The database is automatically initialized using environment variables. The included `init-db.sql` serves as a safety net. ### 2. EMQX Message Broker Enables real-time communication with trading bots: @@ -99,12 +435,85 @@ This runs the API in a Docker container - simple and isolated. ``` This starts the API from source with hot-reloading enabled. -## Getting Started +## 🤖 MCP AI Assistant Integration + +### Claude Desktop (Recommended) + +1. **Install Claude Desktop** + - Download from [https://claude.ai/download](https://claude.ai/download) + +2. **Configure the MCP Server** + - Open (or create) your Claude Desktop config file: + - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` + - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + +3. **Add the Hummingbot MCP configuration:** + ```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"] + } + } + } + ``` + +4. **Restart Claude Desktop** + +5. **Start using Hummingbot with natural language:** + - **First-time setup**: "Set up my Solana wallet" → Progressive credential setup with `setup_connector` + - **Trading**: "What's the current price to swap 0.01 SOL for USDC? Execute the trade" + - **Portfolio**: "What are my current portfolio balances across all exchanges?" + - **Gateway**: "Start Gateway in development mode with passphrase 'admin'" + - **Strategies**: "Create a PMM strategy for ETH-USDT on Binance" + +### ChatGPT / OpenAI + +1. **Install the OpenAI CLI** (if available in your region) + - Follow OpenAI's official MCP setup guide + +2. **Configure the MCP server** similar to Claude Desktop: + ```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"] + } + } + } + ``` + +### Google Gemini + +1. **Install Gemini CLI** (if available) + - Refer to Google's MCP integration documentation + +2. **Add Hummingbot MCP server** to your Gemini configuration -Once the API is running, you can access it at `http://localhost:8000` +### Available MCP Capabilities -### First Steps -1. **Visit the API Documentation**: Go to `http://localhost:8000/docs` to explore the interactive Swagger documentation +Once connected, your AI assistant can: +- 📊 **Portfolio Management**: View balances, positions, and P&L across exchanges +- 📈 **Market Data**: Get real-time prices, orderbook depth, and funding rates +- 🤖 **Bot Control**: Create, start, stop, and monitor trading bots +- 📋 **Order Management**: Place, cancel, and track orders +- 🔍 **Performance Analytics**: Analyze trading performance and statistics +- ⚙️ **Strategy Configuration**: Create and modify trading strategies +- 🌐 **Gateway Management**: Start, stop, and configure the Gateway container for DEX trading + +## Getting Started (Alternative Methods) + +Once the API is running, you can also access it directly: + +### Option 1: Web Dashboard +1. **Access the Dashboard**: Go to `http://localhost:8501` +2. **Login**: Use the username and password you configured during setup +3. **Explore**: Navigate through the visual interface + +### Option 2: Swagger UI (API Documentation) +1. **Visit the API Documentation**: Go to `http://localhost:8000/docs` 2. **Authenticate**: Use the username and password you configured during setup 3. **Test endpoints**: Use the Swagger interface to test API functionality @@ -280,6 +689,34 @@ This script will: 3. Automatically fix any missing configuration 4. Test the connection to ensure everything works +#### "role 'postgres' does not exist" Error + +If you see errors like `FATAL: role "postgres" does not exist` in the PostgreSQL logs: + +**Cause**: The PostgreSQL container is configured to create only the `hbot` user (via `POSTGRES_USER=hbot`). The default `postgres` superuser is NOT created. This error occurs when something tries to connect using the default `postgres` username. + +**Solutions**: + +1. **Always specify the correct user** when connecting: + ```bash + # Correct - use hbot user + docker exec -it hummingbot-postgres psql -U hbot -d hummingbot_api + + # Incorrect - tries to use 'postgres' user (doesn't exist) + docker exec -it hummingbot-postgres psql + ``` + +2. **If you need the postgres superuser** (not recommended), you can create it: + ```bash + docker exec -it hummingbot-postgres psql -U hbot -d postgres -c "CREATE ROLE postgres WITH SUPERUSER LOGIN PASSWORD 'your-password';" + ``` + +3. **Complete database reset** (⚠️ deletes all data): + ```bash + docker compose down -v + ./setup.sh + ``` + #### Manual Database Verification If you prefer to check manually: @@ -291,13 +728,50 @@ docker ps | grep -E "hummingbot-postgres|hummingbot-broker" # Check PostgreSQL logs docker logs hummingbot-postgres -# Verify database connection +# Verify database connection (use hbot user, not postgres) docker exec -it hummingbot-postgres psql -U hbot -d hummingbot_api -# If connection fails, run the initialization script -docker exec -i hummingbot-postgres psql -U postgres < init-db.sql +# List all database users +docker exec -it hummingbot-postgres psql -U hbot -d postgres -c "\du" ``` +#### "database 'hbot' does not exist" During Setup + +If you see this error during `./setup.sh`: + +``` +⚠️ Database initialization may be incomplete. Running manual initialization... +psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: database "hbot" does not exist +❌ Failed to initialize database. +``` + +**Cause**: The setup script tried to connect to a database named `hbot` (the username) instead of `hummingbot_api` (the actual database name). This was a bug in older versions of setup.sh. + +**Solution**: + +1. **Update setup.sh**: Pull the latest version with the fix: + ```bash + git pull origin main + ``` + +2. **Or manually fix the database**: + ```bash + # The database already exists, just verify it + docker exec hummingbot-postgres psql -U hbot -d postgres -c "\l" + + # You should see 'hummingbot_api' in the list + # Test connection + docker exec hummingbot-postgres psql -U hbot -d hummingbot_api -c "SELECT version();" + ``` + +3. **If database doesn't exist**, run the fix script: + ```bash + chmod +x fix-database.sh + ./fix-database.sh + ``` + +**Prevention**: This issue is fixed in the latest version of setup.sh. The script now correctly specifies `-d postgres` when running manual initialization. + #### Complete Database Reset If you need to start fresh (⚠️ this will delete all data): diff --git a/dashboard-credentials.yml b/dashboard-credentials.yml new file mode 100644 index 00000000..92ad99b5 --- /dev/null +++ b/dashboard-credentials.yml @@ -0,0 +1,15 @@ +# This only works if you change the env variable in the docker-compose.yml +credentials: + usernames: + admin: + email: admin@gmail.com + name: John Doe + logged_in: False + password: abc +cookie: + expiry_days: 0 + key: some_signature_key # Must be string + name: some_cookie_name +pre-authorized: + emails: + - admin@admin.com diff --git a/docker-compose.yml b/docker-compose.yml index c33f7ebb..a32947b5 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,4 +1,21 @@ services: + # Uncomment to enable Dashboard (optional web interface) + # dashboard: + # container_name: dashboard + # image: hummingbot/dashboard:latest + # ports: + # - "8501:8501" + # environment: + # - AUTH_SYSTEM_ENABLED=False + # - BACKEND_API_HOST=hummingbot-api + # - BACKEND_API_PORT=8000 + # - BACKEND_API_USERNAME=${USERNAME} + # - BACKEND_API_PASSWORD=${PASSWORD} + # volumes: + # - ./dashboard-credentials.yml:/home/dashboard/credentials.yml + # - ./pages:/home/dashboard/pages + # networks: + # - emqx-bridge hummingbot-api: container_name: hummingbot-api image: hummingbot/hummingbot-api:latest diff --git a/init-db.sql b/init-db.sql index 10d5e352..0c0af9f5 100644 --- a/init-db.sql +++ b/init-db.sql @@ -31,7 +31,7 @@ WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = 'hummingbot_api')\gexe GRANT ALL PRIVILEGES ON DATABASE hummingbot_api TO hbot; -- Connect to the database and grant schema privileges -\c hummingbot_api +\c hummingbot_api hbot -- Grant privileges on the public schema GRANT ALL ON SCHEMA public TO hbot; diff --git a/setup.sh b/setup.sh index 819e39dc..ef5a1861 100755 --- a/setup.sh +++ b/setup.sh @@ -30,6 +30,12 @@ echo -n "API password [default: admin]: " read PASSWORD PASSWORD=${PASSWORD:-admin} +echo "" +echo -e "${YELLOW}Optional Services${NC}" +echo -n "Enable Dashboard web interface? (y/n) [default: n]: " +read ENABLE_DASHBOARD +ENABLE_DASHBOARD=${ENABLE_DASHBOARD:-n} + echo "" echo -e "${YELLOW}Gateway Configuration (Optional)${NC}" echo -n "Gateway passphrase [default: admin, press Enter to skip]: " @@ -123,6 +129,24 @@ EOF echo -e "${GREEN}✅ .env file created successfully!${NC}" echo "" + +# Enable Dashboard if requested +if [[ "$ENABLE_DASHBOARD" =~ ^[Yy]$ ]]; then + echo -e "${GREEN}📊 Enabling Dashboard in docker-compose.yml...${NC}" + + # Remove the comment line first + sed -i.bak '/^ # Uncomment to enable Dashboard (optional web interface)/d' docker-compose.yml + + # Uncomment the dashboard service lines + sed -i.bak '/^ # dashboard:/,/^ # - emqx-bridge$/s/^ # / /' docker-compose.yml + + # Remove backup file + rm -f docker-compose.yml.bak + + echo -e "${GREEN}✅ Dashboard enabled!${NC}" + echo "" +fi + # Display configuration summary echo -e "${BLUE}📋 Configuration Summary${NC}" echo "=======================" @@ -158,16 +182,16 @@ echo -e "${PURPLE}💡 Pro tip:${NC} You can modify environment variables in .en echo -e "${PURPLE}📚 Documentation:${NC} Check config.py for all available settings" echo -e "${PURPLE}🔒 Security:${NC} The password verification file secures bot credentials" echo "" -echo -e "${GREEN}🐳 Starting required Docker containers and pulling Hummingbot image...${NC}" +echo -e "${GREEN}🐳 Starting services (API, EMQX, PostgreSQL)...${NC}" -# Run docker operations in parallel -docker compose up emqx postgres -d & +# Start all services (MCP and Dashboard are optional - see docker-compose.yml) +docker compose up -d & docker pull hummingbot/hummingbot:latest & # Wait for both operations to complete wait -echo -e "${GREEN}✅ Docker containers started!${NC}" +echo -e "${GREEN}✅ All Docker containers started!${NC}" echo "" # Wait for PostgreSQL to be ready @@ -197,18 +221,18 @@ if [ "$DB_READY" = true ]; then echo -e "${YELLOW}🔍 Verifying database configuration...${NC}" # Check if hbot user exists - USER_EXISTS=$(docker exec hummingbot-postgres psql -U postgres -tAc "SELECT 1 FROM pg_roles WHERE rolname='hbot'" 2>/dev/null) + USER_EXISTS=$(docker exec hummingbot-postgres psql -U hbot -tAc "SELECT 1 FROM pg_roles WHERE rolname='hbot'" 2>/dev/null) # Check if database exists - DB_EXISTS=$(docker exec hummingbot-postgres psql -U postgres -tAc "SELECT 1 FROM pg_database WHERE datname='hummingbot_api'" 2>/dev/null) + DB_EXISTS=$(docker exec hummingbot-postgres psql -U hbot -d postgres -tAc "SELECT 1 FROM pg_database WHERE datname='hummingbot_api'" 2>/dev/null) if [ "$USER_EXISTS" = "1" ] && [ "$DB_EXISTS" = "1" ]; then echo -e "${GREEN}✅ Database 'hummingbot_api' and user 'hbot' verified successfully!${NC}" else echo -e "${YELLOW}⚠️ Database initialization may be incomplete. Running manual initialization...${NC}" - # Run the init script manually - docker exec -i hummingbot-postgres psql -U postgres < init-db.sql + # Run the init script manually (connect to postgres database as hbot user) + docker exec -i hummingbot-postgres psql -U hbot -d postgres < init-db.sql if [ $? -eq 0 ]; then echo -e "${GREEN}✅ Database manually initialized successfully!${NC}" @@ -228,3 +252,67 @@ else fi echo -e "${GREEN}✅ Setup completed!${NC}" +echo "" + +# Display services information +echo -e "${BLUE}🎉 Your Hummingbot API Platform is Running!${NC}" +echo "=========================================" +echo "" +echo -e "${CYAN}Available Services:${NC}" +echo -e " 🔧 ${GREEN}API${NC} - http://localhost:8000" +echo -e " 📚 ${GREEN}API Docs${NC} - http://localhost:8000/docs (Swagger UI)" +echo -e " 📡 ${GREEN}EMQX Broker${NC} - localhost:1883" +echo -e " 💾 ${GREEN}PostgreSQL${NC} - localhost:5432" + +if [[ "$ENABLE_DASHBOARD" =~ ^[Yy]$ ]]; then + echo -e " 📊 ${GREEN}Dashboard${NC} - http://localhost:8501" +fi + +echo "" + +echo -e "${YELLOW}📝 Next Steps:${NC}" +echo "" +echo "1. ${CYAN}Access the API:${NC}" +echo " • Swagger UI: http://localhost:8000/docs (full REST API documentation)" + +echo "" +echo "2. ${CYAN}Connect an AI Assistant:${NC}" +echo "" +echo " ${GREEN}Claude Code (CLI) Setup:${NC}" +echo " Add the MCP server with one command:" +echo "" +echo -e " ${BLUE}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${NC}" +echo "" +echo " Then use natural language in your terminal:" +echo ' - "Show me my portfolio balances"' +echo ' - "Create a market making strategy for ETH-USDT on Binance"' +echo "" +echo " ${PURPLE}Other AI assistants:${NC} See CLAUDE.md, GEMINI.md, or AGENTS.md for setup" + +if [[ "$ENABLE_DASHBOARD" =~ ^[Yy]$ ]]; then + echo "" + echo "3. ${CYAN}Access Dashboard:${NC}" + echo " • Web UI: http://localhost:8501" +fi + +echo "" +echo -e "${CYAN}Available Access Methods:${NC}" +echo " ✅ Swagger UI (http://localhost:8000/docs) - Full REST API" +echo " ✅ MCP - AI Assistant integration (Claude, ChatGPT, Gemini)" + +if [[ "$ENABLE_DASHBOARD" =~ ^[Yy]$ ]]; then + echo " ✅ Dashboard (http://localhost:8501) - Web interface" +else + echo " ⚪ Dashboard - Run setup.sh again to enable web UI" +fi + +echo "" + +echo -e "${PURPLE}💡 Tips:${NC}" +echo " • View logs: docker compose logs -f" +echo " • Stop services: docker compose down" +echo " • Restart services: docker compose restart" +echo "" + +echo -e "${GREEN}Ready to start trading! 🤖💰${NC}" +echo ""