Real-Time Push

The TypeScript SDK's PushClient maintains a persistent WebSocket connection to the Tiger OpenAPI server. It supports automatic reconnection, heartbeat keep-alive, and callback-based delivery of market data and account events.

Quick Start

import { ClientConfig } from 'tigeropen';
import { PushClient } from 'tigeropen';

const config = new ClientConfig({
  propertiesFilePath: 'tiger_openapi_config.properties',
});

const pc = new PushClient(config);

// Register callbacks before connecting
pc.onConnect = () => {
  console.log('Connected to push server');
};

pc.onDisconnect = () => {
  console.log('Disconnected from push server');
};

pc.onError = (err: Error) => {
  console.error('Push error:', err.message);
};

pc.onQuote = (data) => {
  console.log(`Quote: ${data.symbol}  price=${data.latestPrice}  vol=${data.volume}`);
};

pc.onTick = (data) => {
  console.log(`Tick: ${data.symbol}  price=${data.price}  size=${data.size}`);
};

pc.onOrder = (data) => {
  console.log(`Order update: id=${data.id}  status=${data.status}`);
};

pc.onAsset = (data) => {
  console.log('Asset change received');
};

pc.onPosition = (data) => {
  console.log('Position change received');
};

// Connect and subscribe
await pc.connect();

pc.subscribeQuote(['AAPL', 'TSLA']);
pc.subscribeTick(['AAPL']);
pc.subscribeDepth(['AAPL']);

pc.subscribeAsset();
pc.subscribeOrder();
pc.subscribePosition();
pc.subscribeTransaction();

Client Lifecycle

constructor

constructor(config: ClientConfig, options?: PushClientOptions)

Creates a new PushClient. The client is idle until connect() is called.

Parameter	Type	Description
`config`	ClientConfig	Loaded configuration (credentials, server URL)
`options`	PushClientOptions?	Optional settings (reconnect interval, timeouts)

connect

async connect(): Promise<void>

Opens the WebSocket connection and starts the background receive loop. Returns when the handshake is complete.

await pc.connect();
console.log('Ready to subscribe');

disconnect

disconnect(): void

Gracefully closes the WebSocket connection.

pc.disconnect();

state (getter)

get state(): ConnectionState

Returns the current connection state: 'connecting', 'connected', or 'disconnected'.

console.log('Current state:', pc.state);

Callback Properties

Callbacks are set as properties on the PushClient instance. All are optional.

Property	Type	Triggered when
`onConnect`	`() => void`	Connection established
`onDisconnect`	`() => void`	Connection closed
`onError`	`(err: Error) => void`	A transport or protocol error occurs
`onKickout`	`(reason: string) => void`	Server forces disconnection
`onQuote`	`(data: QuoteData) => void`	Real-time quote update
`onTick`	`(data: TickData) => void`	Trade tick received
`onDepth`	`(data: DepthData) => void`	Order-book depth update
`onOption`	`(data: OptionData) => void`	Option quote update
`onFuture`	`(data: FutureData) => void`	Futures quote update
`onKline`	`(data: KlineData) => void`	K-line bar update
`onAsset`	`(data: AssetData) => void`	Account asset change
`onPosition`	`(data: PositionData) => void`	Position change
`onOrder`	`(data: OrderData) => void`	Order status change
`onTransaction`	`(data: TransactionData) => void`	Fill / execution received

pc.onQuote = (data) => {
  const pct = (data.changeRatio * 100).toFixed(2);
  console.log(`${data.symbol}: $${data.latestPrice} (${pct}%)`);
};

pc.onDepth = (data) => {
  console.log(`Depth update for ${data.symbol}`);
  console.log('  Best bid:', data.bids[0]);
  console.log('  Best ask:', data.asks[0]);
};

pc.onKline = (data) => {
  console.log(`Kline ${data.symbol}: O=${data.open} H=${data.high} L=${data.low} C=${data.close}`);
};

pc.onTransaction = (data) => {
  console.log(`Fill: ${data.symbol} qty=${data.quantity} price=${data.price}`);
};

Market Data Subscriptions

subscribeQuote / unsubscribeQuote

subscribeQuote(symbols: string[]): void
unsubscribeQuote(symbols: string[]): void

Subscribe to or unsubscribe from real-time best-bid/ask and last-price updates.

pc.subscribeQuote(['AAPL', 'TSLA', 'MSFT']);
// Later, remove a single symbol
pc.unsubscribeQuote(['TSLA']);

subscribeTick / unsubscribeTick

subscribeTick(symbols: string[]): void
unsubscribeTick(symbols: string[]): void

Subscribe to tick-by-tick trade data (each individual executed trade).

pc.subscribeTick(['AAPL']);
pc.unsubscribeTick(['AAPL']);

subscribeDepth / unsubscribeDepth

subscribeDepth(symbols: string[]): void
unsubscribeDepth(symbols: string[]): void

Subscribe to Level 2 order-book depth updates (up to 10 bid/ask levels).

pc.subscribeDepth(['AAPL']);
pc.unsubscribeDepth(['AAPL']);

subscribeOption / unsubscribeOption

subscribeOption(symbols: string[]): void
unsubscribeOption(symbols: string[]): void

Subscribe to real-time option quote updates using OCC-style identifiers.

pc.subscribeOption(['AAPL  250117C00150000']);
pc.unsubscribeOption(['AAPL  250117C00150000']);

subscribeFuture / unsubscribeFuture

subscribeFuture(symbols: string[]): void
unsubscribeFuture(symbols: string[]): void

Subscribe to real-time futures quote updates.

pc.subscribeFuture(['ES2506', 'NQ2506']);
pc.unsubscribeFuture(['ES2506']);

subscribeKline / unsubscribeKline

subscribeKline(symbols: string[]): void
unsubscribeKline(symbols: string[]): void

Subscribe to real-time K-line bar updates (1-minute bars by default).

pc.subscribeKline(['AAPL']);
pc.unsubscribeKline(['AAPL']);

Account Subscriptions

subscribeAsset / unsubscribeAsset

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

Subscribe to account asset changes (cash balance, net liquidation value, buying power). Omit account to use the account from the config file.

pc.subscribeAsset();           // use config account
pc.subscribeAsset('DU123456'); // explicit account
pc.unsubscribeAsset();

subscribePosition / unsubscribePosition

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

Subscribe to position updates (new position opened, quantity changed, position closed).

pc.subscribePosition();
pc.unsubscribePosition();

subscribeOrder / unsubscribeOrder

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

Subscribe to order status changes (submitted, partially filled, fully filled, cancelled).

pc.subscribeOrder();
pc.unsubscribeOrder();

subscribeTransaction / unsubscribeTransaction

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

Subscribe to individual fill (execution) events.

pc.subscribeTransaction();
pc.unsubscribeTransaction();

Complete Subscription Reference

// Market data subscriptions
pc.subscribeQuote(['AAPL', 'TSLA']);
pc.subscribeTick(['AAPL']);
pc.subscribeDepth(['AAPL']);
pc.subscribeOption(['AAPL  250117C00150000']);
pc.subscribeFuture(['ES2506']);
pc.subscribeKline(['AAPL']);

// Account subscriptions
pc.subscribeAsset();
pc.subscribePosition();
pc.subscribeOrder();
pc.subscribeTransaction();

// Unsubscribe from market data
pc.unsubscribeQuote(['TSLA']);
pc.unsubscribeTick(['AAPL']);
pc.unsubscribeDepth(['AAPL']);
pc.unsubscribeOption(['AAPL  250117C00150000']);
pc.unsubscribeFuture(['ES2506']);
pc.unsubscribeKline(['AAPL']);

// Unsubscribe from account events
pc.unsubscribeAsset();
pc.unsubscribePosition();
pc.unsubscribeOrder();
pc.unsubscribeTransaction();