API 接口要点¶
通讯协议及数据包¶
- 通讯协议为标准websocket协议，服务地址为 ws://127.0.0.1:7777/, 不使用ssl及数据压缩
- 每个数据包均为 json 编码的 object, UTF-8 编码
- 每个数据包中均有一个 aid 字段，此字段值即为数据包名
- 允许数据包中携带协议中未写出的额外字段，接收方可以忽略这些字段的信息
- 当数值型字段的值为 NAN 时，在json中以字符串 "NAN" 表示。
异步通讯¶
协议按双向异步结构设计，任何一方都可以随时向对方发送数据包，也应该随时准备接收对方发来的数据包。发出的包之间无需等待对方回应。
从主进程接收业务数据¶
当从主进程向扩展进程发送数据时, 与其它很多协议不同, 天勤的通讯协议并不会按照 "类别" 或 "请求", 将数据分解为多个包发送. 相反, 天勤只使用一种包 rtn_data, 来将主程序内存中的全部数据 (实时行情, 历史行情, 交易数据等) 送往扩展进程. 为减少数据量, 主程序每次发送 rtn_data 时, 通常只包含与前次相比有差异的数据. ( 注意: 协议并不承诺无差异的数据一定不会发送 )
基于这一协议, 我们强烈建议 扩展进程应设法维护一个完整的业务信息存储区 (在内存,数据库或文件中), 并在每次收到 rtn_data 时更新此存储区中的内容. 扩展进程中的业务代码, 应从这一存储区中获取业务信息, 而 不要直接让业务逻辑处理接收到的每个:ref:`rtn_data`包
请求实时行情数据¶
扩展进程可以发送 subscribe_quote 来请求订阅行情数据, 需要注意几点:
- 合约代码必须带交易所代码, 例如cu1801应该写作 SHFE.cu1801. 目前支持的交易所为 CFFEX, SHFE, DCE, CZCE, INE
- 用户自定义的组合, 交易所代码都为 USER
- 合约代码及交易所代码都是大小写敏感的
- 主进程给扩展进程推送的实时行情, 不保证只含有订阅的合约, 未订阅合约的行情也可能在数据包中出现
获取K线及Tick线数据¶
扩展进程可以发送 set_chart 来请求订阅图表数据, 需要注意几点:
- 合约代码必须带交易所代码, 合约代码及交易所代码都是大小写敏感的
- 主进程给扩展进程推送的数据, 不保证只含有订阅的合约
技术指标扩展¶
扩展进程可以为主进程提供自定义技术指标，实现步骤如下：
- 扩展进程向主进程发送 register_indicator_class 包，声明本扩展进程可以实现哪些技术指标
- 用户在主进程图表中添加/修改/删除技术指标时，主进程发送 update_indicator_instance 包 或 delete_indicator_instance 给扩展进程
- 扩展进程负责计算各技术指标实例的指标值，并将计算结果通过 set_indicator_data 包发送给主进程
- 主进程收到 set_indicator_data 包后，在图表上更新显示
- 一般情况下，扩展进程可以通过 rtn_data 得到计算技术指标所需的行情数据。（非必需，技术指标也可以基于其它任何数据源计算）
交易指令¶
扩展进程可以通过 insert_order 和 cancel_order 来实现报单及撤单, 注意要点:
- 天勤对于实盘交易和模拟交易使用相同的KEY机制: unit_id + order_id. 这两者都是由下单者指定的任意字符串, 不限长度
- unit_id 为交易单元, 用作委托单的逻辑分组, 用户可以将自己认为有逻辑关联的一批委托单使用同一个unit_id报单, sdk支持按unit_id过滤处理
- order_id 为用户单号, 由下单方任意指定. 同一个 unit_id 下 order_id 应该确保不重复
See also¶
如果您需要将自己的程序连接到此扩展接口，下面是一些可能有用的资源:
python¶
python的标准库中没有包含websocket协议，因此你需要安装一个第三方库来实现通讯。 我们用过 tornado，这里还有一些其它的推荐 https://github.com/vinta/awesome-python#websocket
javascript¶
javascript为websocket及json提供了原生支持，不需要任何第三方库