# 盈透证券 (IBKR) 实盘交易指南

QuantDinger 支持通过盈透证券 TWS 或 IB Gateway 进行美股和港股的实盘交易。

## 概述

此功能可通过您的盈透证券账户实现美股和港股的自动化交易执行。配置完成后，您的交易策略可以通过 IBKR API 自动下单。

## 前置条件

- 盈透证券账户
- 已安装 TWS (Trader Workstation) 或 IB Gateway
- 已订阅市场数据（用于实时报价）

## 安装

`ib_insync` 库已包含在 `requirements.txt` 中。如需手动安装：

```bash
pip install ib_insync
```

## 端口参考

| 客户端 | 实盘端口 | 模拟盘端口 |
|--------|----------|------------|
| TWS    | 7497     | 7496       |
| IB Gateway | 4001 | 4002       |

## TWS / IB Gateway 配置

1. 打开 TWS 或 IB Gateway
2. 进入 **配置** → **API** → **设置**
3. 启用以下选项：
   - ✅ 启用 ActiveX 和 Socket 客户端
   - ✅ 仅允许来自本地主机的连接
4. 设置 Socket 端口（参考上表）
5. 点击 应用 / 确定

## 策略配置

创建美股或港股策略时，在"实盘交易"部分配置 IBKR 连接：

| 字段 | 说明 | 示例 |
|------|------|------|
| **券商** | 选择"盈透证券" | - |
| **主机地址** | TWS/Gateway 主机地址 | `127.0.0.1` |
| **端口** | TWS/Gateway API 端口 | `7497`（TWS 实盘） |
| **客户端 ID** | 唯一客户端标识 | `1` |
| **账户号** | 账户 ID（可选） | 留空自动选择 |

## 代码格式

| 市场 | 格式 | 示例 |
|------|------|------|
| 美股 | 股票代码 | `AAPL`, `TSLA`, `GOOGL`, `MSFT` |
| 港股 | `XXXX.HK` 或数字 | `0700.HK`, `00700`, `700` |

## 交易流程

```
策略信号 → 待执行订单队列 → IBKR 执行 → 持仓更新
```

1. 您的策略生成买入/卖出信号
2. 信号作为待执行订单入队
3. 后台工作线程连接 IBKR 并执行订单
4. 更新持仓和交易记录

## 支持的信号类型

| 信号 | 动作 | 说明 |
|------|------|------|
| `open_long` | 买入 | 开多仓 |
| `add_long` | 买入 | 加多仓 |
| `close_long` | 卖出 | 平多仓 |
| `reduce_long` | 卖出 | 减多仓 |

> **注意**：当前版本暂不支持做空交易。

## API 接口

### 连接管理

```
GET  /api/ibkr/status          # 获取连接状态
POST /api/ibkr/connect         # 连接到 TWS/Gateway
POST /api/ibkr/disconnect      # 断开连接
```

### 账户查询

```
GET  /api/ibkr/account         # 账户信息
GET  /api/ibkr/positions       # 当前持仓
GET  /api/ibkr/orders          # 未成交订单
```

### 交易

```
POST   /api/ibkr/order         # 下单
DELETE /api/ibkr/order/<id>    # 撤单
```

### 行情数据

```
GET  /api/ibkr/quote?symbol=AAPL&marketType=USStock
```

## 使用示例

### 测试连接（通过 curl）

```bash
curl -X POST http://localhost:5000/api/ibkr/connect \
  -H "Content-Type: application/json" \
  -d '{"host": "127.0.0.1", "port": 7497, "clientId": 1}'
```

### 下单

```bash
# 市价单：买入 10 股苹果
curl -X POST http://localhost:5000/api/ibkr/order \
  -H "Content-Type: application/json" \
  -d '{"symbol": "AAPL", "side": "buy", "quantity": 10, "marketType": "USStock"}'

# 限价单：卖出 100 股腾讯
curl -X POST http://localhost:5000/api/ibkr/order \
  -H "Content-Type: application/json" \
  -d '{"symbol": "0700.HK", "side": "sell", "quantity": 100, "marketType": "HShare", "orderType": "limit", "price": 300}'
```

## 重要说明

1. **TWS/Gateway 必须运行**：交易前确保 TWS 或 IB Gateway 已启动并登录
2. **市场数据订阅**：实时报价可能需要向 IBKR 订阅市场数据
3. **客户端 ID**：如果多个程序连接同一个 TWS/Gateway，使用不同的 clientId
4. **账户选择**：如有多个子账户，请指定 `account` 参数
5. **交易时间**：订单仅在市场交易时间执行

## 常见问题排查

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| 连接失败 | TWS/Gateway 未运行 | 启动并登录 TWS/Gateway |
| 连接失败 | 端口错误 | 检查 TWS/Gateway 中的 API 端口设置 |
| 连接失败 | API 未启用 | 在 TWS/Gateway 设置中启用 Socket API |
| 客户端 ID 冲突 | 相同 clientId 已连接 | 使用不同的 clientId |
| 无效合约 | 代码格式错误 | 检查股票代码格式 |
| 订单被拒绝 | 资金/保证金不足 | 检查账户余额 |

## Docker 部署

在 Docker 中运行 QuantDinger 时，TWS/IB Gateway 必须能从容器中访问：

1. 在宿主机上运行 TWS/Gateway
2. 使用 `host.docker.internal` 作为主机地址（Docker Desktop）
3. 或配置 host 网络模式

## 安全建议

- 在 TWS/Gateway 中仅启用"仅允许来自本地主机的连接"
- 使用模拟盘账户进行测试
- 在策略中设置适当的仓位限制
- 定期监控您的账户

## 参见

- [Python 策略开发指南](STRATEGY_DEV_GUIDE_CN.md)
- [盈透证券 API 文档](https://interactivebrokers.github.io/tws-api/)