tdxquant 0.1.0

通达信量化(TdxQuant) HTTP SDK —— 统一返回 DataFrame，字段金融规范化(snake_case)

tdx-api

通达信量化（TdxQuant）HTTP SDK —— 直接调用通达信客户端官方 HTTP 接口（POST http://127.0.0.1:17709/），统一返回 pandas.DataFrame，字段重命名为金融行业规范的 snake_case。

工作方式

通达信量化客户端原生提供 HTTP 调用方式（无需 tqcenter / DLL / 自建网关）：

你的代码(SDK) ──HTTP/JSON──► 通达信客户端(127.0.0.1:17709)

1. 启动支持 TQ 的通达信客户端（它会监听 127.0.0.1:17709）
2. SDK 直接 POST 调用，字段重命名 + DataFrame 封装在 SDK 内完成

请求格式：{"id":1, "method":"<tqcenter方法名>", "params":{...}}，method 为 tqcenter 函数名，params 为底层参数名。

安装

uv sync          # 本地开发
# 或 pip install -e .

需要 Python ≥ 3.13、通达信金融终端（量化模拟版 / 专业研究版等支持 TQ 策略的版本）。

快速开始

from tdx_api import TdxAPI

api = TdxAPI()   # 默认 http://127.0.0.1:17709，需通达信客户端在线

# K线（OHLCV 长表）
df = api.get_kline("000001.SZ", freq="daily", adjust="qfq", start_date="20260101")
# 实时快照
snap = api.get_snapshot("000001.SZ")
# 股票 / 板块 / ETF
api.get_stock_list()                   # 所有分类合并(带 market/category 列)
api.get_sector_list()
api.get_track_etf("000300.SH")
# 财务
api.get_financial("600519.SH", fields=["Fn193","Fn194"], start_date="20240101")
# 交易日历
api.get_trading_calendar("20260101", "20260613")

从别的机器调用：TdxAPI(base_url="http://通达信机器IP:17709")。

接口总览

类别	方法	说明
行情	get_kline	K线（OHLCV 长表）
	get_snapshot	实时快照（五档）
	get_instrument_info / get_more_info	基本信息
	get_dividend_factors	分红送配
财务	get_financial / get_financial_by_date	专业财务（FNxxx）
	get_stock_trade_data(_by_date)	股票交易（GPx）
	get_sector_trade_data(_by_date)	板块交易（BKx）
	get_market_trade_data(_by_date)	市场交易（SCx）
	get_stock_single_data	单点数据（GOx）
	get_share_capital(_by_date)	股本数据
板块	get_stock_list	分类成分股（market 不传返回全部，带 market/category 列）
	get_sector_list / get_user_sectors	板块列表
	get_sector_stocks	板块成分股
证券	get_convertible_bond	可转债
	get_ipo_info	新股/新债申购
	get_track_etf	跟踪指数的 ETF
日历	get_trading_dates / get_trading_calendar	交易日

交易类（order_stock）按需求不做。完整参数与字段说明见 docs/api_reference.md。

字段命名规范

• 全部 snake_case 小写，采用金融行业惯例（OHLCV / bid-ask / nav / pct_chg）。
• 原字段 → 新字段完整血缘见 docs/field_lineage.md。
• 通达信专业编码字段（FNxxx/GPx 等）保留转小写，需对照通达信字段手册。

代码格式：000001.SZ / 600519.SH（6 位 + 市场后缀）；频率 daily/5min/...； 复权 none/qfq/hfq；日期严格 YYYYMMDD（区间用 start_date/end_date，按日期点用 date）。

测试

uv run pytest                     # 单元测试（字段血缘契约 + 拼装逻辑）
uv run pytest --runintegration    # 集成测试（需通达信客户端在线）

项目结构

tdx_api/
├── client.py          # HTTP 客户端（POST 17709）+ DataFrame 拼装
├── schema.py          # 字段血缘映射表（唯一真实来源）
├── enums.py           # Freq / Adjust 枚举 + validate_date 日期校验
├── exceptions.py      # 异常
└── api/               # 各业务接口（mixin）
    ├── market.py  financial.py  sector.py  instrument.py  calendar.py

常见问题

• server return none / 连接失败：确认通达信客户端已启动并登录行情；SDK 默认连 127.0.0.1:17709。
• 502 Bad Gateway：本机代理（Clash/V2Ray）劫持 localhost 请求。SDK 已默认 trust_env=False 直连，若仍异常请关闭代理。
• 财务/专业数据为空：需先在通达信客户端下载对应盘后/专业财务数据。
• get_financial 报 end_time 缺失：底层要求结束日期，end_date 留空时 SDK 自动取当天。