tqsdk

TqSdk Development Guide

TqSdk is an open-source Python quantitative trading library developed by Xinyi Technology, based on the Kuaiqi trading and market data server system, supporting market data acquisition, strategy development, backtesting, and live trading for futures, options, and stocks.

When to Use This Skill

Triggered when the user needs the following:

Write quantitative trading strategies using TqSdk
Obtain real-time market data, K-line, and Tick data for futures/options/stocks
Perform strategy backtesting (supports Tick-level and K-line-level)
Configure live trading and simulated trading accounts
Use TargetPosTask for target position trading
Use technical indicators (ta/tafunc) for strategy analysis
Use algorithmic trading modules (TWAP/VWAP)
Debug issues related to the TqSdk asynchronous programming model

Installation

# 安装/升级
pip install tqsdk -U

# 国内镜像（推荐）
pip install tqsdk -U -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host=pypi.tuna.tsinghua.edu.cn

Environment requirements: Python 3, Windows 7+ / macOS / Linux Note: TqSdk uses asyncio, which some IDEs (such as Spyder) do not support. It is recommended to use IDEs that support asyncio, such as VS Code, Cursor, and Trae.

Core Concepts

Programming Model

TqSdk usessingle-threaded asynchronous model, and the core loop is:

from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("快期账户", "账户密码"))

# 1. 获取数据引用对象
quote = api.get_quote("SHFE.rb2401")
klines = api.get_kline_serial("SHFE.rb2401", 60)

# 2. 在循环中等待数据更新
while True:
    api.wait_update()
    # 3. 使用 is_changing() 判断哪个对象更新了
    if api.is_changing(quote):
        print(f"最新价: {quote.last_price}")
    if api.is_changing(klines):
        print(f"最新K线收盘价: {klines.close.iloc[-1]}")

api.close()

Key points:

get_quote()、get_kline_serial() etc. returnreference objects, and values are automatically updated at wait_update() automatically updates at
Each reference object only needs to call the retrieval function once
wait_update() is a blocking function that returns only after receiving a data packet
is_changing() determines whether the specified object was updated in the most recent wait_update whether it is updated in

Contract Code Format

Format:交易所代码.合约代码(case-sensitive)

# 期货合约
"SHFE.cu2401"    # 上期所铜
"DCE.m2401"      # 大商所豆粕
"CZCE.SR401"     # 郑商所白糖（注意：郑商所字母大写，三位数字）
"CFFEX.IF2401"   # 中金所沪深300股指
"INE.sc2401"     # 上期能源原油
"GFEX.si2401"    # 广期所工业硅

# 期权合约
"DCE.m2401-C-3500"     # 大商所豆粕看涨期权
"SHFE.au2404C480"      # 上期所黄金看涨期权
"CFFEX.IO2402-C-4000"  # 中金所沪深300股指期权

# 主连/指数
"KQ.m@CFFEX.IF"  # 中金所IF主连合约
"KQ.i@SHFE.bu"   # 上期所沥青指数

# 外盘
"KQD.m@CBOT.ZS"  # 美黄豆主连

# 跨期组合
"CZCE.SPD SR401&SR403"  # 郑商所跨期
"DCE.SP a2409&a2501"    # 大商所跨期

# 股票（专业版）
"SSE.600000"   # 上交所浦发银行
"SZSE.000001"  # 深交所平安银行

Account Types

Simulated trading (free)

from tqsdk import TqApi, TqAuth

# 临时模拟账户（程序结束后数据丢失）
api = TqApi(auth=TqAuth("快期账户", "账户密码"))

# 指定初始资金的模拟账户
from tqsdk import TqSim
api = TqApi(TqSim(init_balance=100000), auth=TqAuth("快期账户", "账户密码"))

Kuaiqi simulated trading (persistent)

from tqsdk import TqApi, TqKq, TqAuth
# 快期模拟账户，数据持久保存，与快期APP互通
api = TqApi(TqKq(), auth=TqAuth("快期账户", "账户密码"))

Live trading (Professional Edition)

from tqsdk import TqApi, TqAccount, TqAuth
api = TqApi(TqAccount("H海通期货", "账号", "密码"), auth=TqAuth("快期账户", "账户密码"))

Direct CTP connection

from tqsdk import TqApi, TqCtp, TqAuth
api = TqApi(TqCtp("tcp://180.168.xxx:41205", "tcp://180.168.xxx:41205", "账号", "密码"),
            auth=TqAuth("快期账户", "账户密码"))

Multi-account

from tqsdk import TqApi, TqMultiAccount, TqAccount, TqSim, TqAuth
api = TqApi(TqMultiAccount([TqAccount("H海通期货", "账号1", "密码1"), TqSim()]),
            auth=TqAuth("快期账户", "账户密码"))

Market Data

Real-time market data

quote = api.get_quote("SHFE.cu2401")
# 主要字段：
# quote.last_price    最新价
# quote.bid_price1    买一价
# quote.ask_price1    卖一价
# quote.volume        成交量
# quote.open_interest 持仓量
# quote.upper_limit   涨停价
# quote.lower_limit   跌停价
# quote.volume_multiple 合约乘数
# quote.price_tick    最小变动价位

K-line data

# K线周期以秒数表示，最多获取最后 8000 根
klines = api.get_kline_serial("SHFE.cu2401", 60)      # 1分钟线
klines = api.get_kline_serial("SHFE.cu2401", 60*60)   # 1小时线
klines = api.get_kline_serial("SHFE.cu2401", 60*60*24) # 日线
klines = api.get_kline_serial("SHFE.cu2401", 10)       # 10秒线

# klines 是 pandas.DataFrame，包含列：
# datetime, open, high, low, close, volume, open_oi, close_oi

# 常见用法
print(klines.close.iloc[-1])              # 最新K线收盘价
ma = klines.close.rolling(20).mean()      # 20周期均线
print(klines.close.iloc[-3:])             # 最近3根K线收盘价

# 检测新K线
while True:
    api.wait_update()
    if api.is_changing(klines.iloc[-1], "datetime"):
        print("新K线产生")

Tick data

ticks = api.get_tick_serial("SHFE.cu2401")
# 返回 pandas.DataFrame，包含 datetime, last_price, volume 等列

Trading Operations

Order placement/cancellation

# 限价单
order = api.insert_order("SHFE.rb2401", "BUY", "OPEN", volume=3, limit_price=4000)

# 市价单
order = api.insert_order("SHFE.rb2401", "BUY", "OPEN", volume=3)

# 等待成交
while order.status != "FINISHED":
    api.wait_update()

# 撤单
api.cancel_order(order)

# 查看委托单状态
# order.status: ALIVE（活跃）/ FINISHED（完成）
# order.volume_orign: 委托手数
# order.volume_left: 未成交手数

Account and position query

# 账户资金
account = api.get_account()
print(account.balance)       # 账户权益
print(account.available)     # 可用资金

# 持仓查询
position = api.get_position("SHFE.rb2401")
print(position.pos_long)     # 多头持仓
print(position.pos_short)    # 空头持仓

TargetPosTask target position

Automatically manage order placement and cancellation, adjusting to the target position:

from tqsdk import TqApi, TqAuth, TargetPosTask

api = TqApi(auth=TqAuth("快期账户", "账户密码"))
target_pos = TargetPosTask(api, "SHFE.rb2401")

# 设置目标持仓
target_pos.set_target_volume(5)   # 多头5手
target_pos.set_target_volume(-3)  # 空头3手
target_pos.set_target_volume(0)   # 平仓

# 价格模式
target_pos = TargetPosTask(api, "SHFE.rb2401", price="PASSIVE")   # 排队价
target_pos = TargetPosTask(api, "SHFE.rb2401", price="ACTIVE")    # 对手价

# 取消和检查完成状态
target_pos.cancel()
while not target_pos.is_finished():
    api.wait_update()

Strategy Backtesting

from datetime import date
from tqsdk import TqApi, TqAuth, TqSim, TqBacktest, BacktestFinished

acc = TqSim(init_balance=1000000)  # 可选：自定义初始资金

try:
    api = TqApi(acc,
                backtest=TqBacktest(start_dt=date(2023, 1, 1), end_dt=date(2023, 12, 31)),
                auth=TqAuth("快期账户", "账户密码"))

    quote = api.get_quote("SHFE.rb2401")
    klines = api.get_kline_serial("SHFE.rb2401", 60*60*24)
    target_pos = TargetPosTask(api, "SHFE.rb2401")

    while True:
        api.wait_update()
        if api.is_changing(klines.iloc[-1], "datetime"):
            ma5 = klines.close.iloc[-6:-1].mean()
            if quote.last_price > ma5:
                target_pos.set_target_volume(1)
            else:
                target_pos.set_target_volume(-1)

except BacktestFinished:
    print(acc.trade_log)    # 交易明细
    print(acc.tqsdk_stat)   # 统计指标
    # tqsdk_stat 包含: init_balance, balance, max_drawdown,
    #   winning_rate, ror, annual_yield, sharpe_ratio 等
    api.close()

Backtesting rules:

Matching rules: transactions are executed at the counterparty price, and partial fills will not occur
Perform fill determination immediately after order submission
Supports Tick-level and K-line-level backtesting
Supports stock backtesting (requires using TqSimStock）
Continuous contracts cannot be traded directly; use quote.underlying_symbol to obtain the underlying

Technical Indicators

Built-in indicators (tqsdk.ta)

from tqsdk.ta import MA, MACD, RSI, BOLL, ATR, KDJ

klines = api.get_kline_serial("SHFE.rb2401", 60*60*24)

# 均线
ma = MA(klines, 20)          # ma.ma 列

# MACD
macd = MACD(klines, 12, 26, 9)  # macd.diff, macd.dea, macd.bar

# 布林带
boll = BOLL(klines, 20, 2)  # boll.mid, boll.top, boll.bottom

# RSI
rsi = RSI(klines, 14)       # rsi.rsi

# KDJ
kdj = KDJ(klines, 9, 3, 3)  # kdj.k, kdj.d, kdj.j

# ATR
atr = ATR(klines, 14)       # atr.atr

Sequence calculation functions (tqsdk.tafunc)

from tqsdk import tafunc

ema = tafunc.ema(klines.close, 20)
std = tafunc.std(klines.close, 20)
highest = tafunc.highest(klines.high, 20)
lowest = tafunc.lowest(klines.low, 20)

Algorithmic Trading

TWAP algorithm

from tqsdk import TqApi
from tqsdk.algorithm import Twap

api = TqApi(auth="快期账户,用户密码")
target_twap = Twap(api, "SHFE.rb2401", "BUY", "OPEN",
                   volume=500, duration=300,
                   min_volume_each_order=10,
                   max_volume_each_order=25)
while True:
    api.wait_update()
    if target_twap.is_finished():
        break
api.close()

VWAP + TargetPosScheduler

from tqsdk import TqApi, TargetPosScheduler
from tqsdk.algorithm import vwap_table

api = TqApi(auth="快期账户,用户密码")
time_table = vwap_table(api, "CZCE.MA401", target_pos=-100, duration=600)
scheduler = TargetPosScheduler(api, "CZCE.MA401", time_table)

while not scheduler.is_finished():
    api.wait_update()
api.close()

Graphical Interface (Web GUI)

from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("快期账户", "账户密码"), web_gui=True)
# 或指定端口
api = TqApi(auth=TqAuth("快期账户", "账户密码"), web_gui=":9876")

After startup, access the displayed address in a browser to view K-line charts, positions, orders, and other information.

Advanced Features

Running Multiple Strategies

Each strategy is an independent process, and multiple strategies can run simultaneously without affecting each other:

# strategy_a.py - 策略A
api = TqApi(TqAccount("期货公司", "账号", "密码"), auth=TqAuth("快期账户", "密码"))
# ...策略逻辑...

# strategy_b.py - 策略B（独立文件，独立运行）
api = TqApi(TqAccount("期货公司", "账号", "密码"), auth=TqAuth("快期账户", "密码"))
# ...策略逻辑...

Unattended operation

import logging
from contextlib import closing

logging.basicConfig(filename='strategy.log', level=logging.INFO)

with closing(TqApi(TqAccount("期货公司", "账号", "密码"),
                   auth=TqAuth("快期账户", "密码"))) as api:
    # 策略代码...
    pass

DingTalk message push

import requests
from json import dumps

def send_msg(content):
    webhook = "你的钉钉webhook地址"
    msg = {"msgtype": "text", "text": {"content": f"天勤量化\n{content}"}}
    requests.post(webhook, data=dumps(msg),
                  headers={"content-type": "application/json;charset=utf-8"})

Custom fees/margin for simulated trading

sim = TqSim()
api = TqApi(sim, auth=TqAuth("快期账户", "账户密码"))
sim.set_commission("SHFE.cu2401", 50)    # 设置每手手续费
sim.set_margin("SHFE.cu2401", 26000)     # 设置每手保证金

Common Strategy Patterns

Arbitrage strategy (spread trading)

q_near = api.get_quote("SHFE.rb2401")
q_far = api.get_quote("SHFE.rb2405")
t_near = TargetPosTask(api, "SHFE.rb2401")
t_far = TargetPosTask(api, "SHFE.rb2405")

while True:
    api.wait_update()
    spread = q_near.last_price - q_far.last_price
    if spread > 250:
        t_near.set_target_volume(-1)  # 空近月
        t_far.set_target_volume(1)    # 多远月
    elif spread < 200:
        t_near.set_target_volume(0)
        t_far.set_target_volume(0)

Moving average strategy

klines = api.get_kline_serial("SHFE.rb2401", 60*15, data_length=200)
target_pos = TargetPosTask(api, "SHFE.rb2401")

while True:
    api.wait_update()
    if api.is_changing(klines.iloc[-1], "datetime"):
        ma5 = klines.close.iloc[-6:-1].mean()
        ma20 = klines.close.iloc[-21:-1].mean()
        if ma5 > ma20:
            target_pos.set_target_volume(1)
        else:
            target_pos.set_target_volume(-1)

Core API Quick Reference

Function	Description
`TqApi(account, auth, backtest, web_gui)`	Create API instance
`api.get_quote(symbol)`	Get real-time quotes
`api.get_kline_serial(symbol, duration, data_length)`	Get K-line series
`api.get_tick_serial(symbol, data_length)`	Get Tick series
`api.insert_order(symbol, direction, offset, volume, limit_price)`	Place order
`api.cancel_order(order)`	Cancel order
`api.get_account()`	Get account funds
`api.get_position(symbol)`	Get positions
`api.get_order(order_id)`	Get orders
`api.get_trade(trade_id)`	Get trade records
`api.wait_update(deadline)`	Wait for data update
`api.is_changing(obj, key)`	Determine whether the object is updated
`api.close()`	Close connection
`TargetPosTask(api, symbol, price)`	Create target position task
`target_pos.set_target_volume(volume)`	Set target position

Reference files

This skill includes the following detailed reference documents (located in the references/ directory):

Getting started

getting_started.md - TqSdk introduction, installation, ten-minute quick start

Usage tutorial

usage_1_strategy_program_backtesting.md - Strategy backtesting, contract quotes, historical data, overall TqSdk structure
usage_2_what_are_the_differences_between_tqsdk_and_vnpy.md - Comparison with vn.py/CTP, trading assistance tools
usage_3_batch_backtesting_parameter_search_and_more.md - Batch backtesting, strategy program structure, TqBacktest
usage_4_efficiently_learning_and_using_tqsdk_in_trae.md - Trae integration, accounts and trading, basic options usage
usage_5_efficiently_learning_and_using_tqsdk_in_cursor_p1/p2.md - Cursor integration, Kuaiqi account, multi-strategy manual
usage_6_strategy_program_graphical_interface.md - Web GUI interface

API reference

api_ref_1_*.md - Algorithm module (TWAP), TargetPosTask advanced features, unattended operation
api_ref_2_*.md - TqSim simulated trading, TqMultiAccount multiple accounts, emergency stop solution
api_ref_3_*.md - tafunc sequence calculation functions
api_ref_4_*.md - Business objects (objs), TqRohon, TqJees
api_ref_5_*.md - Trading strategy examples
api_ref_6_*.md - TqSdk Professional Edition
api_ref_7_*.md - ta technical indicator calculation functions
api_ref_8_*.md - TqCtp direct CTP connection, TqZq, TqYida
api_ref_9_*.md - TqApi framework and core business (complete API documentation)
api_ref_10_*.md - Version change log
api_ref_11_*.md - Time-dimension target positions, GUI library collaboration
api_ref_12_*.md - lib business utility library, DataDownloader, advanced orders
api_ref_13_*.md - risk_rule risk control module, TqKq, algorithm module examples
api_ref_14_*.md - EDB data service + Coze natural language investment research

Strategy examples (about 50 complete strategies, from shinnytech.com)

Trend strategies (15):

strategies_trend_a_p1~p4.md - TRIX, fractal trend, CMO momentum, vortex indicator, Hull moving average, Keltner channel, Qstick, Aroon
strategies_trend_b_p1.md - Momentum ranking, volume-price trend (VPT)
strategies_trend_b_p2.md - Aberration Bollinger Bands, Four Price of Fiali, escalator
strategies_trend_b_p3.md - Dual Thrust、R-Breaker

Arbitrage strategies (15):

strategies_arbitrage_p1~p5.md - Hot-rolled coil-stainless steel, glass-soda ash, white sugar-starch, PTA industry chain, live pig feed, coking coal-coke, MTO methanol-to-olefins, copper-aluminum price ratio, soybean crushing, crack spread, stock index calendar spread, Box options, multi-tenor arbitrage, steel mill profit, multi-oil arbitrage

Mean Reversion and Other Strategies (15):

strategies_other_p1~p5.md - Kalman Filter Pairs, Distance Method Pairs, Pivot Point, CCI, RSI Overbought/Oversold, Z-Score, Mean Reversion, Iceberg Order, Order Book Algorithm, POV Volume Ratio, Random Forest Prediction, ATR Volatility, Turtle Trading, VWAP Algorithm, Grid Trading

For detailed information, please refer to the corresponding reference files.

Resource Links

Official Documentation:https://doc.shinnytech.com/tqsdk/latest/
Kuaqi Account Registration: Kuaqi Official Website
User Forum: Tianqin User Forum
License: Apache License 2.0