tqsdk

[TqSdk](https://github.com/shinnytech/tqsdk-python) 是信易科技开发的开源Python期货/期权量化交易SDK。通过统一的异步API提供实时行情、历史数据、回测和实盘交易功能。

> 文档：https://doc.shinnytech.com/tqsdk/latest/
> 免费版提供延时行情（15分钟延迟），专业版支持实时数据。

## 安装

```bash
pip install tqsdk
```

## 快速入门

```python
from tqsdk import TqApi, TqAuth, TqBacktest
from datetime import date

# 实盘模式（免费账户提供延时行情）
api = TqApi(auth=TqAuth("your_username", "your_password"))

# 获取实时行情
quote = api.get_quote("SHFE.cu2401")  # Shanghai copper futures
print(f"最新价: {quote.last_price}, 成交量: {quote.volume}")

# 获取K线数据
klines = api.get_kline_serial("SHFE.cu2401", duration_seconds=60)  # 1-min bars
print(klines.tail())

# 关闭API
api.close()
```

## 代码格式

```
EXCHANGE.CONTRACT
```

| 交易所 | 代码 | 示例 |
|---|---|---|
| 上海期货交易所 | `SHFE` | `SHFE.cu2401`（铜） |
| 大连商品交易所 | `DCE` | `DCE.m2405`（豆粕） |
| 郑州商品交易所 | `CZCE` | `CZCE.CF405`（棉花） |
| 中国金融期货交易所 | `CFFEX` | `CFFEX.IF2401`（沪深300期货） |
| 上海国际能源交易中心 | `INE` | `INE.sc2407`（原油） |
| 广州期货交易所 | `GFEX` | `GFEX.si2407`（工业硅） |
| 上交所期权 | `SSE` | `SSE.10004816`（50ETF期权） |
| 深交所期权 | `SZSE` | `SZSE.90000001`（300ETF期权） |

---

## 行情数据

### 实时行情

```python
from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("user", "pass"))

quote = api.get_quote("CFFEX.IF2401")
# 关键字段：
# quote.last_price      — 最新价
# quote.bid_price1      — 买一价
# quote.ask_price1      — 卖一价
# quote.bid_volume1     — 买一量
# quote.ask_volume1     — 卖一量
# quote.highest         — 日最高价
# quote.lowest          — 日最低价
# quote.open            — 开盘价
# quote.close           — 昨收价
# quote.volume          — 总成交量
# quote.amount          — 总成交额
# quote.open_interest   — 持仓量
# quote.upper_limit     — 涨停价
# quote.lower_limit     — 跌停价
# quote.pre_settlement  — 昨结算价
# quote.settlement      — 今结算价

# 等待行情更新
while True:
    api.wait_update()
    if api.is_changing(quote, "last_price"):
        print(f"Price update: {quote.last_price}")
```

### K线数据

```python
# 获取K线序列（返回pandas DataFrame）
klines = api.get_kline_serial(
    "SHFE.cu2401",
    duration_seconds=60,     # K线周期：60=1分钟, 300=5分钟, 3600=1小时, 86400=日线
    data_length=200          # 获取K线数量
)
# 列：datetime, open, high, low, close, volume, open_oi, close_oi

# 多周期
klines_1m = api.get_kline_serial("SHFE.cu2401", 60)
klines_5m = api.get_kline_serial("SHFE.cu2401", 300)
klines_1d = api.get_kline_serial("SHFE.cu2401", 86400)
```

### Tick数据

```python
ticks = api.get_tick_serial("SHFE.cu2401", data_length=500)
# 列：datetime, last_price, highest, lowest, bid_price1, ask_price1,
#          bid_volume1, ask_volume1, volume, amount, open_interest
```

---

## 交易

### 下单

```python
from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("user", "pass"))

# 限价单 — buy open 2 lots
order = api.insert_order(
    symbol="SHFE.cu2401",
    direction="BUY",           # "BUY" or "SELL"
    offset="OPEN",             # "OPEN", "CLOSE", "CLOSETODAY"
    volume=2,                  # Number of lots
    limit_price=68000.0        # Limit price (None for market order)
)

# 市价单（FAK — 即成剩撤）
order = api.insert_order(
    symbol="SHFE.cu2401",
    direction="BUY",
    offset="OPEN",
    volume=2
)

# 撤单
api.cancel_order(order)

# 检查委托状态
while True:
    api.wait_update()
    if order.status == "FINISHED":
        print(f"Order finished: filled={order.volume_orign - order.volume_left}")
        break
```

### 持仓与账户

```python
# 获取账户信息
account = api.get_account()
# account.balance        — 账户余额
# account.available      — 可用资金
# account.margin         — 已用保证金
# account.float_profit   — 浮动盈亏
# account.position_profit — 持仓盈亏
# account.commission     — 今日手续费

# 获取持仓
position = api.get_position("SHFE.cu2401")
# position.pos_long      — 多头持仓量
# position.pos_short     — 空头持仓量
# position.pos_long_today — 今多仓
# position.float_profit_long  — 多头浮动盈亏
# position.float_profit_short — 空头浮动盈亏
# position.open_price_long    — 多头平均开仓价
# position.open_price_short   — 空头平均开仓价
```

---

## 回测

```python
from tqsdk import TqApi, TqAuth, TqBacktest, TqSim
from datetime import date

# 创建回测API
api = TqApi(
    backtest=TqBacktest(
        start_dt=date(2024, 1, 1),
        end_dt=date(2024, 6, 30)
    ),
    account=TqSim(init_balance=1000000),  # 模拟账户，初始资金100万
    auth=TqAuth("user", "pass")
)

# 策略逻辑（同一套代码适用于实盘和回测）
klines = api.get_kline_serial("CFFEX.IF2401", 60 * 60)  # 1-hour bars
position = api.get_position("CFFEX.IF2401")

while True:
    api.wait_update()
    if api.is_changing(klines.iloc[-1], "close"):
        ma5 = klines["close"].iloc[-5:].mean()
        ma20 = klines["close"].iloc[-20:].mean()

        if ma5 > ma20 and position.pos_long == 0:
            api.insert_order("CFFEX.IF2401", "BUY", "OPEN", 1, klines.iloc[-1]["close"])
        elif ma5 < ma20 and position.pos_long > 0:
            api.insert_order("CFFEX.IF2401", "SELL", "CLOSE", 1, klines.iloc[-1]["close"])

api.close()
```

---

## 进阶示例

### 双合约价差交易

```python
from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("user", "pass"))

quote_near = api.get_quote("SHFE.rb2401")   # Near-month rebar
quote_far = api.get_quote("SHFE.rb2405")    # Far-month rebar
pos_near = api.get_position("SHFE.rb2401")
pos_far = api.get_position("SHFE.rb2405")

SPREAD_OPEN = 100    # 开仓价差阈值
SPREAD_CLOSE = 20    # 平仓价差阈值

while True:
    api.wait_update()
    spread = quote_near.last_price - quote_far.last_price

    if spread > SPREAD_OPEN and pos_near.pos_short == 0:
        # 价差过大：卖近月，买远月
        api.insert_order("SHFE.rb2401", "SELL", "OPEN", 1, quote_near.bid_price1)
        api.insert_order("SHFE.rb2405", "BUY", "OPEN", 1, quote_far.ask_price1)
        print(f"Open spread trade: spread={spread:.0f}")

    elif spread < SPREAD_CLOSE and pos_near.pos_short > 0:
        # 价差收敛：双腿平仓
        api.insert_order("SHFE.rb2401", "BUY", "CLOSE", 1, quote_near.ask_price1)
        api.insert_order("SHFE.rb2405", "SELL", "CLOSE", 1, quote_far.bid_price1)
        print(f"Close spread trade: spread={spread:.0f}")
```

### 基于ATR的止损策略

```python
from tqsdk import TqApi, TqAuth
import numpy as np

api = TqApi(auth=TqAuth("user", "pass"))

symbol = "CFFEX.IF2401"
klines = api.get_kline_serial(symbol, 86400, data_length=50)  # 日线
position = api.get_position(symbol)

ATR_PERIOD = 14
ATR_MULTIPLIER = 2.0
entry_price = 0.0

while True:
    api.wait_update()
    if not api.is_changing(klines.iloc[-1], "close"):
        continue

    # 计算ATR
    highs = klines["high"].iloc[-ATR_PERIOD-1:]
    lows = klines["low"].iloc[-ATR_PERIOD-1:]
    closes = klines["close"].iloc[-ATR_PERIOD-1:]
    tr = np.maximum(highs.values[1:] - lows.values[1:],
                    np.abs(highs.values[1:] - closes.values[:-1]),
                    np.abs(lows.values[1:] - closes.values[:-1]))
    atr = np.mean(tr[-ATR_PERIOD:])

    current_price = klines.iloc[-1]["close"]
    ma20 = klines["close"].iloc[-20:].mean()

    if position.pos_long == 0:
        # 入场：价格在20日均线之上
        if current_price > ma20:
            api.insert_order(symbol, "BUY", "OPEN", 1, current_price)
            entry_price = current_price
            print(f"Entry: price={current_price:.2f}, ATR={atr:.2f}")
    else:
        # ATR跟踪止损
        stop_price = entry_price - ATR_MULTIPLIER * atr
        if current_price < stop_price:
            api.insert_order(symbol, "SELL", "CLOSE", position.pos_long, current_price)
            print(f"Stop loss: price={current_price:.2f}, stop={stop_price:.2f}")

api.close()
```

---

## 使用技巧

- 免费版提供延时行情（15分钟延迟），专业版支持实时数据。
- 同一套代码适用于回测和实盘，只需修改API初始化。
- `api.wait_update()` 是核心事件循环，所有数据更新通过它接收。
- 使用 `api.is_changing()` 检查特定数据是否已更新。
- 支持国内所有主要交易所的期货和期权。
- 文档：https://doc.shinnytech.com/tqsdk/latest/

## 目标持仓助手（TargetPosTask）

TqSdk提供便捷的目标持仓管理工具，自动完成开平仓操作：

```python
from tqsdk import TqApi, TqAuth, TargetPosTask

api = TqApi(auth=TqAuth("user", "pass"))
symbol = "SHFE.cu2401"
target = TargetPosTask(api, symbol)
klines = api.get_kline_serial(symbol, 86400, data_length=30)

while True:
    api.wait_update()
    if api.is_changing(klines.iloc[-1], "close"):
        ma5 = klines["close"].iloc[-5:].mean()
        ma20 = klines["close"].iloc[-20:].mean()
        if ma5 > ma20:
            target.set_target_volume(3)     # 自动调整到多头3手
        elif ma5 < ma20:
            target.set_target_volume(-3)    # 自动调整到空头3手
        else:
            target.set_target_volume(0)     # 自动平仓
api.close()
```

## 期权交易

```python
from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("user", "pass"))

# 获取期权合约列表
options = api.query_options("SSE.510050")  # 50ETF期权
print(f"共 {len(options)} 个期权合约")

# 获取特定期权行情
quote = api.get_quote("SSE.10004816")
print(f"最新价: {quote.last_price}")
print(f"隐含波动率: {quote.implied_volatility}")
print(f"Delta: {quote.delta}, Gamma: {quote.gamma}")
print(f"Theta: {quote.theta}, Vega: {quote.vega}")
api.close()
```

## 常见错误处理

| 错误 | 原因 | 解决方法 |
|------|------|----------|
| `Authentication failed` | 账户密码错误 | 检查TqAuth的用户名密码 |
| `Insufficient margin` | 保证金不足 | 检查 `account.available` |
| `Symbol not found` | 合约代码错误或已过期 | 检查代码格式和合约月份 |
| `Connection lost` | 网络断开 | TqSdk会自动重连 |
| `Backtest data not available` | 历史数据不可用 | 检查回测日期范围 |

## 支持的K线周期

| 周期 | duration_seconds | 说明 |
|------|-----------------|------|
| 3秒 | `3` | 超短线 |
| 5秒 | `5` | 超短线 |
| 10秒 | `10` | 短线 |
| 15秒 | `15` | 短线 |
| 30秒 | `30` | 短线 |
| 1分钟 | `60` | 最常用短线周期 |
| 5分钟 | `300` | 常用日内周期 |
| 15分钟 | `900` | 日内波段 |
| 30分钟 | `1800` | 日内波段 |
| 1小时 | `3600` | 中线周期 |
| 2小时 | `7200` | 中线周期 |
| 4小时 | `14400` | 中线周期 |
| 日线 | `86400` | 趋势跟踪 |

## 进阶示例：海龟交易策略

```python
from tqsdk import TqApi, TqAuth, TargetPosTask
import numpy as np

api = TqApi(auth=TqAuth("user", "pass"))
symbol = "CFFEX.IF2401"
klines = api.get_kline_serial(symbol, 86400, data_length=60)
target = TargetPosTask(api, symbol)

ENTRY_PERIOD = 20    # 唐奇安通道入场周期
EXIT_PERIOD = 10     # 唐奇安通道出场周期
ATR_PERIOD = 20      # ATR周期
RISK_RATIO = 0.01    # 单笔风险比例

while True:
    api.wait_update()
    if not api.is_changing(klines.iloc[-1], "close"):
        continue

    highs = klines["high"].values
    lows = klines["low"].values
    closes = klines["close"].values

    if len(closes) < ENTRY_PERIOD + 1:
        continue

    # 唐奇安通道
    entry_high = np.max(highs[-ENTRY_PERIOD-1:-1])
    entry_low = np.min(lows[-ENTRY_PERIOD-1:-1])
    exit_high = np.max(highs[-EXIT_PERIOD-1:-1])
    exit_low = np.min(lows[-EXIT_PERIOD-1:-1])

    # 计算ATR
    tr = np.maximum(highs[1:] - lows[1:],
                    np.abs(highs[1:] - closes[:-1]),
                    np.abs(lows[1:] - closes[:-1]))
    atr = np.mean(tr[-ATR_PERIOD:])

    current = closes[-1]
    account = api.get_account()
    position = api.get_position(symbol)
    unit_size = max(1, int(account.balance * RISK_RATIO / atr))

    if position.pos_long == 0 and position.pos_short == 0:
        if current > entry_high:
            target.set_target_volume(unit_size)      # 突码20日高点做多
        elif current < entry_low:
            target.set_target_volume(-unit_size)     # 突码20日低点做空
    elif position.pos_long > 0:
        if current < exit_low:
            target.set_target_volume(0)              # 跌码10日低点平多
    elif position.pos_short > 0:
        if current > exit_high:
            target.set_target_volume(0)              # 突码10日高点平空
api.close()
```

## 进阶示例：多品种强弱对冲

```python
from tqsdk import TqApi, TqAuth, TargetPosTask

api = TqApi(auth=TqAuth("user", "pass"))

# 黑色系品种：螺纹钢 vs 铁矿石
symbol_a = "SHFE.rb2405"
symbol_b = "DCE.i2405"
klines_a = api.get_kline_serial(symbol_a, 86400, data_length=30)
klines_b = api.get_kline_serial(symbol_b, 86400, data_length=30)
target_a = TargetPosTask(api, symbol_a)
target_b = TargetPosTask(api, symbol_b)
LOOKBACK = 20

while True:
    api.wait_update()
    if len(klines_a) < LOOKBACK or len(klines_b) < LOOKBACK:
        continue

    ret_a = (klines_a.iloc[-1]["close"] / klines_a.iloc[-LOOKBACK]["close"]) - 1
    ret_b = (klines_b.iloc[-1]["close"] / klines_b.iloc[-LOOKBACK]["close"]) - 1

    if ret_a > ret_b + 0.02:       # 强弱差大于2%
        target_a.set_target_volume(1)    # 做多强势品种
        target_b.set_target_volume(-1)   # 做空弱势品种
    elif ret_a < ret_b - 0.02:     # 强弱反转
        target_a.set_target_volume(0)
        target_b.set_target_volume(0)
api.close()
```

---

---

## 🤖 AI Agent 高阶使用指南

对于 AI Agent，在使用该量化/数据工具时应遵循以下高阶策略和最佳实践，以确保任务的高效完成：

### 1. 数据校验与错误处理
在获取数据或执行操作后，AI 应当主动检查返回的结果格式是否符合预期，以及是否存在缺失值（NaN）或空数据。
* **示例策略**：在通过 API 获取数据框（DataFrame）后，使用 `if df.empty:` 进行校验；捕获 `Exception` 以防网络或接口错误导致进程崩溃。

### 2. 多步组合分析
AI 经常需要进行宏观经济分析或跨市场对比。应善于将当前接口与其他数据源或工具组合使用。
* **示例策略**：先获取板块或指数的宏观数据，再筛选成分股，最后对具体标的进行深入的财务或技术面分析，形成完整的决策链条。

### 3. 构建动态监控与日志
对于交易和策略类任务，AI 可以定期拉取数据并建立监控机制。
* **示例策略**：使用循环或定时任务检查特定标的的异动（如涨跌停、放量），并在发现满足条件的信号时输出结构化日志或触发预警。

---

## 社区与支持

由 **大佬量化** 维护 — 量化交易教学与策略研发团队。

微信客服: **bossquant1** · [Bilibili](https://space.bilibili.com/48693330) · 搜索 **大佬量化** — 微信公众号 / Bilibili / 抖音