TqSdk: a Python futures trading SDK with a diff-based market data feed

What TqSdk actually solves for a futures trader

Writing a futures strategy usually means stitching together a market data feed, a broker API, a historical database and a backtest harness. Each of those has its own authentication, its own reconnect logic and its own data format. TqSdk collapses that into one Python package: the README describes a solution covering historical data, live data, debugging, backtesting, simulated trading, live trading, monitoring and risk management. The audience is narrow and specific. This is a library for people trading Chinese futures, options and stocks, and the README states support for live trading at most of the futures companies in that market. If you trade CME contracts or crypto, nothing here applies to you.

The design decision that shapes everything else is that the user does not run a database. The README says quotes and trading data live in an in-memory database with no access latency, and that all contracts' tick and K-line history is served from the provider side. That removes a large piece of operational work, and it also means your data access is only as good as the connection to TianQin's gateways.

The diff protocol and the two gateways behind every call

The architecture diagram in the repository shows two server-side components. A market data gateway supplies live quotes and history. A trading relay gateway connects to the futures company's trading system. Both speak a single protocol to the client, which the README calls the diff protocol, and TqSdk is a client of that protocol.

That explains the shape of the API. You do not poll for prices. You subscribe with get_quote, then call api.wait_update() in a loop, and the library tells you what changed. The README's example computes a spread between two rebar contracts and prints it on every update. The same pattern covers orders and positions: a wait_update call can signal a quote change, an order change or an account change, and the code inspects what moved. This is a push model with a local cache, which is why the README can claim no access latency on reads. The trade-off is that the correctness of your loop depends on wait_update being called often enough, and a long blocking operation inside the loop delays every subsequent update.

Installing TqSdk and running a first spread strategy

TqSdk requires Python 3.9 or higher. The README gives a single install command:

pip install tqsdk

The package pulls in websockets, requests, numpy, pandas, scipy, aiohttp and several smaller dependencies listed in setup.py, so expect a normal scientific Python install footprint. There is no separate server to start and no database to create.

The README's quick start is a rebar calendar spread. It needs a trading account and a TianQin account, both passed at construction time:

from tqsdk import TqApi, TqAuth, TqAccount, TargetPosTask

api = TqApi(TqAccount("H海通期货", "4003242", "123456"), auth=TqAuth("快期账户", "账户密码"))
q_2610 = api.get_quote("SHFE.rb2610")
t_2610 = TargetPosTask(api, "SHFE.rb2610")
q_2701 = api.get_quote("SHFE.rb2701")
t_2701 = TargetPosTask(api, "SHFE.rb2701")

The two get_quote calls subscribe to the near and far month contracts on the Shanghai Futures Exchange. TargetPosTask is the piece worth understanding: instead of sending an order, you declare the position you want, and the task works toward it. The loop in the README then reads last_price from each quote and calls set_target_volume(1), set_target_volume(-1) or set_target_volume(0) when the spread crosses 250 or falls below 200. What you should see is a printed spread line on each update, and, once a threshold is crossed, the task adjusting the account until the requested volumes are held. If you only want to read data, the same script works with a TqAuth and no TqAccount.

Where TqSdk stops being the right tool

The dependency on TianQin's gateways is the main boundary. The README states that the market data gateway provides real-time and historical data and that the trading relay gateway connects to the futures company. Neither is something you host. If you need a system that keeps running with no external service in the path, TqSdk is the wrong choice, and the README offers no self-hosted alternative.

Execution semantics are the second limitation, and it is subtler. TargetPosTask is convenient, but declaring a target position hides the order sequence used to reach it. For a strategy where the exact order type, price and timing matter, the abstraction works against you, and you would place orders directly. The README does not document rollback behaviour for a partially filled target, so a position that is half-established when the process dies is a case you have to reason about yourself.

The third constraint is platform support in the literal sense. The README lists support for trading at most futures companies, not all of them. Before building anything, confirm your broker is covered.

TqSdk against vn.py and other Python trading stacks

vn.py is the comparison people search for, and the two take opposite approaches to the same problem. vn.py is a framework: you assemble an application from gateways, engines and apps, and you own the deployment, the database and the broker connections. TqSdk is a library with a hosted backend: you import it, authenticate, and the data and trading paths are already wired. The practical difference shows up on day one. A vn.py setup asks you to choose and configure a gateway and a data source before your first quote. TqSdk asks for a TianQin account and a broker account in the constructor. The cost appears later, when you want a broker or an asset class outside the covered set, or when you want to run without the vendor in the loop.

The same axis separates TqSdk from research-oriented projects such as QUANTAXIS, Hikyuu and QuantDigger. Those centre on data storage, backtesting and analysis, and leave live execution to you. TqSdk treats backtest, simulation and live trading as three modes of one API, which is its main advantage and the reason its API surface is tied to a single provider.

Releases, licence and the cost of staying current

The repository is not archived, and the last push was on 2026-08-18. Releases are frequent: 3.9.9 on 2026-05-19, 3.10.1 on 2026-06-11 and 3.10.2 on 2026-08-18. A cadence of roughly one release every month or two means the upgrade cost is real but bounded, and the version number in setup.py is the one you get from pip.

The dependency list is where upgrades can bite. setup.py pins websockets>=10.1 while requirements.txt still lists websockets>=8.1, and it requires pandas>=1.1.0, numpy, scipy, aiohttp, pyjwt and psutil>=5.9.6, plus tqsdk_ctpse and tqsdk_sm. A major pandas or numpy release can break a strategy that relied on older behaviour, so pinning your own environment is the safer habit when you move from a backtest to live trading.

The licence is Apache-2.0, as stated in the LICENSE file and in the setup.py classifier. That permits commercial use and modification with the usual attribution and notice requirements. It says nothing about the TianQin service itself: the library is open source, the gateways and the data feed are a commercial service, and your account terms are a separate matter. This is not legal advice.

Editorial conclusion

TqSdk fits Python developers who already trade Chinese futures through a supported broker and want live quotes, backtesting and order placement in one process. It does not fit anyone trading outside the covered markets, anyone who wants a fully self-hosted stack with no vendor account, or anyone unwilling to depend on the TianQin gateways. Before writing a strategy, verify three things: that your broker is among the supported ones, that your Python is 3.9 or newer, and that your account credentials work with TqAuth, since every example in the README passes a TqAuth object.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. shinnytech/tqsdk-python on GitHub