Docs
English

获取合约

合约介绍

合约是指交易的买卖对象或者标的物（比如一只股票或一只期权），合约是由交易所统一制定的。比如购买老虎证券的股票，可以通过 TIGR 这个字母代号和市场信息（即 market='US'，美国市场）来唯一标识。通过合约信息，我们在下单或者获取行情时就可以唯一的确定一个标的物。常见的合约包括股票合约，期权合约，期货合约等。

大多数合约（如：股票，差价合约，指数或外汇）可通过以下四个基础属性唯一确定：

  • 标的代码 (symbol)：一般美股、英股等合约代码都是英文字母，港股、A 股等合约代码是数字，比如老虎证券的 symbol 是 TIGR。
  • 合约类型 (security type)：常见合约类型包括：STK（股票），OPT（期权），FUT（期货），CASH（外汇），比如老虎证券股票的合约类型是 STK。
  • 货币类型 (currency)：常见货币包括 USD（美元），HKD（港币）。
  • 交易所 (exchange)：STK 类型的合约一般不会用到交易所字段，订单会自动路由，期货合约都用到交易所字段。

获取单个合约信息

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)

说明

查询交易所需的单个合约信息。此方法提供字符串和枚举两种重载版本。

参数（字符串版本）

参数名类型是否必填描述
symbolutility::string_tYes股票代码，如 U("AAPL")
sec_typeutility::string_tYes证券类型，如 U("STK")、U("OPT")、U("FUT")
currencyutility::string_tNo币种，如 U("USD")、U("HKD")
exchangeutility::string_tNo交易所，如 U("CBOE")
expirytime_tNo合约到期日时间戳（毫秒），默认 -1
strikeutility::string_tNo行权价（适用于期权）
rightutility::string_tNo看涨看跌（适用于期权），U("PUT") 看跌，U("CALL") 看涨

参数（枚举版本）

参数名类型是否必填描述
symbolutility::string_tYes股票代码
sec_typeSecTypeNo证券类型，默认 SecType::STK
currencyCurrencyNo币种，默认 Currency::ALL
exchangeutility::string_tNo交易所
expirytime_tNo合约到期日时间戳，默认 -1
strikeutility::string_tNo行权价
rightRightNo期权方向，默认 Right::ALL

返回

web::json::value JSON 对象，包含合约信息

对象属性

属性名类型描述
identifierstring唯一标识，股票 identifier 和 symbol 相同，期权为 21 位标识符
symbolstring股票代码
sec_typestringSTK 股票/OPT 期权/FUT 期货/WAR 窝轮/IOPT 牛熊证等
namestring合约名称
currencystring币种，如：USD/HKD/CNH
exchangestring交易所
expirystring期权和期货专有，过期日
strikefloat期权专有，行权价格
multiplierfloat乘数，每手对应的数量
put_callstring期权专有，CALL 或者 PUT
marketstring市场，如：US/HK/CN
min_tickfloat最小报价单位
tickSizesarray最小报价单位价格区间
shortablebool是否可做空
marginablebool是否可融资
lot_sizefloat单笔交易中可交易的最小资产数量

示例

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

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

// 期货合约
value fut_contract = trade_client.get_contract(U("ES2306"), U("FUT"));
ucout << fut_contract.serialize() << std::endl;

SDK model shape

get_contract 返回原始 web::json::value。可转换的 Contract 模型字段来自 include/tigerapi/model.h，包括 contract_id、symbol、currency、sec_type、exchange、expiry、strike、right、multiplier、local_symbol、identifier、primary_exchange、market、trading_class 和 lot_size。SDK 仓库没有该 HTTP 响应的已验证 fixture，因此不提供合成 JSON。

返回示例

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

获取多个合约信息

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 查询指定代码、证券类型和到期日的行情合约；三个参数均必填，返回 web::json::value。

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

说明

查询交易所需的多个合约信息，以 JSON 数组形式返回

参数

参数名类型是否必填描述
symbolsvalueYes股票代码数组。单次请求上限为 50
sec_typeutility::string_tNo证券类型，默认 U("STK")
currencyutility::string_tNo币种
exchangeutility::string_tNo交易所
expirytime_tNo合约到期日时间戳，默认 -1
strikeutility::string_tNo行权价
rightutility::string_tNo期权方向

返回

web::json::value JSON 数组

示例

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;

本地生成合约对象

C++ SDK 提供 ContractUtil 工具类，可以在本地直接构建合约对象，无需发起网络请求。

股票

#include "tigerapi/contract_util.h"

using namespace TIGER_API;

// 美股
Contract contract = ContractUtil::stock_contract(U("TIGR"), U("USD"));

// 港股
Contract contract = ContractUtil::stock_contract(U("00700"), U("HKD"));

期权

#include "tigerapi/contract_util.h"

using namespace TIGER_API;

// 方式一：使用四要素
Contract contract = ContractUtil::option_contract(
    U("AAPL"),          // symbol
    U("20240621"),       // expiry
    U("190"),            // strike
    U("CALL"),           // right
    U("USD"),            // currency
    100                  // multiplier
);

// 方式二：使用 OCC 标识符
Contract contract = ContractUtil::option_contract(U("AAPL  240621C00190000"));

// 解析期权标识符
auto [symbol, expiry, right, strike] = ContractUtil::extract_option_info(U("AAPL  240621C00190000"));

期货

#include "tigerapi/contract_util.h"

using namespace TIGER_API;

// 使用合约代码
Contract contract = ContractUtil::future_contract(U("CL2312"), U("USD"));

// 使用完整参数
Contract contract = ContractUtil::future_contract(
    U("CL"),             // symbol
    U("USD"),            // currency
    U("20231220"),       // expiry
    U("NYMEX"),          // exchange
    U("202312"),         // contract_month
    1000                 // multiplier
);

Contract 对象

C++ SDK 的 Contract 结构体包含以下主要属性：

属性名类型描述
contract_idlong合约 ID
symbolutility::string_t标的代码
sec_typeutility::string_t合约类型
currencyutility::string_t币种
exchangeutility::string_t交易所
marketutility::string_t市场
expiryutility::string_t过期日
strikeutility::string_t行权价
rightutility::string_t期权方向 PUT/CALL
multiplierint乘数
contract_monthutility::string_t合约月份（期货）
local_symbolutility::string_t本地标识
identifierutility::string_t唯一标识

Updated 8 days ago

What’s Next

Did this page help you?