Get Contracts

Initialization

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

from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig

client_config = TigerOpenClientConfig(props_path='your_config_directory_path')
trade_client = TradeClient(client_config)

For details, see Prerequisites.

Contract Introduction

A contract identifies a tradable instrument, such as a stock, option, or futures contract. For example, Tiger Brokers stock is identified by the symbol TIGR and the US market. Trading and market data APIs use contract information to identify the instrument unambiguously.

Most contracts (such as stocks, CFDs, indices, or forex) can be uniquely determined by the following four basic attributes:

Symbol: Generally, US and UK stock contract codes are English letters, while HK and A-share contract codes are numbers. For example, Tiger Brokers' symbol is TIGR.
Security Type: Common contract types include STK (stock), OPT (option), FUT (futures), CASH (forex). For example, Tiger Brokers stock contract type is STK.
Currency: Common currencies include USD (US Dollar), HKD (Hong Kong Dollar).
Exchange: STK type contracts generally don't use the exchange field, orders are automatically routed. Futures contracts use the exchange field.

Some contracts (such as options and futures) require additional information to uniquely identify them due to their more complex nature.

Here are several common contract types and their constituent elements:

Stock

contract = Contract()
contract.symbol ="TIGR"
contract.sec_type ="STK"
contract.currency ="USD" #not required
contract.market = "US" #not required

Options

Tiger Brokers API's option contracts support two methods:

Specify the four option attributes: symbol (underlying stock symbol), expiry (expiration date), strike (strike price), and right (call or put).
The other is the standard OCC option contract format with a fixed length of 21 characters, including four parts:
- Related stock or ETF code, such as (AAPL), fixed at six characters, padded with spaces if insufficient
- Option expiration date, 6 digits, format: yymmdd
- Option type, value is P or C, representing put or call
- Option strike price, value is price x 1000, fixed at 8 digits, padded with zeros if insufficient

Get Single Contract Information

TradeClient.get_contract(symbol, sec_type=SecurityType.STK, currency=None, exchange=None, expiry=None, strike=None, put_call=None, lang=None)

Description

Retrieves single contract information required for trading.

Parameters

Parameter	Type	Required	Description
symbol	str	Yes	Stock symbol, e.g., 'AAPL'
sec_type	SecurityType	No	Security type, tigeropen.common.consts.SecurityType enum, Default: SecurityType.STK
currency	Currency	No	Currency, tigeropen.common.consts.Currency enum, e.g., Currency.USD
exchange	str	No	Exchange, optional, e.g., 'CBOE'
expiry	str	No	Contract expiration date (for futures/options), format yyyyMMdd, e.g., '20220130'
strike	float	No	Strike price (for options)
put_call	str	No	Put/Call (for options), 'PUT' for put, 'CALL' for call
lang	Language or str	No	Language for returned text; defaults to the client configuration

Return

tigeropen.trade.domain.contract.Contract contract object, see Object Introduction. Common attributes:

Object Attributes

Attribute	Type	Description
identifier	str	Unique identifier, stock identifier same as symbol, option is 21-character identifier like 'AAPL 220729C00150000', futures identifier
symbol	str	Stock symbol, option contract symbol is the underlying symbol
sec_type	str	STK stock/OPT option/FUT futures/WAR warrant/IOPT CBBC, etc., default STK
name	str	Contract name
currency	str	Currency, e.g., USD/HKD/CNH
exchange	str	Exchange
expiry	str	Options and futures only, option or futures expiration date
strike	float	Options only, option strike price
multiplier	float	Multiplier, quantity per lot
put_call	str	Options only, option direction, CALL or PUT
local_symbol	str	Global accounts only, HK stocks for identifying warrants and CBBCs
short_margin	float	Short margin ratio (deprecated, use short_initial_margin instead)
short_initial_margin	float	Short initial margin ratio in the range (0, 1]
short_maintenance_margin	float	Short maintenance margin ratio (prime accounts have values, global account contracts don't)
short_fee_rate	float	Short fee rate
shortable	bool	Whether borrow inventory is currently available; this does not by itself grant the account permission to short
shortable_count	int	Short pool remaining
long_initial_margin	float	Long initial margin
long_maintenance_margin	float	Long maintenance margin
contract_month	str	Contract month, e.g., 202201 for January 2022
primary_exchange	str	Stock listing exchange
marginable	bool	Whether the contract is marginable
market	str	Market, e.g., US/HK/CN
min_tick	float	Fixed minimum tick for futures. For stocks this may be `None`; use `tick_sizes` for the complete tiered configuration
tick_sizes	list	Tiered minimum ticks. Each item has `begin`, `end` (`"Infinity"` means no upper bound), `type` (`OPEN`, `CLOSED`, `OPEN_CLOSED`, or `CLOSED_OPEN`), and `tick_size`. Order prices must be multiples of the applicable `tick_size`
trading_class	str	Contract trading class name
close_only	bool	Whether the contract is restricted to closing transactions
status	int	Contract trading status: 0 means not tradable and 1 means tradable
continuous	bool	Futures only. Whether this is a continuous contract
trade	bool	Whether the contract is tradable
last_trading_date	str	Futures only, last trading date, e.g., '20211220' for December 20, 2021
first_notice_date	str	Futures only, first notice date. Contract cannot open long positions after first notice date. Existing long positions will be force-closed before first notice date (usually 3 trading days prior), e.g., '20211222' for December 22, 2021
last_bidding_close_time	int	Futures only, bidding close timestamp
is_etf	bool	Whether the contract is an ETF
etf_leverage	int	ETF leverage ratio, only exists when contract is ETF
discounted_day_initial_margin	float	Futures only, intraday discount initial margin ratio
discounted_day_maintenance_margin	float	Futures only, intraday discount maintenance margin ratio
discounted_time_zone_code	float	Futures only, intraday discount time zone
discounted_start_at	float	Futures only, intraday discount start time
discounted_end_at	float	Futures only, intraday discount end time
lot_size	float	Minimum tradable asset quantity in single transaction
support_overnight_trading	bool	Whether the contract supports overnight trading
support_fractional_share	bool	Whether the contract supports fractional share trading (prime/paper trading accounts only)

📘
Note
print only displays partial attributes, use print(contract.to_str()) to print all attributes

Example

# Stock
contract = trade_client.get_contract('AAPL', sec_type=SecurityType.STK)
# Future
# contract = trade_client.get_contract('ES2306', sec_type=SecurityType.FUT)
print(contract)
# By default only prints contract symbol/type/currency. Use to_str to print all attributes. For more attributes, specify attribute name directly, e.g., contract.short_margin
print(contract.to_str())

# View short initial margin
print(contract.short_initial_margin)

Example Response

{'contract_id': 1916, 'symbol': 'AAPL', 'currency': 'USD', 'sec_type': 'STK', 'exchange': None, 'origin_symbol': None, 
'local_symbol': 'AAPL', 'expiry': None, 'strike': None, 'put_call': None, 'multiplier': 1.0, 'name': 'Apple Inc', 
'short_margin': 0.35, 'short_initial_margin': 0.35, 'short_maintenance_margin': 0.3, 'short_fee_rate': None, 
'shortable': True, 'shortable_count': None, 'long_initial_margin': 0.3, 'long_maintenance_margin': 0.25, 
'contract_month': None, 'identifier': 'AAPL', 'primary_exchange': 'NASDAQ', 'market': 'US', 'min_tick': None, 
'tick_sizes': [{'begin': '0', 'end': '1', 'type': 'CLOSED', 'tick_size': 0.0001}, {'begin': '1', 'end': 'Infinity', 
'type': 'OPEN', 'tick_size': 0.01}], 'trading_class': 'AAPL', 'status': 1, 'marginable': True, 'trade': True, 
'close_only': False, 'continuous': None, 'last_trading_date': None, 'first_notice_date': None, 
'last_bidding_close_time': None, 'is_etf': False, 'etf_leverage': None, 'discounted_day_initial_margin': None, 
'discounted_day_maintenance_margin': None, 'discounted_time_zone_code': None, 'discounted_start_at': None, 
'discounted_end_at': None, 'categories': None, 'lot_size': 1.0, 'support_overnight_trading': True}

Rate Limit

The base rate limit is 60 requests/minute.

Get Multiple Contract Information

TradeClient.get_contracts(symbol, sec_type=SecurityType.STK, currency=None, exchange=None, lang=None)

Description

Returns a list of contracts that match the query.

Parameters

Parameter	Type	Required	Description
symbol	str	Yes	Stock symbol, e.g., 'AAPL'. Maximum 50 symbols per request
sec_type	SecurityType	No	Security type, tigeropen.common.consts.SecurityType enum, Default: SecurityType.STK
currency	Currency	No	Currency, tigeropen.common.consts.Currency enum, e.g., Currency.USD
exchange	str	No	Exchange, optional, e.g., 'CBOE'
lang	Language or str	No	Language for returned text; defaults to the client configuration

Return

list

Each item in the list is a contract object (tigeropen.trade.domain.contract.Contract), see Object Introduction. Common attributes:

Object Attributes

Attribute	Description
identifier	Unique identifier, stock identifier same as symbol, option is 21-character identifier like 'AAPL 220729C00150000', futures identifier
symbol	Stock symbol, option contract symbol is the underlying symbol
sec_type	STK stock/OPT option/FUT futures/WAR warrant/IOPT CBBC, etc., default STK
name	Contract name
currency	Currency, e.g., USD/HKD/CNH
exchange	Exchange
expiry	Options and futures only, option or futures expiration date
strike	Options only, option strike price
multiplier	Multiplier, quantity per lot
put_call	Options only, option direction, CALL or PUT
local_symbol	Global accounts only, HK stocks for identifying warrants and CBBCs
short_margin	Short margin ratio (deprecated, use short_initial_margin instead)
short_initial_margin	Short initial margin ratio
short_maintenance_margin	Short maintenance margin ratio (prime accounts have values, global account contracts don't)
short_fee_rate	Short fee rate
shortable	Whether borrow inventory is currently available; this does not by itself grant the account permission to short
long_initial_margin	Long initial margin
long_maintenance_margin	Long maintenance margin
contract_month	Contract month, e.g., 202201 for January 2022
primary_exchange	Stock listing exchange
market	Market, e.g., US/HK/CN
min_tick	Fixed minimum tick for futures. For stocks this may be `None`; use `tick_sizes` for the complete tiered configuration
tick_sizes	Tiered minimum ticks. Each item has `begin`, `end`, `type`, and `tick_size`; order prices must be multiples of the applicable `tick_size`
trading_class	Contract trading class name
status	Contract trading status: 0 means not tradable and 1 means tradable
continuous	Futures only. Whether this is a continuous contract
trade	Futures only. Whether the contract is tradable
last_trading_date	Futures only, last trading date, e.g., '20211220' for December 20, 2021
first_notice_date	Futures only, first notice date. Contract cannot open long positions after first notice date. Existing long positions will be force-closed before first notice date (usually 3 trading days prior), e.g., '20211222' for December 22, 2021
last_bidding_close_time	Futures only, bidding close timestamp
is_etf	Whether the contract is an ETF
etf_leverage	ETF leverage ratio, only exists when contract is ETF
discounted_day_initial_margin	Futures only, Intraday initial margin discount
discounted_day_maintenance_margin	Futures only, Intraday maintenance margin discount
discounted_time_zone_code	Futures only, Intraday margin discount period time zone
discounted_start_at	Futures only, Intraday margin discount start time
discounted_end_at	Futures only, Intraday margin discount end time
lot_size	Quantity represented by one lot
support_overnight_trading	Whether overnight trading is supported
support_fractional_share	Whether fractional-share trading is supported
close_only	Whether the contract can only be closed
marginable	Whether the contract is marginable
categories	Contract category tags
underlying_contract_name	Underlying asset contract name

📘
Note
print only displays partial attributes, use print(contract.to_str()) to print all attributes

Example

contracts = trade_client.get_contracts('AAPL', sec_type=SecurityType.STK)
print(contracts)
print(contracts[0].to_str())

Example Response

[
{'contract_id': 1916, 'symbol': 'AAPL', 'currency': 'USD', 'sec_type': 'STK', 'exchange': None, 'origin_symbol': None, 
 'local_symbol': 'AAPL', 'expiry': None, 'strike': None, 'put_call': None, 'multiplier': 1.0, 'name': 'Apple Inc', 
 'short_margin': None, 'short_initial_margin': None, 'short_maintenance_margin': None, 'short_fee_rate': None, 
 'shortable': None, 'shortable_count': None, 'long_initial_margin': None, 'long_maintenance_margin': None, 
 'contract_month': None, 'identifier': 'AAPL', 'primary_exchange': None, 'market': 'US', 'min_tick': None, 
 'tick_sizes': [{'begin': '0', 'end': '1', 'type': 'CLOSED', 'tick_size': 0.0001}, {'begin': '1', 'end': 'Infinity', 
 'type': 'OPEN', 'tick_size': 0.01}], 'trading_class': 'AAPL', 'status': 1, 'marginable': None, 'trade': True, 
 'close_only': False, 'continuous': None, 'last_trading_date': None, 'first_notice_date': None, 
 'last_bidding_close_time': None, 'is_etf': False, 'etf_leverage': None, 'discounted_day_initial_margin': None, 
 'discounted_day_maintenance_margin': None, 'discounted_time_zone_code': None, 'discounted_start_at': None, 
 'discounted_end_at': None, 'categories': None, 'lot_size': 1.0, 'support_overnight_trading': True}]

Rate Limit

The base rate limit is 60 requests/minute.

Create Contract Objects Locally

Stock

from tigeropen.common.util.contract_utils import stock_contract

# US Stock
contract = stock_contract(symbol='TIGR', currency='USD')

# HK Stock
contract = stock_contract(symbol='00700', currency='HKD')

# SG Stock
contract = stock_contract(symbol = '1A1.SI',currency = 'SGD')

# AU Stock
contract = stock_contract(symbol = 'MXT.AU', currency = 'AUD')

Options

from tigeropen.common.util.contract_utils import option_contract, option_contract_by_symbol
contract = option_contract(identifier='AAPL  190118P00160000')
# or
contract = option_contract_by_symbol('AAPL', '20200110', strike=280.0, put_call='PUT', currency='USD')

# Convert between option symbol and four elements
from tigeropen.common.util.contract_utils import extract_option_info, get_option_identifier

# Create option symbol from four elements
underlying_symbol='AAPL'
expiry='20200110'
put_call='PUT'
strike=280
identifier = get_option_identifier(underlying_symbol, expiry, put_call, strike)
# Extract four elements from option symbol identifier='AAPL  190118P00160000'
symbol, expiry, put_call, strike = extract_option_info(identifier)
print(identifier)

Futures

# Prime/Paper Trading
from tigeropen.common.util.contract_utils import future_contract
contract = future_contract(symbol='CL2312', currency='USD')

# Global
from tigeropen.common.util.contract_utils import future_contract
contract = future_contract(symbol='CL', currency='USD', expiry='20190328', multiplier=1.0, exchange='SGX')

# US Futures
contract = future_contract(symbol='RB', currency='USD', expiry='20250829', multiplier=1.0, exchange='NYMEX')

# HK Futures
contract = future_contract(symbol='2318', currency='HKD', expiry='20251230', multiplier=500.0, exchange='HKEX')

# SG Futures
contract = future_contract(symbol='SSG', currency='SGD', expiry='20250429', multiplier=100.0, exchange='SGX')

HK Warrants

from tigeropen.common.util.contract_utils import war_contract_by_symbol
contract = war_contract_by_symbol('01810', '20221116', 14.52, 'CALL', local_symbol='14759', multiplier=2000, currency='HKD')

HK CBBCs

from tigeropen.common.util.contract_utils import iopt_contract_by_symbol
contract = iopt_contract_by_symbol('02318', '20200420', 87.4, 'CALL', local_symbol='63379', currency='HKD')

Funds

from tigeropen.common.util.contract_utils import fund_contract

# US Fund
contract = fund_contract('IE00B11XZ988.USD')

# HK Fund
contract = fund_contract('LU0476943708.HKD')

# SG Fund
contract = fund_contract('LU2023250843.SGD')

# AU Fund
contract = fund_contract('SG9999015184.AUD')

Crypto

from tigeropen.common.util.contract_utils import cc_contract
contract = cc_contract('BTC')

Get Option/Warrant/CBBC Contract List

TradeClient.get_derivative_contracts(symbol, sec_type, expiry, lang=None)

Input Parameters:

Parameter	Type	Required	Description
symbol	str	Yes	Stock symbol list, supports only one symbol
sec_type	SecurityType	Yes	Contract type, currently supports: OPT option/ WAR HK warrant/ IOPT HK CBBC
expiry	str	Yes	Expiration date (yyyyMMdd), required for OPT, e.g., '20220929'
lang	str	No	Language support: zh_CN, zh_TW, en_US, default: en_US

Return:
list

Each item in the list is a contract object (tigeropen.trade.domain.contract.Contract), see Object Introduction. Common attributes:

Name	Type	Description
symbol	string	Stock symbol
name	string	Contract name
exchange	string	Exchange
market	string	Market
sec_type	string	Contract type
currency	string	Currency
expiry	string	Expiration date (options, warrants, CBBCs, futures), e.g., 20171117
right	string	Option direction (options, warrants, CBBCs), PUT/CALL
strike	float	Strike price
multiplier	float	Multiplier, quantity per lot (options, warrants, CBBCs, futures)

Request Example:

contracts = trade_client.get_derivative_contracts('00700', SecurityType.WAR, '20220929')
print(contracts)

Example Response

[
    {
        "symbol": "29298",
        "name": "[email protected]",
        "exchange": "SEHK",
        "market": "HK",
        "sec_type": "WAR",
        "currency": "HKD",
        "expiry": "20250925",
        "strike": "500.5",
        "multiplier": 10000.0,
        "right": "CALL"
    }, {
        "symbol": "29290",
        "name": "[email protected]",
        "exchange": "SEHK",
        "market": "HK",
        "sec_type": "WAR",
        "currency": "HKD",
        "expiry": "20250925",
        "strike": "500.5",
        "multiplier": 10000.0,
        "right": "CALL"
    }
]

Rate Limit

The base rate limit is 60 requests/minute.