192 lines
3.9 KiB
Markdown
192 lines
3.9 KiB
Markdown
# Bitget Python SDK 迁移指南
|
||
|
||
## 概述
|
||
|
||
已将 Bitget 交易 API 从手动实现迁移到使用 **CCXT Python SDK**。
|
||
|
||
## 主要变化
|
||
|
||
### 1. 依赖变更
|
||
|
||
**新增依赖：**
|
||
```bash
|
||
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）
|
||
```python
|
||
# 订单响应格式
|
||
{
|
||
'orderId': '123456789',
|
||
'fillPrice': '50000.5',
|
||
...
|
||
}
|
||
```
|
||
|
||
#### 新版本（CCXT）
|
||
```python
|
||
# 订单响应格式
|
||
{
|
||
'id': '123456789',
|
||
'price': '50000.0', # 委托价格
|
||
'average': '50000.5', # 成交均价
|
||
'status': 'closed', # CCXT 标准状态
|
||
...
|
||
}
|
||
```
|
||
|
||
### 4. 订单方向变化
|
||
|
||
#### 旧版本
|
||
```python
|
||
side_map = {
|
||
OrderSide.LONG: 'open_long',
|
||
OrderSide.SHORT: 'open_short'
|
||
}
|
||
```
|
||
|
||
#### 新版本（CCXT 标准化）
|
||
```python
|
||
side_map = {
|
||
OrderSide.LONG: 'buy',
|
||
OrderSide.SHORT: 'sell'
|
||
}
|
||
```
|
||
|
||
### 5. 交易对格式
|
||
|
||
#### 旧版本
|
||
```
|
||
BTCUSDT
|
||
ETHUSDT
|
||
```
|
||
|
||
#### 新版本（CCXT 标准化）
|
||
```
|
||
BTC/USDT:USDT
|
||
ETH/USDT:USDT
|
||
```
|
||
|
||
新实现会自动进行格式转换。
|
||
|
||
## 安装步骤
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
在 `.env` 文件中配置：
|
||
|
||
```bash
|
||
# 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. 测试连接
|
||
|
||
```bash
|
||
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 行：
|
||
```python
|
||
# 从
|
||
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. 测试网是否可用
|