十分钟快速入门

推荐：先把 TqSdk Skills 交给 AI

复制下面的提示词给你的 AI 编码工具，再写下想完成的任务。AI 会先读取使用规则，按需检查环境、安装 TqSdk，再帮你写代码或排错。

请先下载并解压 TqSdk 官方技能包：
https://doc.shinnytech.com/tqsdk/latest/ai_editor/skills/tqsdk-trading-and-data.zip
先阅读其中的 SKILL.md，再按任务读取 references/ 中的说明。
如果需要在本地运行代码，请先检查项目的 Python 环境和 TqSdk；未安装时按项目依赖要求安装到该环境，验证能导入后再继续，不要自动升级已有版本。

如果 AI 无法下载，请手动下载完整技能包并解压后交给它。只有对话能力的 AI 可以提供代码和安装步骤；实际安装需要有本地执行能力的工具。

推荐的 AI Agent 工具：

详细说明请见 TqSdk Skills 压缩包与使用说明 。

希望快速开始使用天勤量化（TqSdk）？本页按“安装 → 登录 → 行情 → K 线 → 下单 → 回测”的顺序，带你跑通第一套程序。

如果已经熟悉其他量化框架，可以先对照 TqSdk与使用Ctp接口开发策略程序有哪些差别 或 TqSdk 与 vn.py 有哪些差别，再回到本页上手。想先了解开发包的整体能力，可以阅读 TqSdk 介绍。

备注

前面的示例默认使用 TqSim 本地模拟账户。快期账户用于登录服务，期货资金账户用于实盘交易，两者请分别填写。实盘接入放在本页最后介绍。

1. 安装 TqSdk

先在电脑上安装 Python 3.9 或更高版本，Windows、macOS 和 Linux 均可使用。

打开命令行窗口（Windows 可使用“命令提示符”或 PowerShell），输入下面的命令，按回车安装 TqSdk：

pip install tqsdk

如果下载较慢，可以改用下面的国内镜像命令安装：

pip install tqsdk -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，继续下面的步骤，准备快期账户并运行第一个行情程序。安装遇到问题时，可查看 常见问题与支持。

2. 准备快期账户

在 快期账户中心 注册账户。TqAuth 接收快期账户的手机号、用户名或邮箱，以及对应密码，详细说明见 快期账户。

将后面的 "快期账户" 和 "账户密码" 替换为你的登录信息。文件不要命名为 tqsdk.py，以免遮蔽已安装的开发包。

3. 打印一次行情

把下面代码保存为 hello_tqsdk.py，然后运行 python hello_tqsdk.py：

hello_tqsdk.py · 打印螺纹钢合约行情
from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("快期账户", "账户密码"))
quote = api.get_quote("SHFE.rb2701")
print(quote)
api.close()

运行后，终端会打印一次行情内容，然后程序结束。SHFE.rb2701 表示上期所螺纹钢 2027 年 1 月合约；如果运行时该合约已到期，请换成仍在交易的合约代码。

这几行代码依次完成：导入开发包、登录服务、获取行情、打印行情、关闭连接。quote 中包含行情时间、最新价、买卖价等字段，例如 quote.last_price 就是最新价。

接下来：让行情持续更新

如果想持续查看行情，把 hello_tqsdk.py 改成下面这样，再次运行：

hello_tqsdk.py · 持续打印行情时间和最新价
from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("快期账户", "账户密码"))
quote = api.get_quote("SHFE.rb2701")

while True:
    api.wait_update()
    print(quote.datetime, quote.last_price)

while True 让程序反复执行循环中的两行代码：

  1. api.wait_update() 等待业务数据更新，收到数据后更新 quote 等对象，再继续往下执行。

  2. print(...) 读取并打印此时的行情时间和最新价，然后回到下一轮等待。

quote 是会更新的行情引用，因此 get_quote() 只需在循环外调用一次。持续调用 wait_update()，才能接收后续数据；只反复执行 print() 不会刷新行情。

你会看到什么： 收到业务数据更新后，终端打印行情时间和最新价。非交易时段可能暂时没有新输出；这不一定是程序出错。按 Ctrl+C 停止这个持续运行的示例。退出时释放连接的完整写法见 策略程序结构。

小技巧

wait_update() 也会发送请求、推进后台任务。它返回并不意味着每个订阅都更新了，所以打印的最新价可能与上次相同。只想在这份行情变化时处理，可以用 api.is_changing(quote) 判断。完整机制见 策略程序结构。

4. 读取 K 线

get_kline_serial() 返回持续更新的 pandas.DataFrame。沿用上面的固定合约，下面单独运行一个简单程序，请求它的 10 秒 K 线：

from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("快期账户", "账户密码"))
klines = api.get_kline_serial("SHFE.rb2701", 10)

while True:
    api.wait_update()
    print("最后一根 K 线的收盘价：", klines.close.iloc[-1])

iloc[-1] 表示最后一根 K 线，其收盘价在形成过程中仍会变化。需要上一根已完成 K 线时，使用 iloc[-2]。更多用法见 t30 - 使用K线/Tick数据 与 技术指标与序列计算函数。

5. 用目标持仓运行模拟策略

先用 TargetPosTask 表达“希望持有多少手”，由它管理下单和撤单。下面程序在启动时选择螺纹钢当前主力合约：上一根收盘价高于最近 15 根已完成 K 线的均价时，目标为多头 1 手；否则目标为空仓。

这里开始使用 KQ.m@SHFE.rb，它是螺纹钢的主连代码，用来查看当前主力合约行情。主连本身不能下单，所以先通过 quote.underlying_symbol 取得对应的实际合约，再用于 K 线订阅和模拟交易。合约代码详见 合约, 行情和历史数据。

ma_sim.py · 在本地模拟账户运行
from tqsdk import TqApi, TqAuth, TargetPosTask
from tqsdk.tafunc import ma

api = TqApi(auth=TqAuth("快期账户", "账户密码"))
quote = api.get_quote("KQ.m@SHFE.rb")
symbol = quote.underlying_symbol  # 主力对应的实际合约
klines = api.get_kline_serial(symbol, 60)
target = TargetPosTask(api, symbol)

while True:
    api.wait_update()
    if api.is_changing(klines.iloc[-1], "datetime"):  # 新 K 线开始
        ma15 = ma(klines.close, 15)  # 15 周期均线
        if klines.close.iloc[-2] > ma15.iloc[-2]:  # 用上一根已完成 K 线判断
            target.set_target_volume(1)  # 目标：多头 1 手
        else:
            target.set_target_volume(0)  # 目标：空仓

这里的 1 是最终目标持仓，不是每次再买 1 手。 条件持续满足时，反复设置同一个目标不会把目标累加。调用后仍需继续 wait_update()，调仓任务才会运行。

ma() 直接计算均线，15 表示每次用连续 15 根 K 线的收盘价求平均。iloc[-2] 取倒数第 2 项，也就是上一根已完成 K 线；收盘价和均线都取这个位置，就不会把最后一根尚未完成的 K 线用于判断。

此教学示例只在启动时选择一次合约，不处理跨交易日换月。它用于说明程序结构，策略效果需要另行评估。目标持仓详见 交易辅助工具，跨品种示例见 t80 - 价差回归策略。

6. 了解账户、下单与撤单

下面用几个短片段介绍账户和委托接口。请单独创建一个本地模拟会话，不要把这些片段加到前面的目标持仓程序中：

from tqsdk import TqApi, TqAuth

api = TqApi(auth=TqAuth("快期账户", "账户密码"))
symbol = api.get_quote("KQ.m@SHFE.rb").underlying_symbol

通过 get_account() 和 get_position() 获取 account 和 position 引用，并读取字段：

account = api.get_account()
position = api.get_position(symbol)
print("可用资金：", account.available, "净持仓：", position.pos)

使用 insert_order() 发送一笔限价委托，得到 order 引用，并在循环中查看状态：

order = api.insert_order(symbol, "BUY", "OPEN", volume=1, limit_price=3000)
while order.status == "ALIVE":
    api.wait_update()
    print("委托状态：", order.status, "未成交手数：", order.volume_left)

这里的 3000 只是演示价格，不保证成交；委托没有成交时，上面的循环会持续等待。需要演示 cancel_order() 撤单时，可以在 insert_order() 之后使用下面的片段，替换上面的等待循环：

api.cancel_order(order)
while order.status == "ALIVE":
    api.wait_update()
print("委托结束：", order.last_msg)

下单和撤单后都需要继续调用 wait_update() 接收结果。完成这个短任务后调用 api.close()；需要限制等待时间时，参考 常见问题与支持 中的超时示例。

备注

insert_order() 返回的是委托引用，不是成交确认。FINISHED 表示委托结束，也可能是撤单或拒单；用 volume_orign - volume_left 了解已成交数量，用 last_msg 查看提示。不要同时对同一合约使用手动下单和目标持仓任务，避免相互干扰。

更完整的委托生命周期见 账户与交易、t40 - 下单/撤单。

7. 把策略放进历史回测

回测沿用前面的程序结构，只需要在创建 API 时传入 TqBacktest。下面先用一个简单例子观察历史 K 线如何更新：

kline_backtest.py · 查看历史 K 线
from datetime import date
from tqsdk import TqApi, TqAuth, TqBacktest, BacktestFinished

api = TqApi(
    backtest=TqBacktest(start_dt=date(2025, 3, 3), end_dt=date(2025, 3, 7)),
    auth=TqAuth("快期账户", "账户密码"),
)
klines = api.get_kline_serial("SHFE.rb2505", 60)
try:
    while True:
        api.wait_update()
        print("历史 K 线收盘价：", klines.close.iloc[-1])
except BacktestFinished:
    print("回测结束")
api.close()

BacktestFinished 表示历史数据回放结束，示例用 try / except 接住这个结束通知，再关闭 API。合约的存续期需要覆盖回测区间，因此示例合约和历史日期应一起调整。

回测仍需登录服务并获取历史数据，具体数据权限以账户为准。需要回测自己的交易逻辑时，把行情示例中的处理部分换成策略；完整说明与图形化报告见 策略程序回测、策略程序图形化界面。

选择适合的模拟账户

账户类型

记录保存在哪里

适合什么场景

TqSim()

当前程序内；默认不跨进程保存

入门、临时模拟、历史回测

TqKq()

快期模拟服务；可在快期客户端查看

希望持续跟踪模拟账户

TqAccount(...)

期货公司的实盘资金账户

完成验证后的实盘接入

使用快期模拟账户：

from tqsdk import TqApi, TqAuth, TqKq

api = TqApi(TqKq(), auth=TqAuth("快期账户", "账户密码"))
# 订阅数据，并持续调用 api.wait_update()。
# 程序退出时调用 api.close()。

如果省略账户参数，TqApi 默认使用 TqSim。这类模拟记录不会出现在快期 APP 等客户端。详情见 快期账户。

了解实盘接入

实盘需要显式传入 TqAccount。下方仅展示配置，填写的是期货公司提供的资金账号与交易密码：

from tqsdk import TqApi, TqAuth, TqAccount

api = TqApi(
    TqAccount("期货公司名称", "期货资金账号", "期货交易密码"),
    auth=TqAuth("快期账户", "快期账户密码"),
)

期货公司名称、接入要求与权限说明见 账户与交易、TqSdk 专业版。支持情况可在 期货公司列表 查询。

下一步