# Bitget 实盘交易配置指南

## 一、获取 Bitget API 密钥

### 1.1 注册 Bitget 账户

1. 访问 [Bitget 官网](https://www.bitget.com/)
2. 注册账户并完成 KYC 认证

### 1.2 开通合约交易

1. 登录后进入「合约」页面
2. 完成合约交易风险测评
3. 开通 U 本位合约交易

### 1.3 创建 API 密钥

1. 进入「账户」→「API 管理」
2. 点击「创建 API」
3. 设置以下内容：
   - **备注名**: Stock Agent
   - **权限**:
     - ✅ 读取
     - ✅ 提现 (可关闭)
     - ✅ 交易 (必需)
   - **IP 白名单**: 添加你的服务器 IP（可选但推荐）
   - **Google 验证**: 完成绑定

4. 创建后获得：
   - **API Key**
   - **API Secret**
   - **Passphrase** (如果设置了)

---

## 二、配置项目

### 2.1 编辑 `.env` 文件

在项目根目录的 `.env` 文件中添加以下配置：

```bash
# ============================================================================
# Bitget API 配置
# ============================================================================
BITGET_API_KEY=你的API_Key
BITGET_API_SECRET=你的API_Secret
BITGET_PASSPHRASE=你的Passphrase

# 使用测试网（强烈建议先在测试网测试！）
BITGET_USE_TESTNET=true

# 实盘交易总开关（false 时仅模拟交易生效）
REAL_TRADING_ENABLED=false

# 风险控制参数
REAL_TRADING_MAX_SINGLE_POSITION=1000
REAL_TRADING_MAX_TOTAL_RATIO=0.5
REAL_TRADING_DEFAULT_LEVERAGE=10
REAL_TRADING_RISK_PER_TRADE=0.02
REAL_TRADING_MAX_ORDERS=5
```

### 2.2 配置项说明

| 配置项 | 说明 | 推荐值 |
|--------|------|--------|
| `BITGET_API_KEY` | Bitget API Key | 从 Bitget 获取 |
| `BITGET_API_SECRET` | Bitget API Secret | 从 Bitget 获取 |
| `BITGET_PASSPHRASE` | API Passphrase | 从 Bitget 获取（如果需要） |
| `BITGET_USE_TESTNET` | 是否使用测试网 | `true`（测试网） |
| `REAL_TRADING_ENABLED` | 实盘交易开关 | `false`（测试前保持 false） |
| `REAL_TRADING_MAX_SINGLE_POSITION` | 单笔最大持仓 | `1000` USDT |
| `REAL_TRADING_DEFAULT_LEVERAGE` | 默认杠杆 | `10`x（低于模拟的20x） |
| `REAL_TRADING_RISK_PER_TRADE` | 每笔风险 | `0.02` (2%) |

---

## 三、测试网测试

### 3.1 Bitget 测试网

**测试网地址**: https://testnet.bitget.com/

**特点**:
- 与生产网相同的 API 接口
- 虚拟资金，无风险
- 适合测试所有功能

### 3.2 配置测试网

确保 `.env` 中设置：
```bash
BITGET_USE_TESTNET=true
```

### 3.3 运行测试脚本

```bash
# 激活虚拟环境
source backend/venv/bin/activate

# 运行测试脚本
python scripts/test_real_trading.py
```

### 3.4 测试内容

测试脚本会依次执行：
1. ✅ API 连接测试
2. ✅ 查询账户余额
3. ✅ 查询当前持仓
4. ⚠️ 下单测试（已注释，需手动取消注释）

---

## 四、生产网注意事项

### 4.1 切换到生产网

⚠️ **警告**: 切换到生产网后，所有交易都是真实资金！

1. 修改 `.env`:
   ```bash
   BITGET_USE_TESTNET=false
   ```

2. **强烈建议**:
   - 先在测试网充分测试所有功能
   - 使用最小资金进行初期测试
   - 设置严格的风险控制参数
   - 保留模拟交易作为回测

### 4.2 风险控制建议

```bash
# 保守配置（推荐初期使用）
REAL_TRADING_MAX_SINGLE_POSITION=100     # 单笔最大 100 USDT
REAL_TRADING_DEFAULT_LEVERAGE=5           # 杠杆降低到 5x
REAL_TRADING_RISK_PER_TRADE=0.01          # 每笔风险 1%
REAL_TRADING_MAX_ORDERS=2                 # 最多 2 个持仓
```

### 4.3 实盘交易检查清单

- [ ] API Key 配置正确
- [ ] 测试网所有功能验证通过
- [ ] 风险参数已设置
- [ ] 小资金试运行（100-1000 USDT）
- [ ] 监控告警已配置
- [ ] 紧急撤单方案已准备

---

## 五、功能验证

### 5.1 API 连接验证

```bash
python scripts/test_real_trading.py
```

**期望输出**:
```
✅ API 连接成功，USDT 余额: xxxxx
```

### 5.2 查询功能验证

测试脚本会自动验证：
- ✅ 账户余额查询
- ✅ 持仓查询
- ✅ 订单状态查询

### 5.3 下单功能验证（测试网）

在测试网环境下，可以取消注释测试脚本中的下单代码进行真实下单测试：

```python
# 在 test_real_trading.py 中找到此部分并取消注释
result = api.place_order(
    symbol=symbol,
    side='open_long',
    order_type='market',
    size=test_size
)
```

---

## 六、故障排查

### 6.1 API 连接失败

**错误**: `API 连接失败`

**解决**:
1. 检查 API Key 和 Secret 是否正确
2. 检查是否在正确的网络（测试网/生产网）
3. 检查 IP 白名单配置

### 6.2 签名验证失败

**错误**: `API 签名验证失败`

**解决**:
1. 检查系统时间是否准确
2. 检查 API Secret 是否完整复制
3. 检查 passphrase 是否正确

### 6.3 权限不足

**错误**: `权限不足`

**解决**:
1. 确认 API Key 已开通「交易」权限
2. 重新创建 API Key 并勾选所有必需权限

---

## 七、安全最佳实践

### 7.1 API Key 安全

- ✅ 不要将 API Key 提交到 Git 仓库
- ✅ 使用 `.env` 文件并添加到 `.gitignore`
- ✅ 定期轮换 API Key
- ✅ 设置 IP 白名单

### 7.2 资金安全

- ✅ 使用测试网充分测试
- ✅ 从小资金开始
- ✅ 设置合理的止损
- ✅ 不要使用全部资金

### 7.3 系统安全

- ✅ 保留实盘交易日志
- ✅ 配置飞书/Telegram 告警
- ✅ 定期检查持仓状态
- ✅ 设置紧急停机方案

---

## 八、下一步

配置完成后：

1. ✅ 运行测试脚本验证连接
2. ✅ 在测试网测试所有功能
3. ✅ 小资金生产网测试（可选）
4. ✅ 配置监控告警
5. ✅ 逐步增加资金规模

---

**祝交易顺利！** 🚀