账户变动推送

String subscribe(Subject subject) 订阅

说明

交易 API 提供了交易相关接口,同时也提供了订阅接口,可以实时获取账户的资产、持仓、订单、订单执行明细的变化信息。 交易推送接口是异步接口,通过实现 ApiComposeCallback 接口可以获得异步请求结果。 回调接口返回值类型,具体回调接口可参见此文档。

输入参数(订阅主题)

参数类型是否必填说明
accountstringNo如不设置订阅资金账号,默认订阅所有的资金账号,包括模拟账号
subjectSubjectYes订阅主题

Subject 为订阅主题,主要包括四种:OrderStatus(订单),Asset(资产),Position(持仓),OrderTransaction(订单执行明细):

  • OrderStatus 推送,是指订单状态发生变化时的推送,订单变化主要包括:Submitted(已提交到交易所),Cancelled(订单已取消),Inactive(订单被拒绝),Filled(订单已成交),其他中间状态时不会推送。
  • Asset 推送,是资产推送,默认每 5 秒推送一次全量资产快照,实盘和模拟盘频率一致。
  • Position 推送,是持仓推送,默认每 5 秒推送一次全量持仓快照,实盘和模拟盘频率一致。
  • OrderTransaction 推送,是订单执行明细报告数据推送。

默认会推送全部资金账号的数据,包括模拟账号,可以按返回数据的 account 区分,或者使用subscribe(String account, Subject subject)方法订阅时指定资金账号。

⚠️

NOTE

订阅上述四种类型的任意一个主题,都会推送全部的四种主题数据,取消四种中的任意一个主题,会取消全部的四种主题数据的订阅。

返回值

字段类型说明
idstringsdk 订阅请求时本地生成的 ID,序列递增。在subscribeEnd(int id, String subject, String result)回调方法中返回请求 id 和订阅是否成功的结果

回调数据字段含义

资产变动回调

字段类型描述
accountString资金账号
currencyString币种。USD 美元,HKD 港币
segTypeString按交易品种划分的分类。S 表示股票,C 表示期货,D 表示数字货币,F 表示基金,CONSOLIDATED 表示股票和基金聚合
availableFundsdouble可用资金,隔夜剩余流动性
excessLiquiditydouble当前剩余流动性
netLiquidationdouble总资产(净清算值)。总资产就是我们账户的净清算现金余额和证券总市值之和
equityWithLoandouble含贷款价值总权益。等于总资产 - 美股期权
buyingPowerdouble购买力。仅适用于股票品种,即 segment 为 S 时有意义
cashBalancedouble现金额。当前所有币种的现金余额之和
grossPositionValuedouble证券总价值
initMarginReqdouble初始保证金
maintMarginReqdouble维持保证金
timestamplong时间戳

持仓变动回调

字段类型描述
accountString资金账号
symbolString持仓标的代码,如 'AAPL', '00700', 'ES', 'CN'
expiryString仅支持期权、窝轮、牛熊证
strikeString仅支持期权、窝轮、牛熊证
rightString仅支持期权、窝轮、牛熊证
identifierString标的标识符。股票的 identifier 与 symbol 相同。期货的会带有合约月份,如 'CN2201'
multiplierint每手数量,仅限 futures, options, warrants, CBBC
marketString市场。US, HK
currencyString币种。USD 美元,HKD 港币
segTypeString按交易品种划分的分类。S 表示股票,C 表示期货,D 表示数字货币,F 表示基金,CONSOLIDATED 表示股票和基金聚合
secTypeStringSTK Stocks, OPT Options, WAR Warrants, IOPT CBBC, CASH FOREX, FUT Futures, FOP Future Options
positionQtydouble持仓数量
salableQtydouble可卖数量
positionlong持仓数量(废弃)
positionScaleint持仓数量的偏移量(废弃),比如 position 值为 2135,positionScale 为 2,实际持仓数为 21.35
saleablelongA 股可卖数量(废弃)
averageCostdouble持仓均价
latestPricedouble标的当前价格
marketValuedouble持仓市值
unrealizedPnldouble持仓盈亏
timestamplong时间戳

订单变动回调

字段类型描述
idlong订单号
accountString资金账号
symbolString持仓标的代码,如 'AAPL', '00700', 'ES', 'CN'
expiryString仅支持期权、窝轮、牛熊证
strikeString仅支持期权、窝轮、牛熊证
rightString仅支持期权、窝轮、牛熊证
identifierString标的标识符。股票的 identifier 与 symbol 相同。期货的会带有合约月份,如 'CN2201'
multiplierint每手数量,仅限 futures, options, warrants, CBBC
actionString买卖方向。BUY 表示买入,SELL 表示卖出。
marketString市场。US、HK
currencyString币种。USD 美元,HKD 港币
segTypeString按交易品种划分的分类。S 表示股票,C 表示期货
secTypeStringSTK Stocks, OPT Options, WAR Warrants, IOPT CBBC, CASH FOREX, FUT Futures, FOP Future Options
orderTypeString订单类型。'MKT'市价单/'LMT'限价单/'STP'止损单/'STP_LMT'止损限价单/'TRAIL'跟踪止损单
isLongboolean是否多头持仓
totalQuantitylong下单数量
totalQuantityScaleint下单数量偏移量,如 totalQuantity=111, totalQuantityScale=2,那么真实 totalQuantity=111*10^(-2)=1.11
filledQuantitylong成交总数量(订单分多笔成交的,filledQuantity 为累计成交总数)
filledQuantityScaleint成交总数量偏移量
avgFillPricedouble成交均价
limitPricedouble限价单价格
stopPricedouble止损价格
realizedPnldouble已实现盈亏(只有综合账号有这个字段)
statusString订单状态
replaceStatusString订单改单状态
cancelStatusString订单撤单状态
outsideRthboolean是否允许盘前盘后交易,仅适用于美股
canModifyboolean是否能修改
canCancelboolean是否能取消
liquidationboolean是否为平仓订单
nameString标的名称
sourceString订单来源(from 'OpenApi', or other)
errorMsgString错误信息
attrDescString订单描述信息
commissionAndFeefloat佣金费用总计
openTimelong下单时间
timestamplong订单状态最后更新时间
userMarkString自定义标注信息
totalCashAmountdouble下单总金额(仅限金额订单)
filledCashAmountdouble成交金额(仅限金额订单)
attrListList<String>订单属性列表,各属性含义如下: LIQUIDATION 强平, FRACTIONAL_SHARE 碎股订单(非整股), EXERCISE 行权, EXPIRE 过期, ASSIGNMENT 被动行权分配, CASH_SETTLE 现金交割, KNOCK_OUT 敲出, RECALL 召回订单, ODD_LOT 碎股订单(非整手), DEALER 交易员下单, GREY_MARKET 港股暗盘订单, BLOCK_TRADE 大宗交易, ATTACHED_ORDER 附加订单, OCA OCA 订单
timeInForcestring订单有效时间。DAY: 当日有效,GTC: 撤销前有效,GTD: 有效至指定日期。

订单执行明细报告回调

字段类型描述
idlong订单执行 ID
orderIdlong订单号
accountString资金账号
symbolString持仓标的代码,如 'AAPL', '00700', 'ES', 'CN'
identifierString标的标识符。股票的 identifier 与 symbol 相同。期货的会带有合约月份,如 'CN2201'
multiplierint每手数量(期权、期货专有)
actionString买卖方向。BUY 表示买入,SELL 表示卖出。
marketString市场。US、HK
currencyString币种。USD 美元,HKD 港币
segTypeString按交易品种划分的分类。S 表示股票,C 表示期货
secTypeString交易品种,标的类型。STK 表示股票,FUT 表示期货
filledPricedouble价格
filledQuantitylong成交数量
createTimelongcreate time
updateTimelongupdate time
transactTimelong成交时间
timestamplongtimestamp

回调接口

实现 ApiComposeCallback 的对应方法

/** 
* 回调接口: 
* 根据不同subject调用不同接口
*/
void assetChange(AssetData data)  //对应subject = Asset
void positionChange(PositionData data) //对应subject = Position
void orderStatusChange(OrderStatusData data) //对应subject = OrderStatus
void orderTransactionChange(OrderTransactionData data) //对应subject = OrderTransaction

示例

实现回调接口示例

package com.tigerbrokers.stock.openapi.demo;

import com.tigerbrokers.stock.openapi.client.socket.ApiComposeCallback;
import com.tigerbrokers.stock.openapi.client.socket.data.pb.AssetData;
import com.tigerbrokers.stock.openapi.client.socket.data.pb.OrderStatusData;
import com.tigerbrokers.stock.openapi.client.socket.data.pb.OrderTransactionData;
import com.tigerbrokers.stock.openapi.client.socket.data.pb.PositionData;
import com.tigerbrokers.stock.openapi.client.util.ApiLogger;
import com.tigerbrokers.stock.openapi.client.util.ProtoMessageUtil;

public class DefaultApiComposeCallback implements ApiComposeCallback {

  @Override
  public void orderStatusChange(OrderStatusData data) {
    ApiLogger.info("orderStatusChange:" + ProtoMessageUtil.toJson(data));
  }

  @Override
  public void orderTransactionChange(OrderTransactionData data) {
    ApiLogger.info("orderTransactionChange:" + ProtoMessageUtil.toJson(data));
  }

  @Override
  public void positionChange(PositionData data) {
    ApiLogger.info("positionChange:" + ProtoMessageUtil.toJson(data));
  }

  @Override
  public void assetChange(AssetData data) {
    ApiLogger.info("assetChange:" + ProtoMessageUtil.toJson(data));
  }

  @Override
  public void subscribeEnd(int id, String subject, String result) {
    ApiLogger.info("subscribe " + subject + " end. id:" + id + ", " + result);
  }

  @Override
  public void cancelSubscribeEnd(int id, String subject, String result) {
    ApiLogger.info("cancel subscribe " + subject + " end. id:" + id + ", " + result);
  }
}

进行订阅

public class WebSocketDemo {

//实际订阅时需要填充tigerId和privateKey,并实现callback接口
  private static ClientConfig clientConfig = ClientConfig.DEFAULT_CONFIG;
  private static WebSocketClient client;
  static {
    //从开发者信息页面导出的配置文件tiger_openapi_config.properties、tiger_openapi_token.properties存放路径
    clientConfig.configFilePath = "your_config_directory_path";
    // clientConfig.secretKey = "xxxxxx";// institutional trader private key

    // 原使用方式(不使用tiger_openapi_config.properties文件),必须配置tigerId, defaultAccount, privateKey三项,如果同时配置了configFilePath路径properties文件配置内容优先
    // clientConfig.tigerId = "your tiger id";
    // clientConfig.defaultAccount = "your account";
    // clientConfig.privateKey = ConfigUtil.readPrivateKey("/Users/tiger/rsa_private_key_pkcs8.pem");
    client = WebSocketClient.getInstance().clientConfig(clientConfig).apiComposeCallback(new DefaultApiComposeCallback());
  }

  public static void subscribe() {
    //创建连接
    client.connect();

    //订阅 订单/资产/持仓/订单执行报告
    client.subscribe(Subject.OrderStatus);    
    client.subscribe(Subject.Asset);
    client.subscribe(Subject.Position);
    client.subscribe(Subject.OrderTransaction);

    //等待
    TimeUnit.SECONDS.sleep(60);
    
    // 取消订阅
    client.cancelSubscribe(Subject.Asset);
    client.cancelSubscribe(Subject.Position);
    client.cancelSubscribe(Subject.OrderStatus);
    client.cancelSubscribe(Subject.OrderTransaction);
    
    //非交易时间段建议关闭连接,调用disconnect()方法会自动注销之前的全部订阅信息
    //client.disconnect();
  }
}

返回示例

assetChange:

{
  "account": "13810712",
  "currency": "USD",
  "segment": "S",
  "availableFunds": 2285040.5475322,
  "excessLiquidity": 2284942.0475322,
  "netLiquidation": 2285529.3735322,
  "equityWithLoan": 2285418.2835322,
  "buyingPower": 9140162.1901287,
  "cashBalance": 2284275.2435322,
  "grossPositionValue": 1143.04,
  "initMarginReq": 377.736,
  "maintMarginReq": 476.236,
  "timestamp": "1669888806020"
}
// position change
positionChange:{"account":"13810712","symbol":"AAPL","identifier":"AAPL","multiplier":1,"market":"US","currency":"USD","segment":"S","secType":"STK","position":"4","averageCost":75.0,"latestPrice":147.23,"marketValue":588.92,"unrealizedPnl":288.92,"timestamp":"1669888802018"}

// order change
orderStatusChange:{"id":"28875370355884032","account":"736845","symbol":"CL","identifier":"CL2312","multiplier":1000,"action":"BUY","market":"US","currency":"USD","segment":"C","secType":"FUT","orderType":"LMT","isLong":true,"totalQuantity":"1","filledQuantity":"1","avgFillPrice":77.76,"limitPrice":77.76,"status":"Filled","outsideRth":true,"name":"WTI原油2312","source":"android","commissionAndFee":4.0,"openTime":"1669200792000","timestamp":"1669200782221"}

// OrderTransaction
orderTransactionChange:{"id":"28875370482237440","orderId":"28875370355884032","account":"736845","symbol":"CL","identifier":"CL2312","multiplier":1000,"action":"BUY","market":"US","currency":"USD","segment":"C","secType":"FUT","filledPrice":77.76,"filledQuantity":"1","createTime":"1669200793664","updateTime":"1669200793664","transactTime":"1669200793593","timestamp":"1669200782233"}

positionChange:

{
  "account": "13810712",
  "symbol": "AAPL",
  "identifier": "AAPL",
  "multiplier": 1,
  "market": "US",
  "currency": "USD",
  "segment": "S",
  "secType": "STK",
  "position": "4",
  "averageCost": 75.0,
  "latestPrice": 147.23,
  "marketValue": 588.92,
  "unrealizedPnl": 288.92,
  "timestamp": "1669888802018"
}

orderStatusChange:

{
  "id": "28875370355884032",
  "account": "736845",
  "symbol": "CL",
  "identifier": "CL2312",
  "multiplier": 1000,
  "action": "BUY",
  "market": "US",
  "currency": "USD",
  "segment": "C",
  "secType": "FUT",
  "orderType": "LMT",
  "isLong": true,
  "totalQuantity": "1",
  "filledQuantity": "1",
  "avgFillPrice": 77.76,
  "limitPrice": 77.76,
  "status": "Filled",
  "outsideRth": true,
  "name": "WTI原油2312",
  "source": "android",
  "commissionAndFee": 4.0,
  "openTime": "1669200792000",
  "timestamp": "1669200782221"
}

orderTransactionChange:

{
  "id": "28875370482237440",
  "orderId": "28875370355884032",
  "account": "736845",
  "symbol": "CL",
  "identifier": "CL2312",
  "multiplier": 1000,
  "action": "BUY",
  "market": "US",
  "currency": "USD",
  "segment": "C",
  "secType": "FUT",
  "filledPrice": 77.76,
  "filledQuantity": "1",
  "createTime": "1669200793664",
  "updateTime": "1669200793664",
  "transactTime": "1669200793593",
  "timestamp": "1669200782233"
}

订单状态通知数据,如果是分多次成交的,filledQuantity 为历史累计成交总数,依次返回数据如下:

{
  "id": 28557131062709999,
  "symbol": "CN",
  "market": "SI",
  "currency": "USD",
  "secType": "FUT",
  "action": "BUY",
  "isLong": true,
  "totalQuantity": 9,
  "totalQuantityScale": 0,
  "filledQuantity": 1,
  "filledQuantityScale": 0,
  "orderType": "MKT",
  "avgFillPrice": 11824.0,
  "status": "PendingSubmit",
  "subStatusList": [],
  "subStatusDescList": [],
  "realizedPnl": 0.0,
  "commissionAndFee": 3.09,
  "gst": 0.22,
  "replaceStatus": "NONE",
  "cancelStatus": "NONE",
  "source": "OpenApi",
  "canModify": true,
  "canCancel": true,
  "multiplier": 1.0,
  "stockId": 15433673,
  "attr": 0,
  "type": "orderstatus",
  "outsideRth": false,
  "limitPrice": 0.0,
  "errorMsg": "",
  "openTime": 1666772819000,
  "updateTime": 1666772819000,
  "latestTime": 1666772819000,
  "userMark": "",
  "name": "FTSE China A50 Index - Nov 2022",
  "identifier": "CN2211",
  "account": "1234567",
  "timestamp": 1666772819780,
  "segment": "C"
}

{id=28557131062709999, symbol=CN, market=SI, currency=USD, secType=FUT, action=BUY, isLong=true, totalQuantity=9, totalQuantityScale=0, filledQuantity=3, filledQuantityScale=0, orderType=MKT, avgFillPrice=11824.0, status=PendingSubmit, subStatusList=[], subStatusDescList=[], realizedPnl=0.0, commissionAndFee=9.27, gst=0.65, replaceStatus=NONE, cancelStatus=NONE, source=OpenApi, canModify=true, canCancel=true, multiplier=1.0, stockId=15433673, attr=0, type=orderstatus, outsideRth=false, limitPrice=0.0, errorMsg=, openTime=1666772819000, updateTime=1666772819000, latestTime=1666772819000, userMark=, name=FTSE China A50 Index - Nov 2022, identifier=CN2211, account=1234567, timestamp=1666772819797, segment=C}

{id=28557131062709999, symbol=CN, market=SI, currency=USD, secType=FUT, action=BUY, isLong=true, totalQuantity=9, totalQuantityScale=0, filledQuantity=8, filledQuantityScale=0, orderType=MKT, avgFillPrice=11824.625, status=PendingSubmit, subStatusList=[], subStatusDescList=[], realizedPnl=0.0, commissionAndFee=24.72, gst=1.73, replaceStatus=NONE, cancelStatus=NONE, source=OpenApi, canModify=true, canCancel=true, multiplier=1.0, stockId=15433673, attr=0, type=orderstatus, outsideRth=false, limitPrice=0.0, errorMsg=, openTime=1666772819000, updateTime=1666772819000, latestTime=1666772819000, userMark=, name=FTSE China A50 Index - Nov 2022, identifier=CN2211, account=1234567, timestamp=1666772819808, segment=C}

{id=28557131062709999, symbol=CN, market=SI, currency=USD, secType=FUT, action=BUY, isLong=true, totalQuantity=9, totalQuantityScale=0, filledQuantity=9, filledQuantityScale=0, orderType=MKT, avgFillPrice=11824.6666666667, status=Filled, subStatusList=[], subStatusDescList=[], realizedPnl=0.0, commissionAndFee=27.81, gst=1.95, replaceStatus=NONE, cancelStatus=NONE, source=OpenApi, canModify=false, canCancel=false, multiplier=1.0, stockId=15433673, attr=0, type=orderstatus, outsideRth=false, limitPrice=0.0, errorMsg=, openTime=1666772819000, updateTime=1666772819000, latestTime=1666772819000, userMark=, name=FTSE China A50 Index - Nov 2022, identifier=CN2211, account=1234567, timestamp=1666772819816, segment=C}

String cancelSubscribe(Subject subject) 取消订阅

说明

取消订阅账户变动的推送

输入参数(退订主题)

参数类型是否必填说明
subjectcom.tigerbrokers.stock.openapi.client.struct.enums.SubjectYes订阅主题

Subject 为要取消订阅的主题,主要包括四种:OrderStatus(订单),Asset(资产),Position(持仓),OrderTransaction(订单执行) 含义同订阅主题一致。

⚠️

NOTE

取消任意一个订阅,会把 OrderStatus(订单),Asset(资产),Position(持仓),OrderTransaction(订单执行)四种订阅都取消

示例

// 取消订阅
client.cancelSubscribe(Subject.Asset);
client.cancelSubscribe(Subject.Position);
client.cancelSubscribe(Subject.OrderStatus);
client.cancelSubscribe(Subject.OrderTransaction);

Did this page help you?