跳转至

01.快速入门 4.1版本API

版本说明

2022/09/05

  • 初稿

2022/09/09

  • 调整onOrder接口;
  • 新增onCancelOrder接口;

2022/09/19

  • 增加配置文件部分线程运行模式说明;
  • 增加部分常见问题说明;

用法概览

以下是使用API的基本流程:

  1. 配置API文件;
  2. 启动应用;
  3. 创建API对象;
  4. 启动API对象;
  5. 查询合约;
  6. 发送报单;
  7. 处理报单回报;
  8. 处理成交回报;
  9. 撤销报单;
  10. 停止API对象;
  11. 退出应用;

用法示例伪代码:

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
int main(int argc, const char *argv[]) {
    std::cout << "xtf api version: " << getXTFVersion() << std::endl;

    // 传入配置文件路径,创建API对象
    XTFApi *api = makeXTFApi("./xtf_trader_api.config");
    if (api == nullptr) {
        std::cout << "xtf api make failed." << std::endl;
        return -1;
    }

    // 创建SPI回调处理对象
    XTFTrader spi(api);

    // 启动API对象,启动成功后会自动调用spi->onStart()接口
    api->start(&spi);
    sleep(1);

    // 登录柜台,登录结果在spi->onLogin()接口中返回
    api->login();
    sleep(1);

    // 创建报单对象
    XTFInputOrder inputOrder;
    inputOrder.localOrderID = 1; // 建议使用本地唯一的编号
    inputOrder.direction = XTF_D_Buy;
    inputOrder.offsetFlag = XTF_OF_Open;
    inputOrder.orderType = XTF_ODT_FAK;
    inputOrder.price = 326.20f;
    inputOrder.volume = 1;
    inputOrder.channelSelectionType = XTF_CS_Auto;
    inputOrder.channelID = 0;
    inputOrder.orderFlag = XTF_ODF_Normal;
    // 查询可用的合约对象
    inputOrder.instrument = api->getInstrumentByID("au2212");

    // 发送报单
    api->insertOrder(inputOrder);
    sleep(1);

    // 登出柜台
    api->logout();
    sleep(1);

    // 停止API对象,API对象停止后,api即失效,不能再次使用。
    api->stop();
    api = nullptr;
    sleep(1);

    std::cout << "xtf api exit." << std::endl;
    return 0;
}

配置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
############################################################
## 创建API实例时,请使用独立的配置文件。
## 多个账号请创建多个API实例,每个API实例使用各自不同的配置文件。

## 资金账号
ACCOUNT_ID=41008313_1

## 账号密码
ACCOUNT_PWD=111111

## 看穿式监管需要的APP_ID
APP_ID=1234

## 看穿式监管需要的授权码
AUTH_CODE=1234

## 查询使用的地址和端口(TCP)
QUERY_SERVER_IP=192.168.4.63
QUERY_SERVER_PORT=33333

## 交易使用的地址和端口(UDP)
TRADE_SERVER_IP=192.168.4.63
TRADE_SERVER_PORT=62000

## 回报数据处理线程绑核,默认不绑核,该线程以busy loop模式运行
## 回报数据处理线程的绑核,可以加快数据的接收和处理,建议为每个API实例绑定一个隔离的CPU核。
#TCP_WORKER_CORE_ID=3

## UDP预热处理时间间隔,单位:毫秒,取值范围:[10,50]
WARM_INTERVAL=20

## UDP预热处理线程绑核,默认不绑核,该线程不是以busy loop模式运行
## 建议将预热线程与用户策略线程绑在同一个物理CPU上
#TRADE_WORKER_CORE_ID=4

## 公共处理线程绑核,默认不绑核,该线程不是以busy loop模式运行
## 公共处理线程主要用于处理通用任务,例如:
## - 慢速数据处理;
## - 心跳超时维护;
## - 其他任务,等;
## 说明:
## - 负数表示不绑核;
## - 公共处理线程是多个API实例共用的,只需要在不同的API实例配置文件中设置一次即可,以第一个API实例创建的配置生效;
#TASK_WORKER_CORE_ID=5

以下参数是必选配置,需要用户根据实际的内容进行编辑配置:

  • ACCOUNT_ID
  • ACCOUNT_PWD
  • APP_ID
  • AUTH_CODE
  • QUERY_SERVER_IP
  • QUERY_SERVER_PORT
  • TRADE_SERVER_IP
  • TRADE_SERVER_PORT

事件时序图

调用不同的API接口,会触发不同的事件回调。下图是一个API生命周期内的核心事件回调时序图:

sequenceDiagram
    participant Client
    participant SPI
    participant API
    participant XTF
    Client ->> API: 创建API实例 makeXTFApi(configPath)
    activate API
    Client ->> API: 调用start()启动API实例
    API -->> XTF: 建立TCP虚链路
    XTF -->> API: 
    API ->> SPI: 通知启动结果 onStart()
    Client ->> API: 调用login()登录柜台
    API -->> XTF: 登录柜台
    XTF -->> API: 
    API ->> SPI: 通知登录结果 onLogin()
    XTF -->> API: 日初静态数据发送完毕
    API ->> SPI: 通知用户可以交易 onReadyForTrading()
    XTF -->> API: 流水数据发送完毕
    API ->> SPI: 通知用户流水已追平 onLoadFinished()
    Client ->> API: 发送报单 insertOrder()
    API -->> XTF: 发送报单请求
    XTF -->> API: 报单请求已接受
    API ->> SPI: 通知用户报单已被接受 onOrder(XTF_OS_Accepted)
    XTF -->> API: 报单回报
    API ->> SPI: 通知用户报单状态 onOrder(XTF_OS_Queuing)
    XTF -->> API: 成交回报
    API ->> SPI: 通知用户报单状态 onOrder(XTF_OS_PartTraded)
    API ->> SPI: 通知用户报单成交 onTrade()
    Client ->> API: 撤销报单 cancelOrder(OrderSysID)
    API -->> XTF: 发送撤单请求
    XTF -->> API: 撤单请求被接受
    XTF -->> API: 报单回报(已撤)
    API ->> SPI: onCancelOrder(XTF_OS_Canceled)
    Client ->> API: 登出柜台 logout()
    API -->> XTF: 发送登出请求
    XTF -->> API: 
    API ->> SPI: 通知登出结果 onLogout()
    Client ->> API: 停止及释放API对象 stop()
    API -->> XTF: 断开TCP虚链路
    API ->> API: 清理API实例资源,释放内存数据
    API ->> SPI: 通知停止结果 onStop()
    deactivate API

创建API

接口定义:XTFApi makeXTFApi(const char configPath);

接口功能:创建一个API实例。API实例的参数配置由configPath指定的配置文件确定。

有两种方式创建API实例:

  1. 配置文件方式,需要传入配置文件路径。如果传入的路径打开失败,那么创建API实例失败,返回空指针;
  2. 参数设置方式,不需要传入配置文件路径。调用函数时配置文件路径参数传入空指针(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
int login(const char *accountID, const char *password);
int login(const char *accountID, const char *password, const char *appID, const char *authCode);

需要说明的是:每个API实例,只能对应一个用户登录。如果API登出后,使用另外的用户再次登录,将会报用户错误。例如:

C++
1
2
3
api-> login(abc, 111111); // OK
api->logout(); // OK
api->login(cde, 222222); // Error

登出柜台

接口定义:

C++
1
int logout()
接口功能:登出柜台。

登出柜台后,用户不能报单和查询等操作。必须重新登录后,才能进行下一步操作。

说明:登录柜台后,API与柜台之间的TCP连接依然保留,API内部保留了用户的所有数据,并没有释放。调用stop()接口,才真正的释放资源。

报单流程

登录柜台后,柜台返回用户相关的所有数据。

当数据准备好之后,API调用onReadyForTrading()接口通知用户,可以开始报单。

注意:此时用户虽可以报单,但当日的流水数据并没有接收完毕。如果需要计算仓位和资金,还需要等待流水数据接收完毕,才能处理。

当流水数据接收完毕后,API调用onLoadFinished()接口通知用户,表明流水数据已追平,可以计算仓位和资金。

建议:如果用户不关心流水,则收到onReadyForTrading()接口之后,即可进行报单操作。反之,应该等待 onLoadFinished() 接口之后,再进行报单操作。

插入报单

接口定义:int insertOrder(const XTFInputOrder &inputOrder);

接口说明:向柜台发送一个报单。

返回值:如果报单发送成功,则返回0;否则,返回非0值。

发送报单,需要构造报单对象。报单对象的定义如下:

C++
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
class XTFInputOrder {
public:
    XTFLocalOrderID         localOrderID;
    XTFDirection            direction;
    XTFOffsetFlag           offsetFlag;
    XTFOrderType            orderType;
    double                  price;
    uint32_t                volume;
    XTFChannelSelectionType channelSelectionType;
    uint8_t                 channelID;
    XTFOrderFlag            orderFlag;
    CONST XTFInstrument    *instrument;
};

参数各字段详细说明,可以参考头文件注释,按需填写即可。这里,主要说明一下合约对象instrument。

合约对象是一个本地对象的指针,保存了报单需要的各类信息。建议在报单之前,调用API查询接口预先做查询,并保存起来,避免每次报单都需要做查询操作。

批量报单

API支持一次发送最大16个报单。

接口定义:

C++
1
int insertOrders(const XTFInputOrder inputOrders[], size\_t orderCount)
接口说明:向柜台发送批量报单,最大16个。

返回值:如果报单发送成功,则返回0;否则,返回非0值。

批量报单对象的设置与单个报单接口相同,请参考“插入报单”部分。

报单回报

报单发送成功后,会调用多次onOrder接口处理报单回报。

接口定义:

C++
1
void onOrder(int errorCode, const XTFOrder *order)

接口说明:当报单成功或报单状态变化时,收到该接口的回调。

详细流程,参考报单回调流程一节;

撤单流程

API提供了多个撤单接口,可以按照报单对象XTFOrder直接撤单,也可以按照报单编号进行撤单。两种方式的撤单,都提供了批量撤单接口。

按报单对象撤单

接口定义:

C++
1
2
3
int cancelOrder(const XTFOrder *order); 

int cancelOrders(const XTFOrder *orders[], size\_t orderCount);

接口说明:按照指定的报单对象进行撤单。

按照报单对象进行撤单,效率比按照编号撤单更好一些。避免了报单的本地查找开销。不过,需要用户自己保存需要撤单的对象指针。

按报单编号撤单

接口定义:

C++
1
2
3
int cancelOrder(XTFOrderIDType orderIDType, long orderID);

int cancelOrders(XTFOrderIDType orderIDType, long orderIDs[], size\_t orderCount);
接口说明:按照报单编号进行撤单。

接口提供了按多种报单编号类型进行撤单,报单编号类型包括:

  1. 本地报单编号;
  2. 柜台报单编号;
  3. 交易所报单编号;

目前,仅支持柜台报单编号撤单,保留后续支持本地报单编号和交易所报单编号的撤单功能。

撤单回报

撤单成功或失败后,会调用撤单回报接口处理。

接口定义:

C++
1
void onCancelOrder(int errorCode, const XTFOrder *cancelOrder)
接口说明:当撤单成功或失败时,收到该接口的回调。

详细流程,参考报单回调流程一节;

报单回调流程

接口回调顺序图如下:

graph TD
报单请求[insertorder]
报单错误[onorder]
报单接收[onorder]
未成交[onorder]
部分成交[onorder+ontrade]
FAK部分成交[ontrade]
全部成交[onorder+ontrade]
撤单[oncancelorder]

报单请求--报单错误-->报单错误
报单请求--报单接收-->报单接收
报单接收--未成交-->未成交--部分成交-->部分成交--全部成交-->全部成交
未成交--全部成交-->全部成交
报单接收--FOK/FAK全部成交-->全部成交
报单接收--FOK/FAK全部撤单-->撤单
报单接收--FAK部分成交-->FAK部分成交--撤单-->撤单
未成交--全部撤单-->撤单
部分成交--撤单-->撤单

正常的报单回报流程

actionCode errorCode orderStatus
第1次回调 XTF_OA_Insert 交易所错误码 XTF_OS_Accepted 收到插入报单的操作应答
第2次回调 XTF_OA_Return 0 XTF_OS_Queuing 收到柜台返回的报单回报
第3次回调 XTF_OA_Return 0 XTF_OS_AllTraded 收到柜台返回的全成回报
成交回报

存在部分成交的报单回报流程

actionCode errorCode orderStatus
第1次回调 XTF_OA_Insert 交易所错误码 XTF_OS_Accepted 收到插入报单的操作应答
第2次回调 XTF_OA_Return 0 XTF_OS_Queuing 收到柜台返回的报单回报
第3次回调 XTF_OA_Return 0 XTF_OS_PartTraded 收到柜台返回的部成回报
成交回报
第4次回调 XTF_OA_Return 0 XTF_OS_AllTraded 收到柜台返回的全成回报
成交回报

说明:对于报单数量(volume字段)较大的场景,部分成交的回调可能有多次。

撤单的报单回报流程

actionCode errorCode orderStatus
第1次回调 XTF_OA_Insert 交易所错误码 XTF_OS_Accepted 收到插入报单的操作应答
第2次回调 XTF_OA_Return 0 XTF_OS_Queuing 收到柜台返回的报单回报
第3次回调 XTF_OA_Return 0 XTF_OS_Canceled 收到柜台返回的撤单回报

说明:对于FAK/FOK报单,交易所返回的报单状态可能为已撤销,并没有Queuing这个中间状态。如果是这种情况,第2次回调(已加入队列)将会被跳过,直接进入已撤状态。

存在部分成交的撤单回报流程

actionCode errorCode orderStatus
第1次回调 XTF_OA_Insert 交易所错误码 XTF_OS_Accepted 收到插入报单的操作应答
第2次回调 XTF_OA_Return 0 XTF_OS_Queuing 收到柜台返回的报单回报
第3次回调 XTF_OA_Return 0 XTF_OS_PartTraded 收到柜台返回的部成回报
成交回报
第4次回调 XTF_OA_Return 0 XTF_OS_Canceled 收到柜台返回的撤单回报

交易所拒单的报单回报流程

actionCode errorCode orderStatus
第1次回调 XTF_OA_Return 交易所错误码 XTF_OS_Rejected 收到柜台返回的拒单回报

柜台重启

在API使用过程中,如果盘中柜台发生重启,那么需要API调用者实现onServerReboot()接口,完成失效数据的清理。

清理的数据类型包括所有的XTF开头的数据结构。

查询接口

查询账户

接口定义:

C++
1
const XTFAccount* getAccount();
接口说明:查询当前账户信息。

查询合约

接口定义:

C++
1
2
3
int getInstrumentCount();
const XTFInstrument* getInstrument(int pos);
const XTFInstrument* getInstrumentByID(const char *instrumentID);

接口说明:查询合约数量和指定合约。

建议报单前,先把目标合约对象查找并存储起来,以加快报单的速度。

查询仓位

接口定义:

C++
1
2
int XTFAccount::getPositionCount() const;
const XTFPosition* XTFAccount::getPosition(int pos) const;

接口说明:查询当前用户下的所有仓位信息。

说明:如果仓位已平,通过该接口是无法查询的。

查询报单

接口定义:

C++
1
2
int getOrderCount() const;
const XTFOrder* getOrder(int pos) const;

接口说明:查询当前用户下的所有报单信息,包括所有状态的报单。