stock-ai-agent/docs/BITGET_SDK_MIGRATION.md

Bitget Python SDK 迁移指南

概述

已将 Bitget 交易 API 从手动实现迁移到使用 CCXT Python SDK。

主要变化

1. 依赖变更

新增依赖：

pip install ccxt>=4.0.0

2. 文件结构

旧文件	新文件	说明
bitget_trading_api.py	bitget_trading_api_sdk.py	使用 CCXT 的新实现
-	scripts/test_bitget_sdk.py	SDK 测试脚本

3. API 响应格式变化

旧版本（直接 API）

# 订单响应格式
{
    'orderId': '123456789',
    'fillPrice': '50000.5',
    ...
}

新版本（CCXT）

# 订单响应格式
{
    'id': '123456789',
    'price': '50000.0',      # 委托价格
    'average': '50000.5',    # 成交均价
    'status': 'closed',      # CCXT 标准状态
    ...
}

4. 订单方向变化

旧版本

side_map = {
    OrderSide.LONG: 'open_long',
    OrderSide.SHORT: 'open_short'
}

新版本（CCXT 标准化）

side_map = {
    OrderSide.LONG: 'buy',
    OrderSide.SHORT: 'sell'
}

5. 交易对格式

旧版本

BTCUSDT
ETHUSDT

新版本（CCXT 标准化）

BTC/USDT:USDT
ETH/USDT:USDT

新实现会自动进行格式转换。

安装步骤

1. 安装依赖

cd backend
pip install -r requirements.txt

2. 配置环境变量

在 .env 文件中配置：

# Bitget API 配置
BITGET_API_KEY=your_api_key_here
BITGET_API_SECRET=your_api_secret_here
BITGET_PASSPHRASE=              # Bitget 不需要，保留兼容性
BITGET_USE_TESTNET=true         # 测试时设为 true

# 实盘交易开关
REAL_TRADING_ENABLED=false      # 生产环境再启用

3. 测试连接

cd scripts
python test_bitget_sdk.py

预期输出：

============================================================
测试 1: API 连接测试
============================================================
✅ API 连接成功，USDT 余额: 10000.00

============================================================
测试 2: 查询账户余额
============================================================
✅ 余额查询成功
  USDT: 可用=10000.00, 冻结=0.00
...

CCXT 的优势

1. 统一接口 - 同样的代码可以支持多个交易所（Binance, OKX, Bybit 等）
2. 更好的维护 - CCXT 团队持续更新，修复 API 变更
3. 内置重试 - 自动处理网络问题和速率限制
4. 标准化格式 - 统一的订单状态、交易对格式
5. 异步支持 - 支持 async/await 模式

API 功能对比

功能	旧实现	新实现（CCXT）
下单	✅	✅
撤单	✅	✅
查询订单	✅	✅
查询挂单	✅	✅
查询持仓	✅	✅
查询余额	✅	✅
设置杠杆	✅	✅
测试网支持	✅	✅
自动重试	❌	✅
速率限制	❌	✅

兼容性说明

• ✅ real_trading_service.py 已更新使用新 SDK
• ✅ 保持相同的公共接口
• ✅ 数据库模型无需更改
• ⚠️ 需要重新测试实盘交易功能

下一步

1. 在测试网验证 - 确保所有功能正常
2. 小资金实盘测试 - 验证订单执行
3. 监控日志 - 检查是否有任何错误
4. 逐步迁移 - 确认稳定后使用新版本

回滚方案

如果需要回滚到旧版本：

1. 修改 real_trading_service.py 第 33 行：

# 从
from app.services.bitget_trading_api_sdk import get_bitget_trading_api

# 改回
from app.services.bitget_trading_api import get_bitget_trading_api

2. 重启服务

相关资源

• CCXT 官方文档: https://docs.ccxt.com/
• CCXT Bitget 支持: https://docs.ccxt.com/#exchange-sources
• Bitget 官方文档: https://www.bitget.com/api-doc

支持

如有问题，请检查：

1. CCXT 版本是否 >= 4.0.0
2. API 密钥是否正确
3. 网络连接是否正常
4. 测试网是否可用