Get Contracts

Contract Introduction

A contract refers to the trading object or underlying asset (such as a stock or option). Contracts are uniformly formulated by exchanges. For example, to purchase Tiger Brokers stock, you can uniquely identify it through the symbol "TIGR" and market information (i.e., market='US', US market). Through contract information, we can uniquely determine an underlying asset when placing orders or obtaining market data. Common contracts include stock contracts, option contracts, futures contracts, etc.

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:

One is the four-element method: symbol (stock code), expiry (option expiration date), strike (option strike price), right (option direction).
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_contract Get Single Contract Information

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

Description

Query 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

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
short_maintenance_margin	float	Short maintenance margin ratio (comprehensive accounts have values, global account contracts don't)
short_fee_rate	float	Short fee rate
shortable	bool	Whether shortable
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 marginable
market	str	Market, e.g., US/HK/CN
min_tick	float	Minimum tick size
tickSizes	`[{"begin":"0","end":"1","tickSize":1.0E-4,"type":"CLOSED"},{"begin":"1","end":"Infinity","tickSize":0.01,"type":"OPEN"}]`	Minimum tick size price ranges, when order price is in begin-end range, must meet tickSize requirement. begin: left price range, end: right price range, type: range type OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN, tickSize: minimum price unit
trading_class	str	Contract trading class name
close_only	bool	Whether close-only
status	str	Contract status
continuous	bool	Futures only, whether continuous contract
trade	bool	Whether 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 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 supports overnight trading
support_fractional_share	bool	Whether supports fractional share trading (comprehensive/demo accounts only)

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

Example

from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')

trade_client = TradeClient(client_config)

# Stock
contract = trade_client.get_contract('AAPL', sec_type=SecurityType.STK)
# Future
# contract = trade_client.get_contract('ES2306', sec_type=SecurityType.STK)
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)

Return Example

{'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}

get_contracts Get Multiple Contract Information

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

Description

Query multiple contract information required for trading, returned as a list

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'

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 (comprehensive accounts have values, global account contracts don't)
short_fee_rate	Short fee rate
shortable	Short pool remaining
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	Minimum tick size
tickSizes	Stock only, minimum tick size price ranges, when order price is in begin-end range, must meet tickSize requirement. begin: left price range, end: right price range, type: range type OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN, tickSize: minimum price unit
trading_class	Contract trading class name
status	Contract status
continuous	Futures only, whether continuous contract
trade	Futures only, whether 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 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

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

Example

from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')

trade_client = TradeClient(client_config)

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

Return Example

[
{'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}]

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

# Comprehensive/Demo
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

# 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')

get_derivative_contracts 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:

from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig
client_config = TigerOpenClientConfig(props_path='/path/to/your/properties/file/')

trade_client = TradeClient(client_config)

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

Response Example:

{
    "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"
}