Get Contract

About 4 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

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

value get_contract(string symbol, SecType sec_type = SecType::STK, Currency currency = Currency::ALL, string exchange = "", long expiry = -1, double strike = 0, Right right = Right::ALL)

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

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

Argument	Type	Description
currency	str	Currency type
symbol	str	Ticker symbol of the asset
exchange	str	The code of the exchange in which the requested asset is traded
short_fee_rate	float	Borrow fee rate
shortable	int	Maximum quantity of shares that can be shorted currently
short_init_margin	float	Current marigin requirement for shorting
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

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

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
symbol	str	Ticker symbol of the asset
exchange	str	The code of the exchange in which the requested asset is traded
short_fee_rate	float	Borrow fee rate
shortable	int	Maximum quantity of shares that can be shorted currently
short_margin	float	urrent marigin requirement for shorting
long_initial_margin	float	Initial margin requirement for taking a long position
long_maintenance_margin	float	Maintenance margin requirement for taking a long position

Example

Response

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

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) Contract object.

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:

    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("20230728"));
        ucout << U("quote contract: ") << res << endl;
    }

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]

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