实时推送

TypeScript SDK 通过 PushClient 提供基于 Protobuf/TCP+TLS 的实时推送服务，支持行情推送和账户推送，内置自动重连和心跳保活机制。以下为完整可运行示例：

import {
  createClientConfig,
  PushClient,
} from '@tigeropenapi/tigeropen';

async function main() {
  const config = createClientConfig();
  const client = new PushClient(config);

  // 通过 setCallbacks 一次性注册所有回调
  client.setCallbacks({
    onConnect: () => {
      console.log('[推送] 连接成功');
    },
    onDisconnect: () => {
      console.log('[推送] 连接断开，等待自动重连...');
    },
    onError: (err) => {
      console.error('[推送] 发生错误:', err);
    },
    onQuote: (data) => {
      console.log(`[行情] ${data.symbol} 最新价: ${data.latestPrice}`);
    },
    onTick: (data) => {
      console.log(`[逐笔] ${data.symbol} 数量: ${data.volume?.length ?? 0}`);
    },
    onOrder: (data) => {
      console.log(`[订单] id=${data.id} 状态: ${data.status}`);
    },
    onAsset: (data) => {
      console.log('[资产] 账户资产变动', data);
    },
    onPosition: (data) => {
      console.log(`[持仓] ${data.symbol} 数量变更`);
    },
    onTransaction: (data) => {
      console.log(`[成交] ${data.symbol} 价格: ${data.filledPrice}`);
    },
  });

  // 连接推送服务
  await client.connect();

  // 订阅行情推送（同步调用）
  client.subscribeQuote(['AAPL', 'TSLA']);

  // 订阅账户推送（不传 account 时使用 config.account）
  client.subscribeAsset();
  client.subscribeOrder();
  client.subscribePosition();
  client.subscribeTransaction();

  console.log('推送已启动，按 Ctrl+C 退出...');

  // 优雅退出
  process.on('SIGINT', () => {
    client.disconnect();
    process.exit(0);
  });
}

main().catch(console.error);

初始化

constructor 创建推送客户端

new PushClient(config: ClientConfig, options?: PushClientOptions)

说明

创建 PushClient 实例。可传入可选的 PushClientOptions 自定义推送服务地址、心跳间隔、重连行为等。

参数

PushClientOptions

示例

import { createClientConfig, PushClient } from '@tigeropenapi/tigeropen';

const config = createClientConfig();
const client = new PushClient(config);

回调注册

TypeScript SDK 通过 setCallbacks 方法一次性注册所有回调。回调参数类型与服务端推送的 Protobuf 消息一致，由 src/push/pb/*.ts 导出（通过 @tigeropenapi/tigeropen 再导出）。

setCallbacks 设置回调

client.setCallbacks(cb: Callbacks): void

Callbacks 接口

所有回调均为可选，只需在 setCallbacks 里提供需要的字段即可。

示例

client.setCallbacks({
  onQuote: (data) => {
    console.log(`${data.symbol}: ${data.latestPrice}`);
  },
  onOrder: (data) => {
    console.log(`订单 ${data.id} 新状态: ${data.status}`);
  },
});

连接管理

connect / disconnect 连接与断开

client.connect(): Promise<void> client.disconnect(): void

说明

• connect：建立 TCP+TLS 连接并完成鉴权，鉴权通过后 Promise resolve，onConnect 回调触发。
• disconnect：主动断开连接（会先发送 DISCONNECT 消息），不会触发自动重连。

自动重连机制

当连接异常断开时，SDK 会按 reconnectInterval 指数退避（最大 60s）尝试重连；重连成功后会自动恢复之前的行情和账户订阅。每次断开与重连成功时分别触发 onDisconnect 和 onConnect。

示例

await client.connect();
console.log('连接成功');

// 在需要时断开
client.disconnect();

state 获取连接状态

client.state: ConnectionState

说明

只读属性，返回当前连接状态。ConnectionState 为数字枚举。

返回值

示例

import { ConnectionState } from '@tigeropenapi/tigeropen';

console.log('当前状态:', client.state);

if (client.state === ConnectionState.Connected) {
  client.subscribeQuote(['AAPL']);
}

行情推送订阅

v0.4.0 说明：修复了加密货币（Cc）推送的 dispatcher 漏洞 —— 之前订阅 Cc 后收到推送会抛 Unknown DataType 错误，现已修复，Cc 推送统一走 onQuote 回调。同时新增股票/期权排行榜、加密货币行情、市场状态 4 对订阅方法（详见下文「v0.4.0 新增」小节）。

以下行情订阅 / 退订方法均为同步调用（返回 void）。symbols 参数以字符串数组形式传入。

subscribeQuote / unsubscribeQuote 订阅行情

client.subscribeQuote(symbols: string[]): void client.unsubscribeQuote(symbols?: string[]): void

说明

订阅/退订股票的实时行情推送，触发 onQuote 回调；unsubscribeQuote 不传参数则取消全部订阅。

参数

示例

// 订阅行情
client.subscribeQuote(['AAPL', 'TSLA']);

// 退订某只股票
client.unsubscribeQuote(['TSLA']);

subscribeTick / unsubscribeTick 订阅逐笔成交

client.subscribeTick(symbols: string[]): void client.unsubscribeTick(symbols?: string[]): void

说明

订阅/退订逐笔成交数据，触发 onTick 回调（参数类型 TradeTickData）。

示例

client.subscribeTick(['AAPL']);

client.setCallbacks({
  onTick: (data) => {
    console.log(`成交: symbol=${data.symbol} 笔数=${data.volume?.length ?? 0}`);
  },
});

subscribeDepth / unsubscribeDepth 订阅深度行情

client.subscribeDepth(symbols: string[]): void client.unsubscribeDepth(symbols?: string[]): void

说明

订阅/退订盘口深度数据，触发 onDepth 回调（参数类型 QuoteDepthData）。

示例

client.subscribeDepth(['AAPL']);

client.setCallbacks({
  onDepth: (data) => {
    console.log('深度更新:', data.symbol);
  },
});

subscribeOption / unsubscribeOption 订阅期权行情

client.subscribeOption(symbols: string[]): void client.unsubscribeOption(symbols?: string[]): void

说明

订阅/退订期权合约实时行情，触发 onOption 回调（参数类型 QuoteData）。

参数

示例

client.subscribeOption(['AAPL  250117C00150000']);

subscribeFuture / unsubscribeFuture 订阅期货行情

client.subscribeFuture(symbols: string[]): void client.unsubscribeFuture(symbols?: string[]): void

说明

订阅/退订期货合约实时行情，触发 onFuture 回调（参数类型 QuoteData）。

示例

client.subscribeFuture(['ES2506', 'NQ2506']);

subscribeKline / unsubscribeKline 订阅K线

client.subscribeKline(symbols: string[]): void client.unsubscribeKline(symbols?: string[]): void

说明

订阅/退订 K 线数据实时推送，触发 onKline 回调（参数类型 KlineData）。

示例

client.subscribeKline(['AAPL']);

client.setCallbacks({
  onKline: (data) => {
    console.log(`K线 ${data.symbol} open=${data.open} close=${data.close}`);
  },
});

subscribeStockTop / unsubscribeStockTop 订阅股票排行榜 (v0.4.0 新增)

client.subscribeStockTop(market: string, indicators: string[]): void client.unsubscribeStockTop(market: string, indicators: string[]): void

说明

订阅指定市场的股票排行榜实时推送，可选择多个指标（最新价 / 涨幅 / 跌幅 / 成交量 / 成交额 / 振幅 / 换手率 等）。订阅后通过 onStockTop 回调（参数类型 StockTopData）接收数据。

参数

回调

onStockTop: (data: StockTopData) => void

示例

client.setCallbacks({
  onStockTop: (data) => {
    console.log(`[StockTop] market=${data.market} items=${data.topData?.length ?? 0}`);
  },
});
// 订阅
client.subscribeStockTop('US', ['LATEST_PRICE', 'HIGHER', 'LOWER']);
// 退订
client.unsubscribeStockTop('US', ['LATEST_PRICE', 'HIGHER', 'LOWER']);

subscribeOptionTop / unsubscribeOptionTop 订阅期权排行榜 (v0.4.0 新增)

client.subscribeOptionTop(market: string, indicators: string[]): void client.unsubscribeOptionTop(market: string, indicators: string[]): void

说明

订阅指定市场的期权排行榜实时推送，可选择多个指标。订阅后通过 onOptionTop 回调（参数类型 OptionTopData）接收数据。

参数

回调

onOptionTop: (data: OptionTopData) => void

示例

client.setCallbacks({
  onOptionTop: (data) => {
    console.log(`[OptionTop] market=${data.market} items=${data.topData?.length ?? 0}`);
  },
});
client.subscribeOptionTop('US', ['VOLUME', 'AMOUNT']);
client.unsubscribeOptionTop('US', ['VOLUME', 'AMOUNT']);

subscribeCc / unsubscribeCc 订阅加密货币行情 (v0.4.0 新增)

client.subscribeCc(symbols: string[]): void client.unsubscribeCc(symbols?: string[]): void

说明

订阅/退订加密货币实时行情推送。

注意：Cc 推送的数据类型与普通股票行情一致，统一走 onQuote 回调，不是新增的回调函数。dispatcher 会将 Cc dataType 路由到 onQuote（与 Python SDK 保持一致）；v0.4.0 之前的版本会抛 Unknown DataType 错误，已修复。

参数

回调

onQuote: (data: QuoteData) => void （复用行情回调）

示例

client.setCallbacks({
  onQuote: (data) => {
    // Cc 推送也会进入这里
    console.log(`[Quote/Cc] ${data.symbol} latest=${data.latestPrice}`);
  },
});
client.subscribeCc(['BTCUSD', 'ETHUSD']);
client.unsubscribeCc(['BTCUSD', 'ETHUSD']);

subscribeMarket / unsubscribeMarket 订阅市场状态 (v0.4.0 新增)

client.subscribeMarket(market: string): void client.unsubscribeMarket(market: string): void

说明

订阅/退订整个市场的状态变化推送（如开盘、收盘、盘前、盘后等状态切换）。

注意：协议上 dataType 为 Quote + market 字段，因此数据也通过 onQuote 回调送达。

参数

回调

onQuote: (data: QuoteData) => void （复用行情回调）

示例

client.setCallbacks({
  onQuote: (data) => {
    // 市场状态变化也会进入这里
    console.log(`[Market/Quote] symbol=${data.symbol}`);
  },
});
client.subscribeMarket('US');
client.unsubscribeMarket('US');

账户推送订阅

以下账户订阅方法均为同步调用；account 参数可选，不传则使用 config.account。

subscribeAsset / unsubscribeAsset 订阅资产变动

client.subscribeAsset(account?: string): void client.unsubscribeAsset(): void

说明

订阅账户资产变动推送，触发 onAsset 回调（参数类型 AssetData）。

参数

示例

client.subscribeAsset();              // 使用 config.account
client.subscribeAsset(config.account); // 显式指定

client.setCallbacks({
  onAsset: (data) => {
    console.log('账户净值:', data.netLiquidation);
  },
});

subscribePosition / unsubscribePosition 订阅持仓变动

client.subscribePosition(account?: string): void client.unsubscribePosition(): void

说明

订阅持仓变动推送，触发 onPosition 回调（参数类型 PositionData）。

示例

client.subscribePosition();

subscribeOrder / unsubscribeOrder 订阅订单状态

client.subscribeOrder(account?: string): void client.unsubscribeOrder(): void

说明

订阅订单状态变更推送，触发 onOrder 回调（参数类型 OrderStatusData）。订单从提交到成交的每次状态变化都会推送。

示例

client.subscribeOrder();

client.setCallbacks({
  onOrder: (data) => {
    console.log(`订单 id=${data.id} 状态: ${data.status}`);
  },
});

subscribeTransaction / unsubscribeTransaction 订阅成交明细

client.subscribeTransaction(account?: string): void client.unsubscribeTransaction(): void

说明

订阅实时成交明细推送，触发 onTransaction 回调（参数类型 OrderTransactionData）。

示例

client.subscribeTransaction();

client.setCallbacks({
  onTransaction: (data) => {
    console.log(`成交 ${data.symbol} 价格: ${data.filledPrice} 数量: ${data.filledQuantity}`);
  },
});

订阅状态查询

getSubscriptions / getAccountSubscriptions

client.getSubscriptions(): Map<SubjectType, string[]> client.getAccountSubscriptions(): SubjectType[]

说明

查询当前已订阅的行情主题与账户主题。

示例

import { SubjectType } from '@tigeropenapi/tigeropen';

const quoteSubs = client.getSubscriptions();
const acctSubs = client.getAccountSubscriptions();
console.log('行情订阅:', quoteSubs, '账户订阅:', acctSubs);