获取合约

初始化

本页所有示例均假设已完成以下初始化:

from tigeropen.trade.trade_client import TradeClient
from tigeropen.tiger_open_config import TigerOpenClientConfig

client_config = TigerOpenClientConfig(props_path='/path/to/tiger_openapi_config.properties')
trade_client = TradeClient(client_config)

详见准备工作


合约介绍

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

大多数合约(如:股票,差价合约,指数或外汇)可通过以下四个基础属性唯一确定:

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

还有一些合约(如:期权和期货)由于其性质更复杂,需要一些额外的信息才能唯一标识。

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

股票

contract = Contract()
contract.symbol ="TIGR"
contract.sec_type ="STK"
contract.currency ="USD" #not required
contract.market = "US" #not required

期权

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

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

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

    • 相关的股票或ETF的代码,比如(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)

说明

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

参数

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

返回

tigeropen.trade.domain.contract.Contract 合约对象, 参见对象介绍。常用属性如下

对象属性

属性名类型描述
identifierstr唯一标识,股票identifier和symbol相同,期权为21位标识符,如:'AAPL 220729C00150000',期货identifier
symbolstr股票代码,期权合约的symbol为对应标的物代码
sec_typestrSTK 股票/OPT 期权/FUT 期货/WAR 窝轮/IOPT 牛熊证等,默认 STK
namestr合约名称
currencystr币种,如:USD/HKD/CNH
exchangestr交易所
expirystr期权和期货专有,期权或期货过期日
strikefloat期权专有,期权的行权价格
multiplierfloat乘数,每手对应的数量
put_callstr期权专有,期权方向,CALL 或者 PUT
local_symbolstr环球账户专有,港股用于识别窝轮和牛熊证
short_marginfloat做空保证金比例(将废弃,请使用short_initial_margin代替)
short_initial_marginfloat做空初始保证金比例,取值范围 (0, 1],如 0.35 表示 35% 的初始保证金要求
short_maintenance_marginfloat做空维持保证金比例,取值范围 (0, 1],通常小于 short_initial_margin。综合/模拟账户有值,环球账户合约无此值。
short_fee_ratefloat融券做空年化费率,如 0.03 表示 3%
shortablebool做空池当前是否有可借出份额(shortable_count > 0 时为 True)。仅表示市场上有库存,不代表账户具备做空权限;账户是否可做空还需结合账户类型和合规限制。
shortable_countint做空池剩余可借出数量(股数),为 0 表示当前市场无可借额度
long_initial_marginfloat做多初始保证金比例,取值范围 (0, 1],如 0.3 表示 30% 的初始保证金要求
long_maintenance_marginfloat做多维持保证金比例,取值范围 (0, 1],通常小于 long_initial_margin
contract_monthstr合约月份, 如202201,表示2022年1月
primary_exchangestr股票上市交易所
marginablebool是否可融资
marketstr市场,如:US/HK/CN
min_tickfloat最小报价单位。对于期货合约有固定值;对于股票合约,最小报价单位随价格区间变化,该字段可能为 None,应优先使用 tick_sizes 字段获取完整的分段配置。
tick_sizeslist分段最小报价单位列表,每项包含:begin(价格区间左端)、end(价格区间右端,"Infinity" 表示无上限)、type(区间类型:OPEN 开区间 / CLOSED 闭区间 / OPEN_CLOSED 左开右闭 / CLOSED_OPEN 左闭右开)、tick_size(该区间内的最小价格变动单位)。下单价格必须是对应 tick_size 的整数倍。
trading_classstr合约的交易级别名称
close_onlybool是否只可平仓
statusint合约交易状态,0 不可交易,1 可交易。注意该字段实际为整型而非字符串。
continuousbool期货专有,是否为连续合约
tradebool期货专有,期货合约是否当前可交易。False 表示该合约已停止交易(如到期)。对于非期货合约可使用 status 字段判断。
last_trading_datestr期货专有,最后交易日,如 '20211220',表示2021年12月20日
first_notice_datestr期货专有,第一通知日,合约在第一通知日后无法开多仓. 已有的多仓会在第一通知日之前(通常为前三个交易日)被强制平仓,如 '20211222',表示2021年12月22日
last_bidding_close_timeint期货专有,竞价截止时间戳
is_etfbool是否是ETF
etf_leverageintETF杠杆倍数,仅当合约为ETF时会存在该值
discounted_day_initial_marginfloat期货专有,日内优惠初始保证金比例
discounted_day_maintenance_marginfloat期货专有,日内优惠维持保证金比例
discounted_time_zone_codefloat期货专有,日内优惠时间时区
discounted_start_atfloat期货专有,日内优惠开始时间
discounted_end_atfloat期货专有,日内优惠结束时间
lot_sizefloat一手(lot)对应的股数,如港股一手为 100 股,美股一手为 1 股,A 股一手为 100 股。下单数量通常需要是该值的整数倍(碎股交易除外)。
support_overnight_tradingbool是否支持夜盘交易
support_fractional_sharebool是否支持碎股交易(仅使用综合/模拟账户),港股碎股最小是1股,美股碎股订单价值最小为1USD,碎股的精度是到0.0001
📘

提示

print时只会显示部分属性,可以用 print(contract.to_str()) 打印全部属性

示例

from tigeropen.common.consts import SecurityType


# Stock
contract = trade_client.get_contract('AAPL', sec_type=SecurityType.STK)
# Future
# contract = trade_client.get_contract('ES2306', sec_type=SecurityType.FUT)
print(contract)
# 默认只打印 合约symbol/合约类型/合约币种. 使用 to_str 打印全部属性. 更多属性查看请直接指定属性名称, 如 contract.short_margin
print(contract.to_str())

# 查看做空初始保证金
print(contract.short_initial_margin)

返回示例

{'contract_id': 1916, '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.35, 'short_initial_margin': 0.35, 'short_maintenance_margin': 0.3, 'short_fee_rate': None, 
'shortable': True, 'shortable_count': None, 'long_initial_margin': 0.3, 'long_maintenance_margin': 0.25, 
'contract_month': None, 'identifier': 'AAPL', 'primary_exchange': 'NASDAQ', '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, 'discounted_day_initial_margin': None, 
'discounted_day_maintenance_margin': None, 'discounted_time_zone_code': None, 'discounted_start_at': None, 
'discounted_end_at': None, 'categories': None, 'lot_size': 1.0, 'support_overnight_trading': True}

get_contracts 获取多个合约信息

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

说明

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

参数

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

返回

list

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

对象属性

属性名描述
identifier唯一标识,股票identifier和symbol相同,期权为21位标识符,如:'AAPL 220729C00150000',期货identifier
symbol股票代码,期权合约的symbol为对应标的物代码
sec_typeSTK 股票/OPT 期权/FUT 期货/WAR 窝轮/IOPT 牛熊证等,默认 STK
name合约名称
currency币种,如:USD/HKD/CNH
exchange交易所
expiry期权和期货专有,期权或期货过期日
strike期权专有,期权的行权价格
multiplier乘数,每手对应的数量
put_call期权专有,期权方向,CALL 或者 PUT
local_symbol环球账户专有,港股用于识别窝轮和牛熊证
short_margin做空保证金比例(将废弃,请使用short_initial_margin代替)
short_initial_margin做空初始保证金比例,取值范围 (0, 1],如 0.35 表示 35% 的初始保证金要求
short_maintenance_margin做空维持保证金比例,取值范围 (0, 1],通常小于 short_initial_margin。综合/模拟账户有值,环球账户合约无此值。
short_fee_rate融券做空年化费率,如 0.03 表示 3%
shortable做空池当前是否有可借出份额(shortable_count > 0 时为 True)。仅表示市场上有库存,不代表账户具备做空权限;账户是否可做空还需结合账户类型和合规限制。
long_initial_margin做多初始保证金比例,取值范围 (0, 1],如 0.3 表示 30% 的初始保证金要求
long_maintenance_margin做多维持保证金比例,取值范围 (0, 1],通常小于 long_initial_margin
contract_month合约月份, 如:202201,表示2022年1月
primary_exchange股票上市交易所
market市场 如:US/HK/CN
min_tick最小报价单位。对于期货合约有固定值;对于股票合约,最小报价单位随价格区间变化,该字段可能为 None,应优先使用 tick_sizes 字段获取完整的分段配置。
tick_sizes分段最小报价单位列表,每项包含:begin(价格区间左端)、end(价格区间右端,"Infinity" 表示无上限)、type(区间类型:OPEN 开区间 / CLOSED 闭区间 / OPEN_CLOSED 左开右闭 / CLOSED_OPEN 左闭右开)、tick_size(该区间内的最小价格变动单位)。下单价格必须是对应 tick_size 的整数倍。
trading_class合约的交易级别名称
status合约交易状态,0 不可交易,1 可交易。注意该字段实际为整型而非字符串。
continuous期货专有,是否为连续合约
trade期货专有,期货合约是否当前可交易。False 表示该合约已停止交易(如到期)。对于非期货合约可使用 status 字段判断。
last_trading_date期货专有,最后交易日,如 '20211220',表示2021年12月20日
first_notice_date期货专有,第一通知日,合约在第一通知日后无法开多仓. 已有的多仓会在第一通知日之前(通常为前三个交易日)被强制平仓,如 :'20211222',表示2021年12月22日
last_bidding_close_time期货专有,竞价截止时间戳
is_etf是否是ETF
etf_leverageETF杠杆倍数,仅当合约为ETF时会存在该值
discounted_day_initial_margin期货专有,日内优惠初始保证金比例
discounted_day_maintenance_margin期货专有,日内优惠维持保证金比例
discounted_time_zone_code期货专有,日内优惠时间时区
discounted_start_at期货专有,日内优惠开始时间
discounted_end_at期货专有,日内优惠结束时间
lot_size一手(lot)对应的股数,如港股一手为 100 股,美股一手为 1 股,A 股一手为 100 股。下单数量通常需要是该值的整数倍(碎股交易除外)。
support_overnight_trading是否支持夜盘交易
support_fractional_share是否支持碎股交易
close_only是否只可平仓
marginable是否可融资
categories合约分类标签
underlying_contract_name底层资产合约名称
📘

提示

print时只会显示部分属性,可以用 print(contract.to_str()) 打印全部属性

示例

contracts = trade_client.get_contracts('AAPL', sec_type=SecurityType.STK)
print(contracts)
print(contracts[0].to_str())

返回示例

【
{'contract_id': 1916, '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': None, 'short_initial_margin': None, 'short_maintenance_margin': None, 'short_fee_rate': None, 
 'shortable': None, 'shortable_count': None, 'long_initial_margin': None, 'long_maintenance_margin': None, 
 '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': None, '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': None, 
 'discounted_day_maintenance_margin': None, 'discounted_time_zone_code': None, 'discounted_start_at': None, 
 'discounted_end_at': None, 'categories': None, 'lot_size': 1.0, 'support_overnight_trading': True}】

本地生成合约对象

股票

from tigeropen.common.util.contract_utils import stock_contract

# US 股票
contract = stock_contract(symbol='TIGR', currency='USD')

# HK 股票
contract = stock_contract(symbol='00700', currency='HKD')

#SG 股票
contract = stock_contract(symbol = '1A1.SI',currency = 'SGD')

#AU 股票
contract = stock_contract(symbol = 'MXT.AU', currency = 'AUD')

期权

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)
print(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')

# US 期货
contract = future_contract(symbol='RB', currency='USD', expiry='20250829', multiplier=1.0, exchange='NYMEX')

# HK 期货
contract = future_contract(symbol='2318', currency='HKD', expiry='20251230', multiplier=500.0, exchange='HKEX')

# SG 期货
contract = future_contract(symbol='SSG', currency='SGD', expiry='20250429', multiplier=100.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')

基金

#US 基金
contract = fund_contract('IE00B11XZ988.USD')

#HK 基金
contract = fund_contract('LU0476943708.HKD')

#SG 基金
contract = fund_contract('LU2023250843.SGD')

#AU 基金
contract = fund_contract('SG9999015184.AUD')

数字货币

from tigeropen.common.util.contract_utils import cc_contract

contract = cc_contract('BTC')


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

TradeClient.get_derivative_contracts(symbol, sec_type, expiry, lang=None)
输入参数:

参数类型是否必填描述
symbolstrYes股票代码列表,仅支持一个symbol
sec_typeSecurityTypeYes合约类型,目前支持: OPT 期权/ WAR 港股窝轮/ IOPT 港股牛熊证
expirystrYes到期日(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乘数,每手对应的数量 (期权、窝轮、牛熊证、期货)

请求示例:

contracts = trade_client.get_derivative_contracts('00700', SecurityType.WAR, '20220929')
print(contracts)

响应示例:

{
    "symbol": "29298",
    "name": "[email protected]",
    "exchange": "SEHK",
    "market": "HK",
    "sec_type": "WAR",
    "currency": "HKD",
    "expiry": "20250925",
    "strike": "500.5",
    "multiplier": 10000.0,
    "right": "CALL"
}, {
    "symbol": "29290",
    "name": "[email protected]",
    "exchange": "SEHK",
    "market": "HK",
    "sec_type": "WAR",
    "currency": "HKD",
    "expiry": "20250925",
    "strike": "500.5",
    "multiplier": 10000.0,
    "right": "CALL"
}