Account Change Push Notifications

The following are all asynchronous APIs that require specifying a method to respond to returned results

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

Note that if no account is specified during subscription, the callback will push data for multiple accounts associated with this tiger_id. When processing callbacks, you need to determine which account the data belongs to.

Asset Change Subscription and Cancellation

Subscription Method

PushClient.subscribe_asset(account)

Cancellation Method

PushClient.unsubscribe_asset()

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

You need to use PushClient.asset_changed to respond to return results. The return result is a tigeropen.push.pb.AssetData_pb2.AssetData object Object Description

Field meanings can be referenced against asset retrieval interfaces get_prime_assets, get_assets

Detailed field explanations refer to objects: PortfolioAccount Integrated/Simulated Assets

PortfolioAccount Global Assets

Callback Data Field Meanings

Asset change callback

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
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='/path/to/your/properties/file/')


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):
    """Can perform custom processing, here only printing"""
    print(f'asset change. {frame}')
    # View available funds
    print(frame.availableFunds)
    # View position market value
    print(frame.grossPositionValue)

# Bind callback method
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()

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='/path/to/your/properties/file/')


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)
    
# Bind callback method
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

You need to use PushClient.position_changed to respond to return results. Data type is tigeropen.push.pb.PositionData_pb2.PositionData Object Description. Fields in list items can be referenced against get_positions 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
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='/path/to/your/properties/file/')


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)
    
# Bind callback method
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

You need to use PushClient.order_changed to respond to return results. Data type is tigeropen.push.pb.OrderStatusData_pb2.OrderStatusData Object Description. Field meanings in return results can be referenced against get_order 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 it's a long position
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 integrated 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 can be modified
canCancel	bool	Whether can be canceled
liquidation	bool	Whether it's 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='/path/to/your/properties/file/')


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}')
    
# Bind callback method
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

You need to use PushClient.transaction_changed to respond to return results. Data type is tigeropen.push.pb.OrderTransactionData_pb2.OrderTransactionData. Field meanings in return results can be referenced against get_transactions 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