Hummingbot API¶

仓库更新

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

概述¶

Hummingbot API 是一个全面的 RESTful API 框架，专为跨多个交易所管理交易操作而设计。它允许个人交易者和团队部署自定义的私有服务器，用于执行交易、管理投资组合、收集数据、部署机器人及其他用途。

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

核心功能¶

⚙️ 标准化且生产就绪 的 API，用于管理机器人、执行交易和监控多交易所投资组合
🔄 功能扩展，包括直接交易、投资组合再平衡和账户管理——全部通过 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 支持多种交易应用：

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

快速入门¶

安装指南 —— Docker 和源码安装的完整说明
快速开始指南 —— 学习如何：
- 添加交易所凭证
- 查看投资组合余额
- 下达你的首个市价单

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

API 路由¶

Hummingbot API 提供以下核心路由：

🐳 Docker 管理¶

管理运行 Hummingbot 的 Docker 容器和实例

GET /docker/running —— 检查 Docker 守护进程是否运行
GET /docker/available-images —— 列出可用的 Docker 镜像
GET /docker/active-containers —— 获取所有正在运行的容器
POST /docker/pull-image - 拉取新的 Docker 镜像
POST /docker/start-container/{name} - 启动容器
POST /docker/stop-container/{name} - 停止容器
POST /docker/remove-container/{name} - 删除容器并归档数据

💼 账户管理¶

处理交易所账户凭证和配置

GET /accounts - 列出所有交易账户
POST /accounts - 创建新的交易账户
PUT /accounts/{id} - 更新账户凭证
DELETE /accounts/{id} - 删除交易账户
GET /accounts/{id}/balances - 获取账户余额

🔌 连接器发现¶

发现并管理可用的交易所连接器

GET /connectors - 列出所有可用连接器
GET /connectors/{name} - 获取连接器详情
GET /connectors/{name}/trading-rules - 获取交易规则和限制
GET /connectors/{name}/markets - 列出支持的交易对

📊 投资组合管理¶

跨交易所监控和分析投资组合表现

GET /portfolio/balances - 获取聚合的投资组合余额
GET /portfolio/performance - 获取投资组合表现指标
GET /portfolio/distribution - 获取代币分布分析
GET /portfolio/history - 获取历史投资组合数据

💱 交易操作¶

执行交易、管理订单和监控仓位

POST /trading/orders - 下单
GET /trading/orders - 列出活跃订单
DELETE /trading/orders/{id} - 取消订单
GET /trading/positions - 获取开仓仓位
GET /trading/history - 获取交易历史
POST /trading/close-position - 平仓

📈 策略管理¶

配置并部署交易策略，支持实时更新

GET /controllers - 列出可用的策略控制器
POST /controllers/{name}/deploy - 部署策略控制器
PUT /controllers/{id}/config - 更新策略参数
GET /scripts - 列出可用的交易脚本
POST /scripts/run - 执行交易脚本

📉 市场数据¶

访问实时和历史市场数据

GET /market-data/ticker/{pair} - 获取当前行情数据
GET /market-data/orderbook/{pair} - 获取订单簿快照
GET /market-data/candles/{pair} - 获取历史 K 线数据
GET /market-data/trades/{pair} - 获取近期交易记录
WS /market-data/stream - 实时市场数据流

🤖 机器人编排¶

部署、配置和管理多个机器人实例

GET /bot-orchestration/bots - 列出所有机器人实例
POST /bot-orchestration/deploy - 部署新机器人
PUT /bot-orchestration/bots/{id}/config - 更新机器人配置
POST /bot-orchestration/bots/{id}/start - 启动机器人
POST /bot-orchestration/bots/{id}/stop - 停止机器人
GET /bot-orchestration/bots/{id}/status - 获取机器人状态

🧪 回测¶

使用历史数据运行策略回测

POST /backtesting/run - 启动新回测
GET /backtesting/results/{id} - 获取回测结果
GET /backtesting/metrics/{id} - 获取性能指标
POST /backtesting/optimize - 运行参数优化

认证

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 客户端 - 核心交易引擎