Hummingbot API¶

运行 Hummingbot 交易机器人的中心枢纽 — 现已通过 MCP（模型上下文协议）集成 AI 助手。

仓库更新

backend-api 已被重命名为 hummingbot-api，标志着代码库的重大重构，提升了架构、模块化和开发者体验。

一个全面的 RESTful API 框架，用于跨多个交易所管理交易操作。Hummingbot API 提供了一个集中式平台，聚合了您所有的交易功能，从基础账户管理到复杂的自动化交易策略。

GitHub 仓库： github.com/hummingbot/hummingbot-api

什么是 Hummingbot API？¶

Hummingbot API 旨在成为您交易操作的中心枢纽，提供以下功能：

🤖 AI 助手集成：通过 MCP（Claude、ChatGPT、Gemini）使用自然语言控制您的交易
多交易所账户管理：在不同交易所创建和管理多个交易账户
投资组合监控：实时余额跟踪和投资组合分布分析
交易执行：在所有账户中执行交易、管理订单并监控持仓
自动化交易：部署和控制带有自动化策略的 Hummingbot 实例
策略管理：实时添加、配置和管理交易策略
完全灵活性：在此强大的 API 框架之上构建任何交易产品

无论您是构建交易仪表盘、实现算法策略，还是创建一个完整的交易平台，Hummingbot API 都能提供您所需的一切工具。

架构¶

graph TB
    subgraph "Clients"
        direction LR
        CUSTOM[Custom Apps]
        DASH[Hummingbot<br/>Dashboard]
        AI[AI Agents]
    end

    subgraph "Hummingbot API"
        direction LR
        API["FastAPI<br/>Server<br/>"]
        PG[(PostgreSQL<br/>Database)]
        MQTT[EMQX<br/>Message Broker]
    end

    subgraph "Bots"
        BOTS[Hummingbot<br/>Instances]
    end

    subgraph "Exchanges"
        EX[Binance, OKX,<br/>Hyperliquid, etc.]
    end

    %% Client connections using API Client
    DASH -->|Hummingbot API Client| API

    %% Bot connections
    BOTS <-->|Commands & Updates| MQTT

    %% Exchange connections
    BOTS <-->|Trade & Data| EX
    API <-->|Trade & Data| EX

    %% Apply theme colors
    classDef clientStyle stroke:#5FFFD7,stroke-width:3px
    classDef apiStyle stroke:#00B1BB,stroke-width:3px
    classDef botsStyle stroke:#E549FF,stroke-width:3px

    class DASH clientStyle
    class API,PG,MQTT apiStyle
    class BOTS botsStyle

核心组件¶

服务器基础设施：
- 使用 HTTP 基本身份验证的 FastAPI 服务器，提供 RESTful API
- PostgreSQL 数据库，用于存储交易数据、账户信息和历史表现
- EMQX 消息代理，用于与机器人实例进行实时通信
交易所连接器：内置主流中心化交易所（CEX）和去中心化交易所（DEX）的连接器——交易和数据获取可通过 Hummingbot API 直接访问，或通过其部署的机器人实现
机器人实例：连接不同交易所的独立 Hummingbot 容器
Docker 管理：编排多个 Hummingbot 容器实例

🎯 与 Hummingbot API 交互的方式¶

选择最适合您工作流程的方式：

1. 🔧 Swagger UI - API 文档（默认）¶

交互式 REST API 文档和测试工具

最适合：希望完全掌控的开发者和高级用户
优势：
完整的 API 访问权限 — 所有端点均可使用
直接测试端点
集成开发
无需额外配置
配置：运行安装后自动可用
访问：http://localhost:8000/docs

2. 🤖 MCP - AI 助手（可选）¶

通过 Claude、ChatGPT 或 Gemini 使用自然语言进行交易指令操作

最适合：偏好对话式交互的用户
优势：
自然语言指令
可完全访问所有 API 功能
上下文帮助与解释
复杂多步骤操作变得简单
通过 setup_connector 工具逐步完成凭据配置
配置：参见 MCP 安装指南
示例：
首次使用：“为我设置 Solana 钱包” → 引导完成凭据配置
交易示例：“0.01 SOL 兑换 USDC 的价格是多少？执行此交易”

3. 📊 仪表板 - 网页界面（可选）¶

常见操作的可视化界面

最适合：偏好图形化界面的用户
优势：
直观的可视化工作流
实时图表与数据展示
快速访问常用任务
限制：并非所有 API 功能都可用（聚焦核心功能）
配置：在安装过程中启用
访问：http://localhost:8501

使用场景¶

Hummingbot API 支持多种交易应用：

自定义 OEMS：构建跨多个交易所的自有交易订单执行管理系统
交易仪表板：构建自定义聊天、网页和移动界面，用于控制机器人
AI 驱动交易：与大语言模型（LLM）集成，实现智能交易工作流
风险管理工具：构建用于监控和管理交易操作的系统
市场数据流：创建实时价格和历史 K 线数据流，供各类应用使用

快速入门¶

安装指南 —— Docker 和源码安装的完整说明
快速入门指南 - 学习如何：
- 添加交易所凭据
- 查看投资组合余额
- 下达您的第一笔市价单

这些指南包含 Docker 设置和 Python API 客户端示例，助你几分钟内开始交易。

API 端点¶

Hummingbot API 按功能模块划分为以下路由接口：

🐳 Docker 管理 - 容器生命周期与编排
💳 账户管理 - 多交易所账户配置
🔌 连接器发现 - 交易所连接器信息查询
📊 投资组合管理 - 实时投资组合跟踪与分析
💹 交易操作 - 委托执行与头寸管理
🤖 机器人编排 - 部署和管理交易机器人
📋 策略管理 - 控制器与脚本
📊 市场数据 - 实时及历史市场数据
🔄 回测 - 使用历史数据测试策略
📈 归档机器人分析 - 历史机器人表现分析
🌐 网关 - 网关容器与去中心化交易所（DEX）基础设施管理
🔄 网关兑换 - DEX 兑换执行与监控
💧 网关 CLMM - 集中流动性头寸管理

有关详细端点文档，请参阅 API 路由器指南。

系统依赖¶

平台包含以下核心服务：

PostgreSQL 数据库¶

存储所有交易数据，包括：

委托单与交易历史
账户状态与余额
持仓与资金费用支付
性能指标

注意：数据库将通过环境变量自动初始化。init-db.sql 文件作为备用保障。

EMQX 消息代理¶

实现与交易机器人的实时通信：

接收运行中机器人的实时更新
发送指令以控制机器人执行
处理实时数据流

配置¶

环境变量¶

在 .env 文件中可用的关键配置选项：

CONFIG_PASSWORD：用于加密 API 密钥和凭证
USERNAME/PASSWORD：API 认证凭据
BROKER_HOST/PORT：EMQX 消息代理设置
DATABASE_URL：PostgreSQL 连接字符串
ACCOUNT_UPDATE_INTERVAL：余额更新频率（分钟）
AWS_API_KEY/AWS_SECRET_KEY：S3 归档（可选）
BANNED_TOKENS：要排除的令牌，以逗号分隔的列表
LOGFIRE_TOKEN：可观测性和监控（生产环境）

机器人实例结构¶

每个机器人维护自己独立的环境：

bots/instances/hummingbot-{name}/
├── conf/           # Configuration files
├── data/           # Bot databases and state
└── logs/           # Execution logs

认证

API 使用 HTTP 基本身份验证：

在设置期间配置用户名和密码
在所有请求的 Authorization 头中包含凭据
示例：Authorization: Basic <base64 编码的凭据>

API 客户端¶

提供了一个现代化的异步 Python 客户端，用于与 Hummingbot API 交互。该客户端被 Hummingbot 控制面板用作所有 API 通信的接口层。

GitHub： hummingbot-api-client
PyPI： pypi.org/project/hummingbot-api-client

安装¶

pip install hummingbot-api-client

使用示例¶

from hummingbot_api_client import HummingbotAPIClient

# Initialize client
client = HummingbotAPIClient(
    base_url="http://localhost:8000",
    username="your-username",
    password="your-password"
)

# Get portfolio data
portfolio = await client.get_portfolio()

# Execute a trade
order = await client.create_order(
    connector="binance",
    trading_pair="BTC-USDT",
    order_type="limit",
    side="buy",
    amount=0.001,
    price=50000
)

Hummingbot 控制面板 - 基于 Hummingbot API 构建的基于 Web 的界面
API 客户端文档 - Python 客户端库
Hummingbot 客户端 - 核心交易引擎