实时推送

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

import { ClientConfig } from '@tigeropenapi/tigeropen';
import { PushClient } from '@tigeropenapi/tigeropen';

async function main() {
  const config = ClientConfig.fromPropertiesFile('tiger_openapi_config.properties');
  const client = new PushClient(config);

  // 设置回调（作为属性赋值）
  client.onConnect = () => {
    console.log('[推送] 连接成功');
  };

  client.onDisconnect = () => {
    console.log('[推送] 连接断开，等待自动重连...');
  };

  client.onError = (err: Error) => {
    console.error('[推送] 发生错误:', err);
  };

  client.onQuote = (data) => {
    console.log(`[行情] ${data.symbol} 最新价: ${data.latestPrice} 涨跌幅: ${data.changePercentage}%`);
  };

  client.onTick = (data) => {
    console.log(`[逐笔] ${data.symbol} 成交价: ${data.price} 数量: ${data.volume}`);
  };

  client.onOrder = (data) => {
    console.log(`[订单] ${data.symbol} 状态变更: ${data.status}`);
  };

  client.onAsset = (data) => {
    console.log('[资产] 账户资产变动', data);
  };

  client.onPosition = (data) => {
    console.log(`[持仓] ${data.symbol} 数量变更`);
  };

  client.onTransaction = (data) => {
    console.log(`[成交] ${data.symbol} 成交价: ${data.filledPrice}`);
  };

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

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

  // 订阅账户推送
  await client.subscribeAsset(config.account);
  await client.subscribeOrder(config.account);
  await client.subscribePosition(config.account);
  await client.subscribeTransaction(config.account);

  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 来自定义重连间隔、心跳超时等行为。

参数

参数名	类型	是否必填	描述
config	ClientConfig	是	客户端配置对象
options	PushClientOptions	否	可选配置项，如重连间隔、最大重连次数等

示例

const config = ClientConfig.fromPropertiesFile('tiger_openapi_config.properties');
const client = new PushClient(config);

回调属性

TypeScript SDK 通过属性赋值方式设置回调，无需调用 setCallbacks 方法。所有回调属性均为可选，只需赋值所需的回调：

属性	类型	描述
onConnect	`() => void`	连接成功时触发
onDisconnect	`() => void`	连接断开时触发（自动重连前也会触发）
onError	`(err: Error) => void`	发生错误时触发
onKickout	`(reason: string) => void`	账户被踢出时触发
onQuote	`(data: QuoteData) => void`	收到行情推送时触发
onTick	`(data: TickData) => void`	收到逐笔成交时触发
onDepth	`(data: DepthData) => void`	收到深度行情更新时触发
onOption	`(data: OptionData) => void`	收到期权行情推送时触发
onFuture	`(data: FutureData) => void`	收到期货行情推送时触发
onKline	`(data: KlineData) => void`	收到 K 线数据推送时触发
onAsset	`(data: AssetData) => void`	收到账户资产变动时触发
onPosition	`(data: PositionData) => void`	收到持仓变动时触发
onOrder	`(data: OrderData) => void`	收到订单状态变更时触发
onTransaction	`(data: TransactionData) => void`	收到成交明细时触发

示例

client.onQuote = (data) => {
  console.log(`${data.symbol}: ${data.latestPrice}`);
};

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

连接管理

connect / disconnect 连接与断开

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

说明

connect：建立 WebSocket 连接，返回 Promise，连接成功后 resolve。连接成功后才能订阅数据。
disconnect：主动断开连接，不会触发自动重连。

自动重连机制

当网络中断时，SDK 会自动尝试重连，重连成功后会自动恢复之前的订阅。每次断开和重连成功时分别触发 onDisconnect 和 onConnect 回调。

示例

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

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

get state 获取连接状态

client.state: ConnectionState

说明

只读属性，返回当前 WebSocket 连接状态。

返回值

值	描述
`'disconnected'`	未连接
`'connecting'`	连接中
`'connected'`	已连接
`'reconnecting'`	重连中

示例

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

if (client.state === 'connected') {
  await client.subscribeQuote(['AAPL']);
}

行情推送订阅

subscribeQuote / unsubscribeQuote 订阅行情

client.subscribeQuote(symbols: string[]): Promise<void> client.unsubscribeQuote(symbols: string[]): Promise<void>

说明

订阅/退订股票的实时行情推送，触发 onQuote 回调。

参数

参数名	类型	描述
symbols	string[]	股票代码列表

示例

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

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

subscribeTick / unsubscribeTick 订阅逐笔成交

client.subscribeTick(symbols: string[]): Promise<void> client.unsubscribeTick(symbols: string[]): Promise<void>

说明

订阅/退订逐笔成交数据，触发 onTick 回调。每笔成交会实时推送价格、数量和买卖方向。

示例

await client.subscribeTick(['AAPL']);

client.onTick = (data) => {
  console.log(`成交: ${data.price} x ${data.volume}`);
};

subscribeDepth / unsubscribeDepth 订阅深度行情

client.subscribeDepth(symbols: string[]): Promise<void> client.unsubscribeDepth(symbols: string[]): Promise<void>

说明

订阅/退订买卖五档盘口深度数据，触发 onDepth 回调。

示例

await client.subscribeDepth(['AAPL']);

client.onDepth = (data) => {
  console.log('买一价:', data.bidList[0]?.price);
  console.log('卖一价:', data.askList[0]?.price);
};

subscribeOption / unsubscribeOption 订阅期权行情

client.subscribeOption(symbols: string[]): Promise<void> client.unsubscribeOption(symbols: string[]): Promise<void>

说明

订阅/退订期权合约实时行情，触发 onOption 回调。

参数

参数名	类型	描述
symbols	string[]	期权合约代码列表，格式：`'AAPL 250117C00150000'`

示例

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

subscribeFuture / unsubscribeFuture 订阅期货行情

client.subscribeFuture(symbols: string[]): Promise<void> client.unsubscribeFuture(symbols: string[]): Promise<void>

说明

订阅/退订期货合约实时行情，触发 onFuture 回调。

示例

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

subscribeKline / unsubscribeKline 订阅K线

client.subscribeKline(symbols: string[]): Promise<void> client.unsubscribeKline(symbols: string[]): Promise<void>

说明

订阅/退订 K 线数据实时推送，触发 onKline 回调。每根 K 线完成时推送。

示例

await client.subscribeKline(['AAPL']);

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

账户推送订阅

subscribeAsset / unsubscribeAsset 订阅资产变动

client.subscribeAsset(account: string): Promise<void> client.unsubscribeAsset(): Promise<void>

说明

订阅账户资产变动推送，触发 onAsset 回调。当账户净值、现金余额等发生变化时推送。

参数

参数名	类型	描述
account	string	账户 ID

示例

await client.subscribeAsset(config.account);

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

subscribePosition / unsubscribePosition 订阅持仓变动

client.subscribePosition(account: string): Promise<void> client.unsubscribePosition(): Promise<void>

说明

订阅持仓变动推送，触发 onPosition 回调。当持仓数量或成本变化时推送。

示例

await client.subscribePosition(config.account);

subscribeOrder / unsubscribeOrder 订阅订单状态

client.subscribeOrder(account: string): Promise<void> client.unsubscribeOrder(): Promise<void>

说明

订阅订单状态变更推送，触发 onOrder 回调。订单从提交到成交的每个状态变化都会推送。

示例

await client.subscribeOrder(config.account);

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

subscribeTransaction / unsubscribeTransaction 订阅成交明细

client.subscribeTransaction(account: string): Promise<void> client.unsubscribeTransaction(): Promise<void>

说明

订阅实时成交明细推送，触发 onTransaction 回调。每次成交时立即推送成交价和数量。

示例

await client.subscribeTransaction(config.account);

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