gavindiaz/DinQuant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Supports Interactive Brokers, US and Hong Kong stocks.

Browse Source 
Signed-off-by: TIANHE <TIANHE@GMAIL.COM>
This commit is contained in:
TIANHE
2026-01-13 02:35:48 +08:00
parent 714dd47c86
commit 7527d73f25
20 changed files with 2250 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/IBKR_TRADING_GUIDE_CN.md
+173
View File
@@ -0,0 +1,173 @@
# 盈透证券 (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/)
docs/IBKR_TRADING_GUIDE_EN.md
+173
View File
@@ -0,0 +1,173 @@
# Interactive Brokers (IBKR) Trading Guide
QuantDinger supports US stocks and Hong Kong stocks live trading via Interactive Brokers TWS or IB Gateway.
## Overview
This feature enables automated trading execution for US and HK stock markets through your Interactive Brokers account. Once configured, your trading strategies can automatically place orders via the IBKR API.
## Prerequisites
- Interactive Brokers account
- TWS (Trader Workstation) or IB Gateway installed
- Market data subscription (for real-time quotes)
## Installation
The `ib_insync` library is already included in `requirements.txt`. If you need to install manually:
```bash
pip install ib_insync
```
## Port Reference
| Client | Live Port | Paper Port |
|--------|-----------|------------|
| TWS | 7497 | 7496 |
| IB Gateway | 4001 | 4002 |
## TWS / IB Gateway Configuration
1. Open TWS or IB Gateway
2. Go to **Configure** → **API** → **Settings**
3. Enable the following options:
- ✅ Enable ActiveX and Socket Clients
- ✅ Allow connections from localhost only
4. Set Socket port (refer to the table above)
5. Click Apply / OK
## Strategy Configuration
When creating a strategy for US or HK stocks, configure the IBKR connection in the "Live Trading" section:
| Field | Description | Example |
|-------|-------------|---------|
| **Broker** | Select "Interactive Brokers" | - |
| **Host** | TWS/Gateway host address | `127.0.0.1` |
| **Port** | TWS/Gateway API port | `7497` (TWS Live) |
| **Client ID** | Unique client identifier | `1` |
| **Account** | Account ID (optional) | Leave empty to auto-select |
## Symbol Format
| Market | Format | Examples |
|--------|--------|----------|
| US Stock | Ticker symbol | `AAPL`, `TSLA`, `GOOGL`, `MSFT` |
| HK Stock | `XXXX.HK` or digits | `0700.HK`, `00700`, `700` |
## Trading Flow
```
Strategy Signal → Pending Order Queue → IBKR Execution → Position Update
```
1. Your strategy generates a buy/sell signal
2. The signal is queued as a pending order
3. The background worker connects to IBKR and executes the order
4. Position and trade records are updated
## Supported Signal Types
| Signal | Action | Description |
|--------|--------|-------------|
| `open_long` | BUY | Open a long position |
| `add_long` | BUY | Add to existing long position |
| `close_long` | SELL | Close long position |
| `reduce_long` | SELL | Reduce long position |
> **Note**: Short selling is not supported in the current implementation.
## API Endpoints
### Connection Management
```
GET /api/ibkr/status # Get connection status
POST /api/ibkr/connect # Connect to TWS/Gateway
POST /api/ibkr/disconnect # Disconnect
```
### Account Queries
```
GET /api/ibkr/account # Account information
GET /api/ibkr/positions # Current positions
GET /api/ibkr/orders # Open orders
```
### Trading
```
POST /api/ibkr/order # Place order
DELETE /api/ibkr/order/<id> # Cancel order
```
### Market Data
```
GET /api/ibkr/quote?symbol=AAPL&marketType=USStock
```
## Usage Examples
### Test Connection (via 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}'
```
### Place Order
```bash
# Market order: buy 10 shares of AAPL
curl -X POST http://localhost:5000/api/ibkr/order \
-H "Content-Type: application/json" \
-d '{"symbol": "AAPL", "side": "buy", "quantity": 10, "marketType": "USStock"}'
# Limit order: sell 100 shares of Tencent
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}'
```
## Important Notes
1. **TWS/Gateway must be running**: Ensure TWS or IB Gateway is started and logged in before trading
2. **Market data subscription**: Real-time quotes may require market data subscription from IBKR
3. **Client ID**: Use different clientId if multiple programs connect to the same TWS/Gateway
4. **Account selection**: Specify `account` parameter if you have multiple sub-accounts
5. **Trading hours**: Orders will only execute during market hours
## Troubleshooting
| Error | Cause | Solution |
|-------|-------|----------|
| Connection failed | TWS/Gateway not running | Start and login to TWS/Gateway |
| Connection failed | Wrong port | Check API port setting in TWS/Gateway |
| Connection failed | API not enabled | Enable Socket API in TWS/Gateway settings |
| Client ID conflict | Same clientId already connected | Use a different clientId |
| Invalid contract | Wrong symbol format | Check symbol format |
| Order rejected | Insufficient funds/margin | Check account balance |
## Docker Deployment
When running QuantDinger in Docker, TWS/IB Gateway must be accessible from the container:
1. Run TWS/Gateway on host machine
2. Use `host.docker.internal` as the host address (Docker Desktop)
3. Or configure host network mode
## Security Recommendations
- Only enable "Allow connections from localhost only" in TWS/Gateway
- Use paper trading account for testing
- Set appropriate position limits in your strategy
- Monitor your account regularly
## See Also
- [Python Strategy Development Guide](STRATEGY_DEV_GUIDE.md)
- [Interactive Brokers API Documentation](https://interactivebrokers.github.io/tws-api/)