Object Descriptions
PortfolioAccount Assets (Standard/Paper Account)
Description
Account asset object for standard/paper accounts. Contains information about the account's total assets, P&L, position market value, cash, available funds, margin, leverage, etc.
In the C++ SDK, account asset interfaces return web::json::value JSON objects, with field names corresponding to the property names in the table below.
Object Properties
| Property | Type | Description |
|---|---|---|
| account | string | Corresponding account ID |
| update_timestamp | int64 | Update time, 13-digit millisecond timestamp |
| segments | object | Account information categorized by trading product. A JSON object with two keys: S for securities and C for futures, values are Segment objects |
Segment Assets by Product (Standard/Paper Account)
Description
Assets divided by securities/futures trading products, each part is a Segment.
Object Properties
| Property | Type | Description |
|---|---|---|
| currency | string | Currency, e.g., USD, HKD |
| capability | string | Account type. Margin account: RegTMargin, Cash account: Cash. Margin accounts support margin trading, unlimited day trades, max buying power of 4x intraday and 2x overnight. |
| category | string | Trading product category. C: Commodities (Futures), S: Securities (Stocks), F: Funds |
| cash_balance | double | Cash balance. The sum of all currency cash balances. |
| cash_available_for_trade | double | Available funds. Used to check whether new positions or IPO subscriptions can be made. |
| cash_available_for_withdrawal | double | Cash amount available for withdrawal |
| buying_power | double | Maximum buying power. Margin accounts have up to 4x buying power intraday and 2x overnight. |
| gross_position_value | double | Total securities value, the sum of market values of all securities positions. |
| equity_with_loan | double | Equity with loan value (ELV), used to calculate opening and closing data metrics. |
| net_liquidation | double | Net liquidation value (total assets). Net liquidation = total securities market value + cash balance + accrued dividends - accrued interest. |
| init_margin | double | Initial margin. Sum of initial margin requirements for all current positions. |
| maintain_margin | double | Maintenance margin. Sum of maintenance margin requirements for all current positions. |
| overnight_margin | double | Overnight margin. Margin checked starting 15 minutes before market close. |
| unrealized_pl | double | Unrealized P&L. Current price * shares - position cost. |
| realized_pl | double | Realized P&L. Total realized P&L from closed positions in the current holding cycle. |
| excess_liquidation | double | Excess liquidity. excess_liquidation = equity_with_loan - maintain_margin. |
| overnight_liquidation | double | Overnight excess liquidity. equity_with_loan - overnight_margin. |
| leverage | double | Leverage. leverage = sum of absolute securities market values / net liquidation. |
| currency_assets | object | Account asset information by currency, a JSON object keyed by currency, values are CurrencyAsset objects |
| uncollected | double | Funds in transit |
| locked_funds | double | Locked funds |
CurrencyAsset Assets by Currency (Standard/Paper Account)
Description
Assets categorized by currency.
Object Properties
| Property | Type | Description |
|---|---|---|
| currency | string | Current currency type. Common currencies: USD (US Dollar), HKD (Hong Kong Dollar), SGD (Singapore Dollar), CNH (Chinese Yuan) |
| cash_balance | double | Tradable cash plus locked cash |
| cash_available_for_trade | double | Cash amount available for trading |
| forex_rate | double | Exchange rate of current currency against base_currency |
PortfolioAccount Assets (Global Account)
Description
Account asset object for global accounts. Contains information about the account's total assets, P&L, position market value, cash, available funds, margin, leverage, etc.
Object Properties
| Property | Type | Description |
|---|---|---|
| account | string | Corresponding account ID |
| summary | object | Account summary information, aggregated from segments, as an Account object |
| segments | object | Account information categorized by trading product. Two keys: S for securities, C for futures |
Account Summary Assets (Global Account)
Description
Summarized asset information across all trading products.
Object Properties
| Property | Type | Description |
|---|---|---|
| accrued_cash | double | Accumulated accrued interest for the current month, updated daily |
| accrued_dividend | double | Accumulated dividends. Sum of all executed but unpaid dividends |
| available_funds | double | Available funds (for trading). Calculated as equity_with_loan - initial_margin_requirement |
| buying_power | double | Buying power: estimated amount of stock assets you can still purchase. Margin accounts have up to 4x buying power intraday and 2x overnight |
| cash | double | Cash amount |
| currency | string | Currency |
| cushion | double | Ratio of excess liquidity to net liquidation. Calculated as: excess_liquidity / net_liquidation |
| day_trades_remaining | int | Remaining day trades for today, -1 means unlimited |
| equity_with_loan | double | Equity with loan value. Securities Segment: cash value + stock value. Futures Segment: cash value - maintenance margin |
| excess_liquidity | double | Excess liquidity |
| gross_position_value | double | Total securities value: long stock value + short stock value + long option value + short option value |
| initial_margin_requirement | double | Initial margin requirement |
| maintenance_margin_requirement | double | Maintenance margin requirement |
| realized_pnl | double | Today's realized P&L |
| unrealized_pnl | double | Unrealized P&L |
| net_liquidation | double | Net liquidation value (total assets). Securities Segment: cash value + stock value + stock option value. Futures Segment: cash value + mark-to-market P&L |
| regt_equity | double | Securities Segment only. Equity with loan calculated per Regulation T |
| regt_margin | double | Securities Segment only. Initial margin requirements calculated per Regulation T |
| sma | double | Securities Segment only. Overnight risk control value |
| timestamp | int64 | Update time |
SecuritySegment Securities Assets (Global Account)
Description
Securities asset information.
Object Properties
| Property | Type | Description |
|---|---|---|
| accrued_cash | double | Accumulated accrued interest for the current month, updated daily |
| accrued_dividend | double | Accumulated dividends. Sum of all executed but unpaid dividends |
| available_funds | double | Available funds (for trading). Calculated as equity_with_loan - initial_margin_requirement |
| cash | double | Cash |
| equity_with_loan | double | Equity with loan value. Calculated as: cash value + stock value |
| excess_liquidity | double | Excess liquidity. Calculated as: equity_with_loan - maintenance_margin_requirement |
| gross_position_value | double | Total securities value: long stock value + short stock value + long option value + short option value |
| initial_margin_requirement | double | Initial margin requirement |
| maintenance_margin_requirement | double | Maintenance margin requirement |
| leverage | double | gross_position_value / net_liquidation |
| net_liquidation | double | Net liquidation value (total assets). Calculated as: cash value + stock value + stock option value |
| regt_equity | double | Equity with loan calculated per Regulation T |
| regt_margin | double | Initial margin requirements calculated per Regulation T |
| sma | double | Overnight risk control value |
| timestamp | int64 | Update time |
CommoditySegment Futures Assets (Global Account)
Description
Futures asset information.
Object Properties
| Property | Type | Description |
|---|---|---|
| accrued_cash | double | Accumulated accrued interest for the current month, updated daily |
| accrued_dividend | double | Accumulated dividends. Sum of all executed but unpaid dividends |
| available_funds | double | Available funds (for trading). Calculated as equity_with_loan - initial_margin_requirement |
| cash | double | Cash |
| equity_with_loan | double | Equity with loan value. Calculated as: cash value - maintenance margin |
| excess_liquidity | double | Excess liquidity. Calculated as: net_liquidation - maintenance_margin_requirement |
| initial_margin_requirement | double | Initial margin requirement |
| maintenance_margin_requirement | double | Maintenance margin requirement |
| net_liquidation | double | Net liquidation value (total assets). Calculated as: cash value + mark-to-market P&L |
| timestamp | int64 | Update time |
MarketValue Assets by Currency (Global Account)
Description
Asset information categorized by currency.
Object Properties
| Property | Type | Description |
|---|---|---|
| currency | string | Currency unit |
| net_liquidation | double | Net liquidation value (total assets) |
| cash_balance | double | Cash |
| stock_market_value | double | Stock market value |
| option_market_value | double | Option market value |
| warrant_value | double | Warrant market value |
| futures_pnl | double | Mark-to-market P&L |
| unrealized_pnl | double | Unrealized P&L |
| realized_pnl | double | Realized P&L |
| exchange_rate | double | Exchange rate against account base currency |
| net_dividend | double | Net value of dividends payable and receivable |
| timestamp | int64 | Update time |
Position
Description
Account position information. Includes the position's contract details, quantity, cost, P&L, etc. In the C++ SDK, Position is defined in tigerapi/model.h.
Object Properties
| Property | Type | Description |
|---|---|---|
| account | string | Corresponding account ID |
| contract | Contract | Contract object |
| position_qty | double | Position quantity |
| quantity | int | Position quantity (deprecated), use with position_scale when fractional positions exist |
| position_scale | int | Position quantity decimal offset (deprecated) |
| average_cost | double | Average cost including commission |
| market_value | double | Market value |
| salable_qty | double | Sellable quantity |
| average_cost_of_carry | double | Accumulated position cost (A-share calculation method) |
| market_price | double | Market price |
| realized_pnl | double | Realized P&L under FIFO method |
| unrealized_pnl | double | Unrealized P&L |
| unrealized_pnl_by_cost_of_carry | double | Unrealized P&L (A-share calculation method) |
| unrealized_pnl_percent_by_cost_of_carry | double | Unrealized P&L percentage (A-share calculation method) |
| today_pnl | double | Today's P&L amount |
| today_pnl_percent | double | Today's P&L percentage |
| last_close_price | double | Last intraday close price (forward adjusted). For US stocks during trading hours, this is the previous trading day's close price |
Order
Description
Order object. Returned when querying orders. In the C++ SDK, Order is defined in tigerapi/model.h.
Object Properties
| Property | Type | Description |
|---|---|---|
| account | string | Account the order belongs to |
| id | int64 | Global order ID |
| order_id | int | Auto-increment order number (deprecated) |
| parent_id | int64 | Parent order ID, currently only used for attached orders in TigerTrade App |
| order_time | int64 | Order placement time, 13-digit millisecond timestamp |
| trade_time | int64 | Order status update time. For filled orders, this is the fill time; for cancelled orders, this is the cancellation time |
| update_time | int64 | Order update time, updated when order properties change (e.g., price modification) |
| expire_time | int64 | GTD order expiry time, 13-digit millisecond timestamp |
| reason | string | Failure reason description when order placement fails |
| action | string | Trade direction, BUY / SELL |
| quantity | int | Order quantity |
| quantity_scale | int | Order quantity offset, default 0. For fractional share orders, quantity and quantity_scale together represent the actual order quantity |
| total_cash_amount | double | Total order amount, empty when ordering by shares |
| filled_cash_amount | double | Filled amount |
| refund_cash_amount | double | Refund amount, equals total order amount - filled amount |
| filled | int | Filled quantity |
| avg_fill_price | double | Average fill price excluding commission |
| commission | double | Includes commission, stamp duty, regulatory fees, etc. |
| realized_pnl | double | Realized P&L |
| trail_stop_price | double | Trailing stop price |
| limit_price | double | Limit order price |
| aux_price | double | In stop orders, the trigger price; in trailing stop orders, the trailing price difference |
| trailing_percent | double | Trailing stop percentage, range 0-100 |
| order_type | string | Order type: MKT Market / LMT Limit / STP Stop / STP_LMT Stop Limit / TRAIL Trailing Stop |
| time_in_force | string | Time in force: DAY Day / GTC Good-Til-Cancelled / GTD Good-Til-Date (requires expire_time) |
| outside_rth | bool | Whether pre/post-market trading is supported, US stocks only |
| trading_session_type | string | Overnight trading session |
| contract | Contract | Contract object |
Transaction
Description
Order transaction records.
Object Properties
| Property | Type | Description |
|---|---|---|
| account | string | Account |
| order_id | int64 | Order ID |
| contract | Contract | Contract object |
| id | int64 | Transaction record ID |
| action | string | Order direction |
| filled_quantity | int | Filled quantity |
| filled_quantity_scale | int | Filled quantity offset |
| filled_price | double | Fill price |
| filled_amount | double | Fill amount |
| transacted_at | string | Transaction time |
OrderLeg Attached Order
Description
Attached orders carried alongside a main order. In the C++ SDK, OrderLeg is defined in tigerapi/model.h.
Object Properties
| Property | Type | Description |
|---|---|---|
| leg_type | string | Attached order type. PROFIT take-profit type, LOSS stop-loss type |
| price | double | Attached order price |
| time_in_force | string | Attached order time in force. DAY (day valid) and GTC (Good-Til-Canceled) |
| outside_rth | bool | Whether attached order allows pre/post-market trading (US stocks only). true = allowed, false = not allowed |
Contract
Description
A contract refers to the trading target or underlying asset (such as a stock or an option). Contracts are standardized by exchanges, and contract information can uniquely identify an underlying asset when placing orders or fetching quotes. In the C++ SDK, Contract is defined in tigerapi/model.h.
Common contract types include stock contracts, option contracts, futures contracts, etc., with the following elements:
- Symbol (symbol): US stocks, UK stocks, etc. use alphabetic codes; HK stocks, A-shares, etc. use numeric codes
- Security Type (sec_type): Common types include STK (Stock), OPT (Option), FUT (Futures), CASH (Forex)
- Currency (currency): Common currencies include USD (US Dollar), HKD (Hong Kong Dollar)
- Exchange (exchange): Generally not needed for STK type; required for futures contracts
Construction Examples
#include "tigerapi/trade_client.h"
using namespace TIGER_API;
// Stock contract
Contract contract = ContractUtil::stock_contract(U("AAPL"), U("USD"));
// Option contract
Contract opt = ContractUtil::option_contract(U("AAPL"), U("20231215"), U("CALL"), 190.0, U("USD"));
// Futures contract
Contract fut = ContractUtil::future_contract(U("CL"), U("USD"), U("20231220"));Object Properties
| Property | Type | Description |
|---|---|---|
| identifier | string | Unique identifier. For stocks, identifier equals symbol; for options, it is a 21-character OCC identifier, e.g., AAPL 220729C00150000 |
| symbol | string | Stock code. For option contracts, symbol is the underlying asset code |
| sec_type | string | STK Stock / OPT Option / FUT Futures / WAR Warrant / IOPT CBBC, etc. Default STK |
| name | string | Contract name |
| currency | string | Currency: USD/HKD/CNH |
| exchange | string | Exchange |
| expiry | string | Options and Futures only. Expiration date |
| strike | double | Options only. Strike price |
| multiplier | double | Contract multiplier (shares per lot) |
| put_call | string | Options only. Option direction: CALL or PUT |
| local_symbol | string | Global accounts only. Used to identify warrants and CBBCs for HK stocks |
| short_initial_margin | double | Short initial margin ratio |
| short_maintenance_margin | double | Short maintenance margin ratio |
| short_fee_rate | double | Short fee rate |
| shortable | int | Short pool remaining |
| long_initial_margin | double | Long initial margin |
| long_maintenance_margin | double | Long maintenance margin |
| contract_month | string | Contract month, e.g., 202201 for January 2022 |
| primary_exchange | string | Primary exchange where the stock is listed |
| market | string | Market: US/HK/CN |
| min_tick | double | Minimum tick size |
| continuous | bool | Futures only. Whether it is a continuous contract |
| trading_class | string | Trading class name of the contract |
| status | string | Contract status: 0 = not tradable, 1 = tradable |
| trade | bool | Futures only. Whether tradable |
| last_trading_date | string | Futures only. Last trading date, e.g., 20211220 |
| first_notice_date | string | Futures only. First notice date. Long positions cannot be opened after this date |
| last_bidding_close_time | int64 | Futures only. Bidding close timestamp |
| is_etf | bool | Whether it is an ETF |
| etf_leverage | int | ETF leverage multiplier, only present for ETF contracts |
| lot_size | double | Minimum tradable quantity per transaction |
| support_overnight_trading | bool | Whether overnight trading is supported |
MarketStatus
Description
Market trading status. In the C++ SDK, MarketStatus is defined in tigerapi/model.h.
Object Properties
| Property | Type | Description |
|---|---|---|
| market | string | Market (US: US stocks, CN: China A-shares, HK: Hong Kong stocks) |
| trading_status | string | Market trading status code: NOT_YET_OPEN; PRE_HOUR_TRADING; TRADING; MIDDLE_CLOSE; POST_HOUR_TRADING; CLOSING; OVERNIGHT_TRADING; EARLY_CLOSED; MARKET_CLOSED |
| status | string | Market status description (Not Yet Open, Trading, Closed, etc.) |
| open_time | string | Most recent opening time |
OptionFilter Option Chain Filter
Description
Option filter parameter object. In the C++ SDK, OptionFilter is defined in tigerapi/model.h.
Object Properties
| Parameter | Type | Required | Description |
|---|---|---|---|
| implied_volatility | double | No | Implied volatility. Reflects market expectations of future stock price volatility. Higher IV indicates greater expected price movement |
| in_the_money | bool | No | Whether in-the-money |
| open_interest | int | No | Open interest. Number of outstanding contracts at end of each trading day. Reflects market depth and liquidity |
| delta | double | No | Delta. Reflects the impact of stock price changes on option price. For every $1 change in stock price, option price changes by approximately delta. Range: -1.0 to 1.0 |
| gamma | double | No | Gamma. Reflects the impact of stock price changes on delta. For every $1 change in stock price, delta changes by gamma |
| theta | double | No | Theta. Reflects the impact of time decay on option price. For each day that passes, option price changes by approximately theta |
| vega | double | No | Vega. Reflects the impact of volatility changes on option price. For every 1% change in volatility, option price changes by approximately vega |
| rho | double | No | Rho. Reflects the impact of risk-free rate changes on option price. For every 1% change in risk-free rate, option price changes by approximately rho |
Order Changes
Fields received in order push callbacks:
| Field | Description |
|---|---|
| id | Order ID |
| account | Fund account |
| symbol | Position symbol code, e.g., AAPL, 00700, ES, CN |
| expiry | Options, warrants, and CBBCs only |
| strike | Options, warrants, and CBBCs only |
| right | Options, warrants, and CBBCs only |
| identifier | Underlying identifier. For stocks, identifier equals symbol. For futures, includes contract month, e.g., CN2201 |
| multiplier | Contract multiplier, for futures, options, warrants, and CBBCs only |
| action | Trade direction. BUY for buy, SELL for sell |
| market | Market: US, HK |
| currency | Currency: USD (US Dollar), HKD (Hong Kong Dollar) |
| segType | Category by trading product. S for securities, C for futures |
| secType | STK Stocks, OPT Options, WAR Warrants, IOPT CBBC, CASH Forex, FUT Futures, FOP Futures Options |
| orderType | Order type: MKT Market / LMT Limit / STP Stop / STP_LMT Stop Limit / TRAIL Trailing Stop |
| isLong | Whether long position |
| totalQuantity | Order quantity |
| totalQuantityScale | Order quantity offset |
| filledQuantity | Total filled quantity (for orders with multiple partial fills, filledQuantity is the cumulative total) |
| filledQuantityScale | Filled quantity offset |
| avgFillPrice | Average fill price |
| limitPrice | Limit order price |
| stopPrice | Stop price |
| realizedPnl | Realized P&L (only available for standard accounts) |
| status | Order status |
| outsideRth | Whether pre/post-market trading is allowed, US stocks only |
| canModify | Whether the order can be modified |
| canCancel | Whether the order can be cancelled |
| name | Underlying name |
| source | Order source |
| errorMsg | Error message |
| openTime | Order placement time |
| timestamp | Last order status update time |
Position Changes
Fields received in position push callbacks:
| Field | Description |
|---|---|
| account | User account |
| symbol | Stock code |
| expiry | Expiration date. Options, warrants, and CBBCs only |
| strike | Strike price. Options, warrants, and CBBCs only |
| right | Option direction PUT/CALL. Options, warrants, and CBBCs only |
| identifier | Underlying identifier |
| multiplier | Contract multiplier. Options, warrants, and CBBCs only |
| market | Trading market |
| currency | Currency type |
| segType | Category by trading product. S for securities, C for futures |
| secType | Security type |
| position | Position |
| positionScale | Position quantity offset |
| averageCost | Average cost |
| latestPrice | Latest price |
| marketValue | Market value |
| unrealizedPnl | Unrealized P&L |
| name | Underlying name |
| timestamp | Server time |
Asset Changes
Fields received in asset push callbacks:
| Field | Description |
|---|---|
| account | User account |
| currency | Currency type |
| segType | Category by trading product. S for securities, C for futures |
| availableFunds | Available funds (equity with loan - initial margin) |
| excessLiquidity | Excess liquidity (equity with loan - maintenance margin) |
| netLiquidation | Net liquidation value |
| equityWithLoan | Equity with loan value |
| buyingPower | Buying power |
| cashBalance | Account cash balance |
| grossPositionValue | Position market value |
| initMarginReq | Current initial margin requirement |
| maintMarginReq | Current maintenance margin requirement |
| timestamp | Server time |
Quote Changes
- Basic Quote
| Field | Sub-field | Description |
|---|---|---|
| symbol | Stock code | |
| type | Type | |
| timestamp | Quote data time | |
| serverTimestamp | Server time | |
| avgPrice | Average price | |
| latestPrice | Latest price | |
| latestPriceTimestamp | Latest price timestamp (not available in pre/post market) | |
| latestTime | Latest price time | |
| preClose | Previous close price | |
| volume | Cumulative volume for the day | |
| amount | Cumulative turnover for the day (not supported for options/futures) | |
| open | Open price | |
| high | High price | |
| low | Low price | |
| hourTradingTag | Pre/post-market indicator (no value during US regular hours). Values: PreMarket/AfterHours | |
| marketStatus | Market status | |
| identifier | Underlying identifier (options only) | |
| openInt | Open interest (options only) | |
| tradeTime | Trade time (futures only) | |
| preSettlement | Previous settlement price (futures only) | |
| minTick | Minimum tick size (futures only) | |
| mi | p | Minute price |
| mi | a | Minute average price |
| mi | t | Minute time |
| mi | v | Minute volume |
| mi | o | Minute open price (futures only) |
| mi | h | Minute high price (futures only) |
| mi | l | Minute low price (futures only) |
- Best Bid/Ask Quote
| Field | Description |
|---|---|
| askPrice | Ask price |
| askSize | Ask size |
| askTimestamp | Ask timestamp (Pre/Post-Mkt data not supported) |
| bidPrice | Bid price |
| bidSize | Bid size |
| bidTimestamp | Bid timestamp (Pre/Post-Mkt data not supported) |