Market Data Subscription Push

Initialization

All examples on this page assume the following initialization has been completed:

from tigeropen.push.push_client import PushClient
from tigeropen.tiger_open_config import TigerOpenClientConfig

client_config = TigerOpenClientConfig(props_path='your_config_directory_path')
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'))
push_client.connect(client_config.tiger_id, client_config.private_key)

For details, see Prerequisites.

For unsubscribe_quote, unsubscribe_cc, unsubscribe_depth_quote, unsubscribe_tick, and unsubscribe_kline, symbols=None and symbols=[] have the same effect: they unsubscribe all symbols for that data type. A non-empty list unsubscribes only the listed symbols.

Subscribe to Stock Quotes

PushClient.subscribe_quote(symbols)

Unsubscribe Method

PushClient.unsubscribe_quote(symbols=None)

Description

Subscribes to and unsubscribes from stock quote updates. The returned data is updated in real-time, meaning data is pushed whenever price or order book data updates.
Callbacks receive basic quote QuoteBasicData (tigeropen.push.pb.QuoteBasicData_pb2.QuoteBasicData) objects and
best bid/offer QuoteBBOData (tigeropen.push.pb.QuoteBasicData_pb2.QuoteBBOData) objects.

Updates are asynchronous. Register PushClient.quote_changed for basic quote QuoteBasicData objects.
Register PushClient.quote_bbo_changed for best bid/offer QuoteBBOData objects.

Cannot subscribe to Hong Kong/US stock index quotes

Parameters

Parameter	Type	Description
symbols	list[str]	List of symbols, e.g., ['AAPL', 'BABA'], English codes should be uppercase

Unsubscribe Method Parameters

Parameter	Type	Description
symbols	list[str]	List of symbols, e.g., ['AAPL', 'BABA']

Return Data

For all stock quote callback fields, see Quote Changes.

⚠️
NOTE
Stock quote callback data has two types: trading data and order book data. The fields returned by these two data types are different.

Example

from tigeropen.push.push_client import PushClient
from tigeropen.push.pb.QuoteBBOData_pb2 import QuoteBBOData
from tigeropen.push.pb.QuoteBasicData_pb2 import QuoteBasicData
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'), use_protobuf=True)

# Define callback methods
def on_quote_changed(frame: QuoteBasicData):
    """Basic quote data callback
    """
    print(f'quote basic change: {frame}')

def on_quote_bbo_changed(frame: QuoteBBOData):
    """Best bid/offer quote, ask/bid 
    """
    print(f'quote bbo changed: {frame}')
  
# Register callbacks
push_client.quote_changed = on_quote_changed
push_client.quote_bbo_changed = on_quote_bbo_changed

# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe
push_client.subscribe_quote(['AAPL', 'BABA'])

# Unsubscribe
push_client.unsubscribe_quote(['AAPL', 'BABA'])
# Disconnect, will cancel all subscriptions
push_client.disconnect()

Callback Data Example

tigeropen.push.pb.QuoteBasicData_pb2.QuoteBasicData data example:

symbol: "00700"
type: BASIC
timestamp: 1677742483530
serverTimestamp: 1677742483586
avgPrice: 365.37
latestPrice: 363.8
latestPriceTimestamp: 1677742483369
latestTime: "03-02 15:34:43"
preClose: 368.8
volume: 12674730
amount: 4630947968
open: 368.2
high: 369
low: 362.4
marketStatus: "Trading"
mi {
  p: 363.8
  a: 365.37
  t: 1677742440000
  v: 27300
}

tigeropen.push.pb.QuoteBasicData_pb2.QuoteBBOData data example:

symbol: "01810"
type: BBO
timestamp: 1677741267291
serverTimestamp: 1677741267329
askPrice: 12.54
askSize: 397600
askTimestamp: 1677741266304
bidPrice: 12.52
bidSize: 787400
bidTimestamp: 1677741266916

Subscribe to Option Quotes

Parameters

Parameter	Type	Description
symbols	list[str]	Composed of four option elements, space-separated: underlying code, expiry date (YYYYMMDD), strike price, option type (CALL/PUT)

Callback Data

Example

push_client.subscribe_option(['AAPL 20230120 150.0 CALL', 'SPY 20220930 470.0 PUT']) or push_client.subscribe_quote(['AAPL 20230120 150.0 CALL', 'SPY 20220930 470.0 PUT'])

from tigeropen.push.push_client import PushClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'))

# Define callback methods
def on_quote_changed(frame: QuoteBasicData):
    """Basic quote data callback
    """
    print(f'quote basic change: {frame}')

def on_quote_bbo_changed(frame: QuoteBBOData):
    """Best bid/offer quote, ask/bid 
    """
    print(f'quote bbo changed: {frame}')

# Register callbacks
push_client.quote_changed = on_quote_changed
push_client.quote_bbo_changed = on_quote_bbo_changed

# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe to option quotes
push_client.subscribe_option(['AAPL 20240119 155.0 PUT', 'SPY 20221118 386.0 CALL'])


# Unsubscribe
push_client.unsubscribe_quote(['AAPL 20240119 155.0 PUT', 'SPY 20221118 386.0 CALL'])
# Disconnect, will cancel all subscriptions
push_client.disconnect()

Subscribe to Futures Quotes

Parameters

Parameter	Type	Description
symbols	`list[str]`	List of futures symbols, e.g., 'CLmain', 'ES2209'

Callback Data

Example

push_client.subscribe_future(['CLmain', 'CN2209'])
# or
push_client.subscribe_quote(['VIXmain', 'ES2209'])

from tigeropen.push.push_client import PushClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'))

# Define callback methods
def on_quote_changed(frame: QuoteBasicData):
    """Basic quote data callback
    """
    print(f'quote basic change: {frame}')

def on_quote_bbo_changed(frame: QuoteBBOData):
    """Best bid/offer quote, ask/bid 
    """
    print(f'quote bbo changed: {frame}')

# Register callbacks
push_client.quote_changed = on_quote_changed
push_client.quote_bbo_changed = on_quote_bbo_changed

# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe to futures quotes
push_client.subscribe_future(['BTCmain', 'CLmain'])


# Unsubscribe
push_client.unsubscribe_quote(['BTCmain', 'CLmain'])
# Disconnect
push_client.disconnect()

Callback Data Example

Basic quotes

symbol: "BTCmain"
type: BASIC
timestamp: 1677571147018
avgPrice: 23562.4
latestPrice: 23355
latestPriceTimestamp: 1677571045000
latestTime: "02-28 01:57:25 -0600"
preClose: 23445
volume: 900
open: 23585
high: 23710
low: 23350
marketStatus: "Trading"
tradeTime: 1677571045000
preSettlement: 23445
minTick: 5
mi {
  p: 23355
  a: 23562.4
  t: 1677571020000
  v: 3
  o: 23350
  h: 23355
  l: 23350
}

Best bid/offer

symbol: "BTCmain"
type: BBO
timestamp: 1677571147018
askPrice: 23365
askSize: 3
askTimestamp: 1677571147018
bidPrice: 23355
bidSize: 1
bidTimestamp: 1677571141150

Subscribe to Crypto Quotes

PushClient.subscribe_cc(symbols)

Cancellation Method

PushClient.unsubscribe_cc(symbols=None)

Description

Subscribes to and unsubscribes from cryptocurrency quote updates. The returned data is updated in real-time, meaning data is pushed whenever price or order book data changes.
Callbacks receive basic quote QuoteBasicData (tigeropen.push.pb.QuoteBasicData_pb2.QuoteBasicData) objects
and best bid/offer QuoteBBOData (tigeropen.push.pb.QuoteBasicData_pb2.QuoteBBOData) objects.

Use PushClient.cc_changed for basic quote QuoteBasicData objects and PushClient.cc_bbo_changed for best bid/offer QuoteBBOData objects.

Parameters

Parameter	Type	Description
symbols	list[str]	List of symbols, e.g. ['BTC'], use uppercase for English symbols

Cancellation Method Parameters

Parameter	Type	Description
symbols	list[str]	List of symbols, e.g. ['BTC']

Return Data

For all quote callback fields, see Quote Changes.

⚠️
NOTE
Quote callback data has two types: trade data and order book data. The fields returned by these two types are different.

Example

from tigeropen.push.push_client import PushClient
from tigeropen.push.pb.QuoteBBOData_pb2 import QuoteBBOData
from tigeropen.push.pb.QuoteBasicData_pb2 import QuoteBasicData
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'), use_protobuf=True)

# Define callback methods
def on_quote_changed(frame: QuoteBasicData):
    """Quote basic data callback
    """
    print(f'quote basic change: {frame}')

def on_quote_bbo_changed(frame: QuoteBBOData):
    """Quote best bid/offer, ask/bid 
    """
    print(f'quote bbo changed: {frame}')
  
# Register callback methods
push_client.cc_changed = on_quote_changed
push_client.cc_bbo_changed = on_quote_bbo_changed

# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe
push_client.subscribe_cc(['BTC'])

# Unsubscribe
push_client.unsubscribe_cc(['BTC'])
# Disconnect, will cancel all subscriptions
push_client.disconnect()

Callback Data Example

tigeropen.push.pb.QuoteBasicData_pb2.QuoteBasicData data example:

	"symbol": "ETH.USD",
	"type": "BASIC",
	"timestamp": "1770041127619",
	"serverTimestamp": "1770041127816",
	"latestPrice": 2322.97,
	"latestPriceTimestamp": "1770041127619",
	"latestTime": "02-02 22:05:27 HKT",
	"preClose": 2313.05,
	"volume": "27711",
	"amount": 6.246553826751E7,
	"open": 2314.18,
	"high": 2374.87,
	"low": 2156.8,
	"marketStatus": "TRADING"

tigeropen.push.pb.QuoteBasicData_pb2.QuoteBBOData data example:



"symbol": "ETH.USD",
    "type": "BBO",
    "timestamp": "1770041127619",
    "askPrice": 2322.97,
    "askTimestamp": "1770041127605",
    "bidPrice": 2322.95,
    "bidSize": "1",
    "bidTimestamp": "1770041127605"

Subscribe to Market Depth

PushClient.subscribe_depth_quote(symbols)

Unsubscribe Method

PushClient.unsubscribe_depth_quote(symbols=None)

Description

Subscribe to market depth for stocks (US/HK), options (US/HK), and futures. US market depth updates every 300ms, while HK market depth updates every 2s; each update returns up to 40 levels of bid/ask order book data. The server pushes the latest order-book snapshot at the corresponding interval.
Updates are asynchronous. Register PushClient.quote_depth_changed to receive QuoteDepthData (tigeropen.push.pb.QuoteDepthData_pb2.QuoteDepthData) objects.

Parameters

Parameter	Type	Description
symbols	`list[str]`	List of symbols, e.g., `['AAPL', 'BABA', 'ESmain', 'AAPL 20240209 180.0 CALL']`

Unsubscribe Method Parameters

Parameter	Type	Description
symbols	`list[str]`	List of symbols, e.g., `['AAPL', 'BABA']`

Example

from tigeropen.push.push_client import PushClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'))

# Define callback methods
def on_quote_depth_changed(frame: QuoteDepthData):
    print(f'quote depth changed: {frame}')
    # Print prices
    print(f'ask price: {frame.ask.price}')
    # First level price
    print(f'ask price item 0: {frame.ask.price[0]}')

    
# Register callbacks
push_client.quote_depth_changed = on_quote_depth_changed
  
# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe to market depth
push_client.subscribe_depth_quote(['AMD', 'MSFT'])


# Unsubscribe
push_client.unsubscribe_depth_quote(['AMD', 'MSFT'])
# Disconnect, will cancel all subscriptions
push_client.disconnect()

Callback Data

tigeropen.push.pb.QuoteDepthData_pb2.QuoteDepthData

⚠️
NOTE
This API will only push up to the top 40 levels of bid/ask data

Data structure:

Field	Type	Description
symbol	string	Stock symbol
timestamp	long	Order book timestamp
ask	OrderBook	Ask side data
bid	OrderBook	Bid side data

OrderBook data structure:

Field	Type	Description
price	`list[float]`	Price for each level
volume	`list[int]`	Order volume
orderCount	`list[int]`	Number of orders (only for HK stocks)
exchange	string	Option data source (only for options). A price or volume of 0 means the quote from this source has expired. See Option Exchanges.
time	long	Option exchange order timestamp (only for options)

Callback Data Example

Order book data example. Adjacent levels may have the same price, where count is optional:

symbol: "00700"
timestamp: 1677742734822
ask {
  price: 363.8
  price: 364
  price: 364.2
  price: 364.4
  price: 364.6
  price: 364.8
  price: 365
  price: 365.2
  price: 365.4
  price: 365.6
  volume: 26900
  volume: 14800
  volume: 15200
  volume: 31500
  volume: 15800
  volume: 7700
  volume: 29400
  volume: 6300
  volume: 6000
  volume: 5500
  orderCount: 27
  orderCount: 20
  orderCount: 19
  orderCount: 22
  orderCount: 14
  orderCount: 10
  orderCount: 20
  orderCount: 12
  orderCount: 10
  orderCount: 11
}
bid {
  price: 363.6
  price: 363.4
  price: 363.2
  price: 363
  price: 362.8
  price: 362.6
  price: 362.4
  price: 362.2
  price: 362
  price: 361.8
  volume: 9400
  volume: 19900
  volume: 35300
  volume: 74200
  volume: 26300
  volume: 16700
  volume: 22500
  volume: 21100
  volume: 40500
  volume: 5600
  orderCount: 16
  orderCount: 23
  orderCount: 36
  orderCount: 79
  orderCount: 30
  orderCount: 32
  orderCount: 31
  orderCount: 34
  orderCount: 143
  orderCount: 26
}

Subscribe to Trade Ticks

PushClient.subscribe_tick(symbols)

Unsubscribe Method

PushClient.unsubscribe_tick(symbols=None)

Description

Trade tick updates are asynchronous. Register PushClient.tick_changed to receive them.
Because trade ticks use a compressed format, the callback data type differs from other market data: it is the converted tigeropen.push.pb.trade_tick.TradeTick, not the original Protobuf type.
Both stocks and futures use this method.

Trade ticks are pushed every 200ms in snapshot mode, with the latest 50 records in each push.

Parameters

Parameter	Type	Description
symbols	list[str]	List of symbols, e.g. ['AAPL', 'BABA']

Unsubscribe Method Parameters

Parameter	Type	Description
symbols	list[str]	List of symbols, e.g. ['AAPL', 'BABA']

Example

import time
from tigeropen.push.pb.trade_tick import TradeTick
from tigeropen.push.push_client import PushClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'))

# Subscribe callback method
def on_tick_changed(data: TradeTick):
    print(f'tick changed: {data}')

    
# Register the callback
push_client.tick_changed = on_tick_changed   
  
# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe to trade ticks
push_client.subscribe_tick(['AMD', 'MSFT'])
# Subscribe to futures ticks
push_client.subscribe_tick(['HSImain', 'CNmain'])


time.sleep(10)
# Unsubscribe
push_client.unsubscribe_tick(['AMD', 'MSFT'])
# Disconnect, will cancel all subscriptions
push_client.disconnect()

Callback Data

tigeropen.push.pb.trade_tick.TradeTick

This callback returns a converted TradeTick/TradeTickItem object with snake_case field names. This differs from other push chapters which return raw protobuf objects with camelCase names.

TradeTick data structure is as follows:

Field	Type	Description
symbol	str	Stock symbol, futures symbol
sec_type	str	STK/FUT
quote_level	str	Market data access level where data originates (for US stocks, `usQuoteBasic` provides fewer trade ticks than `usStockQuote`); futures have no level distinction
timestamp	int	Data timestamp
ticks	`list[TradeTickItem]`	Collection of trade ticks

ticks data structure is as follows:

Field	Type	Description
sn	int	Tick sequence number
volume	int	Volume
tick_type	str	means unchanged, + means up, - means down (futures ticks don't have this)
price	double	Transaction price
time	int	Trade timestamp
cond	str	Decoded trade condition for this tick; see Trade Tick Conditions. Futures ticks do not provide this field.
part_code	str	Exchange code for each trade (US stocks only)
part_code_name	str	Exchange name for each trade (US stocks only)

Callback Data Example

symbol: "00700"
type: "-+"
sn: 37998
priceBase: 3636
priceOffset: 1
time: 1677742815311
time: 69
price: 0
price: 2
volume: 500
volume: 100
quoteLevel: "hkStockQuoteLv2"
timestamp: 1677742815776
secType: "STK"

Subscribe to Full Trade Ticks

PushClient.subscribe_tick(symbols)

Unsubscribe Method

PushClient.unsubscribe_tick(symbols=None)

Description

Subscribes to stock full tick-by-tick trade data. Requires permission approval from your account manager. Full tick-by-tick trade updates are asynchronous. Register PushClient.full_tick_changed to receive them.
Callback object tigeropen.push.pb.TickData_pb2.TickData

Parameters

Parameter	Type	Description
symbols	`list[str]`	List of symbols, e.g. `['AAPL', 'BABA']`

Also, modify the configuration client_config.use_full_tick = True to enable full tick mode, and pass client_config=client_config when initializing PushClient

Unsubscribe Method Parameters

Parameter	Type	Description
symbols	`list[str]`	List of symbols, e.g. `['AAPL', 'BABA']`

Example

import time
from tigeropen.push.pb.TickData_pb2 import TickData
from tigeropen.push.push_client import PushClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')

client_config.use_full_tick = True
# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'), client_config=client_config)

# Subscribe callback method
def on_full_tick_changed(frame: TickData):
    print(f'full tick changed: {frame}')

    
# Register the callback
push_client.full_tick_changed = on_full_tick_changed
  
# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe to full trade ticks
push_client.subscribe_tick(['AMD', 'MSFT', '00700'])


time.sleep(10)
# Unsubscribe
push_client.unsubscribe_tick(['AMD', 'MSFT'])
# Disconnect, will cancel all subscriptions
push_client.disconnect()

Callback Data

tigeropen.push.pb.TickData_pb2.TickData

TickData data structure is as follows:

Field	Type	Description
symbol	str	Stock symbol, futures symbol
source	str	Data source identifier, e.g. "NLS" (National Last Sale)
timestamp	int	Data timestamp
ticks	`list[Tick]`	Collection of full trade ticks

Each Tick item in ticks has the following data structure:

Field	Type	Description
sn	int	Tick sequence number
volume	int	Volume
type	str	means unchanged, + means up, - means down (futures ticks don't have this)
price	double	Transaction price
time	int	Trade timestamp
partCode	str	Exchange code for each trade (US stocks only)

Callback Data Example

symbol: "NVDA"
ticks {
  sn: 2381
  time: 1712669401076
  price: 874.1
  volume: 10
  type: "*"
  partCode: "t"
}
ticks {
  sn: 2382
  time: 1712669401076
  price: 874.1
  volume: 11
  type: "*"
  partCode: "t"
}
ticks {
  sn: 2383
  time: 1712669401076
  price: 874.1
  volume: 3
  type: "*"
  partCode: "t"
}
timestamp: 1712669403808
source: "NLS"

Subscribe to Minute Bars

PushClient.subscribe_kline(symbols=None)

Unsubscribe Method

PushClient.unsubscribe_kline(symbols=None)

Description

Subscribe to minute candlestick bars for stocks.

Request Parameters

Parameter	Type	Description
symbols	list[str]	List of stock symbols

Callback

Subscription Example

from tigeropen.push.push_client import PushClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'))

def on_kline_changed(frame: KlineData):
    print(f'kline changed: {frame}')
    
push_client.kline_changed = on_kline_changed

push_client.connect(client_config.tiger_id, client_config.private_key)

symbols = ['AAPL']

push_client.subscribe_kline(symbols)

Callback Result Example

{
  "time":"1712584560000",
  "open":168.9779,
  "high":169.0015,
  "low":168.9752,
  "close":169.0,
  "avg":168.778,
  "volume":"3664",
  "count":114,
  "symbol":"AAPL",
  "amount":617820.6508,
  "serverTimestamp":"1712584569746"
}

Subscribe to Stock Popular Trading Rankings

PushClient.subscribe_stock_top(market, indicators=None)

Unsubscribe Method

PushClient.unsubscribe_stock_top(market, indicators=None)

Description

Subscribe to stock market ranking data. No pushes occur during non-trading hours. The server runs the ranking push task every 30 seconds; ranking size is configurable and defaults to 10.
Updates are asynchronous. Register PushClient.stock_top_changed to receive StockTopData objects. Each indicator is sorted by value in descending order.

Supports subscription to US and Hong Kong market stock indicators. Intraday data rankings have all indicators from StockRankingIndicator. US pre-market and after-hours only have change rate (changeRate) and 5-minute change rate (changeRate5Min) ranking data.

Parameters

Parameter	Type	Required	Description
market	str or Market enum	Yes	Market, supports HK, US
indicators	`list[tigeropen.common.consts.StockRankingIndicator]`	No	Stock ranking indicators, defaults to all indicators. Refer to StockRankingIndicator enum values (changeRate: daily change rate; changeRate5Min: 5-minute change rate; turnoverRate: turnover rate; amount: daily turnover amount; volume: daily volume; amplitude: daily amplitude)

Callback Data

StockTopData data structure is as follows:

Field	Type	Description
market	str	Market: US/HK
timestamp	int	Timestamp
topData	`list[TopData]`	List of ranking data for each indicator

TopData data structure is as follows:

Field	Type	Description
targetName	str	Indicator name (changeRate, changeRate5Min, turnoverRate, amount, volume, amplitude)
item	`list[StockItem]`	List of ranking data under this indicator dimension

StockItem data structure is as follows:

Field	Type	Description
symbol	str	Symbol
latestPrice	float	Latest price
targetValue	float	Corresponding indicator value

Example

from tigeropen.push.push_client import PushClient
from tigeropen.common.consts import OptionRankingIndicator, StockRankingIndicator
from tigeropen.push.pb.StockTopData_pb2 import StockTopData
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'))

# Define callback method
def on_stock_top_changed(frame: StockTopData):
    print(f'stock top changed: {frame}')

# Register the callback
push_client.stock_top_changed = on_stock_top_changed

# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe
push_client.subscribe_stock_top("HK", [StockRankingIndicator.Amount])

# Unsubscribe
push_client.unsubscribe_stock_top("HK", [StockRankingIndicator.Amount])

Callback Data Example

topData {
  targetName: "amount"
  item {
    symbol: "02800"
    latestPrice: 19.55
    targetValue: 3338633741
  }
  item {
    symbol: "00700"
    latestPrice: 338.8
    targetValue: 2950736047
  }
  item {
    symbol: "02828"
    latestPrice: 66.34
    targetValue: 1533436182
  }
  item {
    symbol: "09988"
    latestPrice: 85.2
    targetValue: 1396707122
  }
  item {
    symbol: "02269"
    latestPrice: 37.1
    targetValue: 1238930730
  }
  item {
    symbol: "03690"
    latestPrice: 127.9
    targetValue: 1167532142
  }
  item {
    symbol: "01211"
    latestPrice: 262.6
    targetValue: 716540400
  }
  item {
    symbol: "03033"
    latestPrice: 3.916
    targetValue: 629691374
  }
  item {
    symbol: "01357"
    latestPrice: 3.29
    targetValue: 589222680
  }
  item {
    symbol: "02318"
    latestPrice: 50.25
    targetValue: 572686837
  }
  item {
    symbol: "01299"
    latestPrice: 80.25
    targetValue: 510098294
  }
  item {
    symbol: "09888"
    latestPrice: 139.7
    targetValue: 504564066
  }
  item {
    symbol: "00388"
    latestPrice: 303.8
    targetValue: 488918091
  }
  item {
    symbol: "07226"
    latestPrice: 4.85
    targetValue: 477161727
  }
  item {
    symbol: "01398"
    latestPrice: 4.16
    targetValue: 459215853
  }
  item {
    symbol: "02331"
    latestPrice: 43.2
    targetValue: 439082885
  }
  item {
    symbol: "02015"
    latestPrice: 137.8
    targetValue: 407068273
  }
  item {
    symbol: "09618"
    latestPrice: 143.9
    targetValue: 389690725
  }
  item {
    symbol: "07552"
    latestPrice: 6.59
    targetValue: 387550625
  }
  item {
    symbol: "01024"
    latestPrice: 54.85
    targetValue: 350567971
  }
  item {
    symbol: "00981"
    latestPrice: 20.65
    targetValue: 349594737
  }
  item {
    symbol: "00386"
    latestPrice: 4.47
    targetValue: 347819789
  }
  item {
    symbol: "00883"
    latestPrice: 11.12
    targetValue: 320431605
  }
  item {
    symbol: "09868"
    latestPrice: 44.05
    targetValue: 292605044
  }
  item {
    symbol: "02020"
    latestPrice: 81.95
    targetValue: 285153726
  }
  item {
    symbol: "03968"
    latestPrice: 36.25
    targetValue: 273604906
  }
  item {
    symbol: "00939"
    latestPrice: 5.05
    targetValue: 270755731
  }
  item {
    symbol: "01088"
    latestPrice: 23.6
    targetValue: 265332533
  }
  item {
    symbol: "00020"
    latestPrice: 2.14
    targetValue: 256621941
  }
  item {
    symbol: "00941"
    latestPrice: 63.25
    targetValue: 248440129
  }
}

Subscribe to Option Popular Trading Rankings

PushClient.subscribe_option_top(market, indicators=None)

Unsubscribe Method

PushClient.unsubscribe_option_top(market, indicators=None)

Description

Subscribe to options market ranking data. No pushes occur during non-trading hours. The server runs the ranking push task every 30 seconds; ranking size is configurable and defaults to 10.
Updates are asynchronous. Register PushClient.option_top_changed to receive OptionTopData objects. Unusually large orders are individual trades with volume greater than 1,000 and are sorted in reverse chronological order. Other indicators are cumulative values for the trading day, sorted in descending order.

Option rankings support the US market only and include all OptionRankingIndicator values during trading hours.

Parameters

Parameter Name	Type	Required	Description
market	str or Market enum	Yes	Market; only US is supported
indicators	`list[tigeropen.common.consts.OptionRankingIndicator]`	No	Options ranking indicators, defaults to all indicators, refer to OptionRankingIndicator enum values (bigOrder: unusual large orders, volume: daily cumulative volume, amount: daily cumulative turnover, openInt: open interest)

Callback Data

OptionTopData data structure is as follows:

Field	Type	Description
market	string	Market: US
timestamp	long	Timestamp
topData	`list[TopData]`	List of ranking data for each indicator

TopData data structure is as follows:

Field	Type	Description
targetName	string	Indicator name (bigOrder, volume, amount, openInt)
bigOrder	`list[BigOrder]`	Unusual large orders indicator (bigOrder) data list
item	`list[OptionItem]`	Ranking data list under this indicator dimension

BigOrder data structure is as follows:

Field	Type	Description
symbol	str	Stock ETF underlying
expiry	str	Expiry date, format: yyyyMMdd
strike	str	Strike price
right	str	CALL/PUT
dir	str	Buy/Sell direction: BUY/SELL/NONE
volume	float	Volume
price	float	Trade price
amount	float	Turnover
tradeTime	int	Trade timestamp

OptionItem data structure is as follows:

Field	Type	Description
symbol	str	Stock ETF underlying
expiry	str	Expiry date, format: yyyyMMdd
strike	str	Strike price
right	str	CALL/PUT
totalAmount	float	Turnover
totalVolume	float	Volume
totalOpenInt	float	Open interest
volumeToOpenInt	float	Volume/Open interest
latestPrice	float	Latest price
updateTime	int	Indicator data update timestamp

Example

from tigeropen.push.push_client import PushClient
from tigeropen.common.consts import OptionRankingIndicator
from tigeropen.push.pb.OptionTopData_pb2 import OptionTopData

from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'))

# Define callback method
def on_option_top_changed(frame: OptionTopData):
    print(f'option top changed: {frame}')

# Register the callback
push_client.option_top_changed = on_option_top_changed

# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe
push_client.subscribe_option_top("US", [OptionRankingIndicator.Amount])

# Unsubscribe
push_client.unsubscribe_option_top("US", [OptionRankingIndicator.Amount])

Callback Data Example

{
    "market":"US",
    "timestamp":"1687277160445",
    "topData":[
        {
            "targetName":"volume",
            "item":[
                {
                    "symbol":"SPY",
                    "expiry":"20230620",
                    "strike":"435.0",
                    "right":"PUT",
                    "totalAmount":5394115,
                    "totalVolume":212478,
                    "totalOpenInt":16377,
                    "volumeToOpenInt":0.012467,
                    "latestPrice":0.25,
                    "updateTime":"1687277254390"
                },
                {
                    "symbol":"SPY",
                    "expiry":"20230620",
                    "strike":"436.0",
                    "right":"PUT",
                    "totalAmount":7754077,
                    "totalVolume":194423,
                    "totalOpenInt":13403,
                    "volumeToOpenInt":0.011408,
                    "latestPrice":0.58,
                    "updateTime":"1687277213603"
                },
                {
                    "symbol":"SPY",
                    "expiry":"20230620",
                    "strike":"437.0",
                    "right":"PUT",
                    "totalAmount":10420625,
                    "totalVolume":182078,
                    "totalOpenInt":13973,
                    "volumeToOpenInt":0.010683,
                    "latestPrice":1.17,
                    "updateTime":"1687277213602"
                },
                {
                    "symbol":"SPY",
                    "expiry":"20230620",
                    "strike":"438.0",
                    "right":"CALL",
                    "totalAmount":4482482,
                    "totalVolume":181899,
                    "totalOpenInt":961,
                    "volumeToOpenInt":0.010673,
                    "latestPrice":0.09,
                    "updateTime":"1687277213603"
                },
                {
                    "symbol":"SPY",
                    "expiry":"20230620",
                    "strike":"436.0",
                    "right":"CALL",
                    "totalAmount":7331667,
                    "totalVolume":150604,
                    "totalOpenInt":238,
                    "volumeToOpenInt":0.008837,
                    "latestPrice":0.66,
                    "updateTime":"1687277208599"
                }
                // .....
            ]
        },
        {
            "targetName":"amount",
            "item":[
                {
                    "symbol":"TSLA",
                    "expiry":"20230721",
                    "strike":"5.0",
                    "right":"CALL",
                    "totalAmount":34061561,
                    "totalVolume":1812,
                    "totalOpenInt":18,
                    "volumeToOpenInt":0.00023,
                    "latestPrice":259.99,
                    "updateTime":"1687276953360"
                },
                {
                    "symbol":"TSLA",
                    "expiry":"20230721",
                    "strike":"500.0",
                    "right":"PUT",
                    "totalAmount":30877216,
                    "totalVolume":1960,
                    "volumeToOpenInt":0.000248,
                    "latestPrice":234.97,
                    "updateTime":"1687276953360"
                },
                {
                    "symbol":"TSLA",
                    "expiry":"20230623",
                    "strike":"265.0",
                    "right":"CALL",
                    "totalAmount":27928028,
                    "totalVolume":66361,
                    "totalOpenInt":12928,
                    "volumeToOpenInt":0.008405,
                    "latestPrice":6.5,
                    "updateTime":"1687277264395"
                },
                {
                    "symbol":"SPY",
                    "expiry":"20230721",
                    "strike":"420.0",
                    "right":"CALL",
                    "totalAmount":21629503,
                    "totalVolume":11105,
                    "totalOpenInt":46931,
                    "volumeToOpenInt":0.000652,
                    "latestPrice":19.27,
                    "updateTime":"1687273142271"
                },
                {
                    "symbol":"TSLA",
                    "expiry":"20230623",
                    "strike":"270.0",
                    "right":"CALL",
                    "totalAmount":17657903,
                    "totalVolume":61012,
                    "totalOpenInt":14302,
                    "volumeToOpenInt":0.007728,
                    "latestPrice":4.52,
                    "updateTime":"1687277254390"
                }
                // .....
            ]
        },
        {
            "targetName":"openInt",
            "item":[
                {
                    "symbol":"AMC",
                    "expiry":"20230721",
                    "strike":"10.0",
                    "right":"CALL",
                    "totalAmount":4933,
                    "totalVolume":750,
                    "totalOpenInt":340843,
                    "volumeToOpenInt":0.00022,
                    "latestPrice":0.1,
                    "updateTime":"1687276788220"
                },
                {
                    "symbol":"AMC",
                    "expiry":"20230721",
                    "strike":"10.0",
                    "right":"PUT",
                    "totalVolume":1,
                    "totalOpenInt":321814,
                    "latestPrice":6.2,
                    "updateTime":"1687276853278"
                },
                {
                    "symbol":"AMC",
                    "expiry":"20230721",
                    "strike":"4.0",
                    "right":"PUT",
                    "totalAmount":117982,
                    "totalVolume":2748,
                    "totalOpenInt":242101,
                    "volumeToOpenInt":0.000806,
                    "latestPrice":0.81,
                    "updateTime":"1687277034280"
                },
                {
                    "symbol":"ATVI",
                    "expiry":"20240119",
                    "strike":"85.0",
                    "right":"PUT",
                    "totalAmount":3500,
                    "totalVolume":26,
                    "totalOpenInt":230702,
                    "volumeToOpenInt":0.000016,
                    "latestPrice":7,
                    "updateTime":"1687274092822"
                },
                {
                    "symbol":"EEM",
                    "expiry":"20231215",
                    "strike":"47.0",
                    "right":"CALL",
                    "totalAmount":310,
                    "totalVolume":15,
                    "totalOpenInt":183054,
                    "volumeToOpenInt":0.000003,
                    "latestPrice":0.18,
                    "updateTime":"1687269619956"
                }
                // .....
            ]
        },
        {
            "targetName":"bigOrder",
            "bigOrder":[
                {
                    "symbol":"AMC",
                    "expiry":"20230818",
                    "strike":"10.0",
                    "right":"PUT",
                    "dir":"Buy",
                    "volume":1000,
                    "price":6.94,
                    "amount":694000,
                    "tradeTime":"1687276860753"
                },
                {
                    "symbol":"GLPI",
                    "expiry":"20230818",
                    "strike":"50.0",
                    "right":"CALL",
                    "dir":"Sell",
                    "volume":1094,
                    "price":1.2,
                    "amount":131280,
                    "tradeTime":"1687276744519"
                },
                {
                    "symbol":"AMD",
                    "expiry":"20230818",
                    "strike":"140.0",
                    "right":"CALL",
                    "dir":"Buy",
                    "volume":1700,
                    "price":3.25,
                    "amount":552500,
                    "tradeTime":"1687276467421"
                },
                {
                    "symbol":"AAPL",
                    "expiry":"20230915",
                    "strike":"185.0",
                    "right":"PUT",
                    "dir":"Sell",
                    "volume":1500,
                    "price":6.65,
                    "amount":997500,
                    "tradeTime":"1687276413267"
                },
                {
                    "symbol":"BABA",
                    "expiry":"20240119",
                    "strike":"75.0",
                    "right":"PUT",
                    "dir":"Sell",
                    "volume":1500,
                    "price":4.8,
                    "amount":720000,
                    "tradeTime":"1687276036749"
                }
                // .....
            ]
        }
    ]
}

Query Subscribed Symbols

PushClient.query_subscribed_quote()

Description

Retrieves the list of subscribed symbols.

This API returns asynchronously. In Protobuf mode, the callback receives a JSON string that must be decoded; in STOMP mode, it receives a dictionary.

Parameters

None

Callback Data

The callback data structure is as follows:

Field	Type	Description
limit	int	Maximum for subscribed quote symbols (stocks, options, futures)
used	int	Number of subscribed quote symbols (stocks, options, futures)
subscribed_symbols	list	Subscribed quote symbols (stocks, options, futures)
quote_depth_limit	int	Maximum number of market depth subscriptions
quote_depth_used	int	Number of market depth subscriptions used
subscribed_quote_depth_symbols	list	Symbols subscribed to market depth
trade_tick_limit	int	Maximum number of trade tick subscriptions
trade_tick_used	int	Number of trade tick subscriptions used
subscribed_trade_tick_symbols	list	Symbols subscribed to trade ticks

Example

import json
import time
from tigeropen.push.push_client import PushClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='your_config_directory_path')


# Initialize PushClient
protocol, host, port = client_config.socket_host_port
push_client = PushClient(host, port, use_ssl=(protocol == 'ssl'), use_protobuf=True)

# Define callback method
def query_subscribed_callback(data):
    """
    data example:
        {'subscribed_symbols': ['QQQ'], 'limit': 1200, 'used': 1, 'symbol_focus_keys': {'qqq': ['open', 'prev_close', 'low', 'volume', 'latest_price', 'close', 'high']},
         'subscribed_quote_depth_symbols': ['NVDA'], 'quote_depth_limit': 20, 'quote_depth_used': 1,
         'subscribed_trade_tick_symbols': ['QQQ', 'AMD', '00700'], 'trade_tick_limit': 1200, 'trade_tick_used': 3}
    """
    # Protobuf mode passes JSON text; STOMP mode passes a dict.
    result = json.loads(data) if isinstance(data, str) else data
    print(f'subscribed data:{result}')
    print(f'subscribed symbols:{result["subscribed_symbols"]}')
    

# Register the callback
push_client.query_subscribed_callback = query_subscribed_callback   
  
# Establish connection        
push_client.connect(client_config.tiger_id, client_config.private_key)

# Create a market data subscription
push_client.subscribe_quote(['QQQ'])
# Subscribe to market depth
push_client.subscribe_depth_quote(['NVDA'])
push_client.subscribe_depth_quote(['HSImain'])

# Subscribe to trade ticks
push_client.subscribe_tick(['QQQ'])
push_client.subscribe_tick(['HSImain'])

# Query subscribed contracts
push_client.query_subscribed_quote()

time.sleep(10)

Callback Data Example

{'subscribed_symbols': ['QQQ'], 'limit': 1200, 'used': 1,
 'subscribed_quote_depth_symbols': ['NVDA'], 'quote_depth_limit': 20, 'quote_depth_used': 1,
 'subscribed_trade_tick_symbols': ['QQQ', 'AMD', '00700'], 'trade_tick_limit': 1200, 'trade_tick_used': 3
 }