Get Contract

Contract Overview

A contract refers to the trading object or underlying asset (e.g., a stock or an option). Contracts are standardized by exchanges. For example, to purchase Tiger Brokers stock, you can uniquely identify it using the symbol TIGR and market information (i.e., market='US', US market). With contract information, we can uniquely determine an underlying asset when placing orders or fetching market data. Common contracts include stock contracts, option contracts, and futures contracts.

Most contracts (such as stocks, CFDs, indices, or forex) can be uniquely identified by the following four basic properties:

Symbol: US and UK stock symbols are typically alphabetic, while HK and A-share symbols are numeric. For example, Tiger Brokers' symbol is TIGR.
Security Type (sec_type): Common types include STK (Stock), OPT (Option), FUT (Futures), CASH (Forex). For example, Tiger Brokers stock has sec_type STK.
Currency: Common currencies include USD (US Dollar) and HKD (Hong Kong Dollar).
Exchange: Generally not used for STK contracts as orders are auto-routed. Futures contracts typically require the exchange field.

get_contract Get Single Contract Info

value TradeClient::get_contract(utility::string_t symbol, utility::string_t sec_type, utility::string_t currency, utility::string_t exchange, time_t expiry, utility::string_t strike, utility::string_t right)

value TradeClient::get_contract(utility::string_t symbol, SecType sec_type, Currency currency, utility::string_t exchange, time_t expiry, utility::string_t strike, Right right)

Description

Query single contract information required for trading. This method provides both string and enum overloaded versions.

Parameters (String Version)

Parameter	Type	Required	Description
symbol	utility::string_t	Yes	Stock symbol, e.g., U("AAPL")
sec_type	utility::string_t	Yes	Security type, e.g., U("STK"), U("OPT"), U("FUT")
currency	utility::string_t	No	Currency, e.g., U("USD"), U("HKD")
exchange	utility::string_t	No	Exchange, e.g., U("CBOE")
expiry	time_t	No	Contract expiry timestamp (milliseconds), default -1
strike	utility::string_t	No	Strike price (for options)
right	utility::string_t	No	Put/Call (for options), U("PUT") or U("CALL")

Parameters (Enum Version)

Parameter	Type	Required	Description
symbol	utility::string_t	Yes	Stock symbol
sec_type	SecType	No	Security type, default SecType::STK
currency	Currency	No	Currency, default Currency::ALL
exchange	utility::string_t	No	Exchange
expiry	time_t	No	Contract expiry timestamp, default -1
strike	utility::string_t	No	Strike price
right	Right	No	Option direction, default Right::ALL

Return

web::json::value JSON object containing contract information

Object Properties

Property	Type	Description
identifier	string	Unique identifier. For stocks, same as symbol; for options, a 21-character identifier
symbol	string	Stock symbol
sec_type	string	STK Stock / OPT Option / FUT Futures / WAR Warrant / IOPT CBBC, etc.
name	string	Contract name
currency	string	Currency, e.g., USD/HKD/CNH
exchange	string	Exchange
expiry	string	Expiry date (options and futures)
strike	float	Strike price (options)
multiplier	float	Multiplier, quantity per lot
put_call	string	CALL or PUT (options)
market	string	Market, e.g., US/HK/CN
min_tick	float	Minimum tick size
tickSizes	array	Tick size price ranges
shortable	bool	Whether shortable
marginable	bool	Whether marginable
lot_size	float	Minimum tradable quantity per transaction

Example

#include "tigerapi/trade_client.h"
#include "tigerapi/client_config.h"

using namespace TIGER_API;

ClientConfig config(false, U("/path/to/your/properties/"));
TradeClient trade_client(config);

// Stock contract
value contract = trade_client.get_contract(U("AAPL"), U("STK"));
ucout << contract.serialize() << std::endl;

// Futures contract
value fut_contract = trade_client.get_contract(U("ES2306"), U("FUT"));
ucout << fut_contract.serialize() << std::endl;

Return Example

{
  "contractId": 1916,
  "symbol": "AAPL",
  "currency": "USD",
  "secType": "STK",
  "exchange": null,
  "localSymbol": "AAPL",
  "multiplier": 1.0,
  "name": "Apple",
  "shortInitialMargin": 0.35,
  "shortMaintenanceMargin": 0.3,
  "longInitialMargin": 0.3,
  "longMaintenanceMargin": 0.25,
  "identifier": "AAPL",
  "primaryExchange": "NASDAQ",
  "market": "US",
  "tickSizes": [
    {"begin": "0", "end": "1", "type": "CLOSED", "tickSize": 0.0001},
    {"begin": "1", "end": "Infinity", "type": "OPEN", "tickSize": 0.01}
  ],
  "tradingClass": "AAPL",
  "status": 1,
  "marginable": true,
  "trade": true,
  "lotSize": 1.0
}

get_contracts Get Multiple Contract Info

value TradeClient::get_contracts(const value &symbols, utility::string_t sec_type, utility::string_t currency, utility::string_t exchange, time_t expiry, utility::string_t strike, utility::string_t right)

Description

Query multiple contract information, returned as a JSON array

Parameters

Parameter	Type	Required	Description
symbols	value	Yes	Stock symbol array. Max 50 per request
sec_type	utility::string_t	No	Security type, default U("STK")
currency	utility::string_t	No	Currency
exchange	utility::string_t	No	Exchange
expiry	time_t	No	Contract expiry timestamp, default -1
strike	utility::string_t	No	Strike price
right	utility::string_t	No	Option direction

Return

web::json::value JSON array

Example

ClientConfig config(false, U("/path/to/your/properties/"));
TradeClient trade_client(config);

value symbols = value::array();
symbols[0] = value::string(U("AAPL"));
symbols[1] = value::string(U("TSLA"));

value contracts = trade_client.get_contracts(symbols, U("STK"));
ucout << contracts.serialize() << std::endl;

Local Contract Object Construction

The C++ SDK provides the ContractUtil utility class to build contract objects locally without making network requests.

Stock

#include "tigerapi/contract_util.h"

using namespace TIGER_API;

// US stock
Contract contract = ContractUtil::stock_contract(U("TIGR"), U("USD"));

// HK stock
Contract contract = ContractUtil::stock_contract(U("00700"), U("HKD"));

Option

#include "tigerapi/contract_util.h"

using namespace TIGER_API;

// Method 1: Using four elements
Contract contract = ContractUtil::option_contract(
    U("AAPL"),          // symbol
    U("20240621"),       // expiry
    U("190"),            // strike
    U("CALL"),           // right
    U("USD"),            // currency
    100                  // multiplier
);

// Method 2: Using OCC identifier
Contract contract = ContractUtil::option_contract(U("AAPL  240621C00190000"));

// Parse option identifier
auto [symbol, expiry, right, strike] = ContractUtil::extract_option_info(U("AAPL  240621C00190000"));

Futures

#include "tigerapi/contract_util.h"

using namespace TIGER_API;

// Using contract code
Contract contract = ContractUtil::future_contract(U("CL2312"), U("USD"));

// Using full parameters
Contract contract = ContractUtil::future_contract(
    U("CL"),             // symbol
    U("USD"),            // currency
    U("20231220"),       // expiry
    U("NYMEX"),          // exchange
    U("202312"),         // contract_month
    1000                 // multiplier
);

Contract Object

The C++ SDK Contract struct contains the following main properties:

Property	Type	Description
contract_id	long	Contract ID
symbol	utility::string_t	Symbol code
sec_type	utility::string_t	Security type
currency	utility::string_t	Currency
exchange	utility::string_t	Exchange
market	utility::string_t	Market
expiry	utility::string_t	Expiry date
strike	utility::string_t	Strike price
right	utility::string_t	Option direction PUT/CALL
multiplier	int	Multiplier
contract_month	utility::string_t	Contract month (futures)
local_symbol	utility::string_t	Local identifier
identifier	utility::string_t	Unique identifier