tqsdk-python 用户认证指南：深入理解 TqAuth 快期账户登录、权限体系与工程实践-平芜编程栈

金融科技

【免费下载链接】tqsdk-python

天勤量化开发包, 期货量化, 实时行情/历史数据/实盘交易

项目地址：https://gitcode.com/gh_mirrors/tq/tqsdk-python

本指南以 tqsdk-python 官方 API 参考文档 doc/reference/tqsdk.auth.rst 为主线，系统讲解用户认证类TqAuth的构造方式、在TqApi中的使用场景、expire_datetime到期时间查询接口，以及底层 OAuth2/JWT 登录、功能授权（grant）检查与期货公司/行情网关寻址的完整实现原理，帮助你写出认证正确、权限边界清晰、可直接实盘/回测运行的天勤量化程序。

一、为什么需要 TqAuth：快期账户是 TqSdk 一切功能的入口

在 tqsdk-python 中，快期账户（Shinny 账户）是使用任何 TqSdk 程序的前提。官方文档在 doc/usage/shinny_account.rst 中明确指出：“传入快期账户是使用任何 TqSdk 程序的前提”。这意味着：

获取实时行情、历史数据、K 线序列，需要快期账户的行情权限；
使用实盘账户（TqAccount）、快期模拟账户（TqKq）下单交易，需要快期账户的交易权限；
回测（TqBacktest）、数据下载（DataDownloader）、本地风控（TqRiskRule）等功能，同样基于快期账户的授权体系。

从源码看，TqAuth的定义位于 tqsdk/auth.py，其 docstring 中的类注释为“信易用户认证类”，构造方法签名如下（tqsdk/auth.py）：

class TqAuth(object): """信易用户认证类""" def __init__(self, user_name: str, password: str): """ 创建快期用户认证类 Args: user_name (str): [必填]快期账户，可以是 邮箱、用户名、手机号 password (str): [必填]快期账户密码 """

注册快期账户后，账户的【手机号】/【邮箱地址】/【用户名】+【密码】即可作为TqAuth的登录凭据。注册入口为官方用户中心（相关说明见 doc/usage/shinny_account.rst）。

二、TqAuth 的构造与参数校验规则

TqAuth(user_name, password)是最常用的构造方式。两个参数均为必填字符串，且底层做了严格校验（tqsdk/auth.py）：

if not isinstance(user_name, str): raise Exception("快期账户必须是字符串") if not user_name.strip(): raise Exception("快期账户不能为空") if not isinstance(password, str): raise Exception("快期账户密码必须是字符串") if not password.strip(): raise Exception("快期账户密码不能为空") self._user_name = user_name self._password = password self._auth_url = os.getenv("TQ_AUTH_URL", "https://auth.shinnytech.com")

即：

参数	类型	必填	说明
`user_name`	`str`	是	快期账户，可为注册时的邮箱、用户名或手机号
`password`	`str`	是	快期账户密码，不允许为空串或纯空白字符

构造时的校验行为可以总结为四点：

user_name和password必须是str类型，否则抛出Exception("快期账户必须是字符串")/Exception("快期账户密码必须是字符串")；
去除首尾空白后不能为空，否则抛出对应的“不能为空”异常；
认证服务地址默认取https://auth.shinnytech.com，同时支持通过环境变量TQ_AUTH_URL覆盖；
构造时不会立即发起网络请求，真正的登录发生在TqApi初始化阶段。

三、在 TqApi 中传入 auth：三种典型使用形态

auth是TqApi.__init__的必填语义参数（类型为Union[TqAuth, str, None]），官方 API 文档对其说明如下（tqsdk/api.py）：

TqAuth对象：例如TqAuth("tianqin@qq.com", "123456")；
str：天勤用户论坛的邮箱和密码，以英文逗号分隔，例如"tianqin@qq.com,123456"；
若既不传TqAuth也不传字符串，则在TqApi初始化时会抛出异常提示必须先提供快期账户（tqsdk/api.py）。

TqApi内部对auth的解析逻辑位于 tqsdk/api.py：

if isinstance(auth, TqAuth): self._auth = auth elif isinstance(auth, str): comma_index = auth.find(',') if comma_index == -1: raise Exception(f"不能正确解析 auth=\"{auth}\", 请填写正确的 auth 参数，以英文逗号分隔用户名和密码，例如：\"tianqin@qq.com,123456\"。") user_name, pwd = auth[:comma_index], auth[comma_index + 1:] self._auth = TqAuth(user_name, pwd) else: self._auth = None

也就是说，字符串形式的auth本质上也会被解析为TqAuth对象。需要特别注意：字符串中必须包含英文逗号，否则会抛出“不能正确解析 auth”的异常。

3.1 最小示例：本地模拟 + 实时行情

最典型的入门写法来自 doc/quickstart.rst 与 tqsdk/demo/tutorial/t10.py：

from tqsdk import TqApi, TqAuth # 创建API实例,传入自己的快期账户 api = TqApi(auth=TqAuth("快期账户", "账户密码")) # 获得上期所 ni2206 的行情引用，当行情有变化时 quote 中的字段会对应更新 quote = api.get_quote("SHFE.ni2206") # 输出 ni2206 的最新行情时间和最新价 print(quote.datetime, quote.last_price) # 关闭api,释放资源 api.close()

当不显式提供account参数时，TqApi会创建一个进程内的临时模拟账户TqSim（tqsdk/api.py），该账户的持仓、委托和成交记录不会显示在快期 APP、快期专业版等客户端中，程序退出即丢失（见 doc/usage/shinny_account.rst）。

3.2 快期模拟账户（TqKq）

注册完成的快期账户可直接作为“快期模拟”账号，通过TqKq登录，模拟账户在快期 APP、快期专业版、快期 v2、快期 v3 和天勤量化上互通：

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

这是 tqsdk/demo/download_orders.py、tqsdk/demo/example/iceberg_algorithm.py 等示例的标准用法。

3.3 实盘账户（TqAccount）

实盘场景下，TqApi需要同时传入TqAccount（期货公司、账号、密码）与TqAuth（快期账户）。每个快期账户最多支持绑定三个实盘账户，快期账户会在用户首次使用某个实盘账户时自动绑定（doc/usage/shinny_account.rst）：

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

TqAuth的官方 docstring 也给出了相同的实盘示例（tqsdk/auth.py）。实盘交易属于 TqSdk 专业版功能，需要购买或申请试用授权，相关说明见 doc/quickstart.rst。

3.4 回测模式

回测场景同样需要auth。TqApi会依据是否传入TqBacktest自动将认证模式切换为bt或real（tqsdk/api.py）：

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("快期账户", "账户密码"))

四、登录流程与令牌管理：OAuth2 密码模式 + JWT

TqAuth的真正登录发生在TqApi._setup_connection()阶段。其调用链为：TqApi.__init__→_setup_connection()→self._auth.init(mode=...)→self._auth.login()（tqsdk/api.py）。

4.1 init(mode)：切换真实/回测授权模式

def init(self, mode="real"): self._mode = mode

mode取值为"real"（实盘/实时模式）或"bt"（回测模式）。该标记直接影响后续的功能权限判断，详见下文“回测模式下的默认权限”。

4.2 login()：获取 access_token 与 refresh_token

login()的实现（tqsdk/auth.py）如下：

def login(self): self._access_token, self._refresh_token = self._request_token({ "grant_type": "password", "username": self._user_name, "password": self._password }) content = jwt.decode(self._access_token, options={"verify_signature": False}) self._grants = content["grants"] self._auth_id = content["sub"]

_request_token向认证服务发送 OAuth2passwordgrant 请求（tqsdk/auth.py）：

def _request_token(self, payload): data = {"client_id": "shinny_tq", "client_secret": "be30b9f4-6862-488a-99ad-21bde0400081"} data.update(payload) url = f"{self._auth_url}/auth/realms/shinnytech/protocol/openid-connect/token" response = requests.post(url=url, headers=self._base_headers, data=data, timeout=30) if response.status_code == 200: content = json.loads(response.content) return content["access_token"], content["refresh_token"] else: raise Exception("用户权限认证失败 (%d,%s)" % (response.status_code, json.loads(response.content)))

这里的请求细节包括：

认证服务地址 =TQ_AUTH_URL环境变量（默认https://auth.shinnytech.com）+/auth/realms/shinnytech/protocol/openid-connect/token；
使用 OAuth2password授权模式，携带client_id/client_secret/username/password；
登录成功后返回access_token与refresh_token两个令牌；
返回的access_token是一个 JWT，SDK 通过jwt.decode(..., verify_signature=False)本地解码出grants（功能授权列表）与sub（账户 ID），从而避免每次请求都向认证服务查询权限；
登录失败时抛出Exception("用户权限认证失败 (status_code, 响应体)")。

后续所有对外请求都通过_base_headers携带Authorization: Bearer <access_token>（tqsdk/auth.py）。

4.3 令牌刷新与实盘账户自动绑定

当程序中的实盘账户尚未被快期账户授权绑定时，TqApi._check_account_auth会调用_add_account自动完成绑定（tqsdk/api.py、tqsdk/auth.py）：

def _add_account(self, account_id): if self._has_account(account_id): return True url = f"{self._auth_url}/auth/realms/shinnytech/rest/update-grant-accounts/{account_id}" response = requests.put(url=url, headers=self._base_headers, timeout=30) if response.status_code == 200: self._access_token, self._refresh_token = self._request_token({ "grant_type": "refresh_token", "refresh_token": self._refresh_token, }) content = jwt.decode(self._access_token, options={"verify_signature": False}) self._grants.update(content["grants"])

即：先调用PUT /update-grant-accounts/{account_id}将实盘账户挂到快期账户名下，再用refresh_token刷新令牌并同步最新的grants。这与文档中“快期账户会在用户使用实盘账户时自动进行绑定，直到该快期账户没有能绑定实盘账户的名额”（doc/usage/shinny_account.rst）的描述完全对应。

五、expire_datetime：查询快期账户授权到期时间

TqAuth对外暴露的唯一公共属性是expire_datetime（tqsdk/auth.py），用于查询快期账户的授权到期时间：

@property def expire_datetime(self): """ 返回快期账户授权到期时间 Returns: datetime.datetime : datetime 模块中的 datetime 类型时间 * 返回授权到期时间，如果查询失败则抛出异常。 * 时区是东八区。 注意: 1. 对于免费用户，将返回到期时间："2099-12-31 23:59:59+08:00"，代表权限永不到期。 2. 当用户升级版本或者续费后，将在下一次使用时获取最新到期时间。 """

其底层实现通过GET {auth_url}/auth/realms/shinnytech/rest/get-grant/tq查询，并解析响应中的exp（到期时间戳）、daysleft（剩余天数）、account_type（账户类型/版本）三个字段（tqsdk/auth.py）：

if self._expire_datetime is None or self._expire_days_left is None or self._product_type is None: url = f"{self._auth_url}/auth/realms/shinnytech/rest/get-grant/tq" response = requests.get(url=url, headers=self._base_headers, timeout=30) content = json.loads(response.content) self._expire_datetime = datetime.datetime.fromtimestamp(content["exp"], tz=_cst_tz) self._expire_days_left = content["daysleft"] self._product_type = content["account_type"]

要点：

行为	说明
返回类型	`datetime.datetime`，时区为东八区（CST）
免费用户	返回`2099-12-31 23:59:59+08:00`，代表权限永不到期
升级/续费	将在下一次使用时获取最新到期时间（属性结果有内存缓存）
查询失败	抛出`Exception("查询快期账户授权到期日期失败")`

官方示例（tqsdk/auth.py）：

from tqsdk import TqApi, TqAuth auth = TqAuth("快期账户", "账户密码") api = TqApi(auth=auth) print(auth.expire_datetime) # 快期账户授权到期时间 api.close()

此外，TqApi在初始化时也会主动查询一次expire_datetime，当剩余天数小于 30 天时会打印续费/升级提醒（tqsdk/api.py）。

六、权限（grant）体系：功能授权与账户授权

login()解码 JWT 后得到grants，其结构为（tqsdk/auth.py）：

self._grants = { "features": [], # 功能授权列表，如 "futr"、"sec"、"tq_dl" 等 "accounts": [] # 已绑定的实盘/模拟账户 ID 列表 }

所有权限检查都以该grants为数据源，相关内部方法如下。

6.1 功能授权检查：_has_feature

def _has_feature(self, feature): if self._mode == "bt" and feature in ["futr", "sec", "lmt_idx"]: # 在回测模式中所有用户都有 futr sec lmt_idx 权限 return True return feature in self._grants["features"]

在**回测模式（mode == "bt"）**下，所有用户自动获得futr（期货）、sec（证券）、lmt_idx（限价指数）三项权限；
其他功能则必须真实存在于grants["features"]中。

6.2 行情权限检查：_has_md_grants

订阅行情/K 线/tick 前会调用_has_md_grants(symbol)做权限校验（调用点见 tqsdk/api.py 的_get_serial_async与 tqsdk/objs_not_entity.py）。其判断逻辑（tqsdk/auth.py）：

def _has_md_grants(self, symbol): symbol_list = symbol if isinstance(symbol, list) else [symbol] for symbol in symbol_list: if symbol.split('.', 1)[0] in (FUTURE_EXCHANGES + SPOT_EXCHANGES + KQ_EXCHANGES + KQD_EXCHANGES) and self._has_feature("futr"): continue elif symbol.split('.', 1)[0] in (["CSI"] + STOCK_EXCHANGES) and self._has_feature("sec"): continue elif symbol in ["SSE.000016", "SSE.000300", "SSE.000905", "SSE.000852"] and self._has_feature("lmt_idx"): continue else: raise Exception(f"您的账户不支持查看 {symbol} 的行情数据，需要购买后才能使用。") return True

即：期货/现货/快期指数类合约需要futr权限；股票与 CSI 指数需要sec权限；四个特定上证指数（SSE.000016、SSE.000300、SSE.000905、SSE.000852）需要lmt_idx权限。校验失败时会抛出带购买指引的异常。

6.3 交易权限检查：_has_td_grants

insert_order等交易操作前会调用_has_td_grants(symbol)（调用点见 tqsdk/api.py 与 tqsdk/api.py）：

def _has_td_grants(self, symbol): # 对于 opt / cmb / adv 权限的检查由 OTG 做 if symbol.split('.', 1)[0] in STOCK_EXCHANGES and self._has_feature("sec"): return True if symbol.split('.', 1)[0] in (FUTURE_EXCHANGES + KQ_EXCHANGES) and self._has_feature("futr"): return True raise Exception(f"您的账户不支持交易 {symbol}，需要购买后才能使用。")

6.4 其他功能型 feature

从源码调用点可以进一步确认以下 feature 与具体功能模块的对应关系：

feature	功能模块	调用点
`tq_trading_status`	交易状态信息查询`get_trading_status`	tqsdk/api.py
`tq_dl`	历史数据下载（`get_tick_data_series`、`DataDownloader`）	tqsdk/api.py、tqsdk/tools/downloader.py
`tq_lc_rk`	本地风控`add_risk_rule`	tqsdk/api.py
`futr`/`sec`/`lmt_idx`	期货行情与交易 / 证券行情与交易 / 限价指数行情	tqsdk/auth.py

当授权不足时，SDK 会抛出类似您的账户不支持 ...，需要购买后才能使用。升级网址：https://www.shinnytech.com/tqsdk-buy/的异常，提醒用户升级专业版或购买对应功能。

七、网关寻址：行情服务器与交易服务器的获取

快期账户登录后还承担“网关寻址”职责——TqApi通过TqAuth的两个内部方法确定连接哪台行情/交易服务器。

7.1 行情服务器：_get_md_url

def _get_md_url(self, stock, backtest): url = f"https://api.shinnytech.com/ns" params = {"stock": str(stock).lower(), "backtest": str(backtest).lower()} response = requests.get(url=url, params=params, headers=self._base_headers, timeout=30) if response.status_code == 200: content = json.loads(response.content) if "mdurl" in content: return content["mdurl"]

TqApi在_setup_connection中若未显式指定md_url，则调用该方法获取行情网关地址（tqsdk/api.py）。其中stock参数由_stock（是否股票模式）决定，backtest参数由是否回测决定。若恰好处于每日 19:00-19:30 的运维时间，会抛出“每日 19:00-19:30 为日常运维时间，请稍后再试”的提示（tqsdk/api.py）。

7.2 交易服务器：_get_td_url

def _get_td_url(self, broker_id, account_id): url = f"https://files.shinnytech.com/{broker_id}.json" params = {"account_id": account_id, "auth": self._user_name} response = requests.get(url=url, params=params, headers=self._base_headers, timeout=30) if response.status_code != 200: raise Exception(f"不支持该期货公司 - {broker_id}，请联系期货公司。") broker_list = json.loads(response.content) if "TQ" not in broker_list[broker_id]["category"]: raise Exception(f"该期货公司 - {broker_id} 暂不支持 TqSdk 登录，请联系期货公司。") return broker_list[broker_id]["url"], ...

该方法的调用发生在BaseOtg._update_otg_info中（tqsdk/tradeable/otg/base_otg.py）：实盘账户（如TqAccount、TqCtp）创建TqApi时，SDK 会根据期货公司代码broker_id从文件服务获取对应的交易网关地址，并校验该公司是否支持 TqSdk 登录（category中是否包含"TQ"）。

八、TqAuth 在插件/环境变量场景下的注入方式

除了在代码中显式创建TqAuth，tqsdk-python 还支持通过环境变量注入认证信息，主要用于策略插件化运行（见 tqsdk/tqwebhelper.py）：

# tqsdk/tqwebhelper.py L335-L339 action = { "_action": os.getenv("TQ_ACTION"), "_http_server_address": os.getenv("TQ_HTTP_SERVER_ADDRESS"), "_auth": os.getenv("TQ_AUTH") }

当TQ_AUTH环境变量被设置时（格式同样为用户名,密码），TqWebHelper会将其解析为TqAuth并替换 API 的认证对象；若代码中同时显式传入了不同的auth，会抛出“策略代码与插件设置中的 auth 参数冲突”异常（tqsdk/tqwebhelper.py）：

if args["_auth"]: comma_index = args["_auth"].find(',') user_name, pwd = args["_auth"][:comma_index], args["_auth"][comma_index + 1:] if self._api._auth is not None and (user_name != self._api._auth._user_name or pwd != self._api._auth._password): raise Exception("策略代码与插件设置中的 auth 参数冲突。可尝试删去代码中的 auth 参数，以插件设置的参数运行。") self._api._auth = TqAuth(user_name, pwd)

这一机制保证了同一个策略文件可以在不同账户/环境下复用，而无需修改代码。相关环境变量还包括TQ_ACTION、TQ_BROKER_ID、TQ_ACCOUNT_ID、TQ_PASSWORD、TQ_START_DT、TQ_END_DT、TQ_INIT_BALANCE等（tqsdk/tqwebhelper.py）。

九、工程实践建议与常见问题排查

结合文档与源码，整理如下实践要点：

账户密码不要硬编码进版本库：推荐像官方示例那样从环境变量读取，例如 tqsdk/api.py 中的写法：

TQ_USER = os.getenv("TQ_USER", "快期账号") TQ_PASS = os.getenv("TQ_PASS", "快期密码") api = TqApi(auth=TqAuth(TQ_USER, TQ_PASS))

区分三类账户形态：TqApi(auth=...)（进程内临时TqSim，数据不持久化）、TqApi(TqKq(), auth=...)（快期模拟账户，多客户端互通）、TqApi(TqAccount(...), auth=...)（实盘账户，需专业版授权且受“每账户最多绑定三个实盘账户”限制）。
字符串形式 auth 必须含英文逗号：auth="tianqin@qq.com,123456"合法；缺少逗号会触发不能正确解析 auth异常。
权限不足时的典型报错：您的账户不支持查看 {symbol} 的行情数据（行情权限）、您的账户不支持交易 {symbol}（交易权限）、{接口} 数据获取方式仅限专业版用户使用（历史数据）、本地风控功能仅限专业版用户使用（风控），对应处理方式是购买/试用相应授权。
回测无需购买期货/证券权限：回测模式下futr、sec、lmt_idx对所有用户开放（tqsdk/auth.py），因此建议先用回测验证策略再上实盘。
到期时间监控：可通过auth.expire_datetime在程序启动时检查授权剩余时间，结合 SDK 内置的“剩余 30 天提醒”机制规划续费。