Get Contract
About 7 min
We refer to what is being traded in an order as a "contract". The specs of a specific contract are set by a exchange, and are used to identify a specific asset in global markets, across the exchanges. This information, and the information required to trade a certain contract, are embedded in the Contract object.
A typical contract object includes the following elements:
- Symbol: The ticker symbol of the stock/equity. The symbol of most U.S stocks only contains letters, HK stocks and Chinese A-Shares uses numbers as symbols of stocks. For example, the symbol of Tiger Brokers (NASDAQ) is TIGR
- Security type: Common Security types includes STK(Stocks), OPT(Options), FUT(Futures) and CASH(Forex). For example, the Security type of Tiger Brokers (NASDAQ) is TIGR
- Exchange: The code of the exchange in which the requested asset is traded. Contracts with Security typ of STK does not require this data field, as the orders will be routed automatically to a designated exchange, However, for futures, this field is necessary
- Currency: USD、HKD
Most stocks, CFDs, indexes or Forexs can be identify by those four elements. However, some contracts like Futures and Options has more attributes in their corresponding contract objects
Here are a few common types of contracts and what elements they consist of.
Stock
ContractItem contract = new ContractItem();
contract.symbol ="TIGR";
contract.secType ="STK";
contract.currency ="USD"; //not require
contract.market = "US"; //not require
Option
Tiger Securities's API support 2 option contract format:
One is the four-factor approach, including symbol, expiry, strike, right.
The other is the standard OCC option contract format, fixed length of 21 bits. contains four parts：
- The code of the relevant stock or ETP, e.g. (AAPL), is fixed at six characters, with the missing digits filled by spaces
- Option expiration date, 6 digits, format: yymmdd
- Option type,including P or C, for put or call
- Option exercise price, the value of the price x 1000, fixed 8 digits, the first few digits are filled by 0
get_contract Get a Contract
TradeClient.get_contract(symbol, sec_type=SecurityType.STK, currency=None, exchange=None, expiry=None, strike=None, put_call=None)
Description
Get the contract Object
Argument
| Argument | Type | Description |
|---|---|---|
| symbol | str | Ticker symbol of the stock/equity, example: 'AAPL' |
| sec_type | SecurityType | Securtiy type, use constants defined in tigeropen.common.consts.SecurityType, example: SecurityType.STK |
| currency | Currency | Currencies, use constants defined in tigeropen.common.consts.Currency, example: Currency.USD |
| exchange | str | Exchange code. This argument is optional, example: 'CBOE' |
| expiry | str | Options expiration date, format: 'yyyyMMdd', example: '220121' |
| strike | float | Options strike price |
| put_call | str | 'PUT' / 'CALL' for options |
Response
tigeropen.trade.domain.contract.Contract Contract Object, Please see Objects for more information. Some attributes of this object are as follows
| Argument | Type | Description |
|---|---|---|
| currency | str | Currency type |
| identifier | str | Unique identifier, the stock identifier is the same as the symbol, the option is a 21-digit identifier, such as: 'AAPL 220729C00150000', the futures identifier |
| symbol | str | Ticker symbol of the asset |
| sec_type | str | STK stock/OPT option/FUT futures/WAR warrant/IOPT CBBC, etc., the default is STK |
| name | str | contract name |
| currency | str | currency,USD/HKD/SGD/cnh |
| exchange | str | The code of the exchange in which the requested asset is traded |
| expire | str | Exclusive to options and futures, option or futures expiration date |
| strike | float | Exclusive to options, the exercise price of the option |
| multiplier | float | Lot quantity |
| put_call | str | Exclusive to options, option directions, call or put |
| local_symbol | str | Exclusive to global account, suitable for HK warrant and CBBC |
| short_fee_rate | float | Borrow fee rate |
| shortable | bool | whether can be short |
| shortable_count | int | Maximum quantity of shares that can be shorted currently |
| short_maintenance_margin | float | short maintenance margin ratio |
| long_initial_margin | float | Initial margin requirement for taking a long position |
| long_maintenance_margin | float | Maintenance margin requirement for taking a long position |
| contract_month | str | The contract month, such as 202201, means January 2022 |
| primary_exchange | str | stock exchange |
| market | str | market US/HK/CN/AU/SG |
| marginable | bool | whether can thade by margin |
| min_tick | float | Minimum quotation unit |
| tickSizes | str | Exclusive to stocks, the minimum quotation unit price interval, that is, when the pending order price is between the begin and end intervals, it must meet the tickSize requirement, begin: the left interval of the price, end: the right interval of the price, type: the interval type OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN( open range/left open right close/closed range/left close right open), tickSize: minimum price unit, example: [{"begin":"0","end":"1","tickSize":1.0E-4,"type":"CLOSED"},{"begin":"1","end":"Infinity","tickSize":0.01,"type":"OPEN"}] |
| trading_class | str | The transaction level name of the contract |
| status | str | contract status |
| continuous | bool | Exclusive to futures, whether it is a continuous contract |
| trade | bool | whether it can be traded |
| last_trading_date | str | Exclusive to futures, the last trading day, such as '20211220', means December 20, 2021 |
| first_notice_date | str | Exclusive to futures, on the first notice day, the contract cannot open long positions after the first notice day. Existing long positions will be forced to close before the first notice day (usually the first three trading days), such as '20211222' , indicating December 22, 2021 |
| last_bidding_close_time | int | Exclusive to futures, bidding deadline timestamp |
| is_etf | bool | is it ETF |
| etf_leverage | int | etf leverage,only current ETF has value |
| discounted_day_initial_margin | float | Futures only, Intraday initial margin discount |
| discounted_day_maintenance_margin | float | Futures only, Intraday maintenance margin discount |
| discounted_time_zone_code | float | Futures only, Intraday margin discount period time zone |
| discounted_start_at | float | Futures only, Intraday margin discount start time |
| discounted_end_at | float | Futures only, Intraday margin discount end time |
Example
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import get_client_config
client_config = get_client_config(private_key_path='path of .pem file', tiger_id='your tiger id', account='your account', secret_key='secret key for registered traders, only applicable to institutions')
trade_client = TradeClient(client_config)
contract = trade_client.get_contract('AAPL', sec_type=SecurityType.STK)
print(contract)
# show all properties
print(contract.to_str())
# look up short init margin
print(contract.short_init_margin)
Response
{'contract_id': None, 'symbol': 'TQQQ', 'currency': 'USD', 'sec_type': 'STK',
'exchange': None, 'origin_symbol': None, 'local_symbol': 'TQQQ', 'expiry': None,
'strike': None, 'put_call': None, 'multiplier': 1.0, 'name': 'Nasdaq 3 ETF',
'short_margin': 0.55, 'short_initial_margin': 0.55, 'short_maintenance_margin': 0.5,
'short_fee_rate': None, 'shortable': None, 'shortable_count': None,
'long_initial_margin': 0.5, 'long_maintenance_margin': 0.45, 'contract_month': None,
'identifier': 'TQQQ', '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': 'TQQQ', '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': True, 'etf_leverage': 3,'discounted_day_initial_margin': 10472.0, 'discounted_day_maintenance_margin': 9520.0, 'discounted_time_zone_code': 'CDT', 'discounted_start_at': '17:30:00', 'discounted_end_at': '15:00:00'}
get_contracts Get Multiple Contracts
TradeClient.get_contracts(symbol, sec_type=SecurityType.STK, currency=None, exchange=None):
Description
Get multiple contract objects. The objects are returned as a list
Argument
| Argument | Type | Description |
|---|---|---|
| symbol | str | Ticker symbol of the stock/equity, example: 'AAPL'. Maximum 50 per request |
| sec_type | SecurityType | Securtiy type, use constants defined in tigeropen.common.consts.SecurityType, example: SecurityType.STK |
| currency | Currency | Currencies, use constants defined in tigeropen.common.consts.Currency, example: Currency.USD |
| exchange | str | Exanche code. This argument is optional, example: 'CBOE' |
Response
list
Each element of this list is a contract object (tigeropen.trade.domain.contract.Contract). Refer to Contract Object for details
| Argument | Type | Description |
|---|---|---|
| currency | str | Currency type |
| identifier | str | Unique identifier, the stock identifier is the same as the symbol, the option is a 21-digit identifier, such as: 'AAPL 220729C00150000', the futures identifier |
| symbol | str | Ticker symbol of the asset |
| sec_type | str | STK stock/OPT option/FUT futures/WAR warrant/IOPT CBBC, etc., the default is STK |
| name | str | contract name |
| currency | str | currency,USD/HKD/SGD/cnh |
| exchange | str | The code of the exchange in which the requested asset is traded |
| expire | str | Exclusive to options and futures, option or futures expiration date |
| strike | float | Exclusive to options, the exercise price of the option |
| multiplier | float | Lot quantity |
| put_call | str | Exclusive to options, option directions, call or put |
| local_symbol | str | Exclusive to global account, suitable for HK warrant and CBBC |
| short_fee_rate | float | Borrow fee rate |
| shortable | int | Maximum quantity of shares that can be shorted currently |
| short_maintenance_margin | float | short maintenance margin ratio |
| long_initial_margin | float | Initial margin requirement for taking a long position |
| long_maintenance_margin | float | Maintenance margin requirement for taking a long position |
| contract_month | str | The contract month, such as 202201, means January 2022 |
| primary_exchange | str | stock exchange |
| market | str | market US/HK/CN/AU/SG |
| min_tick | float | Minimum quotation unit |
| tickSizes | str | Exclusive to stocks, the minimum quotation unit price interval, that is, when the pending order price is between the begin and end intervals, it must meet the tickSize requirement, begin: the left interval of the price, end: the right interval of the price, type: the interval type OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN( open range/left open right close/closed range/left close right open), tickSize: minimum price unit, example:[{"begin":"0","end":"1","tickSize":1.0E-4,"type":"CLOSED"},{"begin":"1","end":"Infinity","tickSize":0.01,"type":"OPEN"}] |
| trading_class | str | The transaction level name of the contract |
| status | str | contract status |
| continuous | bool | Exclusive to futures, whether it is a continuous contract |
| trade | bool | Exclusive to futures, whether it can be traded |
| last_trading_date | str | Exclusive to futures, the last trading day, such as '20211220', means December 20, 2021 |
| first_notice_date | str | Exclusive to futures, on the first notice day, the contract cannot open long positions after the first notice day. Existing long positions will be forced to close before the first notice day (usually the first three trading days), such as '20211222' , indicating December 22, 2021 |
| last_bidding_close_time | int | Exclusive to futures, bidding deadline timestamp |
| is_etf | bool | is it ETF |
| etf_leverage | int | etf leverage,only current ETF has value |
Example
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import get_client_config
client_config = get_client_config(private_key_path='path of .pem file', tiger_id='your tiger id', account='your account', secret_key='secret key for registered traders, only applicable to institutions')
trade_client = TradeClient(client_config)
contracts = trade_client.get_contracts('AAPL', sec_type=SecurityType.STK)
print(contracts)
print(contract[0].to_str())
Response Example
[AAPL/STK/USD, JD/STK/USD]
{'contract_id': None, '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.4, 'short_initial_margin': 0.4, 'short_maintenance_margin': 0.4, 'short_fee_rate': 3.25, 'shortable': 0, 'shortable_count': 0, 'long_initial_margin': 0.3, 'long_maintenance_margin': 0.4, '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': 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}
Construct Contract Object Locally
Stocks
from tigeropen.common.util.contract_utils import stock_contract
contract = stock_contract(symbol='TIGR', currency='USD')
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')
Futures
# prime account/paper account
from tigeropen.common.util.contract_utils import future_contract
contract = future_contract(symbol='CL2312', currency='USD')
# global account
from tigeropen.common.util.contract_utils import future_contract
contract = future_contract(symbol='CL', currency='USD', expiry='20190328', multiplier=1.0, exchange='SGX')
Hongkong CBBC
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')
get_derivative_contracts
Get Option/WAR/CBBC Contract List
Argument
| Argument | Type | Required | Description |
|---|---|---|---|
| symbols | str | Yes | security code, only support one symbol now |
| sec_type | SecurityType | Yes | security type support: (OPT/WAR/IOPT) |
| expiry | str | expiry date str, format:yyyyMMdd, e.g. '20220929' | |
| lang | str | No | language, support: zh_CN,zh_TW,en_US, default: en_US |
Responselist
Each item in the list is a contract object( refer to tigeropen.trade.domain.contract.Contract)
| Argument | Type | Description |
|---|---|---|
| symbol | string | security code |
| name | string | contract name |
| exchange | string | exchange code |
| market | string | trading market |
| sec_type | string | security type |
| currency | string | trading currency |
| expiry | string | expiry date str(OPT、WAR、IOPT、FUT)，e.g. 20171117 |
| right | string | option right(OPT、WAR、IOPT), including: PUT/CALL |
| strike | float | strike price |
| multiplier | float | multiplier (OPT,WAR,IOPT,FUT) |
Example
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import get_client_config
client_config = get_client_config(private_key_path='private key path', tiger_id='your tiger id', account='your account', secret_key='institution trader\'s secret key')
trade_client = TradeClient(client_config)
contracts = trade_client.get_derivative_contracts('00700', SecurityType.WAR, '20220929')
print(contracts)
Example Response
[23009/WAR/HKD, 12554/WAR/HKD, 12566/WAR/HKD, 12491/WAR/HKD, 12492/WAR/HKD, 11436/WAR/HKD, 11803/WAR/HKD, 11985/WAR/HKD, 11996/WAR/HKD, 28456/WAR/HKD, 28465/WAR/HKD, 29814/WAR/HKD, 27695/WAR/HKD, 13252/WAR/HKD, 25315/WAR/HKD, 13590/WAR/HKD]