获取合约

大约 5 分钟

合约介绍

合约是指交易的买卖对象或者标的物（比如一只股票或一只期权），合约是由交易所统一制定的。比如购买老虎证券的股票，可以通过TIGR这个字母代号和市场信息（即market=’US‘，美国市场）来唯一标识。类似的，在购买期权或者期货产品时，可能会需要用到其他一些标识字段。

通过合约信息，我们在下单或者获取行情时就可以唯一的确定一个标的物。

常见的合约包括股票合约，期权合约，期货合约等。

大部分合约包括如下几个要素:

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

绝大多数股票，差价合约，指数或外汇对可以通过这四个属性来唯一确定。

由于其性质，更复杂的合约（如期权和期货）需要一些额外的信息。

以下是几种常见类型合约，以及其由哪些要素构成。

股票

Contract contract = ContractUtil::stock_contract(U("AAPL"), U("USD"));

期权

老虎API的期权合约支持两种方式：

  • 一种是四要素方式，即symbol（股票代码），expiry（期权过期日），strike（期权行权价格），right（期权方向）。

  • 另一种是标准OCC期权合约格式，长度固定为21位。包含四部分：

    • 相关的股票或ETP的代码，比如（AAPL），固定占六位字符，不足位数由空格填充
    • 期权到期日，6位数字，格式为：yymmdd
    • 期权类型，取值为 P 或者 C, 表示 put 或 call
    • 期权行权价格，取值为 价格 x 1000, 固定占8位数字，前面不足的位数由0填充

    期权标识符

Contract contract = ContractUtil::option_contract(U("AAPL"), U("20230721"), U("185.0"), U("PUT"), U("USD"));
Contract contract = ContractUtil::option_contract(U("AAPL 230721C00185000"));

get_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)

说明

查询交易所需的单个合约信息

参数

参数名类型是否必填描述
symbolstrYes股票代码，如 'AAPL'
sec_typeSecurityTypeNo证券类型，tigerapi/enums.h SecurityType 枚举，默认为： SecurityType.STK
currencyCurrencyNo币种，tigerapi/enums.h Currency 枚举，如 Currency.USD
exchangestrNo交易所，非必填，如 'CBOE'
expirystrNo合约到期日（适用于期货/期权），格式 yyyyMMdd，如 ‘20220130’
strikefloatNo行权价（适用于期权）
put_callstrNo看涨看跌（适用于期权），'PUT' 看跌， 'CALL' 看涨

返回

合约对象, 参见对象介绍。常用属性如下

参数名类型描述
currencystr币种
symbolstr合约代码
exchangestr交易所
short_fee_ratefloat卖空参考利率
shortableint卖空池余额
long_initial_marginfloat做多初始保证金
long_maintenance_marginfloat做多维持保证金
short_initial_marginfloat做空初始保证金比例
short_maintenance_marginfloat做空维持保证金比例（综合账号有值，环球账号合约没有值）
is_etfbool是否是ETF
etf_leverageintETF杠杆倍数，仅当合约为ETF时会存在该值

示例

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

    config.private_key = "xxxxxx your private key string xxxxxxxx";
    config.tiger_id = "your tiger id";
    config.account = "your account";



    /**
     * 使用封装后的交易接口 TradeClient
     */
    std::shared_ptr<TradeClient> trade_client = std::make_shared<TradeClient>(config);
    TestTradeClient::test_trade(trade_client);


    return 0;
}

返回示例

{
    "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 获取多个合约信息

TradeClient.get_contracts(symbol, sec_type=SecurityType.STK, currency=None, exchange=None):

说明

查询交易所需的多个合约信息，以列表的形式返回

参数

参数名类型是否必填描述
symbolstrYes股票代码，如 'AAPL'。单次请求上限为50
sec_typeSecurityTypeNo证券类型，tigerapi/enums.h SecurityType 枚举，默认为：SecurityType.STK
currencyCurrencyNo币种，tigerapi/enums.h Currency 枚举，如 Currency.USD
exchangestrNo交易所，非必填，如 'CBOE'

返回

参见对象介绍。常用属性如下

参数名类型描述
currencystr币种
symbolstr合约代码
exchangestr交易所
short_fee_ratefloat卖空参考利率
shortableint卖空池余额
short_marginfloat卖空保证金
long_initial_marginfloat做多初始保证金
long_maintenance_marginfloat做多维持保证金

示例

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

本地生成合约对象

股票：

Contract contract = ContractUtil::stock_contract(U("AAPL"), U("USD"));

期权

Contract contract = ContractUtil::option_contract(U("AAPL"), U("20230721"), U("185.0"), U("PUT"), U("USD"));
Contract contract = ContractUtil::option_contract(U("AAPL 230721C00185000"));

期货

Contract contract = ContractUtil::future_contract(U("NG2308"), U("USD"));

get_quote_contract

获取期权/窝轮/牛熊证合约列表

输入参数：

参数类型是否必填描述
symbolsstrYes股票代码列表，仅支持一个symbol
sec_typeSecurityTypeYes合约类型 目前支持: (OPT 期权/ WAR 港股窝轮/ IOPT 港股牛熊证)
expirystr到期日(yyyyMMdd), 如果是OPT必须有值. 如 '20220929'
langstrNo语言支持: zh_CN,zh_TW,en_US, 默认: en_US

返回结果：list

列表中每一项为合约对象（tigeropen.trade.domain.contract.Contract），参见对象介绍。常用属性如下

名称类型说明
symbolstring股票代码
namestring合约名称
exchangestring交易所
marketstring市场
sec_typestring合约类型
currencystring币种
expirystring到期日(期权、窝轮、牛熊证、期货)， 如 20171117
rightstring期权方向(期权、窝轮、牛熊证), PUT/CALL
strikefloat行权价
multiplierfloat每手数量(期权、窝轮、牛熊证、期货)

请求示例:

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

响应示例：

[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]
上次编辑于: