Hummingbot: Trading Agent

This tool helps you manage multiple Hummingbot API servers with a simple flow:
1. No parameters → List all configured servers
2. action="add" + name + (optional host/port/username/password) → Add a new server
3. action="modify" + name + (host/port/username/password) → Modify existing server (partial updates supported)
4. action="set_default" + name → Set a server as default (reconnects client)
5. action="remove" + name → Remove a server

Use this tool to discover what's available and understand how things work.

Progressive flow:
1. action="list" → List all controllers and their configs
2. action="list" + controller_type → List controllers of that type with config counts
3. action="describe" + controller_name → Show controller code + list its configs + explain parameters
4. action="describe" + config_name → Show specific config details + which controller it uses

Common Enum Values for Controller Configs:

Position Mode (position_mode):
- "HEDGE" - Allows holding both long and short positions simultaneously
- "ONEWAY" - Allows only one direction position at a time
- Note: Use as string value, e.g., position_mode: "HEDGE"

Trade Side (side):
- 1 or "BUY" - For long/buy positions
- 2 or "SELL" - For short/sell positions
- 3 - Other trade types
- Note: Numeric values are required for controller configs

Order Type (order_type, open_order_type, take_profit_order_type, etc.):
- 1 or "MARKET" - Market order
- 2 or "LIMIT" - Limit order
- 3 or "LIMIT_MAKER" - Limit maker order (post-only)
- 4 - Other order types
- Note: Numeric values are required for controller configs

Supports CLMM DEX connectors (Meteora, Raydium, Uniswap V3) for concentrated liquidity pools.

Actions:
- list_pools: Browse available CLMM pools with filtering and sorting
- get_pool_info: Get detailed information about a specific pool (requires network and pool_address)

This tool provides a comprehensive view of your entire portfolio by fetching data from multiple sources
in parallel. By default, it returns all four types of data, but you can filter to only include
specific sections.

Data Sources (fetched in parallel using asyncio.gather):
1. Token Balances - Holdings across all connected CEX/DEX exchanges
2. Perpetual Positions - Open perpetual futures positions from CEX
3. LP Positions (CLMM) - Real-time concentrated liquidity positions from blockchain DEXs
   - Queries database to find all pools user has interacted with
   - Calls get_positions() for each pool to fetch real-time blockchain data
   - Includes real-time fees and token amounts
4. Active Orders - Currently open orders across all exchanges

NOTE: This only shows ACTIVE/OPEN positions. For historical data, use search_history() instead.

Actions:
- "stop_bot": Stop and archive the entire bot forever (controller_names not needed)
- "stop_controllers": Stop specific controllers by setting manual_kill_switch to True (requires controller_names)
- "start_controllers": Start/resume specific controllers by setting manual_kill_switch to False (requires controller_names)

Supports CLMM DEX connectors (Meteora, Raydium, Uniswap V3) for concentrated liquidity positions.

Actions:
- open_position: Create a new CLMM position with initial liquidity
- close_position: Close a position completely (removes all liquidity)
- collect_fees: Collect accumulated fees from a position
- get_positions: Get all positions owned by a wallet for a specific pool (fetches real-time data from blockchain)

Open Position Parameters (required for open_position):
    connector: CLMM connector name (e.g., 'meteora', 'raydium')
    network: Network ID in 'chain-network' format (e.g., 'solana-mainnet-beta')
    pool_address: Pool contract address
    lower_price: Lower price bound (e.g., '150')
    upper_price: Upper price bound (e.g., '250')
    base_token_amount: Amount of base token to provide (optional)
    quote_token_amount: Amount of quote token to provide (optional)
    slippage_pct: Maximum slippage percentage (default: 1.0)
    wallet_address: Wallet address (optional, uses default if not provided)
    extra_params: Additional connector-specific parameters (e.g., {"strategyType": 0} for Meteora)

Close/Collect Parameters (required for close_position and collect_fees):
    connector: CLMM connector name
    network: Network ID in 'chain-network' format
    position_address: Position NFT address
    wallet_address: Wallet address (optional)

Get Positions Parameters (required for get_positions):
    connector: CLMM connector name
    network: Network ID in 'chain-network' format
    pool_address: Pool contract address
    wallet_address: Wallet address (optional)

Resource Types:
- chains: Get all blockchain chains
- networks: List/get/update network configurations (format: 'chain-network')
- tokens: List/add/delete tokens per network
- connectors: List/get/update DEX connector configurations
- pools: List/add liquidity pools per connector/network
- wallets: Add/delete wallets for blockchain chains

Supports:
- get_status: Check Gateway container status
- start: Start Gateway with configuration
- stop: Stop Gateway container
- restart: Restart Gateway (optionally with new config)
- get_logs: Get container logs

Supports DEX router swaps via Jupiter (Solana) and 0x (Ethereum).

Actions:
- quote: Get price quote for a swap before executing
- execute: Execute a swap transaction on DEX
- search: Search swap history with filters
- get_status: Get status of a specific swap by transaction hash

Quote/Execute Parameters (required for quote/execute):
    connector: DEX router connector (e.g., 'jupiter', '0x')
    network: Network ID in 'chain-network' format (e.g., 'solana-mainnet-beta', 'ethereum-mainnet')
    trading_pair: Trading pair in BASE-QUOTE format (e.g., 'SOL-USDC', 'ETH-USDT')
    side: Trade side - 'BUY' (buy base with quote) or 'SELL' (sell base for quote)
    amount: Amount to swap (for BUY: base to receive, for SELL: base to sell)
    slippage_pct: Maximum slippage percentage (default: 1.0)
    wallet_address: Wallet address for execute (optional, uses default if not provided)

Get Status Parameters:
    transaction_hash: Transaction hash to check status

Search Parameters (all optional):
    search_connector: Filter by connector
    search_network: Filter by network
    search_wallet_address: Filter by wallet address
    search_trading_pair: Filter by trading pair
    status: Filter by status (SUBMITTED, CONFIRMED, FAILED)
    start_time: Start timestamp (unix seconds)
    end_time: End timestamp (unix seconds)
    limit: Max results (default: 50, max: 1000)
    offset: Pagination offset (default: 0)

IMPORTANT: When creating a config without specifying config_data details, you MUST first use the explore_controllers tool
with action="describe" and the controller_name to understand what parameters are required. The config_data must include
ALL relevant parameters for the controller to function properly.

Controllers = are essentially strategies that can be run in Hummingbot.
Configs = are the parameters that the controller uses to run.

This tool is for historical analysis, reporting, and tax purposes.
For real-time current state, use get_portfolio_overview() instead.

Data Types:
- orders: Historical order data (filled, cancelled, failed)
- perp_positions: Perpetual positions (both open and closed)
- clmm_positions: CLMM LP positions (both open and closed)

Common Filters (apply to all data types):
    account_names: Filter by account names (optional)
    connector_names: Filter by connector names (optional)
    trading_pairs: Filter by trading pairs (optional)
    status: Filter by status (optional, e.g., 'OPEN', 'CLOSED', 'FILLED', 'CANCELED')
    start_time: Start timestamp in seconds (optional)
    end_time: End timestamp in seconds (optional)
    limit: Maximum number of results (default: 50, max: 1000)
    offset: Pagination offset (default: 0)

CLMM-Specific Filters:
    network: Network filter for CLMM positions (optional)
    wallet_address: Wallet address filter for CLMM positions (optional)
    position_addresses: Specific position addresses for CLMM (optional)

Examples:
- Search filled orders: search_history("orders", status="FILLED", limit=100)
- Search closed perp positions: search_history("perp_positions", status="CLOSED")
- Search all CLMM positions: search_history("clmm_positions", limit=100)

This tool guides you through the entire process of connecting an exchange with a four-step flow:
1. No parameters → List available exchanges
2. Connector only → Show required credential fields
3. Connector + credentials, no account → Select account from available accounts
4. All parameters → Connect the exchange (with override confirmation if needed)

{
  "mcpServers": {
    "hummingbot-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HUMMINGBOT_API_URL",
        "-e",
        "HUMMINGBOT_API_USERNAME",
        "-e",
        "HUMMINGBOT_API_PASSWORD",
        "hummingbot/hummingbot-mcp"
      ],
      "env": {
        "HUMMINGBOT_API_URL": "http://localhost:8000",
        "HUMMINGBOT_API_USERNAME": "admin",
        "HUMMINGBOT_API_PASSWORD": "password"
      }
    }
  }
}