API 参考¶

本文档描述 eltdx 1.0 的对外调用方式。按方法查看参数和解析字段时，优先看 METHOD_REFERENCE.md。底层命令号、请求 payload 和响应字段以 docs/COMMANDS_7709.md 及协议相关文档为准。

总入口¶

真实连接 7709 主站：

from eltdx import TdxClient

with TdxClient(timeout=3) as client:
    count = client.codes.count("sz")

默认 TdxClient() 使用真实 7709 主站。单元测试或离线示例可以显式使用内存客户端：

with TdxClient.in_memory() as client:
    request = client.codes.count("sz")

可以直接传主站：

with TdxClient(host="HOST:PORT", 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 延迟，把可用节点排在前面并缓存到当前客户端。默认关闭测速；测速只使用临时探测连接，不创建业务 Engine，也不进行协议握手。

不传 host / hosts 时，客户端会读取包内的默认主站配置；如果配置文件缺失，会退回代码内置列表。测速结果会原子写入当前用户数据目录的 tdx_server_ranking.json，下次启动可复用已保存的排名；软件升级不会覆盖这张本地排名表。可调用 eltdx.hosts.refresh_server_ranking() 手动重新测速并保存。

真实 socket 默认每 30 秒发一次 0x0004 心跳，用来维持长时间空闲连接。短脚本不用管；需要改间隔或关闭时：

TdxClient(heartbeat_interval=60)
TdxClient(heartbeat_interval=None)

常用连接参数：

参数	默认值	说明
`host`	`None`	指定单个 7709 主站
`hosts`	`None`	指定多个 7709 主站
`timeout`	`8.0`	数字 IP 或已缓存 endpoint 的端到端请求上限，覆盖排队、连接、握手、发送、响应和一次 retry
`server_count`	`1`	使用的服务器数量
`connections_per_server`	`1`	每台选中服务器的 TCP 连接数；未显式设置 `pool_size` 时据此计算总数
`pool_size`	`1`	TCP/Slot 总数；显式设置后可启用并发请求
`runtime_workers`	`None`	自动取 `min(pool_size, 系统允许的逻辑处理器数)`；可手动指定1到 `pool_size`
`max_connections_per_host`	`None`	自动按分布计算每台服务器的活动连接硬上限
`connect_concurrency`	`1`	全局同时建连和握手数量；需要并发时显式设置
`connect_concurrency_per_host`	`1`	单台服务器同时建连和握手数量
`probe_hosts`	`False`	创建客户端时是否测速、持久化并缓存候选主站排名
`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 没有该例外。

默认使用 1 个服务器和 1 个 Slot。pool_size=N 表示 native Engine 最多拥有 N 个 Rust Slot、N 个 TCP socket 和 N 个业务 wire request 同时在途；需要并发时显式设置 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.helpers.full_quotes(["sz000001", "sh600000"])

`client.quotes.get_depth(codes)`¶

按代码列表直接发起一次 0x0547 刷新，首次刷新用于建立实时五档，后续可通过推送增量更新。

client.quotes.get_depth(["sz000001", "sh600000"])

代码表便捷方法¶

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 自动拉到空页并合并。前后复权由主站计算。本地计算和审计使用 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 正式开盘撮合。

标准客户端从专用候选节点中选择集合竞价服务器；启用测速时，排名在客户端构造时完成，集合竞价首次请求时才建立业务连接并握手，后续复用连接。普通行情、K 线和成交使用默认候选节点。

成交入口传入代码列表时返回以规范化完整代码为键的结果字典；底层仍逐只请求，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 事件，计算每个除权事件日期的前、后复权仿射系数：

adjusted = round(raw * scale + offset, 2)

普通复权 K 线直接使用 client.bars.get(..., adjust="qfq" / "hfq")。将本地系数用于完整 K 线时，必须以第一根 K 线日期设置 start_date，否则早于服务端第一根可用 K 线的权息事件可能污染后复权基准；即使日期范围正确，本地 0x000f 计算与服务端 0x052d 结果仍可能相差约 0.01～0.02 元。

低频数据缓存¶

Helpers 只缓存组合查询内部使用的财务批次、证券表和已验证的短线统计资源。股本变迁、代码数量、代码表、直接财务查询、实时行情、分时、成交明细和 K 线每次按请求读取。

行情价格精度由 0x044d 代码表的 decimal 字段决定。客户端首次请求某市场行情时会自动加载并缓存该市场代码表，快照、分类行情、刷新行情和分时解析均按证券自身精度换算；不会根据代码前缀硬编码可转债规则。

client.helpers.shortline_indicators("sz000001", refresh_stats=True)
client.clear_cache()

`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。

client.session.handshake()

`heartbeat()`¶

心跳保活，对应 0x0004。

client.session.heartbeat()

`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。

client.codes.list("sz", start=0, limit=1600)

`all(market)`¶

自动分页拉取某市场全量代码表，不需要先调用 count()。

client.codes.all("bj")
client.codes.a_shares("bj")
client.codes.all_a_shares()

`client.quotes`¶

`client.quotes.get_snapshots(codes)`¶

按指定代码列表查询当前行情，包含买一 / 卖一盘口。需要完整行情和五档盘口时，使用 client.helpers.full_quotes()；单独查询五档数据时，使用 client.quotes.get_depth()。

client.quotes.get_snapshots(["sz000001", "sh600000"])

`legacy(codes)`¶

直接调用一次 0x053e 旧版批量行情接口，返回 list[LegacyQuote]。

client.quotes.legacy(["sz000001", "sh600000"])

`list_by_category(category, sort_by=None, start=0, count=80, ascending=False)`¶

查询分类行情列表，对应 0x054b。

client.quotes.list_by_category("沪深A股", sort_by="涨幅", count=100)

`refresh(codes=None, cursors=None)`¶

行情增量刷新协议，对应 0x0547，单次最多 100 个代码。

client.quotes.refresh(["sz000001"], cursors={"sz000001": 0})

refresh() 发起一次增量刷新请求。服务端主动推送帧会进入 transport 的 push queue，可用下面两个方法读取。

`client.quotes.get_depth(codes)`¶

按代码列表直接发起一次 0x0547 刷新，等价于 refresh(codes, cursors={})，返回 QuoteRefreshPage。首次刷新用于建立实时五档，后续可由推送队列增量更新；单次最多 100 个代码。

client.quotes.get_depth(["sz000001", "sh600000"])

`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)`¶

取出当前队列里已经收到的全部推送帧。

frames = client.quotes.drain_pushes()

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。这个入口不循环下载整文件。

chunk = client.resources.read("zhb.zip", offset=0, size=30000)

`download_file(path, chunk_size=30000, max_bytes=None)`¶

循环调用 0x06b9 并按实际返回长度拼接完整文件，返回 bytes。chunk_size 范围为 1..60000；max_bytes 可限制最多下载的字节数。

payload = client.resources.download_file("zhb.zip")

`read_stats(path="zhb.zip", chunk_size=30000)`¶

下载并解析 zhb.zip 中的 tdxstat.cfg 和 tdxstat2.cfg，返回 TdxStatsResource。两个 CFG 使用 GBK 解码，结构化字段可通过 stats.row(market_id, code) 查询。

stats = client.resources.read_stats()
stat, stat2 = stats.row(0, "000001")

该解析只针对已知的 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, bar_time="start")`¶

查询 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)
client.bars.get("sz000001", period="5m", count=48, bar_time="end")

all_pages=False 时校验并使用 count，只请求一页。all_pages=True 时使用 page_size 自动请求到空页，max_pages 防止异常情况下无限循环，返回合并后的 KlineSeries。短页不会提前停止。

code 传入字符串时返回单个 KlineSeries；传入代码列表时按连接池并发逐只请求，返回以规范化完整代码为键的字典。batch_size 控制同时请求的最大代码数，默认跟随连接池容量；列表中的重复代码会去重。

bar_time 控制分钟级 bar 的时间戳语义："start"（默认）= 通达信原始的开始时间（上午最后一根 5 分钟 bar 标 11:25、下午第一根标 13:00）；"end" = 右端点（= 开始 + 一个周期时长，同一根标 11:30），用于对齐 Tushare / 同花顺。日线及以上周期不受影响（只有日期，无"一根 bar 跨多久"的问题），因此对现有日线调用完全无影响。周期时长取自响应中已解析的 period_raw / period_param_raw，故 period="13m" 这类多分钟周期也能正确偏移 13 分钟；非法取值抛 ValueError。

返回字段包括 period_name、adjust_mode、bars；每根 K 线提供 time、open/high/low/close、volume_lots 和 amount。

`client.delisted_bars`¶

`get(code, period="day", start=0, count=800, adjust=None, include_raw=False, all_pages=False, page_size=800, max_pages=200, batch_size=None)`¶

查询退市股票的不复权日线。code 为字符串时返回 KlineSeries；为列表或元组时返回 {标准代码: KlineSeries}。仅支持日线、不复权，传入其他周期或复权模式会抛出 ValueError。

client.delisted_bars.get("T000038", count=20)
client.delisted_bars.get("sz000038", all_pages=True, page_size=800)
client.delisted_bars.get(["T000038", "002087"], all_pages=True, batch_size=2)

代码支持 T000038、sz000038 和 000038。单页上限 800 根，start=0 取最新页；all_pages=True 自动分页，直到返回空页，结果按日期升序合并。max_pages 默认 200，未到空页便达上限时抛出 RuntimeError。

批量查询时每只股票独立分页。batch_size 为正整数或 None，默认随连接池容量，实际并发不超过 pool_size。相同标准代码会合并，空列表会报错；任一股票查询失败时，整次调用会抛出异常。

volume_wire_value 和 volume_raw 为股数，volume_lots 为手数，amount 为成交额（元）。time 以上海时区当天 00:00 表示交易日期。完整参数和返回字段见退市 K 线接口。

`client.minutes`¶

`today(code, include_raw=False, batch_size=None)`¶

查询主站当前保存的分时，对应 0x0537。凌晨、周末或节假日可能返回最近交易日数据。

client.minutes.today("sz000001")
client.minutes.today(["sz000001", "sh600487"], batch_size=8)

当日分时接口：查询当天每分钟行情。传单个代码返回 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.minutes.sparkline("sz000001", selector=1)

`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 盘后固定价格真实成交。

client.trades.today("sz000001", start=0, count=1800)
client.trades.today(["sz000001", "sh600000"])

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；不传日期查询当日，传入日期查询历史。标准客户端使用专用候选节点，启用测速时排名在客户端构造阶段完成，首次调用时才建连和握手；它不是逐笔成交接口，即使返回 09:25:00 也仍按快照解释。

client.auctions.series("sz000001")
client.auctions.series("sz000001", "2026-05-20")

`client.money_flow`¶

`daily(code, include_raw=False, batch_size=75)`¶

读取一只或多只证券最近的日资金流向分档数据，对应 0x0ffc。传入字符串返回 MoneyFlowBlock，传入代码列表返回 MoneyFlowBatch。该接口使用独立的专用主站池；启用测速时排名在客户端构造阶段完成，首次调用时才建立业务连接并握手。

flow = client.money_flow.daily("sz000063")
print(flow.records[0].date, flow.records[0].main_net)

完整参数和返回字段见资金流向日数据。

`history(code, *, days=60, start=0, count=None, include_raw=False, batch_size=75)`¶

历史日资金流向，走 7615 TQLEX 的 CWServ.tdxf10_gg_sj 区间通道（{"Params": ["zjlx_sj", code, str(days), code]}）。days 只接受 3 / 5 / 10 / 20 / 60，其它值抛 ValueError；start / count 是拿到响应后的客户端切片，count 上限 800。传单个代码返回 FundFlowRangeSeries（定义在 eltdx.models.money_flow，已由 eltdx.models 导出），传代码列表返回 dict[str, FundFlowRangeSeries]（键为规范化后的完整代码）。

返回值原样保留服务端 N00x 列，不做语义臆测：N001 日期、N002 代码、N003 名称、N004 主力净额、N005 超大单净买入、N006 大单净买入、N007 主买净额、N009 上市日期。行序即服务端顺序。

不再使用 7709 0x052d 的 category 22

旧实现走 K 线命令的 22 号周期，实测 18 台可达主站（普通池 + 资金流向专用池）对该 category 一律返回 2 字节 0000 空 payload，而同一连接上的 category=4（日线）正常有数据——属服务端行为。真实客户端走的就是本 7615 通道，因此 history() 不再碰 7709，也不做空数据换台（旧 DTO FundFlowHistorySeries 仍在 Rust 侧导出，但已不是本方法的返回值）。

series = client.money_flow.history("sz000001")                        # 默认 60 日
window = client.money_flow.history("688004", days=60, start=0, count=5)
batch = client.money_flow.history(["sz000001", "sh600000"], days=20)

print(window.count, window.rows[0])
print(sorted(batch))

history() 与 7709 0x052d 的 period="flow" 无关：client.bars.get(..., period="flow") 会直接抛 ValueError，因为它返回的不是 OHLC。完整说明见资金流向日数据。

`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 线。start_date=None 使用全部有日期的权息事件，不会自动推断服务端第一根可用 K 线日期。

client.corporate.adjustment_factors(
    "sz000858",
    anchor_date="2024-06-03",
    start_date="1998-04-27",
)

应用到本地不复权 K 线时，必须以第一根 K 线日期设置 start_date；前复权选择第一条满足 bar_date < factor.date 的系数，后复权选择最后一条满足 factor.date <= bar_date 的系数，再计算 round(raw * scale + offset, 2)。本地计算与服务端复权价格可能存在差异，已知样本中约为 0.01～0.02 元。直接获取服务端复权 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。

client.limits.special(start_index=0)

0x0452 按表内行号分页取记录。需要查询某个代码时，先扫描建本地索引：

records = client.limits.scan_special()

`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：

response = client.f10.hot_topics("000034")
print(response.entry)
print(response.rows[:3])

分区驱动方法¶

以下 9 个方法把整页的多个分区合并成一个入口，用 section 选择分区（合法取值见 F10_7615.md 与 eltdx f10 sections）：

调用方法	分区数	底层 Entry
`shareholders(code, section="count", *, report_date=None, kind="000", filter1="", filter2="", page=1, page_size=20)`	11	`CWServ.tdxf10_gg_gdyj`（`institution_holdings` 走 `CWServ.tdxf10_gg_gdyj_jgcgmx`）
`capital_structure(code, section="structure", *, date=None)`	5	`CWServ.tdxf10_gg_gbjg`（`restricted_detail` 走 `CWServ.tdxf10_gg_gbjg_xsjjmx`）
`business_report(code, section="business", *, report_date=None)`	6	`CWServ.tdxf10_gg_jyfx`
`industry_analysis(code, section="peers", *, arg="")`	10	`CWServ.tdxf10_gg_hyfx`（`comparable` / `comparable_profile` 走 `CWServ.tdxf10_gg_kbgs`）
`trading_report(code, section="margin", *, arg="", date=None, page=1, page_size=20)`	11	`CWServ.tdxf10_gg_jyds`（`margin_history` 走 `CWServ.tdxf10_gg_sj`）
`fund_report(code, section="basic", *, arg="", date=None, page=1, page_size=20)`	30	`CWServ.skef10_jj_*`
`market_report(code, section="board_info", *, arg="", date=None, page=1, page_size=20)`	20	`CWServ.skef10_bk_` / `skef10_zs_` / `skef10_dpzx_*`
`profit_forecast(code, section="ylyctj")`	5	`CWServ.tdxf10_gg_ybpj`
`digest(code, section="tips", *, page=1, page_size=20)`	8	`CWServ.tdxf10_gg_zxts`（`interaction` 走 `CWServ.tdxf10_gg_zxtstzzhd`）

client.f10.shareholders("688004", "count")
client.f10.capital_structure("688004", "buyback")
client.f10.business_report("688004", "customers", report_date="20260630")
client.f10.industry_analysis("688004", "valuation", arg="011")
client.f10.trading_report("688004", "margin_history")
client.f10.fund_report("510300", "dividends")
client.f10.market_report("880472", "board_flow")
client.f10.profit_forecast("688004", section="yzyq")
client.f10.digest("688004", "events")
client.f10.industry_analysis("688004", "comparable")

ETF / 场外基金、板块 / 指数 / 大盘共用同一批方法，靠 code 与 section 分派；资金流向仍由 client.money_flow.history() 提供，trading_report() 不重复实现。

需要直接调用 Entry 时，可以使用通用 TQLEX 调用：

client.f10.call("CWServ.tdxf10_gg_gsgk", params=["8", "000034", ""])

完整 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")

`client.helpers.market_stat()`¶

全市场涨跌统计概览，来自统计指数 sh880005 / sh880001 / sh880006（0x053e 旧版批量行情一次取回）。

with TdxClient(timeout=3) as client:
    stat = client.helpers.market_stat()
    print(stat.up_count, stat.down_count, stat.limit_up_count, stat.total_amount)

返回 MarketStat（up_count / down_count / neutral_count / suspended_count / total_count / total_amount / total_volume / total_market_cap / limit_up_count / limit_down_count）。详见 helpers/全市场统计.md。

`client.helpers.today_fund_flow(code)`¶

个股当日资金流向分布，基于当日 L1 逐笔成交（0x0fc5）本地分类。

with TdxClient(timeout=3) as client:
    flow = client.helpers.today_fund_flow("sz000001")
    print(flow.main_net_inflow, flow.total_net_inflow)

返回 FundFlow（super_in / large_in / medium_in / small_in 与对应 _out，以及 main_net_inflow / total_net_inflow）。详见 helpers/当日资金流.md。

`client.company_info`¶

F10 公司信息的 7709 协议通道（与 HTTP 的 client.f10 并列）。

`category(code, market)` — `0x02cf`¶

读取公司信息文件的段落目录，返回 list[CompanyInfoCategory]（name / filename / start / length）。

`content(code, market, filename, offset, length)` — `0x02d0`¶

按目录读取某段正文，返回 GBK 解码后的 str。

详见 methods/0x02cf-公司信息目录接口.md 与 methods/0x02d0-公司信息内容接口.md。

`client.resources.block_meta(filename)` — `0x02c5`¶

查询板块文件在服务器上的字节大小与 MD5，返回 BlockMeta（size / md5）。详见 methods/0x02c5-板块文件元数据接口.md。

扩展行情 `eltdx.ex`（端口 7727）¶

期货、期权、港股、外盘、外汇等非 A 股市场走独立的扩展行情协议（7727）。它是独立子包，自带连接与帧编解码，不经过 7709 引擎。

from eltdx.ex import ExTdxClient

with ExTdxClient.from_best_host() as client:
    print(client.get_instrument_count())
    quote = client.get_instrument_quote(47, "IFL0")
    bars = client.get_instrument_bars(4, 47, "IFL0", count=100)   # category, market, code
    intraday = client.get_instrument_bars(0, 47, "IFL0", count=48, bar_time="end")

注意 get_instrument_bars 的第一个参数是 category（周期），第二个才是 market。 早期文档曾把它写成 get_instrument_bars(market, code)，那是错的——会把 market 当成 category，请以 EXTENDED_MARKET.md 的签名为准。

不要用 get_markets() 做首条调用。 实测所有内置主站都不回应 0x23f4，该调用只会阻塞到超时；这与 eltdx 无关——easy_tdx 1.20.7 在同一主机上同样超时，且两者请求帧逐字节相同。需要市场清单请直接用 ExMarket 枚举。证据链见 EXTENDED_MARKET.md。

ExTdxClient 提供 get_markets / get_instrument_count / get_instrument_info / get_instrument_quote / get_instrument_quote_list / get_instrument_bars / history_instrument_bars_range / minute_time / history_minute_time / transaction / history_transaction；港股逐笔自动翻页。ExMarket 枚举描述支持的扩展市场。详见 EXTENDED_MARKET.md。

MAC 协议 `eltdx.mac` 与 MAC-EX `eltdx.ex.MacExClient`¶

MAC 协议（0x1c 帧）覆盖批量报价、分类排行、复权 K 线、多日分时、逐笔、板块、集合竞价、异动等。

from eltdx.mac import MacClient, Period, Adjust

with MacClient() as client:
    quotes = client.get_stock_quotes([(0, "000001"), (1, "600000")])   # [(market, code), ...]
    bars = client.get_stock_kline(0, "000001", period=Period.DAILY, adjust=Adjust.QFQ)
    intraday = client.get_stock_kline(0, "000001", period=Period.MIN_5, count=48, bar_time="end")

get_stock_quotes 收的是 (market, code) 元组列表，不是裸代码字符串； get_stock_kline 的前两个位置参数是 market, code，且周期枚举叫 Period.DAILY （没有 Period.DAY）。

MAC-EX（from eltdx.ex import MacExClient）在扩展行情连接上使用 MAC 风格命令（登录 0x2454 + goods 系列）。详见 EXTENDED_MARKET.md。

本地行情文件 `eltdx.offline`¶

读写通达信本地行情文件，纯标准库实现，不联网。

from eltdx import offline

bars = offline.read_daily_bar("sz000001")          # vipdoc 下的 .day
offline.write_daily_bar("sz000001", bars)          # 写回 / 追加
mins = offline.read_min_bar("sz000001")             # .lc1/.lc5
exbars = offline.read_ex_daily_bar(...)             # 扩展市场日线
blocks = offline.read_gbbq(...)                     # 股本变迁

入口：read_daily_bar / write_daily_bar / read_min_bar / write_min_bar / read_ex_daily_bar / write_ex_daily_bar / read_block / read_gbbq / read_history_financial。详见 OFFLINE.md。

专业财报 `eltdx.financial`¶

从计算服务器下载并解析专业财报文件（tdxfin/gpcw.txt 与 gpcwYYYYMMDD.zip）。底层复用 0x06b9 文件下载能力（ResourceApi.download_file），不做重复实现。

from eltdx import TdxClient
from eltdx.financial import list_archive_files, download_records, open_calc_client

with open_calc_client() as client:                 # 指向计算服务器
    files = list_archive_files(client)
    records = download_records(client, files[0].filename)

详见 FINANCIAL.md。

API 参考¶

总入口¶

组合与便捷方法¶

client.helpers.board_quotes() / client.helpers.board_member_quotes(board_code)¶

client.helpers.full_quotes(codes)¶

client.quotes.get_depth(codes)¶

代码表便捷方法¶

K 线便捷方法¶

分时和成交明细便捷方法¶

集合竞价便捷方法¶

股本变迁和本地复权系数¶

低频数据缓存¶

include_raw¶

JSON 输出¶

client.session¶

handshake()¶

heartbeat()¶

client.codes¶

count(market)¶

list(market, start=0, limit=1600)¶

all(market)¶

client.quotes¶

client.quotes.get_snapshots(codes)¶

legacy(codes)¶

list_by_category(category, sort_by=None, start=0, count=80, ascending=False)¶

refresh(codes=None, cursors=None)¶

client.quotes.get_depth(codes)¶

poll_push(timeout=0.0, parse=False)¶

drain_pushes(parse=False)¶

client.resources¶

read(path, offset=0, size=30000)¶

download_file(path, chunk_size=30000, max_bytes=None)¶

read_stats(path="zhb.zip", chunk_size=30000)¶

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, bar_time="start")¶

client.delisted_bars¶

get(code, period="day", start=0, count=800, adjust=None, include_raw=False, all_pages=False, page_size=800, max_pages=200, batch_size=None)¶

client.minutes¶

today(code, include_raw=False, batch_size=None)¶

history(code, trading_date, include_raw=False, batch_size=None)¶

recent(code, trading_date=None, include_raw=False, batch_size=None)¶

aux(code, kind="buy_sell_strength", include_raw=False)¶

sparkline(code, selector=1, window=20, include_raw=False)¶

client.trades¶

today(code, start=0, count=1800, include_raw=False, batch_size=None)¶

history(code, trading_date, start=0, count=1800, include_raw=False, batch_size=None)¶

client.auctions¶

series(code, date=None, include_raw=False)¶

client.money_flow¶

daily(code, include_raw=False, batch_size=75)¶

history(code, *, days=60, start=0, count=None, include_raw=False, batch_size=75)¶

client.corporate¶

capital_changes(code_or_codes, include_raw=False, batch_size=75)¶

adjustment_factors(code_or_codes, anchor_date=None, *, start_date=None, batch_size=75)¶

finance_batch(codes, fields=None, include_raw=False)¶

client.limits¶

special(start_index=0)¶

client.f10¶

分区驱动方法¶

client.helpers¶

client.helpers.market_stat()¶

client.helpers.today_fund_flow(code)¶

client.company_info¶

category(code, market) — 0x02cf¶

content(code, market, filename, offset, length) — 0x02d0¶

client.resources.block_meta(filename) — 0x02c5¶

扩展行情 eltdx.ex（端口 7727）¶

MAC 协议 eltdx.mac 与 MAC-EX eltdx.ex.MacExClient¶

本地行情文件 eltdx.offline¶

专业财报 eltdx.financial¶

`client.helpers.board_quotes()` / `client.helpers.board_member_quotes(board_code)`¶

`client.helpers.full_quotes(codes)`¶

`client.quotes.get_depth(codes)`¶

`include_raw`¶

`client.session`¶

`handshake()`¶

`heartbeat()`¶

`client.codes`¶

`count(market)`¶

`list(market, start=0, limit=1600)`¶

`all(market)`¶

`client.quotes`¶

`client.quotes.get_snapshots(codes)`¶

`legacy(codes)`¶

`list_by_category(category, sort_by=None, start=0, count=80, ascending=False)`¶

`refresh(codes=None, cursors=None)`¶

`client.quotes.get_depth(codes)`¶

`poll_push(timeout=0.0, parse=False)`¶

`drain_pushes(parse=False)`¶

`client.resources`¶

`read(path, offset=0, size=30000)`¶

`download_file(path, chunk_size=30000, max_bytes=None)`¶

`read_stats(path="zhb.zip", chunk_size=30000)`¶

`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, bar_time="start")`¶

`client.delisted_bars`¶

`get(code, period="day", start=0, count=800, adjust=None, include_raw=False, all_pages=False, page_size=800, max_pages=200, batch_size=None)`¶

`client.minutes`¶

`today(code, include_raw=False, batch_size=None)`¶

`history(code, trading_date, include_raw=False, batch_size=None)`¶

`recent(code, trading_date=None, include_raw=False, batch_size=None)`¶

`aux(code, kind="buy_sell_strength", include_raw=False)`¶

`sparkline(code, selector=1, window=20, include_raw=False)`¶

`client.trades`¶

`today(code, start=0, count=1800, include_raw=False, batch_size=None)`¶

`history(code, trading_date, start=0, count=1800, include_raw=False, batch_size=None)`¶

`client.auctions`¶

`series(code, date=None, include_raw=False)`¶

`client.money_flow`¶

`daily(code, include_raw=False, batch_size=75)`¶

`history(code, *, days=60, start=0, count=None, include_raw=False, batch_size=75)`¶

`client.corporate`¶

`capital_changes(code_or_codes, include_raw=False, batch_size=75)`¶

`adjustment_factors(code_or_codes, anchor_date=None, *, start_date=None, batch_size=75)`¶

`finance_batch(codes, fields=None, include_raw=False)`¶

`client.limits`¶

`special(start_index=0)`¶

`client.f10`¶

`client.helpers`¶

`client.helpers.market_stat()`¶

`client.helpers.today_fund_flow(code)`¶

`client.company_info`¶

`category(code, market)` — `0x02cf`¶

`content(code, market, filename, offset, length)` — `0x02d0`¶

`client.resources.block_meta(filename)` — `0x02c5`¶

扩展行情 `eltdx.ex`（端口 7727）¶

MAC 协议 `eltdx.mac` 与 MAC-EX `eltdx.ex.MacExClient`¶

本地行情文件 `eltdx.offline`¶

专业财报 `eltdx.financial`¶