XtTraderApi 开发 Skill
北京睿智融科（迅投）统一交易 TraderApi 的权威开发参考。本 skill 把分散在原始包里的 demo、帮助文档、头文件（开发字典）整理为可直接查阅的知识库，并附带一个行情 + 交易独立自我验证示例。
> 原始包路径约定：本 skill 的 ../XtTraderApi_V1.6_20260727/（与本 skill 同级）即官方原始发布目录，内含 test/（各语言 demo）、doc/（C++/Java/C# API 文档 + 使用手册/常见错误 docx + PDF）、include/（C++ 头文件，即开发字典源头）、lib/（各平台 dll/lib/pyd）、config/（traderApi.ini 等）。
何时使用本 skill
- 编写/调试迅投 GT TraderApi 程序（Python 优先，亦含 C++/C#/Java 参考）
- 行情：订阅行情、主动请求行情快照、解析
CPriceData - 交易：股票/期货普通单、算法单、组合单、撤单/暂停/恢复
- 查询：资金、持仓、委托、成交、历史数据、产品、可下单量、股东号
- 排查：连不上服务器、登录失败、账户 key 状态异常、废单/撤单失败、流控
- 需要"开发字典"：市场代码、价格/委托/对冲/状态等枚举、请求/回调结构体、ini 配置项
核心工作流（务必按顺序）
1. createXtTraderApi(address) 创建 API 实例
2. setCallback(cb) 设置回调（继承 XtTraderApiCallback）
3. init("../config") 加载配置（默认读运行目录上一级 config/）
4. join() / join_async() 阻塞线程（单实例用 join；多实例必须用 joinAll/joinAll_async）
│
▼ onConnected(success, err) 连接结果回调
5. userLoginSync(...) / userLogin() 登录（machineInfo/appid/authcode 期货中继模式必填）
│
▼ onUserLogin / onRtnLoginStatusWithActKey
6. 等待账户 key 主推：status == BROKER_LOGIN_STATUS_OK（或 CLOSED）后才可交易
│
▼ 之后才能调用 行情/交易/查询 接口
关键约束（踩坑点）
- 只有
onRtnLoginStatusWithActKey返回账户status == BROKER_LOGIN_STATUS_OK（或CLOSED收盘后）时，该资金账号才真正可用，下单/查询前必须判此状态。 - 行情订阅/请求、下单、查询都依赖"资金账号 → accountKey"映射，来自
onRtnLoginStatusWithActKey的account_id / account_key / account_type（1期货 2股票 3信用）。 - 同步接口（带
Sync后缀，返回XtError/数据，用error.isSuccess()判断）与异步接口（带nRequestId，结果走onXxx回调）二选一；demo 同时演示了两种，按业务需要选。 - 多实例（
createXtTraderApi多次）必须用joinAll()/joinAll_async()，否则实例会退出。 - 股票下单市场只能填
SH/SZ，填错或为空会被 API 直接打回（废单）。期货平台号m_nPlatformID填20001。
目录导航
| 你想做的事 | 看这里 |
|---|---|
| 整体机制、回调清单 | references/api-index.md |
| 市场代码 / 枚举 / 结构体 / ini | references/dev-dictionary.md |
| 行情订阅 + 主动请求 | references/api-index.md 行情段 + dev-dictionary.md 的 CSubscribData/CPriceData |
| 下单 / 撤单 | references/api-index.md 交易段 + dev-dictionary.md 的 COrdinaryOrder/CAlgorithmOrder 等 |
| 账户/持仓/委托/成交查询 | references/api-index.md 查询段 |
| 跑一个能跑的自我验证 | examples/self_verify_quote_trade.py |
| 官方完整 demo | 原始包 test/Python/*.py、test/C++/demo1~8、test/C#/Program.cs、Java/src/test/* |
| 官方文档 | 原始包 doc/{c++ApiDoc,javaApiDoc,c#ApiDoc}/trader_api_help.html、doc/*.docx、doc/*.pdf |
快速示例：行情 + 交易自检
# 在含有 XtTraderPyApi 运行时的目录运行（见示例文件顶部说明）
python examples/self_verify_quote_trade.py
该示例会：连接→登录→等待账户就绪，然后独立对「行情」和「交易」两条链路做 PASS/FAIL 自检（行情：订阅/请求快照并校验字段；交易：校验账户状态 + 资金/可下单量查询；默认不真实下单，加 --trade 才做"小额下单即撤"闭环）。详见 examples/self_verify_quote_trade.py 头部注释。
常见错误速查（详见原始包 doc/TraderApi 常见错误文档.docx）
- 连接失败 / SSL：检查
traderApi.ini的isUseSSL、服务器地址端口、以及server.crt是否在 config 目录。 - 登录失败：用户名密码、
appid/authcode（期货中继必填）、machineInfo格式（IP|MAC|磁盘序列号|CPU|主机名|磁盘信息|CPUID|主板，无关字段填空）。 - 废单：市场代码错误、价格类型/委托类型枚举越界、委托量为 0、未等账户
OK状态就下单。 - 流控：
[flowControl]段useFlowControl/maxOrderNum/stockDurationMilliSec。 - 多实例退出：忘记
joinAll()。
语言支持
- Python：
test/Python/XtTraderPyApi.cp3xx-win_amd64.pyd+ 配套 dll；from XtTraderPyApi import *。 - C++：
test/C++/demo1~8+include/XtTraderApi.h、XtStructs.h、XtDataType.h。 - C#：
test/C#/（含headers/头文件）。 - Java：
Java/src/xti/（枚举与结构体已封装为 Java 类）+Java/src/test/demo。
