Account Change Push Notifications

Initialization

All examples on this page assume the following initialization has been completed (push client):

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.

All APIs on this page are asynchronous and deliver updates through registered callbacks.

If a subscription does not specify an account, its callback receives data for every account associated with the tiger_id. Use the account field to route each update.

Asset Change Subscription and Cancellation

Subscription Method

PushClient.subscribe_asset(account)

Cancellation Method

PushClient.unsubscribe_asset()

Note

Asset data is pushed as a full snapshot every 5 seconds by default, with the same frequency applied to both live and paper trading accounts.

Parameters

Parameter	Type	Description
account	str	Account ID to subscribe to. If not provided, subscribes to all associated accounts. Note: If no account is specified during subscription, callback will push data for multiple accounts, and you need to determine which account the data belongs to when processing callbacks

Return

Handle asset updates through PushClient.asset_changed. Each update is a tigeropen.push.pb.AssetData_pb2.AssetData object. See AssetChange.

For related asset fields, see get_prime_assets and get_assets.

For full field definitions, see PortfolioAccount Assets (Prime/Paper Trading Account) and PortfolioAccount Global Assets.

Callback Data Field Meanings

The callback includes the following fields:

Field	Type	Description
account	str	Fund account number
currency	str	Currency. USD for US Dollar, HKD for Hong Kong Dollar
segType	str	Classification by trading instrument. S for stocks, C for futures, D for cryptocurrencies, F for funds, CONSOLIDATED for the aggregation of stocks and funds.
availableFunds	float	Available funds, overnight remaining liquidity
excessLiquidity	float	Current remaining liquidity
netLiquidation	float	Total assets (net liquidation value). Total assets is the sum of net cash balance and total market value of securities in our account
equityWithLoan	float	Total equity with loan value. Equals total assets - US stock options
buyingPower	float	Buying power. Only applicable to stock instruments, i.e., meaningful when segment is S
cashBalance	float	Cash amount. Sum of current cash balances in all currencies
grossPositionValue	float	Total securities value
initMarginReq	float	Initial margin requirement
maintMarginReq	float	Maintenance margin requirement
timestamp	int	Timestamp

Example

from tigeropen.push.pb.AssetData_pb2 import AssetData
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'))

# Define callback method
def on_asset_changed(frame: AssetData):
    """Process an asset update; this example prints selected fields."""
    print(f'asset change. {frame}')
    # View available funds
    print(frame.availableFunds)
    # View position market value
    print(frame.grossPositionValue)

# Register the callback
push_client.asset_changed = on_asset_changed
# Connect
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe 
push_client.subscribe_asset(account=client_config.account)


# Unsubscribe from asset changes
# push_client.unsubscribe_asset()

Callback Data Example

account: "111111"
currency: "USD"
segType: "S"
availableFunds: 1593.1191893
excessLiquidity: 1730.5666908
netLiquidation: 2856.1016998
equityWithLoan: 2858.1016998
buyingPower: 6372.4767571
cashBalance: 484.1516697
grossPositionValue: 2373.95003
initMarginReq: 1264.9825105
maintMarginReq: 1127.535009
timestamp: 1677745420121

Position Change Subscription and Cancellation

Subscription Method

PushClient.subscribe_position(account)

Cancellation Method

PushClient.unsubscribe_position()

Note

Position data is pushed as a full snapshot every 5 seconds by default, with the same frequency applied to both live and paper trading accounts.

Parameters

Parameter	Type	Description
account	str	Account ID to subscribe to. If not provided, subscribes to all associated accounts. Note: If no account is specified during subscription, callback will push data for multiple accounts, and you need to determine which account the data belongs to when processing callbacks

Example

from tigeropen.push.pb.PositionData_pb2 import PositionData
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'))

# Define callback method
def on_position_changed(frame: PositionData):
    print(f'position change. {frame}')
    # Position symbol
    print(frame.symbol)
    # Position cost
    print(frame.averageCost)
    
# Register the callback
push_client.position_changed = on_position_changed
# Connect
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe to position changes
push_client.subscribe_position(account=client_config.account)
# Unsubscribe from position changes
push_client.unsubscribe_position()

Return

Handle position updates through PushClient.position_changed. Each update is a tigeropen.push.pb.PositionData_pb2.PositionData object. See PositionChange, get_positions, and the Position object.

Field	Type	Description
account	str	Fund account number
symbol	str	Position symbol code, e.g., 'AAPL', '00700', 'ES', 'CN'
expiry	str	Only for options, warrants, CBBC
strike	str	Only for options, warrants, CBBC
right	str	Only for options, warrants, CBBC
identifier	str	Symbol identifier. For stocks, identifier is the same as symbol. For futures, it includes contract month, e.g., 'CN2201'
multiplier	int	Quantity per lot, limited to futures, options, warrants, CBBC
market	str	Market. US, HK
currency	str	Currency. USD for US Dollar, HKD for Hong Kong Dollar
segType	str	Classification by trading instrument. S for stocks, C for futures, D for cryptocurrencies, F for funds, CONSOLIDATED for the aggregation of stocks and funds.
secType	str	STK Stocks, OPT Options, WAR Warrants, IOPT CBBC, CASH FOREX, FUT Futures, FOP Future Options
position	int	Position quantity
positionScale	int	Position quantity offset
averageCost	float	Average position cost
latestPrice	float	Current price of the symbol
marketValue	float	Position market value
unrealizedPnl	float	Position profit/loss
name	str	Symbol name
timestamp	int	Timestamp

Callback Data Example

Stock position change push

account: "111111"
symbol: "BILI"
identifier: "BILI"
multiplier: 1
market: "US"
currency: "USD"
segType: "S"
secType: "STK"
position: 100
averageCost: 80
latestPrice: 19.83
marketValue: 1983
unrealizedPnl: -6017
timestamp: 1677745420121

Order Change Subscription and Cancellation

Subscription Method

PushClient.subscribe_order(account=None)

Cancellation Method

PushClient.unsubscribe_order()

Parameters

Parameter	Type	Description
account	str	Account ID to subscribe to. If not provided, subscribes to all associated accounts. Note: If no account is specified during subscription, callback will push data for multiple accounts, and you need to determine which account the data belongs to when processing callbacks

Example

from tigeropen.push.pb.OrderStatusData_pb2 import OrderStatusData
from tigeropen.push.push_client import PushClient
from tigeropen.common.consts import OrderStatus
from tigeropen.common.util.order_utils import get_order_status
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'))

# Define callback method
def on_order_changed(frame: OrderStatusData):
    print(f'order changed: {frame}')
    print(f'order status: {frame.status}')
    # Convert order status value to enum type
    status_enum = OrderStatus[frame.status]
    # or 
    # status_enum = get_order_status(frame.status)
    
# Register the callback
push_client.order_changed = on_order_changed
# Connect
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe to order changes
push_client.subscribe_order(account=client_config.account)
# Unsubscribe from order changes
push_client.unsubscribe_order()

Return

Handle order updates through PushClient.order_changed. Each update is a tigeropen.push.pb.OrderStatusData_pb2.OrderStatusData object. See OrderChange, get_order, and the Order object.

Field	Type	Description
id	int	Order number
account	str	Fund account number
symbol	str	Position symbol code, e.g., 'AAPL', '00700', 'ES', 'CN'
expiry	str	Only for options, warrants, CBBC
strike	str	Only for options, warrants, CBBC
right	str	Only for options, warrants, CBBC
identifier	str	Symbol identifier. For stocks, identifier is the same as symbol. For futures, it includes contract month, e.g., 'CN2201'
multiplier	int	Quantity per lot, limited to futures, options, warrants, CBBC
action	str	Buy/sell direction. BUY for buy, SELL for sell
market	str	Market. US, HK
currency	str	Currency. USD for US Dollar, HKD for Hong Kong Dollar
segType	str	Classification by trading instrument. S for stocks, C for futures
secType	str	STK Stocks, OPT Options, WAR Warrants, IOPT CBBC, CASH FOREX, FUT Futures, FOP Future Options
orderType	str	Order type. 'MKT' market order/'LMT' limit order/'STP' stop order/'STP_LMT' stop limit order/'TRAIL' trailing stop order
isLong	boolean	Whether the position is long
totalQuantity	int	Order quantity
totalQuantityScale	int	Order quantity offset. If totalQuantity=111, totalQuantityScale=2, then real totalQuantity=111*10^(-2)=1.11
filledQuantity	int	Total filled quantity (for orders with multiple fills, filledQuantity is cumulative total filled)
filledQuantityScale	int	Total filled quantity offset
avgFillPrice	float	Average fill price
limitPrice	float	Limit order price
stopPrice	float	Stop price
realizedPnl	float	Realized profit/loss (only for prime accounts)
status	str	Order status. Note: status value is OrderStatus enum name, can use `OrderStatus[value]` to convert to enum type
replaceStatus	str	Order replace status
cancelStatus	str	Order cancel status
outsideRth	bool	Whether to allow pre-market and after-hours trading, only applicable to US stocks
canModify	bool	Whether the order can be modified
canCancel	bool	Whether the order can be canceled
liquidation	bool	Whether this is a liquidation order
name	str	Symbol name
source	str	Order source (from 'OpenApi', or other)
errorMsg	str	Error message
attrDesc	str	Order description information
commissionAndFee	float	Total commission and fees
openTime	int	Order placement time
timestamp	int	Last update time of order status
userMark	str	Order remark
totalCashAmount	float	Total order amount
filledCashAmount	float	Total filled amount
attrList	list[str]	Order attribute list, meaning of each attribute: LIQUIDATION forced liquidation, FRACTIONAL_SHARE fractional share order (non-whole share), EXERCISE exercise, EXPIRE expiry, ASSIGNMENT passive exercise assignment, CASH_SETTLE cash settlement, KNOCK_OUT knock-out, RECALL recall order, ODD_LOT odd lot order (non-whole lot), DEALER dealer order, GREY_MARKET HK grey market order, BLOCK_TRADE block trade, ATTACHED_ORDER attached order, OCA OCA order
timeInForce	str	Order validity time. DAY: valid for the day, GTC: valid until canceled, GTD: valid until specified date

Callback Data Example

Stock order push example

id: 40536123722044416
account: "12345"
symbol: "01810"
identifier: "01810"
multiplier: 1
action: "SELL"
market: "HK"
currency: "HKD"
segType: "S"
secType: "STK"
orderType: "LMT"
isLong: true
totalQuantity: 200
limitPrice: 100.5
status: "HELD"
replaceStatus: "NONE"
cancelStatus: "NONE"
outsideRth: true
canModify: true
canCancel: true
name: "XIAOMI-W"
source: "OpenApi"
openTime: 1758165280000
timestamp: 1758165280758
timeInForce: "DAY"

Futures order push example

{"id":"28875370355884032","account":"12345","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 Crude Oil 2312",
"source":"android","commissionAndFee":4.0,"openTime":"1669200792000","timestamp":"1669200782221"}

Order Execution Details Subscription and Cancellation

Subscription Method

PushClient.subscribe_transaction(account=client_config.account)

Cancellation Method

PushClient.unsubscribe_transaction()

Parameters

Parameter	Type	Description
account	str	Account ID to subscribe to. If not provided, subscribes to all associated accounts. Note: If no account is specified during subscription, callback will push data for multiple accounts, and you need to determine which account the data belongs to when processing callbacks

Example

from tigeropen.push.pb.OrderTransactionData_pb2 import OrderTransactionData
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'))

# Define callback method
def on_transaction_changed(frame: OrderTransactionData):
    print(f'transaction changed: {frame}')
    
# Register the callback
push_client.transaction_changed = on_transaction_changed
# Connect
push_client.connect(client_config.tiger_id, client_config.private_key)

# Subscribe
pushClient.subscribe_transaction(account=client_config.account)
# Unsubscribe
pushClient.unsubscribe_transaction()

Return

Use PushClient.transaction_changed to handle results. The data type is tigeropen.push.pb.OrderTransactionData_pb2.OrderTransactionData. For field meanings, see get_transactions and Transaction.

Field	Type	Description
id	int	Order execution ID
orderId	int	Order number
account	str	Fund account number
symbol	str	Position symbol code, e.g., 'AAPL', '00700', 'ES', 'CN'
identifier	str	Symbol identifier. For stocks, identifier is the same as symbol. For futures, it includes contract month, e.g., 'CN2201'
multiplier	int	Quantity per lot (options, futures specific)
action	str	Buy/sell direction. BUY for buy, SELL for sell
market	str	Market. US, HK
currency	str	Currency. USD for US Dollar, HKD for Hong Kong Dollar
segType	str	Classification by trading instrument. S for stocks, C for futures
secType	str	Trading instrument, security type. STK for stocks, FUT for futures
filledPrice	float	Price
filledQuantity	int	Filled quantity
createTime	int	Create time
updateTime	int	Update time
transactTime	int	Transaction time
timestamp	int	Timestamp

Callback Data Example

id: 2999543887211111111
orderId: 29995438111111111
account: "1111111"
symbol: "ZC"
identifier: "ZC2305"
multiplier: 5000
action: "BUY"
market: "US"
currency: "USD"
segType: "C"
secType: "FUT"
filledPrice: 6.385
filledQuantity: 1
createTime: 1677746237303
updateTime: 1677746237303
transactTime: 1677746237289
timestamp: 1677746237313