14.Hummingbot API自动化

Hummingbot API 是框架的现代化演进，它将原本基于命令行的交互方式升级为标准的 RESTful 接口。这意味着可以用编程方式管理交易机器人，不再需要手动输入命令。对于需要同时运行多个策略、构建自定义监控面板或者将交易逻辑集成到更大系统的用户来说，API 是必不可少的基础设施。

API 架构与认证机制

Hummingbot API 采用典型的三层架构设计。最上层是 FastAPI 提供的高性能 HTTP 服务，中间层通过 MQTT 消息代理与实际的机器人实例通信，底层则是 PostgreSQL 数据库持久化存储所有交易数据。这种设计让 API 既能直接执行交易，也能管理分布在不同容器中的机器人集群。

认证机制使用 HTTP Basic Auth，这是最简单也最可靠的方式。在请求头中携带 base64 编码的用户名密码即可，不需要复杂的 JWT 刷新逻辑。.env 文件中的 API_USERNAME 和 API_PASSWORD 就是访问凭证，建议在首次部署时修改为高强度密码。

curl -u admin:admin http://localhost:8000/health

这行命令测试 API 是否正常运行。-u 参数自动处理 Basic Auth 的编码工作，如果返回 {"status":"healthy"}，说明服务已经就绪。生产环境务必修改默认密码，否则相当于把交易权限公开到网络。

API 的核心组件包括 Docker 管理器、账户系统、交易引擎和策略编排器。Docker 管理器负责创建和销毁机器人容器，账户系统统一管理所有交易所凭证，交易引擎直接对接交易所接口，策略编排器则控制 V2 控制器的生命周期。这些组件通过依赖注入共享同一个数据库会话，保证数据一致性。

Python 客户端安装与使用

虽然直接用 curl 可以调用 API，但官方提供的 Python 客户端封装了异步请求、错误重试和数据序列化等繁琐工作。安装只需要一行 pip 命令，依赖项极少。

pip install hummingbot-api-client

安装完成后，创建客户端实例需要指定三个参数：API 地址、用户名和密码。建议在代码中从环境变量读取凭证，避免硬编码泄露。

from hummingbot_api_client import HummingbotAPIClient

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

这个客户端是异步设计的，所有网络操作都返回协程对象。调用 await client.init() 会初始化连接池和会话，而 await client.close() 确保资源正确释放。使用 async with 语法可以自动管理生命周期。

import asyncio

async def main():
    client = HummingbotAPIClient(...)
    await client.init()
    try:
        portfolio = await client.portfolio.get_state()
        print(portfolio)
    finally:
        await client.close()

asyncio.run(main())

这种模式避免了连接泄漏，特别是在高频调用时。客户端内部实现了指数退避重试机制，当 API 暂时不可用时会自动重试三次，每次间隔时间翻倍。

账户与凭证管理接口

Hummingbot API 引入"账户"概念来隔离不同用途的凭证。默认只有一个 master_account，但可以为不同策略创建独立账户，比如 arbitrage_account、market_making_account。每个账户下的凭证加密存储，用配置密码解密。

添加凭证前，先查询交易所需要哪些字段。不同交易所的认证方式差异很大，Hyperliquid 需要 API 密钥和私钥，Binance 只需要 API Key 和 Secret，而 OKX 还需要 Passphrase。

config_fields = await client.connectors.get_config_map("hyperliquid")
print(config_fields)
# 输出: ['hyperliquid_api_key', 'hyperliquid_api_secret', 'use_vault']

返回的列表就是该交易所必需的配置项。use_vault 是布尔值，表示是否使用 Hyperliquid 的 vault 地址作为交易账户。这种动态配置查询避免了硬编码字段名，当交易所更新认证方式时，代码无需修改。

添加凭证的接口设计得很安全，敏感信息在传输过程中被加密，服务器端存储时也经过二次加密。

credentials = {
    "hyperliquid_api_key": "0x1234...abcd",
    "hyperliquid_api_secret": "your-private-key",
    "use_vault": False
}
result = await client.accounts.add_credential(
    account_name="master_account",
    connector_name="hyperliquid",
    credentials=credentials
)

调用成功后，API 会立即测试凭证有效性。如果返回 Connector credentials added successfully，说明可以正常交易。失败的情况包括：API 密钥权限不足、IP 白名单限制、或者密钥已过期。错误信息会明确指出问题所在。

账户管理还支持删除和更新凭证。删除操作不可逆，但不会影响已经部署的机器人，它们会继续保持运行直到重启。更新凭证会立即生效，正在运行的机器人会在下次重连时使用新凭证。

投资组合查询与监控

获取投资组合状态是 API 最常用的功能之一。与在客户端用 balance 命令只能查看单个交易所不同，API 可以聚合所有账户在所有交易所的资产，生成全局视图。

portfolio = await client.portfolio.get_state()
for account_name, exchanges in portfolio.items():
    for exchange, balances in exchanges.items():
        for balance in balances:
            print(f"{balance['token']}: {balance['units']}")

返回的数据结构是嵌套字典，第一层是账户名，第二层是交易所，第三层是具体资产。每个资产包含五个字段：units 是总数量，available_units 是可交易数量，price 是当前美元计价，value 是总价值。这种设计既保留了细节，又便于汇总计算。

API 还提供历史绩效查询，可以按时间范围筛选。

history = await client.portfolio.get_history(
    start_time="2024-01-01T00:00:00Z",
    end_time="2024-01-31T23:59:59Z"
)

返回的数据包含每个时间点的总资产价值、各交易所占比、盈亏曲线等。这对于评估策略表现、计算夏普比率等专业指标非常有用。数据存储在 PostgreSQL 中，支持快速聚合查询，即使一年的分钟级数据也能在秒内返回。

实时监控方面，API 通过 MQTT 推送账户变动事件。可以订阅 account_updates/{account_name} 主题，当余额发生变化时立即收到通知。这比轮询更高效，特别适合需要快速反应的场景，比如跨交易所套利。

交易操作与订单管理

下单接口支持所有订单类型：限价单、市价单、止损限价单。每个订单需要指定账户、交易所、交易对、方向、数量和价格。对于永续合约，还需要 position_action 参数区分开仓和平仓。

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"
)

返回的 order 字典包含 order_id，这是后续操作的关键标识。订单状态可能是 SUBMITTED、ACCEPTED、PARTIALLY_FILLED 等。API 不保证订单立即成交，只保证已送达交易所。

撤单操作需要订单 ID，支持批量撤销。

await client.trading.cancel_order(
    account_name="master_account",
    connector_name="hyperliquid",
    order_id="12345"
)

如果订单已经成交或不存在，API 会返回 404 错误。建议在撤单前先用 get_order 查询状态，避免无效操作。

获取交易规则是下单前的必要步骤。不同交易对的最小订单量、价格精度、数量精度都有差异。

rules = await client.connectors.get_trading_rules(
    connector_name="hyperliquid",
    trading_pairs=["HYPE-USDC"]
)
hype_rules = rules["HYPE-USDC"]
print(f"最小价格变动: {hype_rules['min_price_increment']}")

返回的规则包含 min_order_size、max_order_size、min_price_increment 等字段。违反这些规则会导致下单失败。API 会自动校验参数，但提前查询可以避免不必要的网络往返。

订单历史查询支持分页和过滤。

orders = await client.trading.get_order_history(
    account_name="master_account",
    start_time="2024-01-01",
    limit=100
)

返回的订单按时间倒序排列，包含完整的成交明细。可以通过 trading_pair 参数筛选特定交易对，或者用 status 参数只查看已成交订单。数据直接从数据库读取，比从交易所查询更快更稳定。

策略实例编排控制

策略编排是 API 的核心价值所在。它允许动态部署、启动、停止策略实例，无需重启整个 Hummingbot 服务。每个策略实例运行在独立的 Docker 容器中，互不影响。

部署策略需要指定配置文件和实例名称。

bot = await client.bot_orchestration.deploy(
    instance_name="hummingbot-dman-1",
    config_file_name="dman_v3.py",
    script_config="conf_dman_v3_1.yml",
    image="hummingbot/hummingbot:latest"
)

config_file_name 是策略脚本文件名，存放在 hummingbot_files/scripts 目录。script_config 是 YAML 配置文件，定义具体参数。API 会自动挂载这些文件到容器内部，策略启动时读取配置。

启动策略实例后，可以通过 MQTT 实时监控状态。

status = await client.bot_orchestration.get_status("hummingbot-dman-1")
print(f"运行状态: {status['status']}")
print(f"已运行: {status['uptime']} 秒")
print(f"净盈亏: {status['net_pnl']} USDT")

返回的状态包含 CPU 和内存使用率、活跃控制器列表、最近日志等。控制器是 V2 策略的基本单元，一个策略实例可以运行多个控制器，每个控制器独立管理一个交易对。

停止策略实例有两种方式：优雅停止和强制停止。

# 优雅停止，会等待控制器平仓
await client.bot_orchestration.stop("hummingbot-dman-1")

# 强制停止，立即取消所有订单
await client.bot_orchestration.stop("hummingbot-dman-1", force=True)

优雅停止适合策略需要保存状态的场景，比如网格策略会把当前网格位置写入数据库，下次启动时可以恢复。强制停止用于紧急情况，比如市场剧烈波动需要立即离场。

策略编排还支持批量操作。

bots = await client.bot_orchestration.list_bots()
for bot in bots:
    if bot['status'] == 'running':
        await client.bot_orchestration.stop(bot['instance_name'])

这在需要维护升级时特别有用，可以一键停止所有策略，更新配置后再批量启动。API 保证操作的原子性，即使网络中断，已发出的命令也会被执行。

日志查询接口可以获取策略的实时输出。

logs = await client.bot_orchestration.get_logs(
    instance_name="hummingbot-dman-1",
    tail=100
)
for log in logs:
    print(f"{log['timestamp']}: {log['message']}")

日志按时间戳排序，支持 tail 参数获取最后 N 行，也支持 since 参数获取某个时间点后的日志。这对于排查策略问题非常有帮助，无需进入容器就能查看详细运行信息。

策略编排的深度集成让 Hummingbot 从单机工具升级为分布式交易系统。配合 Dashboard 或 Condor，可以构建完整的自动化交易基础设施，实现策略的灰度发布、A/B 测试和动态扩容。这是 V2 框架相比 V1 的最大优势，也是专业量化团队的必备能力。