API 参考¶
本文档描述 eltdx 1.0 的对外调用方式。按方法查看参数和解析字段时,优先看 METHOD_REFERENCE.md。底层命令号、请求 payload 和响应字段以 docs/COMMANDS_7709.md 及协议相关文档为准。
总入口¶
真实连接 7709 主站:
默认 TdxClient() 使用真实 7709 主站。单元测试或离线示例可以显式使用内存客户端:
可以直接传主站:
with TdxClient(host="116.205.183.150:7709", timeout=3) as client:
quotes = client.helpers.full_quotes(["sz000001", "sh600000"])
也可以使用连接池和主站测速:
with TdxClient.from_hosts(
server_count=2,
connections_per_server=4,
probe_hosts=True,
timeout=3,
) as client:
quotes = client.helpers.full_quotes(["sz000001", "sh600000"])
probe_hosts=True 会在构造 TdxClient 时,用 TCP connect 并发测量普通 43 台和集合竞价、资金流向专用 35 台候选主站(两组地址去重),把连得上的、延迟低的排在前面并缓存到当前客户端。默认开启测速;测速只使用临时探测连接,不创建业务 Engine,也不进行协议握手。probe_hosts=False 可跳过这一步。
不传 host / hosts 时,客户端会读取包内 tdx_server.json 的43台默认主站。如果这个文件缺失,会退回代码内置列表。测速结果会原子写入当前用户数据目录的 tdx_server_ranking.json,下次启动先复用已保存的排名再刷新;软件升级不会覆盖这张本地排名表。可调用 eltdx.hosts.refresh_server_ranking() 手动重新测速并保存。
真实 socket 默认每 30 秒发一次 0x0004 心跳,用来维持长时间空闲连接。短脚本不用管;需要改间隔或关闭时:
常用连接参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
host |
None |
指定单个 7709 主站 |
hosts |
None |
指定多个 7709 主站 |
timeout |
8.0 |
数字 IP 或已缓存 endpoint 的端到端请求上限,覆盖排队、连接、握手、发送、响应和一次 retry |
server_count |
2 |
从持久测速排名中使用的服务器数量 |
connections_per_server |
4 |
每台选中服务器的 TCP 连接数;未显式设置 pool_size 时据此计算总数 |
pool_size |
None,自动为 8 |
兼容参数,显式指定 TCP/Slot 总数时在选中服务器之间尽量平均分配 |
runtime_workers |
None |
自动取 min(pool_size, 系统允许的逻辑处理器数);可手动指定1到 pool_size |
max_connections_per_host |
None |
自动按分布计算每台服务器的活动连接硬上限 |
connect_concurrency |
None |
自动计算全局同时建连和握手数量,最大默认32 |
connect_concurrency_per_host |
None |
每台服务器同时建连和握手数量,默认最多2 |
probe_hosts |
True |
创建客户端时是否测速、持久化并缓存普通 43 台和专用 35 台候选主站排名 |
heartbeat_interval |
30.0 |
后台心跳秒数;None 表示关闭,非 None 时必须大于 0 |
max_pending_requests |
256 |
pool 中等待空闲 slot 的最大请求数;满时抛 PoolBusyError |
push_queue_size |
1024 |
共享 push buffer 的最大帧数 |
push_queue_bytes |
64 * 1024 * 1024 |
共享 push buffer 的最大 wire bytes |
global_raw_bytes |
None |
自动按 Slot 数增长、最高256 MiB的 Engine raw 预算 |
global_decoded_bytes |
None |
自动按 Slot 数增长、最高2 GiB的 Engine decoded 预算 |
自定义 hostname 的首次 DNS 解析在 native Engine request deadline 外执行,标准库解析无法严格取消;它不占用 pool Slot 或 TCP 连接,解析结束后会重新检查 transport epoch 和 close 状态。数字 IP 和已缓存 endpoint 没有该例外。
默认不传 pool_size,由最快2台服务器乘以每台4个 Slot 得到8。pool_size=N 继续表示 native Engine 最多拥有 N 个 Rust Slot、N 个 TCP socket 和 N 个业务 wire request 同时在途;它不是 worker 数。显式同时传 pool_size、server_count 和 connections_per_server 时,三者乘积必须一致。请求在 Supervisor 的全池 FIFO admission 中等待空闲 Slot;等待 permit 和 active lease 分开计数。
多请求必须固定在同一连接时可使用 pin:
with client.transport.pin() as pinned:
first = pinned.execute(0x06B9, {"path": "zhb.zip", "offset": 0, "size": 30000})
second = pinned.execute(0x06B9, {"path": "zhb.zip", "offset": 30000, "size": 30000})
pin context 独占一个 slot;context 退出或 proxy close() 会取消未完成 wire request 并归还 lease。它不会关闭共享 pool,也不能在 pool close/reopen 后继续使用。
组合与便捷方法¶
这一组方法组合底层分组 API,提供分页、五档补齐、解析和本地计算等常用能力。
client.helpers.board_quotes() / client.helpers.board_member_quotes(board_code)¶
板块 Helper 使用 0x06b9 准备板块资料,使用 0x044d 核对当前证券名单,再使用 0x054c 按最多 80 个代码分批查询行情。board_quotes() 默认返回概念板块,也可通过 category 选择其他分类或全部板块;board_member_quotes() 必须传板块代码,只查询该板块的有效成分股。资料按服务端日期每天首次调用准备一次,可用 refresh=True 强制刷新。详见板块行情和板块成分股行情。
client.helpers.full_quotes(codes)¶
批量查询完整五档行情,自动按 80 个代码拆批,底层组合 0x054c 基础快照和 0x0547 首次刷新。
client.quotes.get_depth(codes)¶
按代码列表直接发起一次 0x0547 刷新,首次刷新用于建立实时五档,后续可通过推送增量更新。
代码表便捷方法¶
client.codes.count("sz")
client.codes.list("sz", start=0, limit=1600)
client.codes.all("sz")
client.codes.all_a_shares()
client.codes.all_stocks()
client.codes.all_etfs()
client.codes.all_indices()
其中 A 股、股票、ETF、指数过滤使用 0x044d 代码表解析出的 category 派生字段。
K 线便捷方法¶
client.bars.get("sz000001", period="day", count=30)
client.bars.get("sz000001", period="day", all_pages=True, page_size=800)
client.bars.get("sz000001", period="day", adjust="qfq")
client.bars.get("sz000001", period="week", adjust="hfq")
client.bars.get("sz000001", period="day", adjust="fixed_qfq", anchor_date="2024-06-03")
all_pages=False 取一页;all_pages=True 自动拉到空页并合并。复权参数直接交给 0x052d 主站计算。本地审计使用 client.corporate.adjustment_factors(),它返回完整的 scale + offset 仿射系数。
常用周期为 1m/5m/15m/30m/60m、day/week/month/quarter/year。复权模式为 none、qfq、hfq、fixed_qfq、fixed_hfq;定点模式需要 anchor_date。
分时和成交明细便捷方法¶
client.minutes.today("sz000001")
client.minutes.history("sz000001", "2026-05-20")
client.trades.today("sz000001")
client.trades.history("sz000001", "2026-05-20")
client.trades.all_history("sz000001", "2026-05-20")
client.trades.all_history(["sz000001", "sh600000"], "2026-05-20")
client.trades.history_batch("sz000001", "2026-05-20")
client.trades.all_history_batch(["sz000001", "sh600000"], "2026-05-20")
成交明细提供单页和完整分页两组入口:
client.trades.today("sz000001")
client.trades.all_today("sz000001")
client.trades.history("sz000001", "2026-05-20")
client.trades.all_history("sz000001", "2026-05-20")
集合竞价便捷方法¶
client.auctions.series("sz000001")
client.auctions.series("sz000001", "2026-05-20")
client.trades.opening_match_history("sz000001", "2026-05-20")
client.trades.opening_match_today(["sz000001", "sh600000"])
client.auctions.series() 返回 0x056a 主站保存的当日或历史集合竞价过程快照;不传日期查询当日,传入日期查询历史。client.trades.opening_match_today() 和 opening_match_history() 分别从 0x0fc5、0x0fc6 只取 09:25 正式开盘撮合。
标准客户端从专用 35 台主站中选择集合竞价服务器;排名在客户端构造时完成,集合竞价首次请求时才建立业务连接并握手,后续复用连接且不重复测速。普通行情、K 线和成交仍使用 43 台默认主站。
成交入口传入代码列表时返回以规范化完整代码为键的结果字典;底层仍逐只请求,batch_size 控制同时查询的股票数,默认跟随连接池大小。
股本变迁和本地复权系数¶
changes = client.corporate.capital_changes("sz000001")
factors = client.corporate.adjustment_factors("sz000001")
anchored = client.corporate.adjustment_factors("sz000001", anchor_date="2024-05-31")
capital_changes() 返回标签 1..15 的广义权息/股本变迁原始业务记录。adjustment_factors() 根据其中的标签 1 事件,计算每个除权事件日期的前、后复权仿射系数:
普通复权 K 线直接使用 client.bars.get(..., adjust="qfq" / "hfq")。
低频数据缓存¶
Helpers 只缓存组合查询内部使用的财务批次、证券表和已验证的短线统计资源。股本变迁、代码数量、代码表、直接财务查询、实时行情、分时、成交明细和 K 线每次按请求读取。
行情价格精度由 0x044d 代码表的 decimal 字段决定。客户端首次请求某市场行情时会自动加载并缓存该市场代码表,快照、分类行情、刷新行情和分时解析均按证券自身精度换算;不会根据代码前缀硬编码可转债规则。
include_raw¶
部分调试场景可以传 include_raw=True:
client.corporate.capital_changes("sz000001", include_raw=True)
client.bars.get("sz000001", period="day", include_raw=True)
client.trades.history("sz000001", "2026-05-20", include_raw=True)
大多数返回模型已经保留 raw_payload 或单条记录的 record_hex,用于抓包对照和协议解析排查。
include_raw=False(默认)时仍保留这些字段的位置,但值为空(b"" 或 "");设为 True 才填充原始内容。
JSON 输出¶
from eltdx import to_json, to_jsonable
data = to_jsonable(client.helpers.full_quotes("sz000001"))
text = to_json(data, indent=2)
client.session¶
handshake()¶
连接后握手,对应 0x000d。
heartbeat()¶
心跳保活,对应 0x0004。
client.codes¶
count(market)¶
查询某市场完整代码表条数,对应 0x044e。结果不限于 A 股;仅统计 A 股时使用 a_share_count(market)。
client.codes.count("sz")
client.codes.count("sh")
client.codes.count("bj")
client.codes.a_share_count("sh")
list(market, start=0, limit=1600)¶
分页查询代码表,对应 0x044d。
all(market)¶
自动分页拉取某市场全量代码表,不需要先调用 count()。
client.quotes¶
client.quotes.get_snapshots(codes)¶
按显式代码列表查询一次 0x054c 基础快照。当前实盘响应只稳定确认买一 / 卖一;普通业务需要完整行情时使用 client.helpers.full_quotes(),直接操作原生五档刷新时才使用 client.quotes.get_depth()。
legacy(codes)¶
直接调用一次 0x053e 旧版批量行情接口,返回 list[LegacyQuote]。
list_by_category(category, sort_by=None, start=0, count=80, ascending=False)¶
查询分类行情列表,对应 0x054b。
refresh(codes=None, cursors=None)¶
行情增量刷新协议,对应 0x0547,单次最多 100 个代码。
refresh() 发起一次增量刷新请求。服务端主动推送帧会进入 transport 的 push queue,可用下面两个方法读取。
client.quotes.get_depth(codes)¶
按代码列表直接发起一次 0x0547 刷新,等价于 refresh(codes, cursors={}),返回 QuoteRefreshPage。首次刷新用于建立实时五档,后续可由推送队列增量更新;单次最多 100 个代码。
poll_push(timeout=0.0, parse=False)¶
读取一个未配对推送帧,默认返回原始 ResponseFrame。确认推送帧可直接按当前上下文解析时,可以传 parse=True。
frame = client.quotes.poll_push(timeout=0.5)
event = client.quotes.poll_push(timeout=0.5, parse=True)
push queue 同时受帧数和字节数限制。满时会丢弃最旧帧以保留最新行情,并在下一次 poll_push() 或 drain_pushes() 抛出一次 PushOverflowError;捕获后继续读取即可,异常消息包含累计丢弃数。
drain_pushes(parse=False)¶
取出当前队列里已经收到的全部推送帧。
close() 成功返回时旧 Rust Slot task、TCP socket、request owner、waiter、pin、push buffer 和 runtime thread 都已结束。若 1 秒内无法证明完成,会抛 TransportCloseTimeoutError 并进入 FAILED_CLOSING;后续可以再次 close() 完成清理,但该实例不能 reopen,请创建新的 TdxClient。
client.resources¶
read(path, offset=0, size=30000)¶
通过 0x06b9 读取一个服务器文件块,返回 FileContentChunk。这个入口不循环下载整文件。
download_file(path, chunk_size=30000, max_bytes=None)¶
循环调用 0x06b9 并按实际返回长度拼接完整文件,返回 bytes。chunk_size 范围为 1..60000;max_bytes 可限制最多下载的字节数。
read_stats(path="zhb.zip", chunk_size=30000)¶
下载并解析 zhb.zip 中的 tdxstat.cfg 和 tdxstat2.cfg,返回 TdxStatsResource。两个 CFG 使用 GBK 解码,结构化字段可通过 stats.row(market_id, code) 查询。
该解析只针对已知的 zhb.zip 格式;其他服务器文件由 download_file() 返回原始 bytes。
client.bars¶
get(code, period="day", start=0, count=800, adjust=None, anchor_date=None, kind=None, include_raw=False, all_pages=False, page_size=800, max_pages=200, batch_size=None)¶
查询 K 线 / 周期线,对应 0x052d。
client.bars.get("sz000001", period="day", count=800)
client.bars.get("sz000001", period="day", adjust="qfq")
client.bars.get("sz000001", period="day", all_pages=True, page_size=800)
client.bars.get(["sz000001", "sh600000"], period="day", count=800, batch_size=2)
all_pages=False 时校验并使用 count,只请求一页。all_pages=True 时使用 page_size 自动请求到空页,max_pages 防止异常情况下无限循环,返回合并后的 KlineSeries。短页不会提前停止。
code 传入字符串时返回单个 KlineSeries;传入代码列表时按连接池并发逐只请求,返回以规范化完整代码为键的字典。batch_size 控制同时请求的最大代码数,默认跟随连接池容量;列表中的重复代码会去重。
返回字段包括 period_name、adjust_mode、bars;每根 K 线提供 time、open/high/low/close、volume_lots 和 amount。
client.minutes¶
today(code, include_raw=False, batch_size=None)¶
查询主站当前保存的分时,对应 0x0537。凌晨、周末或节假日可能返回最近交易日数据。
当日分时接口:查询当天每分钟行情。传单个代码返回 MinuteSeries,传代码列表返回 {完整代码: MinuteSeries}。
history(code, trading_date, include_raw=False, batch_size=None)¶
查询指定日期历史分时,对应 0x0fb4。
client.minutes.history("sz000001", "2026-05-20")
client.minutes.history(["sz000001", "sh600487"], "2026-05-20", batch_size=8)
指定日期历史分时接口:查询某个交易日的分钟行情;代码列表返回按代码组织的字典。
recent(code, trading_date=None, include_raw=False, batch_size=None)¶
查询近期历史分时,对应 0x0feb。
client.minutes.recent("sz000001", "2026-05-20")
client.minutes.recent(["sz000001", "sh600487"], "2026-05-20", batch_size=8)
近期历史分时接口:查询近期分钟行情;代码列表返回按代码组织的字典。
aux(code, kind="buy_sell_strength", include_raw=False)¶
查询分时副图数据,对应 0x051b。
client.minutes.aux("sz000001", kind="buy_sell_strength")
client.minutes.aux("sz000001", kind="volume_comparison")
sparkline(code, selector=1, window=20, include_raw=False)¶
查询单标的小走势图,对应 0x0fd1。
client.trades¶
当日成交明细的批量字段接口为 today_batch(),完整当日成交明细接口为 all_today_batch();它们返回 TradeBatch,需要某一行时再调用 tick(index),需要列数据时调用 column(name),避免一开始为每一笔成交创建 Python 对象。
today(code, start=0, count=1800, include_raw=False, batch_size=None)¶
查询主站当前保存的混合明细,对应 0x0fc5。凌晨、周末或节假日可能返回最近交易日数据。ticks 原样保留 status=8 竞价快照;actual_trades 排除这些非成交快照,并保留 09:25、15:00 和 status=5 盘后固定价格真实成交。
after_hours_trades 可单独取得 15:05-15:30、status=5 的盘后固定价格成交。完整秒级竞价过程和竞价数量使用 client.auctions.series()。
history(code, trading_date, start=0, count=1800, include_raw=False, batch_size=None)¶
查询历史混合明细增强接口,对应 0x0fc6。原始 ticks 与真实成交视图的分类规则和当日接口一致。
client.trades.history("sz000001", "2026-05-20")
client.trades.history(["sz000001", "sh600000"], "2026-05-20")
client.auctions¶
series(code, date=None, include_raw=False)¶
查询主站保存的当日或历史集合竞价过程快照,对应 0x056a;不传日期查询当日,传入日期查询历史。标准客户端统一使用 35 台专用主站,排名在客户端构造时完成,首次调用时才建连和握手,不重复测速;它不是逐笔成交接口,即使返回 09:25:00 也仍按快照解释。
client.money_flow¶
daily(code, include_raw=False, batch_size=75)¶
读取一只或多只证券最近的日资金流向分档数据,对应 0x0ffc。传入字符串返回 MoneyFlowBlock,传入代码列表返回 MoneyFlowBatch。该接口使用独立的 35 台专用主站池,排名在客户端构造时完成,首次调用时才建立业务连接并握手,不重复测速。
完整参数和返回字段见 资金流向日数据。
client.corporate¶
capital_changes(code_or_codes, include_raw=False, batch_size=75)¶
查询标签 1..15 的广义权息和股本变迁资料,对应 0x000f。传单个代码返回 CapitalChangeBlock;传代码列表默认按 75 只拆批,batch_size 可设为 1..200。超量批次按连接池 Slot 数并发请求;主站按响应大小截断时会自动补拉未返回的代码。
client.corporate.capital_changes("sz000001")
client.corporate.capital_changes(["sz000001", "sh600000", "bj920000"])
adjustment_factors(code_or_codes, anchor_date=None, *, start_date=None, batch_size=75)¶
传单个代码返回 AdjustmentFactorResponse;传代码列表返回 AdjustmentFactorBatch。批量调用复用批量 0x000f 返回的股票块,在本地逐只计算,不会为每只股票单独请求。每个除权事件日期一条 AdjustmentFactor,包含 qfq_scale/qfq_offset 与 hfq_scale/hfq_offset,用于应用到本地不复权 K 线。
client.corporate.adjustment_factors(
"sz000858",
anchor_date="2024-06-03",
start_date="1998-04-27",
)
应用到本地不复权 K 线时,前复权选择第一条满足 bar_date < factor.date 的系数,后复权选择最后一条满足 factor.date <= bar_date 的系数,再计算 round(raw * scale + offset, 2)。直接获取服务端复权 K 线时,使用 client.bars.get(..., adjust="none" / "qfq" / "hfq")。
finance_batch(codes, fields=None, include_raw=False)¶
批量查询财务字段,对应 0x0010。fields 只过滤本地返回字段,底层仍请求完整记录。
client.corporate.finance_batch(["sz000001", "sh600000"])
client.corporate.finance_batch(["sz000001"], fields=["流通股本", "total_shares"])
client.limits¶
special(start_index=0)¶
查询特殊品种涨跌停限制表,对应 0x0452。
0x0452 按表内行号分页取记录。需要查询某个代码时,先扫描建本地索引:
client.f10¶
client.f10 走 7615/TQLEX HTTP 网关,独立于 7709 socket 握手。它适合查询 F10 资料、题材、公告、财务报表和估值数据。
client.f10.company_profile("000034")
client.f10.hot_topics("000034")
client.f10.announcements("000034")
client.f10.finance_report("000034")
client.f10.valuation("000034")
client.f10.limit_up_down_list("20260810")
常规 F10 方法返回 F10Response,涨跌停列表返回 LimitBoardLadder(其中每行是 LimitBoardLadderRow)。常用数据在第一张表或模型的 rows:
需要直接调用 Entry 时,可以使用通用 TQLEX 调用:
完整 F10 方法表见 F10_7615.md。
client.helpers¶
client.helpers 提供常用问题的组合调用。
with TdxClient(timeout=3) as client:
profiles = client.helpers.stock_profile_table(["sz000001", "sh600000"])
shortline = client.helpers.shortline_indicators(["sz000001", "sh600000"])
topics = client.helpers.stock_topics("000034")
stocks = client.helpers.topic_stocks("000034", topic_name="存储芯片")
auction = client.helpers.auction_data("sz000001", "2026-05-20")