WebSocket对接协议

合约个数范围内可任意切换同类的合约
请求连接订阅合约或品种订阅指定分类订阅指定市场取消订阅
发送心跳维持连接***(重要)重新订阅/重连机制/数据接收处理
设置接收字段请求k线请求实时行情
命令输出和错误代码
备用调试编码
行情实体结构参考:model.html
品种合约代码信息参考:symbols.html
编码信息和连接日志查询:checkauth.html *期限信息,连接诊断信息这里查询
范例代码:C# WebSocket订阅范例
*备用调试编码:正式编码后加"DEV"3个字母,即为调试编码。在不影响正式编码使用同时,方便开发环境中调试。(调试编码只允许1连接点,只允许订阅BTC,推送频率为每秒)
*注意:只保证接口数据正常输出,不提供软件系统,限个人开发者使用,接口使用禁止涉及违法业务。
*注意:实现对接至少2个步骤,1-建立连接,2-订阅合约,3-发送心跳保持连接,4-断线重连机制

.请求连接

调用演示
ws.connect ws://(ip地址):(端口)/connect/json/(编码)
调用协议
地址:ws://ip:port/connect/{type}/{token}
协议:WS
参数:type,string,必填,返回数据结构选 json。接收信息和数据格式和该选择匹配
参数:token,string,必填,编码
输出:json
结构:参考 输出结构和错误代码*
范例json:{"Cmd":"connect","Code":0,"Msg":"connect xxx"}, 返回{"Cmd":"connect","Code":0,"Msg".... 代表成功。
text:connect:0:connect xxx, 返回 connect:0:.... 代表成功。
form:Cmd=connect&Code=0&Msg=connect xxx, 返回 Cmd=connect&Code=0&Msg=connect.... 代表成功。
注意:连接数超出允许连接数后,之前的连接会被系统关闭。
注意:连接失败请做日志,方便诊断问题,重复的多次连接建议间隔10秒以上,反复重连系统可能会认定异常并阻挡。
注意:由于系统/网络复杂,连接中断不可避免,建议在“发送心跳无正确返回”时执行重新连接。
↑回顶部

.订阅品种合约

订阅合约或品种,一次最多100个
调用演示
ws.send /sub/EURJPY,SH600128
调用协议
地址:/sub/{symbols}
协议:WS
参数:symbols,string,必填,完整代码,逗号分隔如BTC,EURJPY,单次最多100个代码品种合约代码信息查询*
参数:支持期货的分组订阅,如订阅CFFEXIC* 则代表订阅CFFEXIC,CFFEXIC1909,CFFEXIC2002...等合约
输出:json
结构:参考 输出结构和错误代码
范例json:{"Cmd":"sub","Code":0,"Msg":"sub:xxx"}, 返回{"Cmd":"sub","Code":0,"Msg".... 代表成功,如果接收到订阅不成功的信息,请记录日志,并需要再次执行订阅命令
text:sub:0:xxx
form:Cmd=sub&Code=0&Msg=xxx
说明:订阅成功后,系统即接收来自服务端的消息,消息的Cmd=rm即为输出实时行情数据,输出数据字段*参考行情实体结构
注意:如果已经订阅了分类,再订阅该分类下的品种,订阅品种将不成功
注意:如果订阅个数超过限制个数,新订阅的品种合约会替换最先订阅的品种合约。
注意:订阅失败请做日志,方便诊断问题,重复多次订阅命令建议间隔5秒执行,或应使用批量订阅。
↑回顶部

.订阅分类

指定分类订阅,一次可多个
调用演示
ws.send /subrout/GBDC,CNIF
调用协议
地址:/subrout/{routs}
协议:WS
参数:routs,string,必填,完整分类代码,逗号分隔。CNST:沪深A股,CNETF:沪深ETF,USST:美股,HKST:港股,GBFSB:外汇,GBCFD:CFD,GBFT:欧美海外期货(GBIF指数/GBCF商品/GBFF外汇),CNFT:国内期货(CNIF指数CNCF商品),GBDC:数字货币,GBIDX:全球股指
输出:json
结构:参考 输出结构和错误代码
范例json:{"Cmd":"subrout","Code":0,"Msg":"subrout:xxx"}, 返回{"Cmd":"subrout","Code":0,"Msg".... 代表成功,如果接收到订阅不成功的信息,请记录日志,并需要再次执行订阅命令
text:subrout:0:xxx
form:Cmd=subrout&Code=0&Msg=xxx
说明:订阅成功后,系统即接收来自服务端的消息,消息的Cmd=rm即为输出实时行情数据,输出数据字段*参考行情实体结构
注意:订阅失败请做日志,方便诊断问题,重复多次订阅命令建议间隔5秒执行,或应使用批量订阅。
↑回顶部

.订阅市场

指定市场订阅,一次可多个
调用演示
ws.send /submkt/TAI,NYMEX
调用协议
地址:/submkt/{markets}
协议:WS
参数:markets,string,必填,完整市场代码,逗号分隔。
输出:json
结构:参考 输出结构和错误代码
范例json:{"Cmd":"submkt","Code":0,"Msg":"submkt:xxx"}, 返回{"Cmd":"submkt","Code":0,"Msg".... 代表成功,如果接收到订阅不成功的信息,请记录日志,并需要再次执行订阅命令
text:submkt:0:xxx
form:Cmd=submkt&Code=0&Msg=xxx
说明:订阅成功后,系统即接收来自服务端的消息,消息的Cmd=rm即为输出实时行情数据,输出数据字段*参考行情实体结构
注意:订阅失败请做日志,方便诊断问题,重复多次订阅命令建议间隔5秒执行,或应使用批量订阅。
↑回顶部

.取消订阅

取消订阅,可多个
调用演示
ws.send /unsub/EURJPY,SH600128
调用协议
地址:/unsub/{symbols}
协议:WS
参数:symbols,string,必填,完整代码或分类,逗号分隔如BTC,EURJPY,CNIF
输出:json
结构:参考 输出结构和错误代码
范例json:{"Cmd":"unsub","Code":0,"Msg":"unsub:xxx"}
text:unsub:0:xxx
form:Cmd=unsub&Code=0&Msg=xxx
↑回顶部

.发送心跳命令,维持连接

服务器端60秒内没有收到连接客户端的心跳命令,将中断该客户端连接
心跳命令可选2个方式发送。方式1.定时每15-60秒内,向服务器端发送心跳命令
方式2.在接收到服务端信息{"Cmd":"heartbeat","Msg":"ping"} 或 heartbear:0:ping 或 Cmd=heartbeat&Code=0&Msg=ping 时,向服务端发送心跳命令
调用演示
ws.send /heartbeat/ok
调用协议
地址:/heartbeat/ok
协议:WS
输出:json
结构:参考 输出结构和错误代码
接收范例json:{"Cmd":"heartbeat","Code":0,"Msg":"ok"}。同样的:如果连续2次发送心跳都没有收到服务端返回的正确信息,则可以认为数据连接已经中断
text:heartbeat:0:ok
form:Cmd=heartbeat&Code=0&Msg=ok
↑回顶部

.重连机制、重新订阅、数据接收处理

1非常重要!重新连接:由于系统/网络复杂,连接中断不可避免,建议每15秒发送心跳,如果连续2次心跳返回不正确/或无返回,则执行重连
2非常重要!重新订阅:如果客户端监测某订阅品种合约无数据接收,不确定是否正确订阅的,可以再次订阅该品种合约
3、不应频繁重连,如果1分钟内超过10次重连,系统会临时屏蔽来自该编码或IP的连接
4、建立的连接数不应超过允许的最大连接数,超过会导致连接中断和数据异常
5、相同命令发送间隔建议5秒以上
6非常重要!数据接收处理:接收到的数据直接进入进队列或做异步逻辑处理,不要做任何同步的耗时处理逻辑,避免接收数据堵塞。
↑回顶部

.设置接收字段

可选功能。指定接收字段,如不指定则传输默认字段(默认字段并非全部),指定后只返回指定字段
调用演示
ws.send /fields/P,Z,Z2,TS,H1,JS
调用协议
地址:/fields/{fields}
协议:WS
参数:fields,string,必填,字段,逗号分隔如Z,Z2,TS,H1,字段请参考 行情实体结构参考
输出:json
结构:参考 输出结构和错误代码
范例json:{"Cmd":"fields","Code":0,"Msg":"fields:xxx"}
text:fields:0:...
form:Cmd=fields&Code=0&Msg=...
↑回顶部

.请求K线

请求一次品种合约某周期最近k线,返回一次性数据,最多25(默认)~90~180~365~730个k数据(视订阅等级定),限制频率每分钟在(订阅个数*8,最大300)次以内。*只能请求正在订阅中的合约的k线
获得连续的K线:持续请求各周期k线并存储更新本地,即可得到连续的历史k线数据。举例:5分钟周期的k线数据每间隔5分钟会产生最近的一个,5分钟请求一次获取即可。依此类推10分钟周期的k线数据间隔10分钟才会产生最近一个,10分钟请求一次获取即可...
更多历史请用http请求获取
调用演示
ws.send /reqk/BTC,1M,10
调用协议
地址:/reqk/{symbol},{period},{num}
协议:WS
参数:symbol,string,必填,完整品种合约代码
参数:period,string,必填,周期1M,3M,5M,10M,15M,30M,1H,2H,4H,D
参数:num,int,必填,1~25~90~180~365~730
输出:json
结构:参考 输出结构和错误代码
范例json:{"Cmd":"reqk-{symbol}-{period}","Code":0,"Msg":"xxx"},Code=0表示成功,且Msg代表输出数据,结构如下
text:reqk-{symbol}-{period}:0:xxx
form:Cmd=reqk-{symbol}-{period}&Code=0&Msg=xxx
Msg:秒时间戳,开,高,低,收,量;秒Tick,Open,High,Low,Close,Vol (数据之间逗号分隔,k之间分号分隔) 如 1582424400,9664.9,9664.9,9664.8,9664.8,1.12;1582424340,9664.9,9665,9661.8,9664.9,26.93
说明:订阅成功后,系统即接收来自服务端的一次性消息,当前的一个动态k线数据是实时推送的,参考*设置接收字段*
注意:相同命令(含参数)重复执行需间隔15秒执行,只能请求正在订阅中的合约(就是已经执行sub成功的合约)的k线
↑回顶部

.请求实时行情

请求一次指定合约的实时行情,返回一次性数据,限制频率每分钟5次以内。*只能请求正在订阅中的合约的行情
部分数据更新比较慢,推送频率很低,此功能可作为补充,及时主动获取
调用演示
ws.send /req/BTC,EURJPY
调用协议
地址:/req/{symbol}
协议:WS
参数:symbol,string,必填,完整品种代码,多个逗号分隔
输出:json
结构:输出结构和行情订阅一样
说明:订阅成功后,系统即接收来自服务端的一次性 cmd=rm的消息
注意:只能请求正在订阅中的合约(就是已经执行sub成功的合约)的行情
↑回顶部

.命令输出和错误代码

结构
json: {"Cmd":"请求源","Code":0,"Msg":""}
text: Cmd:Code:Msg
form: Cmd=请求源&Code=0&Msg=xxx
说明
Code >= 0,调用成功
Code <0 表示调用失败,并输出错误信息 Msg 失败提示
Cmd,请求源
↑回顶部

.行情实体结构参考

model.html
输出结构和连接时使用的参数匹配
json: {"Cmd":"rm","M":"xx","S":"xx","C":"xx" .... }
text: rm:M,S,C ....
form: Cmd=rm&M=xx&S=xx&C=xx...
↑回顶部