综合交易平台API开发简介
大纲
1 Api概述
2 通用规则
3 交易业务
4 行情业务
综合交易平台Api包括交易Api和行情Api。交易Api建立在Tcp协议上,实现了客户端和综合交易平台之间的双向异步通讯。行情Api可以运行在Tcp或者在Udp协议上。下面把综合交易平台简称为Thost,交易Api简称为TraderApi,行情Api简称为MdUserApi。上述2种Api统称为Api。
概述 - 通讯模式
Api有3种通讯模式:
1、 对话通讯模式:由客户端主动发起请求。Thost收到请求、处理请求后,返回1条或者多条响应纪录。例如登入、各项查询、报单、撤单等操作;2、私有通讯模式:由Thost主动向客户端发出的相关信息。例如委托回报、成交回报、错单回报等;3、广播通讯模式:由Thost主动向所有客户端发出的公共信息,例如行情等。
有3种方式订阅公有流和私有流
enumTHOST_TE_RESUME_TYPE
{
// 从当天的第一条记录开始接收数据流
THOST_TERT_RESTART = 0,
// 接收上次断线以后的数据流
THOST_TERT_RESUME,
// 接收本次登入以后的数据流
THOST_TERT_QUICK
};
概述 - 初始化过程
MdUserApi的初始化过程比较简单,默认按照Quick的方式订阅公有流和私有流。
概述 - 样例代码
TraderApi样例代码:testTraderApi
– 初始化,登入,确认结算结果,查询合约,查询资金,查询持仓,报单,收委托回报,撤单
MdUserApi样例代码:testMdUserApi
– 初始化,登入,订阅,收行情
概述 - 接口文件
TraderApi接口文件:
ThostFtdcTraderApi.h:
定义了请求接口CThostFtdcUserApi,事件处理接口CThostFtdcUserSpi。
ThostFtdcUserApiStruct.h:
定义了接口方法中用到的数据结构。
ThostFtdcUserApiDataType.h:
定义了数据结构中用到数据类型,枚举描述。
thosttraderapi.lib:静态连接库
thosttraderapi.dll:动态链接库
MdUserApi接口文件:
ThostFtdcMdApi.h:
定义了请求接口CThostFtdcMdApi,事件处理接口CThostFtdcMdSpi。
ThostFtdcUserApiStruct.h,ThostFtdcUserApiDataType.h:和TraderApi公用。
thostMdapi.lib:静态连接库
thostMdapi.dll:动态链接库
通用规则 -命名规则
Api的方法都是遵循一定的命名规则来设定。
请求指令:Req***, OnRsp***。如ReqUserLogin,OnRspUserLogin。
查询指令:ReqQry***,OnRspQry***。如ReqQryInstrument,OnRspQryInstrument。
回报消息:OnRtn***,如OnRtnOrder,OnRtnTrade。
错误回报:OnErrRtn***,如OnErrRtnOrderInsert,OnErrRtnOrderAction。
通用规则 –查询/请求
请求查询合约
virtual intReqQryInstrument(CThostFtdcQryInstrumentField *pQryInstrument, intnRequestID) = 0;
请求查询合约响应
virtual voidOnRspQryInstrument(CThostFtdcInstrumentField *pInstrument,CThostFtdcRspInfoField *pRspInfo, int nRequestID, bool bIsLast){};
查询参数
如果查询参数为空,说明需要查询所有数据。如果需要查询某个交易所的合约,就在查询参数中指定ExchangeID。
请求编号RequestID
发送请求时需要设定RequestID,TraderApi返回响应时返回相关请求的RequestID。
因为TraderApi是异步实现的,终端程序可能连续发出多个请求和查询指令。RequestID可以把请求/查询指令和相关的回报关联起来。
指令返回值
如果调用方法成功,返回0。否则表示不成功。
响应信息RspInfo
如果RspInfo为空,或者RspInfo的错误代码为0,说明查询成功。
否则RspInfo中会保存错误编码和错误信息。
查询响应数据
查询响应方法每次返回1条记录。如果没有查询结果,就返回空指针。
结束标志IsLast
无论是否有查询响应数据没,只要查询响应结束,IsLast为true。
交易业务 –交易序列号
从报单到成交的交易过程中,会产生如下几组交易序列号:
FrontID + SessionID + OrderRef
用户使用这组交易序列号可以按照自己的方式来唯一标示发出的任何一笔委托。
用户登入成功后,会收到前置机编号FrontID, 会话编号SessionID和最大报单引用MaxOrderRef。
用户在报单时设定报单引用OrderRef。OrderRef可以从MaxOrderRef开始递增。
如果用户没有设定OrderRef,在报单响应中,Thost会为用户设置一个的OrderRef。使得每个报单的这组序列号保持唯一。
因为这组交易序列号是由用户设定的。所以在没有得到报单响应前,就可以使用这组交易序列号进行撤单操作。
BrokerID +BrokerOrderSeq
Thost收到用户报单后,为每个经纪公司的报单生成1组交易序列号。
exchangeID + traderID + OrderLocalID
交易席位在向交易所报单时,产生这组交易序列号,标示每一笔发往交易所的报单。
exchangeID +OrderSysID
交易所接受了投资者报单,产生这组交易序列号,标示每一笔收到的报单。
用户撤单时也可以使用这组交易序列号
注意:服务器在触发服务器预埋单、条件单时,会发送新的委托指令到交易所,需要设置新的OrderRef和OrderSysID。
交易业务 –用户登入
用户登入指令是ReqUserLogin。
用户登入时需要输入:经纪公司代码,用户代码(就是投资者代码),密码,用户端产品信息(就是终端程序的名称)
登入成功后,Thost返回:
当前会话的参数。用户可以用这些参数定义自己的交易序列号FrontID+SessionID+MaxOrderRef
当前各个交易所的时间。终端程序依此可以估计未来各个交易所的时间。
交易业务 –准备交易
在1个交易日中:
为了让投资者了解当前的交易风险。终端程序要在第一次发送交易指令之前,查询投资者结算结果(ReqQrySettlementInfo)和确认投资者结算结果(ReqSettlementInfoConfirm),才能正常发送交易指令,包括报单、撤单、服务器预埋单等指令。
如果投资者已经确认过了结算结果,以后登入Thost,不再需要确认结算结果,就可以发送交易指令了。
可以通过请求查询结算信息确认(ReqQrySettlementInfoConfirm)方法了解今天是否做了确认结算结果的操作。
交易业务 –报单指令
报单指令是:ReqOrderInsert。
报单指令中如下字段需要如下设置:
///成交量类型:任何数量
fldOrder.VolumeCondition = THOST_FTDC_VC_AV;
/// 最小成交量:1
fldOrder.MinVolume = 1;
/// 强平原因:非强平
fldOrder.ForceCloseReason =THOST_FTDC_FCC_NotForceClose;
/// 自动挂起标志:是
fldOrder.IsAutoSuspend = 1;
///用户强评标志:否
fldOrder.UserForceClose = 0;
如果发送立即限价单:
/// 报单价格条件类型:限价
OrderPriceType = THOST_FTDC_OPT_LimitPrice;
/// 价格:用户设定
LimitPrice = ……;
/// 有效期类型类型:当日有效
TimeCondition = THOST_FTDC_TC_GFD;
如果发送立即市价单
/// 报单价格条件类型:任意价
fldOrder.OrderPriceType = THOST_FTDC_OPT_AnyPrice;
///价格:0
fldOrder.LimitPrice = 0;
///有效期类型类型:立即完成,否则撤销
fldOrder.TimeCondition = THOST_FTDC_TC_IOC;
如果发送触发单
///触发条件:用户设定
ContingentCondition = ……;
///止损价:用户设定
StopPrice = ……;
/// 报单价格条件类型:限价
OrderPriceType = THOST_FTDC_OPT_LimitPrice;
/// 价格:用户设定
LimitPrice = ……;
/// 有效期类型类型:当日有效
TimeCondition = THOST_FTDC_TC_GFD;
关于平仓
上期所区分昨仓和今仓。
平昨仓时,开平标志类型设置为平仓THOST_FTDC_OF_Close
平今仓时,开平标志类型设置为平今仓THOST_FTDC_OF_CloseToday
其他交易所不区分昨仓和今仓。
开平标志类型统一设置为平仓THOST_FTDC_OF_Close
报单响应和回报
Thost收到报单指令,如果没有通过参数校验,拒绝接受报单指令。用户就会收到OnRspOrderInsert消息,其中包含了错误编码和错误消息。
如果Thost接受了报单指令,用户不会收到OnRspOrderInser,而会收到OnRtnOrder,用来更新委托状态。
交易所收到报单后,通过校验。用户会收到OnRtnOrder、OnRtnTrade。
如果交易所认为报单错误,用户就会收到OnErrRtnOrder。
交易业务 –撤单指令
撤单指令是:ReqOrderAction。
撤单输入参数:
/// 报单操作引用,
/// OrderRef相似,由用户自己设定,保持递增。如果用户不设定的话,由Thost来设定。
OrderActionRef
/// 操作标志类型:撤单
ActionFlag = THOST_FTDC_AF_Delete
/// 交易序列号
FrontID +SessionID+OrderRef,
ExchangID+OrderSysID。
/// 其他参数
BrokerID,
UserID,
InvestorID,
InstrumentID,
撤单响应和回报:和报单响应和回报相似。
Thost收到撤单指令,如果没有通过参数校验,拒绝接受撤单指令。用户就会收到OnRspOrderAction消息,其中包含了错误编码和错误消息。
如果Thost接受了撤单指令,用户不会收到OnRspOrderAction,而会收到OnRtnOrder,用来更新委托状态。
交易所收到撤单后,通过校验,执行了撤单操作。用户会收到OnRtnOrder。
如果交易所认为报单错误,用户就会收到OnErrRtnOrderAction。
注意:2阶段提交的指令都是这个规律,包括银期转账。
交易业务-委托回报
委托回报的事件处理方法是:OnRtnOrder()。
委托回报描述了报单的当前状态,其中包括:
原始的报单指令
上述几组交易序列号:
FrontID + SessionID + OrderRef,
BrokerID + BrokerOrderSeq,
ExchangeID + TraderID + LocalOrderID
ExchangeID + OrderSysID,
报单委托状态
///TFtdcOrderStatusType是一个报单状态类型
///全部成交
#defineTHOST_FTDC_OST_AllTraded '0'
///部分成交还在队列中
#defineTHOST_FTDC_OST_PartTradedQueueing '1'
///部分成交不在队列中
#defineTHOST_FTDC_OST_PartTradedNotQueueing '2'
///未成交还在队列中
#defineTHOST_FTDC_OST_NoTradeQueueing '3'
///未成交不在队列中
#defineTHOST_FTDC_OST_NoTradeNotQueueing '4'
///撤单
#defineTHOST_FTDC_OST_Canceled '5'
///未知
#defineTHOST_FTDC_OST_Unknown 'a'
///尚未触发
#defineTHOST_FTDC_OST_NotTouched 'b'
交易业务–成交回报
成交回报的事件处理方法是:OnRtnTrade()。
成交回报描述了报单的成交事件
包括下述几组交易序列号:
BrokerID +BrokerOrderSeq,
ExchangeID + TraderID +LocalOrderID
ExchangeID +OrderSysID,
交易业务 –交易时序
交易业务 –其他业务
查询基础数据:交易所,合约,投资者,手续费率,保证金率,交易编码
查询交易数据:资金,持仓,(组合)持仓明细
其他交易功能:发送预埋单、条件单
查询/回报:委托,成交,交易所状态
银期转账
行情业务 –订阅/退订
订阅
SubscribeMarketData
OnRspSubMarketData
OnRtnDepthMarketData
退订
UnSubMarketData
OnRspUnSubMarketData