Hummingbot API Developer Guide

This guide demonstrates how to use the Hummingbot API directly using curl or the Python client. It covers adding exchange credentials, viewing your portfolio, and placing orders.

Prerequisites

• Miniconda or Anaconda — conda must be on your PATH (the Makefile uses it for make install / make run).
• Docker and Docker Compose — make run starts EMQX and PostgreSQL in Docker, then runs the API on your machine with Uvicorn.
• Exchange API keys — only needed when you call trading endpoints; see this Binance API keys guide as an example.
• hummingbot-api-client (optional) — for the Python examples later in this guide; install with pip in any Python 3.12+ environment, or use the conda env after make install.

Install from Source (for developers)

Use this when you are contributing to hummingbot-api or running the API on your host with hot reload (not the all-in-Docker make deploy path).

1. Clone the repository

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

2. Install dependencies (make install)

make install

This will:

• Create the hummingbot-api conda environment from environment.yml (currently Python 3.12 and project dependencies)
• Install pre-commit hooks
• Run make setup, which executes ./setup.sh and creates .env (API user/password, database URL for local Postgres, broker settings, etc.)

You do not need to run make setup separately first — make install already invokes it at the end.

3. Start the stack in development mode (make run)

make run

make run starts Postgres and EMQX in the background (Docker), then launches the API on your machine with live reload—when you change Python code, the server restarts automatically. You do not need to run conda activate yourself; the command uses the hummingbot-api conda environment for you.

Requirements before this step:

• Docker is installed and the daemon is running.
• .env exists (from step 2). For local dev, DATABASE_URL should point at Postgres on localhost (the default from setup.sh is correct while EMQX/Postgres are published on localhost).

The API will be available at http://localhost:8000 (Swagger at http://localhost:8000/docs).

Setup Python Client (Optional)

If you want to use the Python client for the examples below:

1. Install the Hummingbot API Client:

   pip install hummingbot-api-client
   

2. Create a new Python file (e.g., hummingbot_api_demo.py):

   touch hummingbot_api_demo.py
   

3. Add the following code to initialize the client:

   import asyncio
   from hummingbot_api_client import HummingbotAPIClient
   
   # Create client instance
   client = HummingbotAPIClient(
       base_url="http://localhost:8000",
       username="admin",
       password="admin"
   )
   

4. To run any of the examples below, use:

   python hummingbot_api_demo.py
   

List Available Exchanges

Get a list of all available exchange connectors. Note that spot and perpetual markets are separate connectors (e.g., hyperliquid for spot and hyperliquid_perpetual for perps).

curlPython Client

curl -u admin:admin -X 'GET' \
  'http://localhost:8000/connectors/' \
  -H 'accept: application/json'

import asyncio
from hummingbot_api_client import HummingbotAPIClient

# Create client instance
client = HummingbotAPIClient(
    base_url="http://localhost:8000",
    username="admin",
    password="admin"
)

async def list_exchanges():
    await client.init()
    try:
        connectors = await client.connectors.list_connectors()
        print("\U0001F4CB Available exchanges/connectors:")
        for connector in connectors:
            print(f"  - {connector}")
        return connectors
    finally:
        await client.close()

def main():
    connectors = asyncio.run(list_exchanges())
    return connectors

if __name__ == "__main__":
    main()

Response:

curlPython Client

[
  "binance",
  "binance_perpetual",
  "hyperliquid",
  "hyperliquid_perpetual",
  "okx",
  "okx_perpetual",
]

📋 Available exchanges/connectors:
  - binance
  - binance_perpetual
  - hyperliquid
  - hyperliquid_perpetual
  - okx
  - okx_perpetual

Get Connector Configuration

Before adding credentials, check what configuration fields are required for your connector:

curlPython Client

curl -u admin:admin -X 'GET' \
  'http://localhost:8000/connectors/hyperliquid/config-map' \
  -H 'accept: application/json'

import asyncio
from hummingbot_api_client import HummingbotAPIClient

# Create client instance
client = HummingbotAPIClient(
    base_url="http://localhost:8000",
    username="admin",
    password="admin"
)

async def get_connector_config():
    await client.init()
    try:
        # Get required config fields for hyperliquid
        config_fields = await client.connectors.get_config_map("hyperliquid")
        print("\U0001F4CB Required configuration fields for hyperliquid:")
        for field in config_fields:
            print(f"  - {field}")
        return config_fields
    finally:
        await client.close()

# Run the async function
config_fields = asyncio.run(get_connector_config())

Response:

curlPython Client

[
  "hyperliquid_api_secret",
  "use_vault",
  "hyperliquid_api_key"
]

📋 Required configuration fields for hyperliquid:
  - hyperliquid_api_secret
  - use_vault
  - hyperliquid_api_key

Add Exchange Credentials

Add your exchange credentials to the API. By default, only the master_account is created. You can add multiple accounts with different names if needed.

For Hyperliquid:

• hyperliquid_api_secret: Your Hyperliquid public address or vault address
• hyperliquid_api_key: Your API private key
• use_vault: Set to true if using vault address, false for normal account

curlPython Client

curl -X POST http://localhost:8000/accounts/add-credential/master_account/hyperliquid \
  -u "admin:admin" \
  -H "Content-Type: application/json" \
  -d '{
    "hyperliquid_api_key": "0x1234...abcd",
    "hyperliquid_api_secret": "your-private-key",
    "use_vault": false
  }'

import asyncio
from hummingbot_api_client import HummingbotAPIClient

# Create client instance
client = HummingbotAPIClient(
    base_url="http://localhost:8000",
    username="admin",
    password="admin"
)

async def add_hyperliquid_credentials():
    await client.init()
    try:
        data = {
            "hyperliquid_api_key": "0x1234....abcde",  # Your public/vault address
            "hyperliquid_api_secret": "your-api-private-key",
            "use_vault": False  # True if using vault address
        }
        # Add credentials for hyperliquid to the 'master_account'
        result = await client.accounts.add_credential("master_account", "hyperliquid", data)
        print("\U0001F511 Added hyperliquid credentials:")
        print(result)
        return result
    finally:
        await client.close()

# Run the async function
asyncio.run(add_hyperliquid_credentials())

Response:

curlPython Client

{
  "message": "Connector credentials added successfully."
}

🔑 Added hyperliquid credentials:
{'message': 'Connector credentials added successfully.'}

View Your Portfolio

Check your portfolio balances across all connected exchanges:

curlPython Client

curl -u admin:admin -X 'POST' \
  'http://localhost:8000/portfolio/state' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

import asyncio
from hummingbot_api_client import HummingbotAPIClient

# Create client instance
client = HummingbotAPIClient(
    base_url="http://localhost:8000",
    username="admin",
    password="admin"
)

async def view_portfolio():
    await client.init()
    try:
        # Get portfolio state
        portfolio = await client.portfolio.get_state()
        print(f"\n\U0001F4CA Portfolio Summary")
        for account_name, exchanges in portfolio.items():
            print(f"\n{account_name}:")
            for exchange, balances in exchanges.items():
                print(f"  {exchange}:")
                for balance in balances:
                    print(f"    {balance['token']}:")
                    print(f"      Units: {balance['units']}")
                    print(f"      Price: ${balance['price']:.2f}")
                    print(f"      Value: ${balance['value']:.2f}")
                    print(f"      Available: {balance['available_units']}")
    finally:
        await client.close()

# Run the async function
asyncio.run(view_portfolio())

Response:

curlPython Client

{
  "master_account": {
    "hyperliquid": [
      {
        "token": "USDC",
        "units": 100.00,
        "price": 1,
        "value": 100.00,
        "available_units": 100.00
      }
    ]
  }
}

📊 Portfolio Summary

master_account:
  hyperliquid:
    USDC:
      Units: 100.00
      Price: $1.00
      Value: $100.00
      Available: 100.00

Get Trading Rules

Before placing orders, fetch the trading rules for your intended trading pair to understand order size limits and price increments:

curlPython Client

curl -u admin:admin -X 'GET' \
  'http://localhost:8000/connectors/hyperliquid/trading-rules?trading_pairs=HYPE-USDC' \
  -H 'accept: application/json'

import asyncio
from hummingbot_api_client import HummingbotAPIClient

async def get_trading_rules():
    client = HummingbotAPIClient(
        base_url="http://localhost:8000",
        username="admin",
        password="admin"
    )
    await client.init()
    try:
        # Get trading rules for HYPE-USDC
        rules = await client.connectors.get_trading_rules(
            connector_name="hyperliquid",
            trading_pairs=["HYPE-USDC"]
        )
        hype_rules = rules["HYPE-USDC"]
        print("\U0001F4CF Trading Rules for HYPE-USDC:")
        print(f"  Min Order Size: {hype_rules['min_order_size']}")
        print(f"  Max Order Size: {hype_rules['max_order_size']}")
        print(f"  Min Price Increment: {hype_rules['min_price_increment']}")
        print(f"  Min Base Amount Increment: {hype_rules['min_base_amount_increment']}")
        print(f"  Supports Limit Orders: {hype_rules['supports_limit_orders']}")
        print(f"  Supports Market Orders: {hype_rules['supports_market_orders']}")
        return rules
    finally:
        await client.close()

# Run the async function
if __name__ == "__main__":
    asyncio.run(get_trading_rules())

Response:

curlPython Client

{
  "HYPE-USDC": {
    "min_order_size": 0,
    "max_order_size": 1e+56,
    "min_price_increment": 0.0001,
    "min_base_amount_increment": 0.01,
    "min_quote_amount_increment": 1e-56,
    "min_notional_size": 0,
    "min_order_value": 0,
    "max_price_significant_digits": 1e+56,
    "supports_limit_orders": true,
    "supports_market_orders": true,
    "buy_order_collateral_token": "USDC",
    "sell_order_collateral_token": "USDC"
  }
}

📏 Trading Rules for HYPE-USDC:
  Min Order Size: 0
  Max Order Size: 1e+56
  Min Price Increment: 0.0001
  Min Base Amount Increment: 0.01
  Supports Limit Orders: True
  Supports Market Orders: True

Place a Limit Order

Execute a limit sell order for HYPE:

curlPython Client

curl -u admin:admin -X 'POST' \
  'http://localhost:8000/trading/orders' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "account_name": "master_account",
  "connector_name": "hyperliquid",
  "trading_pair": "HYPE-USDC",
  "trade_type": "SELL",
  "amount": 1,
  "order_type": "LIMIT",
  "price": 47.1,
  "position_action": "OPEN"
}'

import asyncio
from hummingbot_api_client import HummingbotAPIClient

# Create client instance
client = HummingbotAPIClient(
    base_url="http://localhost:8000",
    username="admin",
    password="admin"
)

async def place_limit_order():
    await client.init()
    try:
        # Place a limit sell order
        order = await client.trading.place_order(
            account_name="master_account",
            connector_name="hyperliquid",
            trading_pair="HYPE-USDC",
            trade_type="SELL",
            amount=1,
            order_type="LIMIT",
            price=47.1,
            position_action="OPEN"
        )
        print(f"\n✅ Order Placed Successfully!")
        print(f"  Order ID: {order['order_id']}")
        print(f"  Status: {order['status']}")
        print(f"  Connector: {order['connector_name']}")
        print(f"  Trading Pair: {order['trading_pair']}")
        print(f"  Type: {order['order_type']} {order['trade_type']}")
        print(f"  Amount: {order['amount']} HYPE")
        print(f"  Price: ${order['price']}")
        return order
    finally:
        await client.close()

# Run the async function
asyncio.run(place_limit_order())

Geo-Restriction Error

If you receive an error like:

{
  "detail": "Failed to place trade: No order book exists for 'HYPE-USDC'."
}

This may indicate you are geo-restricted from trading on the exchange. Check your API logs for more details:

docker logs hummingbot-api

Complete Example

Here's a complete example that performs all three operations:

curlPython Client

echo "🔑 Adding Exchange Account..."
curl -X POST "http://localhost:8000/accounts/add-account?account_name=master_account" \
  -u "admin:admin" \
  -H "accept: application/json"

# Step 2: Add credentials for hyperliquid
curl -X POST "http://localhost:8000/accounts/add-credential/master_account/hyperliquid" \
  -u "admin:admin" \
  -H "Content-Type: application/json" \
  -d '{
    "hyperliquid_api_key": "0x1234...abcd",
    "hyperliquid_api_secret": "your-arbitrum-private-key",
    "use_vault": false
  }'

# Wait for account sync
sleep 2

# Step 3: View portfolio
echo -e "\n\U0001F4CA Fetching Portfolio..."
curl -X POST "http://localhost:8000/portfolio/state" \
  -u "admin:admin" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{}'

# Step 4: Get trading rules for HYPE-USDC
echo -e "\n\U0001F4CF Getting Trading Rules..."
curl -X GET "http://localhost:8000/connectors/hyperliquid/trading-rules?trading_pairs=HYPE-USDC" \
  -u "admin:admin" \
  -H "accept: application/json"

# Step 5: Place limit order
echo -e "\n\U0001F4B1 Placing Limit Order..."
curl -X POST "http://localhost:8000/trading/orders" \
  -u "admin:admin" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "account_name": "master_account",
    "connector_name": "hyperliquid",
    "trading_pair": "HYPE-USDC",
    "trade_type": "SELL",
    "amount": 1,
    "order_type": "LIMIT",
    "price": 47.1,
    "position_action": "OPEN"
  }'

Save this code to hummingbot_api_demo.py:

import asyncio
from hummingbot_api_client import HummingbotAPIClient

async def main():
    # Initialize client
    client = HummingbotAPIClient(
        base_url="http://localhost:8000",
        username="admin",
        password="admin"
    )
    await client.init()
    try:
        # Step 1: Add exchange account
        print("🔑 Adding Exchange Account...")
        try:
            account = await client.accounts.add_account(
                account_name="master_account"
            )
            print(f"✓ Account '{account['account_name']}' added successfully!")
        except Exception as e:
            if "Account already exists" in str(e):
                print("ℹ️ Account already exists, continuing...")
            else:
                raise

        # Step 2: Add credentials for hyperliquid
        print("\n🔑 Adding Hyperliquid Credentials...")
        credentials = {
            "hyperliquid_api_key": "0x1234...abcd",
            "hyperliquid_api_secret": "your-arbitrum-private-key",
            "use_vault": False
        }
        cred_result = await client.accounts.add_credential(
            account_name="master_account",
            connector_name="hyperliquid",
            credentials=credentials
        )
        print(f"✓ Credentials added: {cred_result}")

        # Wait for account sync
        await asyncio.sleep(2)

        # Step 3: View portfolio
        print("\n📊 Fetching Portfolio...")
        portfolio = await client.portfolio.get_state()
        print("Portfolio State:")
        for account, exchanges in portfolio.items():
            for exchange, balances in exchanges.items():
                for balance in balances:
                    print(f"  {account}/{exchange}: {balance['units']:.2f} {balance['token']} (${balance['value']:.2f})")

        # Step 4: Get trading rules
        print("\n📏 Getting Trading Rules for HYPE-USDC...")
        rules = await client.connectors.get_trading_rules(
            connector_name="hyperliquid",
            trading_pairs=["HYPE-USDC"]
        )
        hype_rules = rules["HYPE-USDC"]
        print(f"  Min Order Size: {hype_rules['min_order_size']}")
        print(f"  Min Price Increment: {hype_rules['min_price_increment']}")

        # Step 5: Place limit order
        print("\n💱 Placing Limit Order...")
        order = await client.trading.place_order(
            account_name="master_account",
            connector_name="hyperliquid",
            trading_pair="HYPE-USDC",
            trade_type="SELL",
            amount=1,
            order_type="LIMIT",
            price=47.1,
            position_action="OPEN"
        )
        print(f"✓ Order {order['order_id']} submitted")
        print(f"  Status: {order['status']}")
        print(f"  Type: {order['order_type']} {order['trade_type']}")
        print(f"  Amount: {order['amount']} HYPE @ ${order['price']}")

    except Exception as e:
        print(f"❌ Error: {e}")
    finally:
        await client.close()

# Run the complete example
if __name__ == "__main__":
    asyncio.run(main())

Run the script:

python hummingbot_api_demo.py

Next Steps

Now that you've completed the quickstart, explore more advanced features:

• Bot Management: Deploy and manage multiple trading bots
• Strategy Configuration: Configure and deploy trading strategies
• Market Data: Access real-time and historical market data
• Backtesting: Test your strategies with historical data

For the complete API reference, visit the API documentation when your API is running.