获取合约
大约 10 分钟
合约介绍
合约是指交易的买卖对象或者标的物（比如一只股票或一只期权），合约是由交易所统一制定的。比如购买老虎证券的股票，可以通过TIGR这个字母代号和市场信息（即market=’US‘，美国市场）来唯一标识。类似的，在购买期权或者期货产品时，可能会需要用到其他一些标识字段。
通过合约信息，我们在下单或者获取行情时就可以唯一的确定一个标的物。
常见的合约包括股票合约，期权合约，期货合约等。
大部分合约包括如下几个要素:
- 标的代码(symbol)，一般美股、英股等合约代码都是英文字母，港股、A股等合约代码是数字，比如老虎证券的symbol是TIGR。
- 合约类型(security type)，常见合约类型包括：STK（股票），OPT（期权），FUT（期货），CASH（外汇），比如老虎证券股票的合约类型是STK。
- 货币类型(currency)，常见货币包括 USD（美元），HKD（港币）。
- 交易所(exchange)，STK类型的合约一般不会用到交易所字段，订单会自动路由，期货合约都用到交易所字段。
绝大多数股票，差价合约，指数或外汇对可以通过这四个属性来唯一确定。
由于其性质，更复杂的合约（如期权和期货）需要一些额外的信息。
以下是几种常见类型合约，以及其由哪些要素构成。
股票
ContractItem contract = new ContractItem();
contract.symbol ="TIGR";
contract.secType ="STK";
contract.currency ="USD"; //非必填，下单时默认为USD
contract.market = "US"; //非必填，合约市场，包括US（美国市场），HK（香港市场），CN（国内市场）等。下单时默认为US
期权
老虎API的期权合约支持两种方式：
一种是四要素方式，即symbol（股票代码），expiry（期权过期日），strike（期权行权价格），right（期权方向）。
另一种是标准OCC期权合约格式，长度固定为21位。包含四部分：
- 相关的股票或ETP的代码，比如（AAPL），固定占六位字符，不足位数由空格填充
- 期权到期日，6位数字，格式为：yymmdd
- 期权类型，取值为 P 或者 C, 表示 put 或 call
- 期权行权价格，取值为 价格 x 1000, 固定占8位数字，前面不足的位数由0填充
get_contract 获取单个合约信息
TradeClient.get_contract(symbol, sec_type=SecurityType.STK, currency=None, exchange=None, expiry=None, strike=None, put_call=None)
说明
查询交易所需的单个合约信息
参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| symbol | str | Yes | 股票代码，如 'AAPL' |
| sec_type | SecurityType | No | 证券类型，tigeropen.common.consts.SecurityType 枚举，默认为： SecurityType.STK |
| currency | Currency | No | 币种，tigeropen.common.consts.Currency 枚举，如 Currency.USD |
| exchange | str | No | 交易所，非必填，如 'CBOE' |
| expiry | str | No | 合约到期日（适用于期货/期权），格式 yyyyMMdd，如 ‘20220130’ |
| strike | float | No | 行权价（适用于期权） |
| put_call | str | No | 看涨看跌（适用于期权），'PUT' 看跌， 'CALL' 看涨 |
返回
tigeropen.trade.domain.contract.Contract 合约对象, 参见对象介绍。常用属性如下
对象属性
| 属性名 | 类型 | 描述 |
|---|---|---|
| identifier | str | 唯一标识，股票identifier和symbol相同，期权为21位标识符，如：'AAPL 220729C00150000'，期货identifier |
| symbol | str | 股票代码，期权合约的symbol为对应标的物代码 |
| sec_type | str | STK 股票/OPT 期权/FUT 期货/WAR 窝轮/IOPT 牛熊证等，默认 STK |
| name | str | 合约名称 |
| currency | str | 币种，USD/HKD/CNH |
| exchange | str | 交易所 |
| expiry | str | 期权和期货专有，期权或期货过期日 |
| strike | float | 期权专有，期权的行权价格 |
| multiplier | float | 每手数量 |
| put_call | str | 期权专有，期权方向，CALL 或者 PUT |
| local_symbol | str | 环球账户专有，港股用于识别窝轮和牛熊证 |
| short_margin | float | 做空保证金比例(将废弃，请使用short_initial_margin代替) |
| short_initial_margin | float | 做空初始保证金比例 |
| short_maintenance_margin | float | 做空维持保证金比例（综合账号有值，环球账号合约没有值） |
| short_fee_rate | float | 做空费率 |
| shortable | bool | 是否可做空 |
| shortable_count | int | 做空池剩余 |
| long_initial_margin | float | 做多初始保证金 |
| long_maintenance_margin | float | 做多维持保证金 |
| contract_month | str | 合约月份， 如202201，表示2022年1月 |
| primary_exchange | str | 股票上市交易所 |
| marginable | bool | 是否可融资 |
| market | str | 市场 /US/HK/CN |
| min_tick | float | 最小报价单位 |
| tickSizes | [{"begin":"0","end":"1","tickSize":1.0E-4,"type":"CLOSED"},{"begin":"1","end":"Infinity","tickSize":0.01,"type":"OPEN"}] | 股票专有，最小报价单位价格区间，即当挂单价格在begin和end区间时，要满足tickSize要求，begin：价格左区间，end：价格右区间，type：区间类型 OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN(开区间/左开右闭/闭区间/左闭右开)，tickSize：最小价格单位 |
| trading_class | str | 合约的交易级别名称 |
| close_only | bool | 是否只可平仓 |
| status | str | 合约状态 |
| continuous | bool | 期货专有，是否为连续合约 |
| trade | bool | 是否可交易 |
| last_trading_date | str | 期货专有，最后交易日，如 '20211220'，表示2021年12月20日 |
| first_notice_date | str | 期货专有，第一通知日，合约在第一通知日后无法开多仓. 已有的多仓会在第一通知日之前（通常为前三个交易日）被强制平仓，如 '20211222'，表示2021年12月22日 |
| last_bidding_close_time | int | 期货专有，竞价截止时间戳 |
| is_etf | bool | 是否是ETF |
| etf_leverage | int | ETF杠杆倍数，仅当合约为ETF时会存在该值 |
| discounted_day_initial_margin | 3069.0 | 期货专有，日内优惠初始保证金比例 |
| discounted_day_maintenance_margin | 2790.0 | 期货专有，日内优惠维持保证金比例 |
| discounted_time_zone_code | CDT | 期货专有，日内优惠时间时区 |
| discounted_start_at | 17:30:00 | 期货专有，日内优惠开始时间 |
| discounted_end_at | 14:30:00 | 期货专有，日内优惠结束时间 |
注意: print时只会显示部分属性, 可以用 print(contract.to_str()) 打印全部属性
示例
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import get_client_config
client_config = get_client_config(private_key_path='私钥路径', tiger_id='your tiger id', account='your account', secret_key='机构交易员专有密钥')
trade_client = TradeClient(client_config)
# Stock
contract = trade_client.get_contract('AAPL', sec_type=SecurityType.STK)
# Future
# contract = trade_client.get_contract('ES2306', sec_type=SecurityType.STK)
print(contract)
# 默认只打印 合约symbol/合约类型/合约币种. 使用 to_str 打印全部属性. 更多属性查看请直接指定属性名称， 如 contract.short_margin
print(contract.to_str())
# 查看做空初始保证金
print(contract.short_initial_margin)
返回示例
{'contract_id': None, 'symbol': 'ES2306', 'currency': 'USD', 'sec_type': 'FUT', 'exchange': None, 'origin_symbol': None,
'local_symbol': 'ES2306', 'expiry': None, 'strike': None, 'put_call': None, 'multiplier': 1.0, 'name': 'SP500 Index 2306',
'short_margin': 12320.0, 'short_initial_margin': 12320.0, 'short_maintenance_margin': 11200.0, 'short_fee_rate': None,
'shortable': None, 'shortable_count': None, 'long_initial_margin': 12320.0, 'long_maintenance_margin': 11200.0,
'contract_month': None, 'identifier': 'ES2306', 'primary_exchange': None, 'market': 'US', 'min_tick': None,
'tick_sizes': [{'begin': '0', 'end': 'Infinity', 'type': 'CLOSED_OPEN', 'tick_size': 0.25}], 'trading_class': 'ES2306',
'status': 1, 'marginable': True, 'trade': True, 'close_only': False, 'continuous': None, 'last_trading_date': None,
'first_notice_date': None, 'last_bidding_close_time': None, 'is_etf': False, 'etf_leverage': None, 'discounted_day_initial_margin': 10472.0, 'discounted_day_maintenance_margin': 9520.0, 'discounted_time_zone_code': 'CDT', 'discounted_start_at': '17:30:00', 'discounted_end_at': '15:00:00'}
get_contracts 获取多个合约信息
TradeClient.get_contracts(symbol, sec_type=SecurityType.STK, currency=None, exchange=None):
说明
查询交易所需的多个合约信息，以列表的形式返回
参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| symbol | str | Yes | 股票代码，如 'AAPL'。单次请求上限为50 |
| sec_type | SecurityType | No | 证券类型，tigeropen.common.consts.SecurityType 枚举，默认为：SecurityType.STK |
| currency | Currency | No | 币种，tigeropen.common.consts.Currency 枚举，如 Currency.USD |
| exchange | str | No | 交易所，非必填，如 'CBOE' |
返回
list
列表中每一项为合约对象（tigeropen.trade.domain.contract.Contract），参见对象介绍。常用属性如下
对象属性
| 属性名 | 类型 | 描述 |
|---|---|---|
| identifier | str | 唯一标识，股票identifier和symbol相同，期权为21位标识符，如：'AAPL 220729C00150000'，期货identifier |
| symbol | str | 股票代码，期权合约的symbol为对应标的物代码 |
| sec_type | str | STK 股票/OPT 期权/FUT 期货/WAR 窝轮/IOPT 牛熊证等，默认 STK |
| name | str | 合约名称 |
| currency | str | 币种，USD/HKD/CNH |
| exchange | str | 交易所 |
| expiry | str | 期权和期货专有，期权或期货过期日 |
| strike | float | 期权专有，期权的行权价格 |
| multiplier | float | 每手数量 |
| put_call | str | 期权专有，期权方向，CALL 或者 PUT |
| local_symbol | str | 环球账户专有，港股用于识别窝轮和牛熊证 |
| short_margin | float | 做空保证金比例(将废弃，请使用short_initial_margin代替) |
| short_initial_margin | float | 做空初始保证金比例 |
| short_maintenance_margin | float | 做空维持保证金比例（综合账号有值，环球账号合约没有值） |
| short_fee_rate | float | 做空费率 |
| shortable | int | 做空池剩余 |
| long_initial_margin | float | 做多初始保证金 |
| long_maintenance_margin | float | 做多维持保证金 |
| contract_month | str | 合约月份， 如202201，表示2022年1月 |
| primary_exchange | str | 股票上市交易所 |
| market | str | 市场 /US/HK/CN |
| min_tick | float | 最小报价单位 |
| tickSizes | [{"begin":"0","end":"1","tickSize":1.0E-4,"type":"CLOSED"},{"begin":"1","end":"Infinity","tickSize":0.01,"type":"OPEN"}] | 股票专有，最小报价单位价格区间，即当挂单价格在begin和end区间时，要满足tickSize要求，begin：价格左区间，end：价格右区间，type：区间类型 OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN(开区间/左开右闭/闭区间/左闭右开)，tickSize：最小价格单位 |
| trading_class | str | 合约的交易级别名称 |
| status | str | 合约状态 |
| continuous | bool | 期货专有，是否为连续合约 |
| trade | bool | 期货专有，是否可交易 |
| last_trading_date | str | 期货专有，最后交易日，如 '20211220'，表示2021年12月20日 |
| first_notice_date | str | 期货专有，第一通知日，合约在第一通知日后无法开多仓. 已有的多仓会在第一通知日之前（通常为前三个交易日）被强制平仓，如 '20211222'，表示2021年12月22日 |
| last_bidding_close_time | int | 期货专有，竞价截止时间戳 |
| is_etf | bool | 是否是ETF |
| etf_leverage | int | ETF杠杆倍数，仅当合约为ETF时会存在该值 |
| discounted_day_initial_margin | float | Futures only, Intraday initial margin discount |
| discounted_day_maintenance_margin | float | Futures only, Intraday maintenance margin discount |
| discounted_time_zone_code | float | Futures only, Intraday margin discount period time zone |
| discounted_start_at | float | Futures only, Intraday margin discount start time |
| discounted_end_at | float | Futures only, Intraday margin discount end time |
注意: print时只会显示部分属性, 可以用 print(contract.to_str()) 打印全部属性
示例
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import get_client_config
client_config = get_client_config(private_key_path='私钥路径', tiger_id='your tiger id', account='your account', secret_key='机构交易员专有密钥')
trade_client = TradeClient(client_config)
contracts = trade_client.get_contracts('AAPL', sec_type=SecurityType.STK)
print(contracts)
print(contract[0].to_str())
返回示例
[AAPL/STK/USD, JD/STK/USD]
{'contract_id': None, 'symbol': 'AAPL', 'currency': 'USD', 'sec_type': 'STK', 'exchange': None, 'origin_symbol': None, 'local_symbol': 'AAPL', 'expiry': None, 'strike': None, 'put_call': None, 'multiplier': 1.0, 'name': '苹果', 'short_margin': 0.4, 'short_initial_margin': 0.4, 'short_maintenance_margin': 0.4, 'short_fee_rate': 3.25, 'shortable': 0, 'shortable_count': 0, 'long_initial_margin': 0.3, 'long_maintenance_margin': 0.4, 'contract_month': None, 'identifier': 'AAPL', 'primary_exchange': None, 'market': 'US', 'min_tick': None, 'tick_sizes': [{'begin': '0', 'end': '1', 'type': 'CLOSED', 'tick_size': 0.0001}, {'begin': '1', 'end': 'Infinity', 'type': 'OPEN', 'tick_size': 0.01}], 'trading_class': 'AAPL', 'status': 1, 'marginable': True, 'trade': True, 'close_only': False, 'continuous': None, 'last_trading_date': None, 'first_notice_date': None, 'last_bidding_close_time': None, 'is_etf': False, 'etf_leverage': None}
本地生成合约对象
股票：
from tigeropen.common.util.contract_utils import stock_contract
contract = stock_contract(symbol='TIGR', currency='USD')
期权
from tigeropen.common.util.contract_utils import option_contract, option_contract_by_symbol
contract = option_contract(identifier='AAPL 190118P00160000')
# 或
contract = option_contract_by_symbol('AAPL', '20200110', strike=280.0, put_call='PUT', currency='USD')
# 期权代码和四要素之间相互转换
from tigeropen.common.util.contract_utils import extract_option_info, get_option_identifier
# 利用四要素组成期权代码 underlying_symbol='AAPL, expiry='20200110', put_call='PUT', strike=280
identifier = get_option_identifier(underlying_symbol, expiry, put_call, strike)
# 从期权代码解析四要素 identifier='AAPL 190118P00160000'
symbol, expiry, put_call, strike = extract_option_info(identifier)
期货
# 综合/模拟
from tigeropen.common.util.contract_utils import future_contract
contract = future_contract(symbol='CL2312', currency='USD')
# 环球
from tigeropen.common.util.contract_utils import future_contract
contract = future_contract(symbol='CL', currency='USD', expiry='20190328', multiplier=1.0, exchange='SGX')
港股窝轮
from tigeropen.common.util.contract_utils import war_contract_by_symbol
contract = war_contract_by_symbol('01810', '20221116', 14.52, 'CALL', local_symbol='14759', multiplier=2000,
currency='HKD')
港股牛熊证
from tigeropen.common.util.contract_utils import iopt_contract_by_symbol
contract = iopt_contract_by_symbol('02318', '20200420', 87.4, 'CALL', local_symbol='63379', currency='HKD')
get_derivative_contracts 获取期权/窝轮/牛熊证合约列表
输入参数：
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| symbols | str | Yes | 股票代码列表，仅支持一个symbol |
| sec_type | SecurityType | Yes | 合约类型 目前支持: (OPT 期权/ WAR 港股窝轮/ IOPT 港股牛熊证) |
| expiry | str | 到期日(yyyyMMdd), 如果是OPT必须有值. 如 '20220929' | |
| lang | str | No | 语言支持: zh_CN,zh_TW,en_US, 默认: en_US |
返回结果：list
列表中每一项为合约对象（tigeropen.trade.domain.contract.Contract），参见对象介绍。常用属性如下
| 名称 | 类型 | 说明 |
|---|---|---|
| symbol | string | 股票代码 |
| name | string | 合约名称 |
| exchange | string | 交易所 |
| market | string | 市场 |
| sec_type | string | 合约类型 |
| currency | string | 币种 |
| expiry | string | 到期日(期权、窝轮、牛熊证、期货)， 如 20171117 |
| right | string | 期权方向(期权、窝轮、牛熊证), PUT/CALL |
| strike | float | 行权价 |
| multiplier | float | 每手数量(期权、窝轮、牛熊证、期货) |
请求示例:
from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import get_client_config
client_config = get_client_config(private_key_path='私钥路径', tiger_id='your tiger id', account='your account', secret_key='机构交易员专有密钥')
trade_client = TradeClient(client_config)
contracts = trade_client.get_derivative_contracts('00700', SecurityType.WAR, '20220929')
print(contracts)
响应示例：
[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]