Get Contract

We refer to what is being traded in an order as a "contract". The specs of a specific contract are set by an 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 stock/equity. The symbol of most U.S stocks only contains letters, HK stocks and Chinese A-Shares use numbers as stock symbols. For example, the symbol for Tiger Brokers (NASDAQ) is TIGR
Security type: Common Security types includes STK (Stocks), OPT (Options).

Options have 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);
}

Options

Our 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, a 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 unused digits filled by spaces
- Option expiration date, 6 digits, format: yymmdd
- Option type, delineated with a 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 Single Contract Information

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 Appendix 1: 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'.
is_etf	bool	Whether it is an ETF
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
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
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 Call

#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;
}

Example 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 Multiple Contract Information

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 Appendix 1: Objects for more 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'.
is_etf	bool	Whether it is an ETF
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
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
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 Call

#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(true, U("tiger_openapi_config.properties"));
    /**
     * Use TradeClient
     */
    std::shared_ptr<TradeClient> trade_client = std::make_shared<TradeClient>(config);
    TestTradeClient::test_trade(trade_client);
    
    return 0;
}

Example 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"));