01.快速入门 4.1版本API
版本说明 2022/09/05 初稿 2022/09/09 调整onOrder接口;新增onCancelOrder接口; 2022/09/19 增加配置文件部分线程运行模式说明;增加部分常见问题说明;
用法概览¶
以下是使用API的基本流程:
- 配置API文件;
- 启动应用;
- 创建API对象;
- 启动API对象;
- 查询合约;
- 发送报单;
- 处理报单回报;
- 处理成交回报;
- 撤销报单;
- 停止API对象;
- 退出应用;
用法示例伪代码:
C++ | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 |
|
配置API¶
API提供配置文件的方式创建实例和设置运行参数。
配置文件内容如下:
C++ | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
|
以下参数是必选配置,需要用户根据实际的内容进行编辑配置:
- ACCOUNT_ID
- ACCOUNT_PWD
- APP_ID
- AUTH_CODE
- QUERY_SERVER_IP
- QUERY_SERVER_PORT
- TRADE_SERVER_IP
- TRADE_SERVER_PORT
事件时序图¶
调用不同的API接口,会触发不同的事件回调。下图是一个API生命周期内的核心事件回调时序图:
创建API¶
接口定义:XTFApi makeXTFApi(const char configPath);
接口功能:创建一个API实例。API实例的参数配置由configPath指定的配置文件确定。
有两种方式创建API实例:
- 配置文件方式,需要传入配置文件路径。如果传入的路径打开失败,那么创建API实例失败,返回空指针;
- 参数设置方式,不需要传入配置文件路径。调用函数时配置文件路径参数传入空指针(nullptr)即可。
创建成功后,需要通过API->setConfig()接口设置以下必选参数:
"ACCOUNT_ID":资金账户ID
"ACCOUNT_PWD":资金账户密码
"APP_ID":应用程序ID
"AUTH_CODE":认证授权码
"TRADE_SERVER_IP":交易服务地址
"TRADE_SERVER_PORT":交易服务端口
"QUERY_SERVER_IP":查询服务地址
"QUERY_SERVER_PORT":查询服务端口
详细内容请参考API->setConfig()接口注释说明。
启动API¶
使用API对象之前,需要启动API。
接口定义:int start(XTFSpi *spi);
接口功能:启动API,传入XTFSpi回调对象。
API启动后,会分配所需的各类资源,并自动向配置文件中设置的柜台地址发起连接。在一切准备就绪后,调用XTFSpi->onStart()接口,通知用户启动成功与否。
停止API¶
使用API结束,需要停止API,释放相关资源。
接口定义:int stop();
接口功能:停止API。
API停止后,会自动断开与柜台的TCP连接,并释放所有相关的资源。
API停止后,API实例对象不再有效,不可使用。
登录柜台¶
API启动后,用户并没有登录柜台。需要调用登录接口,向柜台发起登录。
接口定义:int login();
接口功能:登录柜台。
登录接口默认是没有参数的,登录的用户和密码等参数,默认从配置文件读取。为方便使用,增加了两个重载接口,可以设置登录用户和密码等参数,如下:
C++ | |
---|---|
1 2 |
|
需要说明的是:每个API实例,只能对应一个用户登录。如果API登出后,使用另外的用户再次登录,将会报用户错误。例如:
C++ | |
---|---|
1 2 3 |
|
登出柜台¶
接口定义:
C++ | |
---|---|
1 |
|
报单流程¶
登录柜台后,柜台返回用户相关的所有数据。
当数据准备好之后,API调用onReadyForTrading()接口通知用户,可以开始报单。
注意:此时用户虽可以报单,但当日的流水数据并没有接收完毕。如果需要计算仓位和资金,还需要等待流水数据接收完毕,才能处理。
当流水数据接收完毕后,API调用onLoadFinished()接口通知用户,表明流水数据已追平,可以计算仓位和资金。
建议:如果用户不关心流水,则收到onReadyForTrading()接口之后,即可进行报单操作。反之,应该等待 onLoadFinished() 接口之后,再进行报单操作。
插入报单¶
接口定义:
C++ | |
---|---|
1 |
|
接口说明:向柜台发送一个报单。
返回值:如果报单发送成功,则返回0;否则,返回非0值。
发送报单,需要构造报单对象。报单对象的定义如下:
C++ | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
|
参数各字段详细说明,可以参考头文件注释,按需填写即可。这里,主要说明一下合约对象instrument。
合约对象是一个本地对象的指针,保存了报单需要的各类信息。建议在报单之前,调用API查询接口预先做查询,并保存起来,避免每次报单都需要做查询操作。
批量报单¶
API支持一次发送最大16个报单。
接口定义:
C++ | |
---|---|
1 |
|
返回值:如果报单发送成功,则返回0;否则,返回非0值。
批量报单对象的设置与单个报单接口相同,请参考“插入报单”部分。
报单回报¶
报单发送成功后,会调用多次onOrder接口处理报单回报。
接口定义:
C++ | |
---|---|
1 |
|
接口说明:当报单成功或报单状态变化时,收到该接口的回调。
详细流程,参考报单回调流程一节;
撤单流程¶
API提供了多个撤单接口,可以按照报单对象XTFOrder直接撤单,也可以按照报单编号进行撤单。两种方式的撤单,都提供了批量撤单接口。
按报单对象撤单¶
接口定义:
C++ | |
---|---|
1 2 |
|
接口说明:按照指定的报单对象进行撤单。
按照报单对象进行撤单,效率比按照编号撤单更好一些。避免了报单的本地查找开销。不过,需要用户自己保存需要撤单的对象指针。
按报单编号撤单¶
接口定义:
C++ | |
---|---|
1 2 |
|
接口提供了按多种报单编号类型进行撤单,报单编号类型包括:
- 本地报单编号;
- 柜台报单编号;
- 交易所报单编号;
目前,仅支持柜台报单编号撤单,保留后续支持本地报单编号和交易所报单编号的撤单功能。
撤单回报¶
撤单成功或失败后,会调用撤单回报接口处理。
接口定义:
C++ | |
---|---|
1 |
|
详细流程,参考报单回调流程一节;
报单回调流程¶
接口回调顺序图如下:
报单回报状态的版本说明:
onOrder=Received
在692版本及之前不支持Received
状态。insertOrder发起报单请求后,如果柜台拒绝或交易所拒绝,会直接转为Rejected
状态,交易所接收后,进入Accepted
状态。onOrder=Accepted
状态为临时状态,在报单应答和报单回报乱序的场景下,会跳过此状态,直接进入后续状态。
限价单类型的说明:
- GFD限价单:
OrderFlag == XTF_ODF_Normal && OrderType == XTF_ODT_Limit
- FAK限价单:
OrderFlag == XTF_ODF_Normal && OrderType == XTF_ODT_FAK
- FOK限价单:
OrderFlag == XTF_ODF_Normal && OrderType == XTF_ODT_FOK
GFD限价单的报单回报流程(正常)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
第3次回调 | XTF_OA_Return | 0 | XTF_OS_Queuing | 收到交易所的排队回报 | |
全部成交 | |||||
第4次回调 | XTF_OA_Return | 0 | XTF_OS_AllTraded | 收到交易所的全成回报 | |
成交回报 |
GFD限价单的报单回报流程(排队后部分成交)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | ||
第3次回调 | XTF_OA_Return | 0 | XTF_OS_Queuing | 收到交易所的排队回报 | |
部分成交 | |||||
第4次回调 | XTF_OA_Return | 0 | XTF_OS_PartTraded | 收到交易所的部成回报 | |
成交回报 | |||||
全部成交 | |||||
第5次回调 | XTF_OA_Return | 0 | XTF_OS_AllTraded | 收到交易所的全成回报 | |
成交回报 |
说明:对于报单数量(volume字段)较大的场景,部分成交的回调可能有多次。
GFD限价单的报单回报流程(立即部分成交)¶
如果GFD限价单报单后立即部分成交,则不会存在XTF_OS_Queuing状态:
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | ||
立即部分成交 | |||||
第3次回调 | XTF_OA_Return | 0 | XTF_OS_PartTraded | 收到交易所的部成回报 | |
成交回报 | |||||
全部成交 | |||||
第4次回调 | XTF_OA_Return | 0 | XTF_OS_AllTraded | 收到交易所的全成回报 | |
成交回报 |
说明:对于报单数量(volume字段)较大的场景,部分成交的回调可能有多次。
GFD限价单的报单回报流程(柜台拒单)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 柜台错误码 | XTF_OS_Rejected | 收到插入报单的柜台拒单 |
GFD限价单的报单回报流程(交易所拒单)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 交易所错误码 | XTF_OS_Rejected | 收到插入报单的交易所拒单 |
撤销GFD限价单的报单回报流程(正常)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
第3次回调 | XTF_OA_Return | 0 | XTF_OS_Queuing | 收到交易所的排队回报 | |
撤销报单 | |||||
第4次回调 | XTF_OA_Return | 0 | XTF_OS_Canceled | 收到交易所的撤单回报 |
撤销GFD限价单的报单回报流程(排队后部分成交)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
第3次回调 | XTF_OA_Return | 0 | XTF_OS_Queuing | 收到交易所的排队回报 | |
部分成交 | |||||
第4次回调 | XTF_OA_Return | 0 | XTF_OS_PartTraded | 收到交易所的部成回报 | |
成交回报 | |||||
撤销报单 | |||||
第5次回调 | XTF_OA_Return | 0 | XTF_OS_Canceled | 收到交易所的撤单回报 |
撤销GFD限价单的报单回报流程(立即部分成交)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
部分成交 | |||||
第3次回调 | XTF_OA_Return | 0 | XTF_OS_PartTraded | 收到交易所的部成回报 | |
成交回报 | |||||
撤销报单 | |||||
第4次回调 | XTF_OA_Return | 0 | XTF_OS_Canceled | 收到交易所的撤单回报 |
撤销GFD限价单的报单回报流程(撤单失败)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
全部成交 | |||||
第3次回调 | XTF_OA_Return | 0 | XTF_OS_AllTraded | 收到交易所的全成回报 | |
成交回报 | |||||
撤销报单 | |||||
第4次回调 | XTF_OA_Cancel | 撤单失败错误码 | — | 收到交易所的撤单错误回报 |
FAK限价单的报单回报流程(全部成交)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
全部成交 | |||||
第3次回调 | XTF_OA_Return | 0 | XTF_OS_AllTraded | 收到交易所的全成回报 | |
成交回报 |
FAK限价单的报单回报流程(部分成交剩余撤单)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
部分成交 | |||||
第3次回调 | XTF_OA_Return | 0 | XTF_OS_PartTraded | 收到交易所的部成回报 | |
成交回报 | |||||
自动撤单 | |||||
第4次回调 | XTF_OA_Return | 0 | XTF_OS_Canceled | 收到交易所的撤单回报 |
FAK限价单的报单回报流程(全部撤单)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
自动撤单 | |||||
第3次回调 | XTF_OA_Return | 0 | XTF_OS_Canceled | 收到交易所的撤单回报 |
FOK限价单的报单回报流程(全部成交)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
全部成交 | |||||
第3次回调 | XTF_OA_Return | 0 | XTF_OS_AllTraded | 收到交易所的全成回报 | |
成交回报 |
FOK限价单的报单回报流程(全部撤单)¶
actionCode | errorCode | orderStatus | |||
---|---|---|---|---|---|
插入报单 | |||||
第1次回调 | XTF_OA_Insert | 0 | XTF_OS_Received | 收到插入报单的柜台应答 | |
第2次回调 | XTF_OA_Insert | 0 | XTF_OS_Accepted | 收到插入报单的交易所应答 | |
自动撤单 | |||||
第3次回调 | XTF_OA_Return | 0 | XTF_OS_Canceled | 收到交易所的撤单回报 |
行权和对冲¶
行权报单和对冲报单都使用XTFExecOrder
,数据结构定义如下:
C++ | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
通过XTFOrderFlag、XTFOrderType、XTFDirection三个字段区分是请求行权、放弃行权、请求对冲、请求不对冲。下面的表格给出了不同报单对应的字段值:
XTFOrderFlag | XTFDirection | XTFOrderType | |
---|---|---|---|
elfClose | |||
请求行权(且行权后不对冲期权) | XTF_ODF_OptionsExecute | XTF_D_Buy | XTF_ODT_NotSelfClose |
放弃行权 | XTF_ODF_OptionsExecute | XTF_D_Sell | — |
请求期权对冲 | XTF_ODF_OptionsSelfClose | XTF_D_Buy | XTF_ODT_SelfCloseOptions |
请求履约对冲 | XTF_ODF_OptionsSelfClose | XTF_D_Buy | XTF_ODT_SelfCloseFutures |
请求期权不对冲 | XTF_ODF_OptionsSelfClose | XTF_D_Sell | XTF_ODT_SelfCloseOptions |
请求履约不对冲 | XTF_ODF_OptionsSelfClose | XTF_D_Sell | XTF_ODT_SelfCloseFutures |
按照上述表格构造行权(对冲)报单后,通过以下接口即可实现报撤单请求:
- 请求报单:insertExecOrder(const XTFExecOrder &execOrder);
- 撤销请求:cancelExecOrder(const XTFOrder *order);
柜台重启¶
在API使用过程中,如果盘中柜台发生重启,那么需要API调用者实现onServerReboot()
接口,完成失效数据的清理。
清理的数据类型包括所有的XTF开头的数据结构。
查询接口¶
查询账户¶
接口定义:
C++ | |
---|---|
1 |
|
查询合约¶
接口定义:
C++ | |
---|---|
1 2 3 |
|
接口说明:查询合约数量和指定合约。
建议报单前,先把目标合约对象查找并存储起来,以加快报单的速度。
查询仓位¶
接口定义:
C++ | |
---|---|
1 2 |
|
接口说明:查询当前用户下的所有仓位信息。
说明:如果仓位已平,通过该接口是无法查询的。
查询报单¶
接口定义:
C++ | |
---|---|
1 2 |
|
接口说明:查询当前用户下的所有报单信息,包括所有状态的报单。