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

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

Contract ContractUtil::stock_contract(const utility::string_t symbol, const utility::string_t currency,
                        const utility::string_t local_symbol, const utility::string_t exchange,
                        long contract_id) {
    return Contract(U("STK"), symbol, currency, local_symbol, exchange, contract_id);
}

Option

Tiger Securities API supports 2 options contract formats:

One is the four-factor approach (symbol, expiry, strike, right).

Contract ContractUtil::option_contract(
    const utility::string_t symbol, 
    const utility::string_t expiry, 
    const utility::string_t strike,
    const utility::string_t right,
    const utility::string_t currency, 
    long multiplier, 
    const utility::string_t local_symbol,
    long contract_id) 
{
    return Contract(
        U("OPT"), symbol, expiry, strike, right, 
        currency, multiplier, local_symbol, contract_id
    );
}

The other is the standard OCC option contract format, fixed length of 21 bits containing 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

Contract ContractUtil::option_contract(
    const utility::string_t identifier, 
    long multiplier, 
    const utility::string_t currency) 
{
    utility::string_t symbol, expiry, right, strike;
    
    std::tie(symbol, expiry, right, strike) = ContractUtil::extract_option_info(identifier);

    if (!expiry.empty() && expiry.find('-') != utility::string_t::npos) {
        expiry.erase(std::remove(expiry.begin(), expiry.end(), '-'), expiry.end());
    }

    return Contract(U("OPT"), symbol, expiry, strike, right, currency, multiplier, U(""), 0);
}

get_contract Get a Contract

value get_contract(utility::string_t symbol, utility::string_t sec_type, utility::string_t currency = U(""), utility::string_t exchange = U(""), time_t expiry = -1, utility::string_t strike = U(""), utility::string_t right = U("")); value get_contract(utility::string_t symbol, SecType sec_type = SecType::STK, Currency currency = Currency::ALL, utility::string_t exchange = U(""), time_t expiry = -1, utility::string_t strike = U(""), Right right = Right::ALL);

Description

Get the contract Object

Parameters

Parameter	Type	Required	Description
symbol	utility::string_t	Yes	Ticker symbol of the stock/equity, example: 'AAPL'
sec_type	SecType	No	Security type default: SecType::STK
currency	Currency	No	Currencies of contract default: Currency::ALL
exchange	utility::string_t	No	Exchange code. Example: 'CBOE'
expiry	time_t	No	Options expiration date default: -1
strike	utility::string_t	No	Options strike price
right	Right	No	'PUT' / 'CALL' for options default: Right::ALL

Response

Contract Object, Please see Objects for more information. Some attributes of this object are as follows

Field	Type	Description
close_only	bool	Whether an asset or position can only be closed (sold or exited) and not opened (bought or entered)
currency	utility::string_t	Currency type，USD/HKD/CNH
identifier	utility::string_t	Unique Identifier: For stocks, the identifier is the same as the symbol. For options, it is a 21-character identifier, such as 'AAPL 220729C00150000'. For futures, it is the futures identifier
is_etf	bool	Whether it is an ETF
local_symbol	utility::string_t	Identify Warrants and Callable Bull/Bear Contracts for Hong Kong Stocks (Global accounts only)
long_initial_margin	float	Initial margin for long positions
long_maintenance_margin	float	Maintenance margin for long positions
marginable	bool	Eligible for margin trading
market	utility::string_t	Market
multiplier	float	Contracts per lot
name	utility::string_t	Contract name
sec_type	utility::string_t	STK - Stock / OPT - Option / FUT - Futures / WAR - Warrant / IOPT - Callable Bull/Bear Contracts (CBBC)
short_fee_rate	float	Short selling fee rate
short_initial_margin	float	Initial margin ratio for short selling
short_maintenance_margin	float	Maintenance Margin Ratio for Short Selling (No value for Global account contracts)
short_margin	float	Short Selling Margin Ratio (Deprecated, use short_initial_margin)
shortable	bool	Whether short selling is allowed
shortable_count	int	Remaining amount in short-selling pool
status	utility::string_t	Contract status
symbol	utility::string_t	Stock Code: For option contracts, the symbol corresponds to the underlying asset code
tickSizes	list<tickSize>	Stock only, Minimum quoting unit price range, i.e., when the order price is within the begin and end range, it must meet the tickSize requirement begin: left range of price, end: right range of price, type: TickSizeType, tickSize: minimum price unit
tradable	bool	Whether asset is tradable
trading_class	utility::string_t	Contract Trading level name

Example

#include "tigerapi/trade_client.h"
#include "tigerapi/contract_util.h"
#include "tigerapi/order_util.h"

using namespace std;
using namespace web;
using namespace web::json;
using namespace TIGER_API;

class TestTradeClient {
public:
    static void test_get_contract(const std::shared_ptr<TradeClient>& trade_client) {
        value res = trade_client->get_contract("AAPL");
        cout << "contract: " << res << endl;
    }

    static void test_trade(const std::shared_ptr<TradeClient>& trade_client) {
        TestTradeClient::test_get_contract(trade_client);
    }
};

int main(int argc, char *args[]) {
    cout << "Tiger Api main" << endl;
    /************************** set config **********************/
    ClientConfig config = ClientConfig(true);

    config.private_key = "-----BEGIN RSA PRIVATE KEY-----\n"
                         "xxxxxx private kye xxxxxxxx"
                         "-----END RSA PRIVATE KEY-----";
    config.tiger_id = "Tiger ID";
    config.account = "Account ID";


    /**
     * Use TradeClient
     */
    std::shared_ptr<TradeClient> trade_client = std::make_shared<TradeClient>(config);
    TestTradeClient::test_trade(trade_client);


    return 0;
}

Response

{
    "closeOnly": false,
    "currency": "USD",
    "identifier": "AAPL",
    "isEtf": false,
    "localSymbol": "AAPL",
    "longInitialMargin": 0.29999999999999999,
    "longMaintenanceMargin": 0.40000000000000002,
    "marginable": true,
    "market": "US",
    "multiplier": 1,
    "name": "Apple Inc",
    "secType": "STK",
    "shortFeeRate": 3.25,
    "shortInitialMargin": 0.40000000000000002,
    "shortMaintenanceMargin": 0.40000000000000002,
    "shortMargin": 0.40000000000000002,
    "shortable": 0,
    "shortableCount": 0,
    "status": 1,
    "symbol": "AAPL",
    "tickSizes": [
        {
            "begin": "0",
            "end": "1",
            "tickSize": 0.0001,
            "type": "CLOSED"
        },
        {
            "begin": "1",
            "end": "Infinity",
            "tickSize": 0.01,
            "type": "OPEN"
        }
    ],
    "tradeable": true,
    "tradingClass": "AAPL"
}

get_contracts Get Multiple Contracts

value get_contracts(const value &symbols, utility::string_t sec_type, utility::string_t currency = U(""), utility::string_t exchange = U(""), time_t expiry = -1, utility::string_t strike = U(""), utility::string_t right = U(""));

Description

Get multiple contract objects. The objects are returned as a list

Parameters

Parameter	Type	Required	Description
symbols	utility::string_t	Yes	Ticker symbol of the stock/equity, example: 'AAPL'. Maximum 50 per request
sec_type	SecType	Yes	Security type, example: SecType::STK
currency	Currency	No	Currencies, example: Currency::USD
exchange	utility::string_t	No	Exchange code, example: 'CBOE'
expiry	time_t	No	Contract expiration date
strike	utility::string_t	No	Strike price
right	utility::string_t	No	'PUT' / 'CALL' / 'ALL'
Response

list

Each element of this list is a contract object (/include/tigerapi/model.h). Refer to Contract Object for details

Field	Type	Description
close_only	bool	Whether an asset or position can only be closed (sold or exited) and not opened (bought or entered)
currency	utility::string_t	Currency type，USD/HKD/CNH
identifier	utility::string_t	Unique Identifier: For stocks, the identifier is the same as the symbol. For options, it is a 21-character identifier, such as 'AAPL 220729C00150000'. For futures, it is the futures identifier
is_etf	bool	Whether it is an ETF
local_symbol	utility::string_t	Identify Warrants and Callable Bull/Bear Contracts for Hong Kong Stocks (Global accounts only)
long_initial_margin	float	Initial margin for long positions
long_maintenance_margin	float	Maintenance margin for long positions
marginable	bool	Eligible for margin trading
market	utility::string_t	Market
multiplier	float	Contracts per lot
name	utility::string_t	Contract name
sec_type	utility::string_t	STK - Stock / OPT - Option / FUT - Futures / WAR - Warrant / IOPT - Callable Bull/Bear Contracts (CBBC)
short_fee_rate	float	Short selling fee rate
short_initial_margin	float	Initial margin ratio for short selling
short_maintenance_margin	float	Maintenance Margin Ratio for Short Selling (No value for Global account contracts)
short_margin	float	Short Selling Margin Ratio (Deprecated, use short_initial_margin)
shortable	bool	Whether short selling is allowed
shortable_count	int	Remaining amount in short-selling pool
status	utility::string_t	Contract status
symbol	utility::string_t	Stock Code: For option contracts, the symbol corresponds to the underlying asset code
tickSizes	list<tickSize>	Stock only, Minimum quoting unit price range, i.e., when the order price is within the begin and end range, it must meet the tickSize requirement begin: left range of price, end: right range of price, type: TickSizeType, tickSize: minimum price unit
tradable	bool	Whether asset is tradable
trading_class	utility::string_t	Contract Trading level name

Example

#include "tigerapi/trade_client.h"
#include "tigerapi/contract_util.h"
#include "tigerapi/order_util.h"

using namespace std;
using namespace web;
using namespace web::json;
using namespace TIGER_API;

class TestTradeClient {
public:
    static void test_get_contracts(const std::shared_ptr<TradeClient>& trade_client) {
        value symbols = value::array();
        symbols[0] = value::string(U("AAPL"));
        symbols[1] = value::string(U("JD"));
        value res = trade_client->get_contracts(symbols, U("STK"));
        ucout << U("contracts: ") << res << endl;
    }

    static void test_trade(const std::shared_ptr<TradeClient>& trade_client) {
        TestTradeClient::test_get_contracts(trade_client);
    }
};

int main(int argc, char *args[]) {
    cout << "Tiger Api main" << endl;
    /************************** set config **********************/
    ClientConfig config = ClientConfig(true);

    config.private_key = "-----BEGIN RSA PRIVATE KEY-----\n"
                         "xxxxxx private kye xxxxxxxx"
                         "-----END RSA PRIVATE KEY-----";
    config.tiger_id = "Tiger ID";
    config.account = "Account ID";


    /**
     * Use TradeClient
     */
    std::shared_ptr<TradeClient> trade_client = std::make_shared<TradeClient>(config);
    TestTradeClient::test_trade(trade_client);


    return 0;
}

Response

[
  {
    "closeOnly":false,
    "contractId":1916,
    "currency":"USD",
    "identifier":"AAPL",
    "isEtf":false,
    "localSymbol":"AAPL",
    "lotSize":1,
    "market":"US",
    "multiplier":1,
    "name":"Apple",
    "secType":"STK",
    "status":1,
    "supportOvernightTrading":true, 
    "symbol":"AAPL",
    "tickSizes":
    [
      {
        "begin":"0",
        "end":"1",
        "tickSize":0.0001,
        "type":"CLOSED"
      },
      {
        "begin":"1",
        "end":"Infinity",
        "tickSize":0.01,
        "type":"OPEN"
      }
    ],
    "tradeable":true,
    "tradingClass":"AAPL"
  },
  {
    "closeOnly":false,
    "contractId":1722,
    "currency":"USD",
    "identifier":"JD",
    "isEtf":false,
    "localSymbol":"JD",
    "lotSize":1,
    "market":"US",
    "multiplier":1,
    "name":"JD.com",
    "secType":"STK",
    "status":1,
    "supportOvernightTrading":true,
    "symbol":"JD",
    "tickSizes":
    [
      {
        "begin":"0",
        "end":"1",
        "tickSize":0.0001,
        "type":"CLOSED"
      },
      {
        "begin":"1",
        "end":"Infinity",
        "tickSize":0.01,
        "type":"OPEN"
      }
    ],
    "tradeable":true,
    "tradingClass":"JD"
  }
]

Construct Contract Object Locally

Stocks：

Contract contract = ContractUtil::stock_contract(U("AAPL"), U("USD"));

Options

Contract contract = ContractUtil::option_contract(U("AAPL"), U("20230721"), U("185.0"), U("PUT"), U("USD"));
Contract contract = ContractUtil::option_contract(U("AAPL 230721C00185000"));

Futures

Contract contract = ContractUtil::future_contract(U("NG2308"), U("USD"));

get_quote_contract

value get_quote_contract(utility::string_t symbol, utility::string_t sec_type, utility::string_t expiry)

Parameters

Parameter	Type	Required	Description
symbol	utility::string_t	Yes	security code
sec_type	SecType	Yes	security type support: (OPT/WAR/IOPT)
expiry	utility::string_t	Yes	expiry date str, format:yyyyMMdd, e.g. '20220929'

Responselist

Each item in the list is a contract object( refer to tigeropen.trade.domain.contract.Contract) Contract object.

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

    static void test_get_quote_contract(const std::shared_ptr<TradeClient>& trade_client) {
        value res = trade_client->get_quote_contract(U("00700"), U("IOPT"), U("20250328"));
        ucout << U("quote contract: ") << res << endl;
    }

Response：

[
  {
    "currency":"HKD",
    "exchange":"SEHK",
    "expiry":"20250328",
    "market":"HK",
    "multiplier":5000,
    "name":"SG#TENCTRC2503A.C",
    "right":"CALL",
    "secType":"IOPT",
    "strike":"357.2",
    "symbol":"67069"
  },
  {
    "currency":"HKD",
    "exchange":"SEHK",
    "expiry":"20250328",
    "market":"HK",
    "multiplier":10000,
    "name":"MS#TENCTRC2503B.C",
    "right":"CALL",
    "secType":"IOPT",
    "strike":"356.2",
    "symbol":"67170"
  },
  {
    "currency":"HKD",
    "exchange":"SEHK",
    "expiry":"20250328",
    "market":"HK",
    "multiplier":5000,
    "name":"MS#TENCTRC2503A.C",
    "right":"CALL",
    "secType":"IOPT",
    "strike":"267.2",
    "symbol":"52228"
  }
]

Get Contract

# get_contract Get a Contract

# get_contracts Get Multiple Contracts

# Construct Contract Object Locally

# get_quote_contract

get_contract Get a Contract

get_contracts Get Multiple Contracts

Construct Contract Object Locally

get_quote_contract