TqSdk Quickstart: Market Data, Orders, Target Positions, and Backtests

# quickstart


.. _quickstart:

十分钟快速入门
=================================================

.. include:: _includes/tqsdk_ai_agent_intro.rst

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

如果你已经熟悉其它量化框架，可以按需对照这些迁移文档，再回到本页上手：

* :ref:`intro`
* :ref:`for_ctp_user`
* :ref:`for_vnpy_user`

如果你正在使用带 AI 能力的开发工具，也可以结合 :ref:`tqsdk_trae` 、:ref:`tqsdk_codebuddy` 、:ref:`tqsdk_codex` 、VSCode 等提升排错和写示例的效率，更多内容请见 :ref:`ai_editor` 。



.. _tqsdk_install:

安装
-------------------------------------------------
天勤量化的核心是TqSdk开发包, 在安装天勤量化 (TqSdk) 前, 你需要先准备适当的环境和Python包管理工具, 包括:

* Python >= 3.9 版本
* Windows 7 以上版本, macOS, 或 Linux


你可以选择使用 `pip` 命令安装 TqSdk, 或者下载源代码安装. 对于一般用户, 我们推荐采用 `pip` 命令安装/升级 TqSdk::

    pip install tqsdk -U

但是由于 `pip` 使用的是国外的服务器，普通用户往往下载速度过慢或不稳定，对于使用 `pip` 命令下载速度较慢的用户，我们推荐采用切换国内源的方式安装/升级 TqSdk::

    pip install tqsdk -U -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host=pypi.tuna.tsinghua.edu.cn

.. _quickstart_0:

注册快期账户
-------------------------------------------------
在使用 TqSdk 之前，需要先准备自己的 **快期账户**。快期账户是运行任何 TqSdk 程序的前提，点击 `注册快期账户 <https://account.shinnytech.com/>`_

快期账户可以使用注册时的手机号、用户名或邮箱登录，详细介绍请见 :ref:`shinny_account`

在注册完快期账户后，建议先只跑通下面这个最小示例，确认安装、账户和行情连接都已经打通::

    from tqsdk import TqApi, TqAuth

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

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

如果这段脚本可以稳定打印时间和最新价，就说明你已经具备继续阅读后续章节的基础。下面我们把这段脚本拆开讲清楚。

.. _quickstart_1:

获取实时行情数据
-------------------------------------------------
通过 TqSdk 获取实时行情数据是很容易的.

首先, 必须引入 tqsdk 模块::

    from tqsdk import TqApi, TqAuth

创建API实例，并填入自己的快期账户::

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

获得上期所 ni2607 合约的行情引用::

    quote = api.get_quote("SHFE.ni2607")

现在, 我们获得了一个对象 quote. 这个对象总是指向 SHFE.ni2607 合约的最新行情. 我们可以通过 quote 的各个字段访问行情数据::

    print (quote.last_price, quote.volume)


要等待行情数据更新, 我们还需要一些代码::

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

:py:meth:`~tqsdk.TqApi.wait_update` 是一个阻塞函数, 程序在这行上等待, 直到收到数据包才返回.

上面这个例子的完整程序请见 :ref:`tutorial-t10` . 你也可以在自己电脑 Python 安装目录的 site-packages/tqsdk/demo 下找到它

很简单, 对吗? 到这里, 你已经了解用 TqSdk 开发程序的几个关键点:

* 创建 TqApi 实例
* 用 api.get_quote() 或 其它函数获取数据引用对象
* 在循环中用 api.wait_update() 等待数据包.
* 收到数据包以后通过引用对象获得所需数据

下面我们将继续介绍 TqSdk 更多的功能. 无论使用哪个功能函数, 都遵循上面的结构.


.. _quickstart_2:

使用K线数据
-------------------------------------------------
你很可能会需要合约的K线数据. 在TqSdk中, 你可以很方便的获得K线数据. 我们来请求 ni2607 合约的10秒线::

    klines = api.get_kline_serial("SHFE.ni2607", 10)

klines是一个pandas.DataFrame对象. 跟 api.get_quote() 一样, api.get_kline_serial() 也是返回K线序列的引用对象. K线序列数据也会跟实时行情一起同步自动更新. 你也同样需要用 api.wait_update() 等待数据刷新.

一旦k线数据收到, 你可以通过 klines 访问 k线数据::

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

这部分的完整示例程序请见 :ref:`tutorial-t30` .

到这里为止, 你已经知道了如何获取实时行情和K线数据, 下面一段将介绍如何访问你的交易账户并发送交易指令


.. _quickstart_3:

交易账户, 下单/撤单
-------------------------------------------------
要获得你的账户资金情况, 可以请求一个资金账户引用对象::

    account = api.get_account()

要获得你交易账户中某个合约的持仓情况, 可以请求一个持仓引用对象::

    position = api.get_position("DCE.m2609")

与行情数据一样, 它们也通过 api.wait_update() 获得更新, 你也同样可以访问它们的成员变量::

    print("可用资金: %.2f" % (account.available))
    print("今多头: %d 手" % (position.volume_long_today))

要在交易账户中发出一个委托单, 使用 api.insert_order() 函数::

    order = api.insert_order(symbol="DCE.m2609", direction="BUY", offset="OPEN", volume=5, limit_price=3000)

这个函数调用后会立即返回, order 是一个指向此委托单的引用对象, 你总是可以通过它的成员变量来了解委托单的最新状态::

    print("委托单状态: %s, 已成交: %d 手" % (order.status, order.volume_orign - order.volume_left))

需要特别注意的是, ``insert_order()`` 只是把下单请求加入待发送队列, 实际报单会在下一次 :py:meth:`~tqsdk.TqApi.wait_update` 时发出。因此下单后请继续驱动主循环, 不要立刻退出程序。

要撤销一个委托单, 使用 api.cancel_order() 函数::

    api.cancel_order(order)

这部分的完整示例程序请见 :ref:`tutorial-t40` .

到这里为止, 我们已经掌握了 TqSdk 中行情和交易相关功能的基本使用. 我们将在下一节中, 组合使用它们, 创建一个自动交易程序



.. _quickstart_4:

构建一个自动交易程序
-------------------------------------------------
在这一节中, 我们将创建一个简单的自动交易程序: 每当行情最新价高于最近15分钟均价时, 开仓买进. 这个程序是这样的::

    klines = api.get_kline_serial("DCE.m2609", 60)
    while True:
        api.wait_update()
        if api.is_changing(klines):
            ma = sum(klines.close.iloc[-15:])/15
            print("最新价", klines.close.iloc[-1], "MA", ma)
            if klines.close.iloc[-1] > ma:
                print("最新价大于MA: 市价开仓")
                api.insert_order(symbol="DCE.m2609", direction="BUY", offset="OPEN", volume=5)

上面的代码中出现了一个新函数 api.is_changing(). 这个函数用于判定指定对象是否在最近一次 wait_update 中被更新.

这部分的完整示例程序请见 :ref:`tutorial-t60` .


.. _quickstart_5:

按照目标持仓自动交易
-------------------------------------------------
在某些场景中, 我们可能会发现, 自己写代码管理下单撤单是一件很麻烦的事情. 在这种情况下, 你可以使用 :py:class:`tqsdk.TargetPosTask`. 你只需要指定账户中预期应有的持仓手数, TqSdk 会自动通过一系列指令调整仓位直到达成目标. 请看例子::

    from tqsdk import TqApi, TqAuth, TargetPosTask

    api = TqApi(auth=TqAuth("快期账户", "账户密码"))
    quote_near = api.get_quote("SHFE.ni2607")
    quote_deferred = api.get_quote("SHFE.ni2608")


    # 创建 ni2607 的目标持仓 task，该 task 负责调整 ni2607 的仓位到指定的目标仓位
    target_pos_near = TargetPosTask(api, "SHFE.ni2607")
    # 创建 ni2608 的目标持仓 task，该 task 负责调整 ni2608 的仓位到指定的目标仓位
    target_pos_deferred = TargetPosTask(api, "SHFE.ni2608")

    while True:
        api.wait_update()
        if api.is_changing(quote_near) or api.is_changing(quote_deferred):
            spread = quote_near.last_price - quote_deferred.last_price
            print("当前价差:", spread)
            if spread > 200:
                print("目标持仓: 空近月，多远月")
                # 设置目标持仓为正数表示多头，负数表示空头，0表示空仓
                target_pos_near.set_target_volume(-1)
                target_pos_deferred.set_target_volume(1)
            elif spread < 150:
                print("目标持仓: 空仓")
                target_pos_near.set_target_volume(0)
                target_pos_deferred.set_target_volume(0)


这部分的完整示例程序请见 :ref:`tutorial-t80` .


.. _quickstart_backtest:

策略回测
-------------------------------------------------
自己的交易程序写好以后, 我们总是希望在实盘运行前, 能先进行一下模拟测试. 要进行模拟测试, 只需要在创建TqApi实例时, 传入一个backtest参数::

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

    api = TqApi(backtest=TqBacktest(start_dt=date(2018, 5, 1), end_dt=date(2018, 10, 1)), auth=TqAuth("快期账户", "账户密码"))

这样, 程序运行时就会按照 TqBacktest 指定的时间范围进行模拟交易测试, 并输出测试结果.

此外 TqSdk 同时还支持股票的回测交易，请见 :ref:`security_backtest`

更多关于策略程序回测的详细信息, 请见 :ref:`backtest`


.. _real_trading:

实盘交易
-------------------------------------------------
要让策略程序在实盘账号运行, 请在创建TqApi时传入一个 :py:class:`~tqsdk.TqAccount` , 填入 期货公司, 账号, 密码 和快期账户信息(使用前请先 import TqAccount)::

    from tqsdk import TqApi, TqAuth, TqAccount

    # 如果要更换为徽商期货，只需要改为 H徽商期货
    api = TqApi(TqAccount("H宏源期货", "412432343", "123456"), auth=TqAuth("快期账户", "账户密码"))

更多关于实盘交易细节，请点击 :ref:`trade`

其中实盘交易是属于 TqSdk 的专业版功能，用户需要购买 TqSdk 专业版才可以进行实盘交易， `点击申请试用或者购买 <https://account.shinnytech.com/>`_

与此同时，TqSdk 支持在部分期货公司开户后进行免费的实盘交易，详细介绍请点击查看 `TqSdk支持的期货公司列表 <https://www.shinnytech.com/blog/tq-support-broker/>`_


.. _sim_trading:

模拟交易和论坛
-------------------------------------------------
如果您需要使用能保存账户资金及持仓信息的模拟交易功能，通过 :py:class:`~tqsdk.TqKq` 对 auth 传入参数进行登录，可以得到一个长期有效的快期模拟账户。快期模拟账户在快期 APP、快期专业版、快期 v2、快期 v3 和天勤量化上是互通的，程序中使用 :py:class:`~tqsdk.TqKq` 产生的模拟持仓、委托和成交记录也可以在这些客户端中查看。

快期模拟的资金可以通过快期 APP、快期专业版的模拟银行进行出入金，也可以通过快期专业版对该账户进行重置::

  from tqsdk import TqApi, TqAuth, TqKq

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



特别地，如果创建 TqApi 实例时没有显式提供账户实例，则会自动创建一个临时模拟账号。这个临时账号是 TqSdk 本地程序内的 :py:class:`~tqsdk.TqSim`，它的持仓、委托和成交记录不会显示在快期 APP、快期专业版、快期 v2 或快期 v3 中；当程序运行结束时，临时账号内的记录会全部丢失::

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



TqSdk 学习视频
-------------------------------------------------
TqSdk 提供简单易懂的十分钟上手视频 `供用户学习 <https://www.shinnytech.com/tqsdkquickstart/>`_


更多内容
-------------------------------------------------
* 要完整了解TqSdk的使用, 请阅读 :ref:`usage`
* 更多TqSdk的示例, 请见 :ref:`demo_strategy`