bt_api_py 项目概览

生成日期：2026-03-07
扫描级别：Exhaustive（详尽扫描）
项目类型：Python Library

项目简介

bt_api_py 是一个专业的统一多交易所交易API框架，专为量化交易者和机构投资者设计。它提供了一套统一的接口来对接全球主流交易所，支持现货、合约、期货、股票等多种交易类型，同时提供同步REST、异步REST和WebSocket三种API模式。

核心价值：

🔌 即插即用 - 新增交易所无需修改核心代码
🌐 统一接口 - 一套API管理73+交易所
⚡ 多种模式 - 同步/异步/WebSocket自由切换
📦 标准化数据 - 27种数据容器屏蔽交易所差异
🚀 高性能 - Cython/C++扩展优化关键路径

快速参考

项目信息

属性	值
项目名称	bt_api_py
类型	Python Library
主要语言	Python 3.11+
支持平台	Linux, Windows, macOS
开源协议	MIT License
PyPI包	bt_api_py
当前版本	0.15

技术栈概览

类别	技术	版本	用途
语言	Python	3.11+	主要开发语言
数据处理	pandas	2.0+	数据分析
数值计算	numpy	1.26+	数组运算
异步HTTP	aiohttp	3.9.0+	异步请求
同步HTTP	requests	2.31+	REST调用
WebSocket	websocket-client	1.6+	实时数据
测试框架	pytest	7.0+	单元测试
代码质量	ruff	0.1+	Linting+格式化
类型检查	mypy	1.0+	静态类型
文档引擎	MkDocs	1.6.0+	文档生成

架构类型

单体应用（Monolith）

统一Python包
Registry模式实现扩展
事件驱动架构
分层设计（数据层/集成层/业务层）

核心特性

1. 多交易所统一接口

支持73+交易所：

✅ 完整支持（REST + WebSocket + 测试通过）：

Binance、HTX (Huobi)、CTP (中国期货)、Interactive Brokers

🔧 已实现 API（仍需继续验证或补齐能力）：

OKX、Bybit、Bitget、Kraken、Gate.io、Upbit、Crypto.com、HitBTC、Phemex、Gemini、KuCoin、MEXC、Bitfinex、Coinbase、Hyperliquid、dYdX、BYDFi

📋 已注册框架：

40+ 个交易所完成基础框架和注册，等待继续补实现、测试或文档

2. 三种API模式

同步REST API：

from bt_api_py import BtApi

api = BtApi()
ticker = api.get_tick("BINANCE___SPOT", "BTCUSDT")

异步REST API：

import asyncio
from bt_api_py import BtApi

async def main():
    api = BtApi()
    ticker = await api.get_tick_async("BINANCE___SPOT", "BTCUSDT")

asyncio.run(main())

WebSocket实时推送：

from bt_api_py import BtApi, EventBus

api = BtApi()
bus = EventBus()

bus.on("ticker", lambda data: print(data))
api.subscribe_ticker("BINANCE___SPOT", "BTCUSDT", bus)

3. 标准化数据容器

27种数据类型：

市场数据：

Ticker（行情）
Bar（K线）
OrderBook（订单簿）
MarkPrice（标记价格）
FundingRate（资金费率）
OpenInterest（持仓量）

交易数据：

Order（订单）
Trade（成交）
Position（持仓）
Balance（余额）
Account（账户）

配置数据：

Symbol（交易对）
Exchange（交易所配置）
Instrument（合约信息）

特殊数据：

Greeks（期权希腊值）
Liquidation（强平）
Pool（流动性池）

4. 即插即用架构

Registry模式：

from bt_api_py import ExchangeRegistry
from bt_api_py.feeds.live_newexchange import NewExchangeFeed

# 注册新交易所（无需修改核心代码）
ExchangeRegistry.register_feed("NEW___SPOT", NewExchangeFeed)

# 创建实例
feed = ExchangeRegistry.create_feed("NEW___SPOT", queue)

5. 事件驱动机制

EventBus事件总线：

from bt_api_py import EventBus

bus = EventBus()

# 订阅事件
bus.on("BarEvent", handle_bar)
bus.on("OrderEvent", handle_order)
bus.on("TradeEvent", handle_trade)

# 发布事件
bus.emit("BarEvent", bar_data)

6. 高性能扩展

Cython优化：

关键计算模块使用Cython实现
编译为平台特定的二进制文件
性能提升10-100倍

C++绑定：

CTP使用SWIG绑定C++库
直接调用底层高性能API
支持Linux/Windows/macOS

项目结构

目录组织

bt_api_py/
├── bt_api_py/              # 主要Python包
│   ├── bt_api.py          # 统一API入口
│   ├── registry.py        # 交易所注册表
│   ├── event_bus.py       # 事件总线
│   ├── exceptions.py      # 异常体系
│   ├── containers/        # 数据容器（27种）
│   ├── feeds/             # 交易所实现（73+）
│   ├── ctp/               # CTP C++扩展
│   ├── functions/         # 业务逻辑
│   └── utils/             # 工具函数
 ├── tests/                 # 测试套件（212个文件）
├── docs/                  # 文档（MkDocs）
├── scripts/               # 开发脚本
├── examples/              # 示例代码
├── pyproject.toml         # 项目配置
├── setup.py               # 安装脚本
├── Makefile               # 常用命令
└── scripts/run_tests.sh           # 测试脚本

代码统计

Python源文件：764个
测试文件：212个
代码行数：~70,000行
文档页面：60+个
支持的交易所：73+个

架构设计

核心架构模式

1. Registry Pattern（注册表模式）

动态注册交易所
无需修改核心代码
支持运行时扩展

2. Event-Driven Architecture（事件驱动架构）

EventBus事件总线
发布/订阅模式
松耦合组件通信

3. Protocol-based Abstraction（协议抽象）

AbstractFeed协议
标准化接口定义
类型安全

4. Factory Pattern（工厂模式）

Registry创建实例
统一的对象创建
依赖注入

5. Data Container Pattern（数据容器模式）

标准化数据结构
自动初始化
统一的访问接口

分层架构

┌─────────────────────────────────────┐
│      用户应用层 (User Code)         │
│   策略、机器人、回测系统            │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│      API层 (BtApi)                  │
│   统一接口、路由、配置              │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│      集成层 (Feeds)                 │
│   交易所适配、协议转换              │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│      数据层 (Containers)            │
│   标准化容器、数据转换              │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│      基础设施层 (Infrastructure)    │
│   Registry, EventBus, Exceptions    │
└─────────────────────────────────────┘

数据流

行情数据流

交易所WebSocket/REST
    ↓
Feed接收原始数据
    ↓
创建数据容器实例
    ↓
调用init_data()解析
    ↓
推送到data_queue
    ↓
EventBus分发事件
    ↓
用户策略处理

交易数据流

用户策略生成信号
    ↓
调用BtApi.create_order()
    ↓
路由到对应Feed
    ↓
调用交易所API
    ↓
接收订单响应
    ↓
创建Order容器
    ↓
推送到用户队列

设计原则

1. 开闭原则（Open/Closed Principle）

对扩展开放，对修改封闭：

新增交易所：注册新Feed
新增数据类型：添加容器类
新增功能：扩展API

2. 单一职责原则（Single Responsibility Principle）

每个组件专注一件事：

BtApi - API路由
Registry - 注册管理
EventBus - 事件分发
Container - 数据表示
Feed - 交易所通信

3. 依赖倒置原则（Dependency Inversion Principle）

依赖抽象，不依赖具体：

# ✓ 正确：依赖抽象协议
def process_feed(feed: AbstractVenueFeed):
    feed.connect()
    feed.subscribe_ticker("BTCUSDT")

# ✗ 错误：依赖具体实现
def process_feed(feed: BinanceSpotFeed):
    feed.connect()

4. 接口隔离原则（Interface Segregation Principle）

小而专的接口：

AbstractFeed定义核心方法
不同交易所实现特定方法
不强制实现不需要的方法

5. 里氏替换原则（Liskov Substitution Principle）

子类可以替换父类：

所有Feed可互换
所有Container可互换
统一的异常处理

关键设计决策

1. 命名约定：`EXCHANGE___TYPE`

原因：

清晰区分交易所和类型
易于解析和路由
避免命名冲突

示例：

BINANCE___SPOT - Binance现货
OKX___SWAP - OKX永续合约
CTP___FUTURE - CTP期货
IB_WEB___STK - IB股票

2. 数据容器自动初始化

原因：

简化使用
统一接口
延迟解析

实现：

order = BinanceOrderData(raw_data)
order.init_data()  # 自动解析
symbol = order.get_symbol()

3. 异常层次结构

原因：

精确错误处理
统一错误接口
易于调试

层次：

BtApiError
├── ExchangeNotFoundError
├── ExchangeConnectionError
├── OrderError
│   ├── InsufficientBalanceError
│   ├── InvalidOrderError
│   └── OrderNotFoundError
└── ...

4. 全局Registry + 实例Registry

原因：

向后兼容
测试隔离
灵活性

使用：

# 全局使用（向后兼容）
ExchangeRegistry.register_feed("TEST", Feed)

# 测试隔离
registry = ExchangeRegistry()
registry.register_feed("TEST", Feed)

性能特性

1. Cython扩展

关键模块：

functions/calculate_number.py - 数值计算
编译为.so（Linux/macOS）或.pyd（Windows）
性能提升10-100倍

2. C++绑定

CTP集成：

SWIG生成Python绑定
直接调用C++ API
最小化性能损失

3. 异步支持

高并发场景：

aiohttp异步HTTP
asyncio协程
并发请求

4. 批量操作

减少API调用：

# 批量获取行情
all_tickers = api.get_all_ticks("BTCUSDT")

测试策略

测试类型

1. 单元测试

快速执行（<1秒）
无外部依赖
Mock外部API

2. 集成测试

真实API调用
需要网络
标记为@pytest.mark.integration

3. 回归测试

所有交易所Feed
数据容器解析
API兼容性

测试标记

@pytest.mark.unit
@pytest.mark.integration
@pytest.mark.slow
@pytest.mark.network
@pytest.mark.binance
@pytest.mark.okx
@pytest.mark.ctp
@pytest.mark.ib

覆盖率目标

新代码：>80%
关键路径：100%
整体项目：>60%

文档结构

Diátaxis框架

1. 入门（Getting Started）

installation.md - 安装指南
quickstart.md - 快速开始
faq.md - 常见问题

2. 使用指南（Guides）

usage_guide.md - 使用指南
best_practices.md - 最佳实践
performance.md - 性能优化
security_best_practices.md - 安全实践

3. API参考（Reference）

bt_api.md - BtApi参考
registry.md - Registry参考
data_containers.md - 数据容器参考
event_bus.md - EventBus参考
exceptions.md - 异常参考

4. 深度解读（Explanation）

architecture.md - 架构设计
developer_guide.md - 开发者指南
exchange_integration_patterns.md - 集成模式

5. 交易所文档（Exchanges）

binance/ - Binance文档
okx/ - OKX文档
ctp/ - CTP文档
ib/ - IB文档

开发工具

代码质量

Ruff（Linter + Formatter）：

替代flake8, isort, black
快速（Rust实现）
自动修复

Mypy（类型检查）：

静态类型分析
类型安全保证
IDE集成

Pre-commit（Git钩子）：

提交前自动检查
保证代码质量
统一代码风格

测试工具

Pytest生态：

pytest-xdist - 并行测试
pytest-cov - 覆盖率
pytest-html - HTML报告
pytest-timeout - 超时控制
pytest-benchmark - 性能测试

文档工具

MkDocs生态：

mkdocs-material - Material主题
mkdocstrings - API文档生成
pymdown-extensions - Markdown扩展

部署场景

1. 本地开发

pip install -e ".[dev]"

2. 生产环境

pip install bt_api_py

3. Docker容器

FROM python:3.11-slim

RUN pip install bt_api_py

COPY your_strategy.py .
CMD ["python", "your_strategy.py"]

4. 云平台

支持平台：

AWS Lambda
Google Cloud Functions
Azure Functions
阿里云函数计算

适用场景

1. 量化交易策略开发

优势：

统一接口简化开发
多交易所策略
回测和实盘一致性

2. 套利交易系统

优势：

同时连接多个交易所
实时价差监控
快速执行

3. 做市商系统

优势：

WebSocket低延迟
高频更新
事件驱动

4. 资产管理平台

优势：

统一管理多交易所
标准化数据
跨平台部署

5. 交易机器人

优势：

事件驱动架构
策略模块化
易于扩展

社区和生态

开源协议

MIT License：

商业友好
允许修改和分发
需要保留版权声明

贡献指南

贡献流程：

Fork仓库
创建功能分支
编写代码和测试
运行质量检查
提交Pull Request

获取帮助

资源：

文档：https://cloudquant.github.io/bt_api_py/
GitHub：https://github.com/cloudQuant/bt_api_py
Issues：https://github.com/cloudQuant/bt_api_py/issues
Email：yunjinqi@gmail.com

未来规划

短期目标（3个月）

完善OKX、KuCoin等交易所测试
增加更多DEX支持
优化WebSocket重连机制
改进错误处理和日志

中期目标（6个月）

实现订单路由和智能下单
添加回测引擎集成
增加风险管理模块
支持更多交易类型（期权、ETF）

长期目标（1年）

构建策略市场
实现多账户管理
添加机器学习集成
开发可视化监控平台

总结

bt_api_py 是一个成熟、专业、高性能的多交易所交易API框架。它通过统一接口、标准化数据和即插即用架构，极大地简化了量化交易系统的开发。无论您是构建套利系统、做市商系统还是资产管理平台，bt_api_py都能为您提供坚实的基础。

核心优势：

✅ 73+交易所支持
✅ 27种标准化数据容器
✅ 三种API模式（同步/异步/WebSocket）
✅ 完善的测试覆盖（198个测试文件）
✅ 高性能Cython/C++扩展
✅ 活跃的社区和文档

开始使用：

pip install bt_api_py

快速验证：

from bt_api_py import BtApi

api = BtApi()
print(f"支持的交易所数量: {len(api.list_available_exchanges())}")

欢迎加入bt_api_py社区！🚀

FilesExpand file tree

project-overview.md

Latest commit

History

project-overview.md

File metadata and controls

bt_api_py 项目概览

项目简介

快速参考

项目信息

技术栈概览

架构类型

核心特性

1. 多交易所统一接口

2. 三种API模式

3. 标准化数据容器

4. 即插即用架构

5. 事件驱动机制

6. 高性能扩展

项目结构

目录组织

代码统计

架构设计

核心架构模式

分层架构

数据流

行情数据流

交易数据流

设计原则

1. 开闭原则（Open/Closed Principle）

2. 单一职责原则（Single Responsibility Principle）

3. 依赖倒置原则（Dependency Inversion Principle）

4. 接口隔离原则（Interface Segregation Principle）

5. 里氏替换原则（Liskov Substitution Principle）

关键设计决策

1. 命名约定：EXCHANGE___TYPE

2. 数据容器自动初始化

3. 异常层次结构

4. 全局Registry + 实例Registry

性能特性

1. Cython扩展

2. C++绑定

3. 异步支持

4. 批量操作

测试策略

测试类型

测试标记

覆盖率目标

文档结构

Diátaxis框架

开发工具

代码质量

测试工具

文档工具

部署场景

1. 本地开发

2. 生产环境

3. Docker容器

4. 云平台

适用场景

1. 量化交易策略开发

2. 套利交易系统

3. 做市商系统

4. 资产管理平台

5. 交易机器人

社区和生态

开源协议

贡献指南

获取帮助

未来规划

短期目标（3个月）

中期目标（6个月）

长期目标（1年）

相关文档

核心文档

API参考

使用指南

总结

1. 命名约定：`EXCHANGE___TYPE`