XTP

通过 DolphinDB 的 XTP 插件,用户可以接收上交所、深交所以及北交所的实时行情,并将数据存储于 DolphinDB 的共享表中。可接收的数据如下表所示:

指数股票基金债券期权
快照
逐笔
订单簿

本插件依赖中泰证券提供的第三方库 libxtpquoteapi.so,可参见文档链接 xtp-中泰证券

安装插件

版本要求

DolphinDB Server 2.00.10 及更高版本,支持 Linux x64。

安装步骤

  1. 在 DolphinDB 客户端中使用 listRemotePlugins 命令查看插件仓库中的插件信息。

    注意:仅展示当前操作系统和 server 版本支持的插件。若无预期插件,可自行编译(请选择对应分支下的插件)或在 DolphinDB 用户社区进行反馈。

    login("admin", "123456")
    listRemotePlugins()
  2. 使用 installPlugin 命令完成插件安装。

    installPlugin("XTP")
  3. 使用 loadPlugin 命令加载插件。

    loadPlugin("XTP")

接口说明

setGlobalConfig

语法

XTP::setGlobalConfig(clientId, saveFilePath, logLevel)

详情

设置一些全局配置项。在创建句柄前必须调用至少一次。无返回值。

参数

clientId INT 类型标量,1-99 之间取值,表示账户 ID。如果需要在多个 DolphinDB 进程中使用同一个账户去连接,则需要使用不同的 clientId

saveFilePath STRING 类型标量,表示存储日志文件的目录,要求必须存在且有可写权限。

logLevel INT 类型标量,表示 xtp 记录日志的级别,0-5 之间取值,分别对应 FATAL ERROR WARNING INFO DEBUG TRACE 级别,默认是 3。

createXTPConnection

语法

XTP::createXTPConnection(name, config)

详情

返回一个连接句柄,可用于登录,订阅数据。

参数

name STRING 类型标量,连接句柄的唯一标识符,不能为空,也不能重复。

config 一个 key 类型为 STRING 的字典,包含如下所示的配置项:

配置项值类型说明
receiveTime整型可选参数,用于设定是否将接收到数据的时间并为表的最后一列,类型为 NANOTIMESTAMP。1:增加该列;其它不增加;默认不增加。
OutputElapsedBOOL可选参数,用于设定是否为行情表增加最后一列。该列数据类型为 LONG,表示插件从收到行情开始到准备插入流表为止的延时,单位为纳秒。true 表示增加该列;默认为 false,表示不增加。
ciphertextINT可选参数,用于设定在登陆时是否密码使用密文传输和传递 IV 值。(加密采用 AES-256-CFB 算法)默认为 1,表示开启;若为其他值,则为关闭。

login

语法

XTP::login(conn, config)

详情

连接 XTP 服务器并登录。无返回值。

注意事项(摘自 XTP 官方文档):

  • 测试环境使用 TCP 的方式推送行情。由于带宽的限制,建议客户只订阅少量股票,否则会出现推送延时、断线等问题。
  • XPT 提供的 API 的默认日志级别是 DEBUG,需要调整到 INFO(或 ERROR),否则可能会导致丢包。本插件已将默认级别调整到 INFO,在调试时可以设置为 DEBUG。

参数

conncreateXTPConnection 接口返回的句柄。

config 一个 key 类型为 STRING 的字典,包含一些配置项:

配置项值类型说明
ip字符串服务器 IP 地址
port整型服务器端口号
localIP字符串可选参数,本地网卡地址,不能为空字符串
user字符串登录用户名
password字符串登录密码
protocalType整型1: TCP;2: UDP
heartBeatInterval整型可选参数,设置心跳检测时间间隔,单位为秒。默认填 30
udpBufferSize整型可选参数,UDP 方式连接时的缓冲区大小,可填 64,128,256,512,单位 MB,默认填 512
udpRecvCPUId整型数组可选参数,UDP 方式接收行情时,接受行情的线程绑定的 CPU 集合。绑核时,将从数组前面的核开始使用。不超过 10 个
udpParseCPUId整型数组可选参数,UDP 方式接收行情时,解析行情的线程绑定的 CPU 集合。绑核时,将从数组前面的核开始使用。不超过 10 个
udpOutputFlag整型可选参数,设定 UDP 方式接收行情时,是否输出异步日志。1:输出;其它不输出;默认不输出

注意:如果在 createXTPConnection 中开启了配置项 ciphertext,则在登陆时传递的密码和 IV 值的类型也要求是 INT 类型数组。

subscribe

语法

XTP::subscribe(conn, quotationType, marketType, codeList, tableDic)

详情

订阅行情数据,收到数据后存储到目标表中。无返回值。

注意事项:

  • 订阅同一个行情类型时,在多次订阅上证、深证市场时,要求传入的 tableDic 相同,如果不同,则以第一次订阅传入的 tableDic 为准。
  • 订阅同一个行情类型时,在多次订阅新三板市场时,要求传入的 tableDic 相同,如果不同,则以第一次订阅传入的 tableDic 为准。
  • 订阅同一个行情类型时,市场类型如果已订阅了 4(上证+深证)则不能再次订阅 1(上证)或 2(深证)。
  • 订阅同一个行情类型时,市场类型如果已订阅了 1(上证)或 2(深证)则不能再次订阅 4(上证+深证)。
  • 如果 marketType 填为 4,则不能填 codeList
  • 各目标表的 schema 可以通过 getSchema 接口获取。
  • 目标表要求是共享表。
  • 公网测试环境仅供客户调试 API 接口,没有订单薄 OB 行情。

参数

conncreateXTPConnection 接口返回的句柄。

quotationType INT 类型标量,表示行情类型。1:快照,2:逐笔,3:订单簿。

marketType INT 类型标量,表示市场类型。1:上证, 2:深证,3:新三板,4:上证+深证。

codeList STRING 类型向量,表示合约 ID 数组。如果不填或者填空,则订阅全市场数据。

tableDic 一个字典,key 类型是 STRING,value 必须是共享表,用来指定输出表。根据行情类型的不同,输出表的数量也不同。如果空缺其中若干表,则相对应的行情会被丢弃,详情如下表所示:

行情类型key说明
快照indexTable、optionTable、actualTable、bondTable指数快照表、期权快照表、现货快照表(股票/基金等)、债券快照表
逐笔entrustTable、tradeTable、statusTable、TickByTickTable逐笔委托表、逐笔成交表、逐笔状态表、逐笔合并表
订单簿orderBookTable订单簿表

注意:自 3.00.0.2/2.00.12.5 版本起,支持 TickByTickTable 即逐笔合并表,其包含收到的三种逐笔数据(委托、成交、状态),该表可以做为 orderbookSnapshotEngine 的输入表。在订阅逐笔数据时,tableDic 如果指定了 “TickByTickTable”,就会忽略其它的表。当 key 为 ”TickByTickTable” 时,value 分成两种情况:

  • value 为一个表,即包含收到的所有数据。
  • value 为一个字典,该字典的键为整形,表示channelNo,值是共享表,会将收到数据按照 channelNo 进行分类,放到不同的表中。

unsubscribe

语法

XTP::unsubscribe(conn, quotationType)

详情

取消订阅某个类型的行情数据。无返回值。

参数

conncreateXTPConnection 接口返回的句柄。

quotationType INT 类型标量,表示行情类型。1:快照;2:逐笔;3:订单簿。

getStatus

语法

XTP::getStatus([conn])

详情

获取订阅的状态信息。返回一个表,表结构如下所示:

列名含义类型
conn连接名称STRING
quotationType订阅类型STRING
startTime订阅开始的时间NANOTIMESTAMP
endTime订阅结束的时间NANOTIMESTAMP
lastMsgTime最后一条消息收到的时间NANOTIMESTAMP
processedMsgCount已经处理的消息数LONG
lastErrMsg最后一条错误信息STRING
failedMsgCount处理失败的消息数LONG
lastFailedTimestamp最后一条错误消息发生的时间NANOTIMESTAMP

参数

conncreateXTPConnection 接口返回的句柄,可选参数。如果不填,则返回当前所有连接的状态信息。

getHandle

语法

XTP::getHandle(name)

详情

返回由 name 指定的连接句柄。

参数

name STRING 类型标量,表示连接句柄的唯一标识符 。

closeXTPConnection

语法

XTP::closeXTPConnection(conn)

详情

断开连接,销毁句柄。

参数

conncreateXTPConnection 接口返回的句柄。

getSchema

语法

XTP::getSchema(type, [needReceiveTime], [needElapsedTime])

详情

返回可存储相应行情类型数据的表的结构。可选的 type 如下表所示:

type含义
indexMarketData指数快照表
optionMarketData期权快照表
actualMarketData现货快照表
bondMarketData债券快照表
BSEMarketData北交所数据表
entrust逐笔委托表
trade逐笔成交表
state逐笔状态表
orderBook订单簿表
TickByTickTable逐笔合并表

参数

type STRING 类型标量,表示类型。

needReceiveTime BOOL 类型标量,可选参数,默认为 false,,表示是否需要包含 receiveTime 列。如果在 createXTPConnection 时指定了 receiveTime 配置,那么该参数须设置为 true。

needElapsedTime BOOL 类型标量,可选参数,表示返回的 shcmea 是否包含 elapsedTime 列。默认为 false,表示不包含。

generateCiphertextAndIV

语法

XTP::generateCiphertextAndIV(password)

详情

对传入的明文密码进行加密,并返回加密后的密码和 IV 值,可用于登录。加密算法为 AES-256-CFB。返回一个元组,第一个元素是密文密码,第二个元素是 IV 值,这两个元素的类型都是 INT 类型数组。

参数

password STRING类型标量,表示明文密码。

使用示例

XTP::setGlobalConfig(11, "/path/to/log", 5)

stockConn = XTP::createXTPConnection("stockConn")

stockConfig = dict(STRING, ANY);
stockConfig["ip"] = "1.2.3.4";
stockConfig["port"] = 6002;
stockConfig["user"] = "3225";
stockConfig["password"] = "225";
stockConfig["protocalType"] = 1;    //1 是 TCP 2 是 UDP, 测试环境只有TCP
stockConfig["heartBeatInterval"] = 60;

XTP::login(stockConn, stockConfig)

tableDic = dict(STRING, ANY);
share  table(1:0, `exchangeID`ticker`lastPrice`qty`turnover`tradesCount`bids`asks`bidQty`askQty`dataTime, [INT, SYMBOL,DOUBLE, LONG,DOUBLE, LONG, DOUBLE[],DOUBLE[],LONG[],LONG[],TIMESTAMP]) as orderBookTable
tableDic["orderBookTable"] = orderBookTable

XTP::subscribe(stockConn, 3, 1, ["600250", "010504"], tableDic)
XTP::getStatus()
XTP::unsubscribe(stockConn, 3)

附录

在使用 createXTPConnection 接口时,可参考如下使用建议(请以 XTP 官方文档描述为准):

  • 如果需要连接多个 XTP 服务器,则需要创建多个句柄,用每个句柄连接不同的服务器。
  • 在登录任一个 XTP 服务器之前,必须创建完毕所有句柄,即在登录后就不允许创建新的句柄,否则会抛出异常。