Get Contract

Contract Overview

A contract identifies a tradable instrument, such as a stock, option, or futures contract. Exchanges standardize contract details. For example, the symbol TIGR and market US identify Tiger Brokers stock. The SDK uses contract information to identify an instrument when placing orders or retrieving market data.

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 a Contract

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

Returns the contract information required to trade one instrument. Overloads accept either strings or enums.

Parameters (String Version)

Parameters (Enum Version)

Return

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

Object Properties

Example

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

using namespace TIGER_API;

ClientConfig config(false, U("your_config_directory_path"));
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;

SDK model shape

get_contract returns raw web::json::value. Convertible Contract fields derived from include/tigerapi/model.h include contract_id, symbol, currency, sec_type, exchange, expiry, strike, right, multiplier, local_symbol, identifier, primary_exchange, market, trading_class, and lot_size. The SDK repository has no verified HTTP response fixture, so no synthetic JSON is shown.

Response Example

{
  "code": 0,
  "message": "success",
  "timestamp": 1785528000000,
  "data": [
    {
      "symbol": "AAPL",
      "secType": "STK",
      "exchange": "SMART",
      "market": "US",
      "lotSize": 1,
      "currency": "USD",
      "name": "Apple Inc"
    }
  ]
}

Get Multiple Contracts

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)

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

get_quote_contract queries a quote contract by symbol, security type, and expiry. All three parameters are required and it returns web::json::value.

auto contract = trade_client.get_quote_contract(U("AAPL"), U("OPT"), U("2025-12-19"));

Description

Returns contract information for multiple instruments as a JSON array.

Parameters

Return

web::json::value JSON array

Example

ClientConfig config(false, U("your_config_directory_path"));
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: