金融工具（合约）

概述

IBApi.Contract 对象表示交易工具，如股票、期货或期权。

每次需要合约的新请求（即市场数据、下单等）被发送到TWS时，平台都会尝试将提供的合约对象与单个候选对象进行匹配。如果有多个合约与同一描述匹配，TWS将返回错误，通知您存在歧义。在这些情况下，TWS需要进一步的信息，以将与所提供的描述相匹配的合约清单缩小到单个要素。

查找合约描述的最佳方法是在TWS本身内。在TWS中，您可以通过双击合约或通过合约信息->描述菜单轻松检查合约的描述，您可以通过右键单击TWS中的合约来访问该菜单：

然后将显示说明：

注意：您可以通过选择 合约信息 -> 详细信息来查看扩展的合约的详细信息。此选项将打开一个网页，显示合约上的所有可用信息。

每当通过TWS API提供合约描述时，TWS都会尝试将给定的描述与单个合约相匹配。这种机制具有很大的灵活性，因为它提供了以多种方式定义同一合约的可能性。

定义合约的最简单方法是提供其名称符号，证券类型，币种和交易所代码。绝大多数股票，差价合约，指数或外汇对都可以通过这四个属性进行唯一定义。更复杂的合约，如期权和期货，由于其性质，需要一些额外的信息。以下是不同类型工具的几个示例。

另请参阅：

• 请求合同详细信息

• 股票合约搜索

• 基本合同

• 传播

请求合同详细信息

IB数据库中有关合同的完整详细信息可以使用IBApi.EClient.reqContractDetails功能检索。这包括有关在IBApi.ContractDetails对象中返回的合约 conID、符号、本地符号、货币等的信息。reqContractDetails将一个合约对象作为参数，该对象可以唯一匹配一个合约，而与其他API函数不同，它也可以采用与IB数据库中的多个合约匹配的合约对象。当存在多个匹配项时，它们将分别返回到函数IBApi::EWrapper::contractDetails.

注意：使用具有currency = USD 的合约对象调用 reqContractDetails 只会返回美国合约，即使存在具有美元货币的非美国工具也是如此。

对债券详细信息的请求将返回到 IBApi::EWrapper::bondContractDetails。由于债券市场数据许可限制，债券合约描述中只有几个可用字段需要返回，即minTick、交易所和短名称。

IBApi::EClient::reqContractDetails函数的一个特殊用途是请求期权链。有关更多详细信息，请参阅期权链。

交易时间表 timeZoneId ：

IBApi::EClient::reqContractDetails 的另一个功能是通过TradingHours和LiquidHours字段请求工具的交易时间表。然后，相应的 timeZoneId 字段将指示工具交易时间表的时区。TWS 将这些 timeZoneId 字符串从计划响应按原样发送到 API，并且可能与 TWS 合约描述中显示的时区不完全匹配。

可能的 timeZoneId 值包括： Europe/Riga, Australia/NSW, Europe/Warsaw, US/Pacific, Europe/Tallinn, Japan, US/Eastern, GB-Eire, Africa/Johannesburg, Israel, Europe/Vilnius, MET, Europe/Helsinki, US/Central, Europe/Budapest, Asia/Calcutta, Hongkong, Europe/Moscow, GMT

广播新闻列表

下面的示例显示了一个"不完整"的新闻IBApi.contract，未定义符号或货币。在大多数情况下，使用这样的合约会导致无效的合约详细信息错误，因为需要符号或 localSymbol。IBApi.EClient.reqContractDetails将使用它从TWS获取整个BroadTape新闻链。

contract = Contract()
contract.secType = "NEWS"
contract.exchange = "BRFG" #Briefing Trader

self.reqContractDetails(10004, ContractSamples.NewsFeedForQuery())

所有返回的对象将通过IBApi.EWrapper.contractDetails 交付。一旦所有合约都已交付，IBApi.EWrapper.contractDetailsEnd标记将被触发以通知它。

 class TestWrapper(wrapper.EWrapper):
     def contractDetails(self, reqId: int, contractDetails: ContractDetails):
    	super().contractDetails(reqId, contractDetails)
    	printinstance(contractDetails)
     def contractDetailsEnd(self, reqId: int):
        super().contractDetailsEnd(reqId)
    	print("ContractDetailsEnd. ReqId:", reqId)

重要提示 ：由于此类查询可能产生大量数据，因此此请求会受到速度的影响。虽然上述请求将立即得到答复，但随后的类似请求将被搁置一分钟。如果执行更多此类请求，则此时间量将增加。为防止出现这种情况，请通过提供至少指定年份（即 2016 年）或年份和月份（即 2016 年 3 月的201603）的到期日期来缩小符合条件的合同数量。

股票合约搜索

从API v973.02和TWS v964开始，一个函数 IBApi::EClient::reqMatchingSymbols 可用于搜索股票合约。输入可以是股票代码的前几个字母，也可以是较长字符串的字符序列，与安全名称中的单词匹配。例如，要搜索股票代码"IBKR"，可以使用输入"I"或"IB"，以及’Interactive’.一词。最多返回 16 个匹配的结果。

• 在对 req 匹配符号的连续调用之间必须有至少 1 秒的间隔

 self.reqMatchingSymbols(211, "IB")

匹配的股票合约将返回到 IBApi::EWrapper::symbolSamples ，其中包含有关现有衍生品合约类型（权证、期权、荷兰权证、期货）的信息。

def symbolSamples(self, reqId: int,
                       contractDescriptions: ListOfContractDescription):
         super().symbolSamples(reqId, contractDescriptions)
         print("Symbol Samples. Request Id: ", reqId)
 
         for contractDescription in contractDescriptions:
             derivSecTypes = ""
             for derivSecType in contractDescription.derivativeSecTypes:
                 derivSecTypes += derivSecType
                 derivSecTypes += " "
             print("Contract: conId:%s, symbol:%s, secType:%s primExchange:%s, "
                   "currency:%s, derivativeSecTypes:%s" % (
                 contractDescription.contract.conId,
                 contractDescription.contract.symbol,
                 contractDescription.contract.secType,
                 contractDescription.contract.primaryExchange,
                 contractDescription.contract.currency, derivSecTypes))

Basic Contracts

FX Pairs

contract = Contract()contract.symbol = "EUR"contract.secType = "CASH"contract.currency = "GBP"contract.exchange = "IDEALPRO"

Cryptocurrency

contract = Contract();contract.symbol = "ETH";contract.secType = "CRYPTO";contract.currency = "USD";contract.exchange = "PAXOS";

Stocks

contract = Contract()contract.symbol = "IBKR"contract.secType = "STK"contract.currency = "USD"#In the API side, NASDAQ is always defined as ISLAND in the exchange fieldcontract.exchange = "ISLAND"

对于某些具有相同符号、货币和交易所的smart-routed股票合约，您还需要指定主要交易所属性来唯一定义合约。这应定义为合约的原生交易所，并且包括所有股票都这样定义是一个良好的习惯。

contract = Contract()contract.symbol = "MSFT"contract.secType = "STK"contract.currency = "USD"contract.exchange = "SMART"#Specify the Primary Exchange attribute to avoid contract ambiguity #(there is an ambiguity because there is also a MSFT contract with primary exchange = "AEB")contract.primaryExchange = "ISLAND"

为了请求市场数据，如果路由交换和主交换由有效的组件交换分隔符分隔，则可以在单个"交换"字段中指定路由交换和主交换，例如交换= “SMART：ARCA”。可用的默认分隔符是冒号"：“和斜杠”/"。可以使用 TWS 全局配置中 API -> 设置下定义的字段来定义其他组件交换分隔符。在 971 之前的 TWS 版本中，组件交换分隔符语法只能用于请求市场数据，而不能用于下订单。

Indexes

IB数据库中可用的指数的ISIN在TWS 965+的API中可用。

contract = Contract()contract.symbol = "DAX"contract.secType = "IND"contract.currency = "EUR"contract.exchange = "DTB"

CFDs

contract = Contract()contract.symbol = "IBDE30"contract.secType = "CFD"contract.currency = "EUR"contract.exchange = "SMART"

Futures

A regular futures contract is commonly defined using an expiry and the symbol field defined as the symbol of the underlying. Historical data for futures is available up to 2 years after they expire by setting the includeExpired flag within the Contract class to True.

contract = Contract()contract.symbol = "ES"contract.secType = "FUT"contract.exchange = "GLOBEX"contract.currency = "USD"contract.lastTradeDateOrContractMonth = "201903"

根据合约，"本地交易品种"字段是IB的期货交易品种（TWS"合约描述"对话框中的品种）。由于本地交易品种唯一定义了期货，因此不需要到期。

contract = Contract()contract.secType = "FUT"contract.exchange = "GLOBEX"contract.currency = "USD"contract.localSymbol = "ESU6"

有时，您可以期望同一标的物有多个具有相同到期日的期货合约。为了排除歧义，可以给出合约的乘数，如下所示：

contract = Contract()contract.symbol = "DAX"contract.secType = "FUT"contract.exchange = "DTB"contract.currency = "EUR"contract.lastTradeDateOrContractMonth = "201903"contract.multiplier = "5"

连续期货可从TWS v971及更高版本的 API 获得。连续期货不能与实时数据一起使用或下订单，而只能用于历史数据。

contract = Contract()contract.symbol = "ES"contract.secType = "CONTFUT"contract.exchange = "GLOBEX"

证券类型"FUT+CONTFUT"可用于请求有关标的资产期货和连续期货的合约详细信息。此证券类型不能与其他功能一起使用。

contract = Contract()contract.symbol = "ES"contract.secType = "FUT+CONTFUT"contract.exchange = "GLOBEX"

Options

期权，如同期货，也需要到期日，还需要加上行使价和乘数：

contract = Contract()contract.symbol = "GOOG"contract.secType = "OPT"contract.exchange = "BOX"contract.currency = "USD"contract.lastTradeDateOrContractMonth = "20190315"contract.strike = 1180contract.right = "C"contract.multiplier = "100"

发现许多期权合约具有几乎相同的描述（即基础品种，行使价，最后交易日，乘数等）并不罕见。添加更多详细信息（如**交易类）**将有助于：

contract = Contract()contract.symbol = "SANT"contract.secType = "OPT"contract.exchange = "MEFFRV"contract.currency = "EUR"contract.lastTradeDateOrContractMonth = "20190621"contract.strike = 7.5contract.right = "C"contract.multiplier = "100"contract.tradingClass = "SANEU"

OCC期权符号可用于通过期权的"本地交易品种"字段在API中定义期权合约。

contract = Contract()#Watch out for the spaces within the local symbol!contract.localSymbol = "C BMW  JUL 20  4800"contract.secType = "OPT"contract.exchange = "DTB"contract.currency = "EUR"

Futures Options

重要提示：在 972 之前的 TWS 版本中，如果定义具有使用行使价的价格放大镜的期货期权，则行使价将为 TWS 中显示的行使价除以价格放大镜。（例如，以美元显示，而不是ZW的美分）
在TWS版本972及更高版本中，执行价格将以相同的方式显示在TWS和API中（不应用价格放大镜）
对于某些期货期权（例如GE），有必要定义交易类别，或使用本地符号或conId。

contract = Contract()contract.symbol = "ES"contract.secType = "FOP"contract.exchange = "GLOBEX"contract.currency = "USD"contract.lastTradeDateOrContractMonth = "20190315"contract.strike = 2900contract.right = "C"contract.multiplier = "50"

Bonds

可以通过将符号定义为 CUSIP 或 ISIN 来指定绑定。

contract = Contract()# enter CUSIP as symbolcontract.symbol= "912828C57"contract.secType = "BOND"contract.exchange = "SMART"contract.currency = "USD"

债券也可以使用conId和交易所定义，也可以像任何证券类型一样。

contract = Contract()contract.conId = 15960357contract.exchange = "SMART"

Mutual Funds

API 目前未完全支持交易共同基金。注意：共同基金订单不能从任何交易系统的模拟账户中发出。

contract = Contract()contract.symbol = "VINIX"contract.secType = "FUND"contract.exchange = "FUNDSERV"contract.currency = "USD"

Commodities

contract = Contract()contract.symbol = "XAUUSD"contract.secType = "CMDTY"contract.exchange = "SMART"contract.currency = "USD"

Standard Warrants

权证与期权一样，需要到期日，权利，行使价和乘数。对于某些权证，有必要定义一个 localSymbol 或 conId 来唯一标识合约。

contract = Contract()contract.symbol = "GOOG"contract.secType = "WAR"contract.exchange = "FWB"contract.currency = "EUR"contract.lastTradeDateOrContractMonth = "20201117"contract.strike = 1500.0contract.right = "C"contract.multiplier = "0.01"

Dutch Warrants and Structured Products

• 要明确定义荷兰认股权证或结构性产品（IOPT），必须使用conId或localSymbol字段。

• 请务必注意，如果将 reqContractDetails 与未完全定义的 IOPT 协定定义一起使用，则可能会返回数千个结果并断开 API 连接。

• IOPT合约定义通常会发生变化，因此需要重新启动TWS或IB网关才能下载新的合约定义。

contract = Contract()contract.localSymbol = "B881G"contract.secType = "IOPT"contract.exchange = "SBF"contract.currency = "EUR"

Spreads

点差合约，也称为组合或组合，组合两个或多个工具。要定义组合合约，需要知道相关IBApi.Contract的 conId。品种的conId可以通过IBApi.EClientSocket.reqContractDetails请求轻松获得。

点差合约的符号可以是其中一个合约腿的符号，或者对于两条腿的组合，两条腿的符号可以用逗号分隔，如下面的示例所示。

Stock Spread

从TWS v971开始，当股票/股票组合在交易品种字段中使用时，它们将按字母顺序具有股票代码，例如"AMD，IBKR"。

contract = Contract()contract.symbol = "IBKR,MCD"contract.secType = "BAG"contract.currency = "USD"contract.exchange = "SMART"
 leg1 = ComboLeg()leg1.conId = 43645865#IBKR STKleg1.ratio = 1leg1.action = "BUY"leg1.exchange = "SMART"leg2 = ComboLeg()leg2.conId = 9408#MCD STKleg2.ratio = 1leg2.action = "SELL"leg2.exchange = "SMART"contract.comboLegs = []contract.comboLegs.append(leg1)contract.comboLegs.append(leg2)

**注意：**EFP被简单地定义为库存和相应SSF的袋子合约，比率为100：1。

Options Spread

contract = Contract()contract.symbol = "DBK"contract.secType = "BAG"contract.currency = "EUR"contract.exchange = "DTB"leg1 = ComboLeg()leg1.conId = 317960956 #DBK JUN 21 2019 Cleg1.ratio = 1leg1.action = "BUY"leg1.exchange = "DTB"
 leg2 = ComboLeg()leg2.conId = 334216780  #DBK MAR 15 2019 Cleg2.ratio = 1leg2.action = "SELL"leg2.exchange = "DTB"
 contract.comboLegs = []contract.comboLegs.append(leg1)contract.comboLegs.append(leg2)

Guaranteed Futures Spread

contract = Contract()contract.symbol = "VIX"contract.secType = "BAG"contract.currency = "USD"contract.exchange = "CFE"
 leg1 = ComboLeg()leg1.conId = 326501438 # VIX FUT 201903leg1.ratio = 1leg1.action = "BUY"leg1.exchange = "CFE"
 leg2 = ComboLeg()leg2.conId = 323072528 # VIX FUT 2019049leg2.ratio = 1leg2.action = "SELL"leg2.exchange = "CFE"
 contract.comboLegs = []contract.comboLegs.append(leg1)contract.comboLegs.append(leg2)

Smart-Routed Futures Spread

期货点差也可以定义为 Smart-routed（非保证）组合。从 API 为非保证组合下订单时，非保证标志必须设置为 1。 Smart-routed期货点差的历史数据通常可从API获得，并具有必要的市场数据订阅。

contract = Contract()contract.symbol = "WTI" # WTI,COIL spread. Symbol can be defined as first leg symbol ("WTI") or currency ("USD")contract.secType = "BAG"contract.currency = "USD"contract.exchange = "SMART"leg1 = ComboLeg()leg1.conId = 55928698 # WTI future June 2017leg1.ratio = 1leg1.action = "BUY"leg1.exchange = "IPE"leg2 = ComboLeg()leg2.conId = 55850663 # COIL future June 2017leg2.ratio = 1leg2.action = "SELL"leg2.exchange = "IPE"
 contract.comboLegs = []contract.comboLegs.append(leg1)contract.comboLegs.append(leg2)

Inter-Commodity Futures

对于商品间期货，TWS中的"本地品种"字段用于API合约定义中的"交易品种"字段，例如"CL.BZ"。它们始终是有保证的组合，这是 API 中的默认值。

contract = Contract()contract.symbol = "CL.BZ" #symbol is 'local symbol' of intercommodity spread. contract.secType = "BAG"contract.currency = "USD"contract.exchange = "NYMEX"leg1 = ComboLeg()leg1.conId = 47207310 #CL Dec'16 @NYMEXleg1.ratio = 1leg1.action = "BUY"leg1.exchange = "NYMEX"leg2 = ComboLeg()leg2.conId = 47195961 #BZ Dec'16 @NYMEXleg2.ratio = 1leg2.action = "SELL"leg2.exchange = "NYMEX"
 contract.comboLegs = []contract.comboLegs.append(leg1)contract.comboLegs.append(leg2)

请注意，交易所直接提供商品间价差，因此尽管腿有不同的基础，但它们是直接路由的。通过API仅为商品间价差合约提供实时数据，而不是历史数据。

在许多情况下，也有可能在商品间价差中创建相同期货合约的价差，这是Smart-routed和非保证的。此点差的历史数据通常可从 API 获得。此外，过期点差合约的历史数据在TWS或API中不可用。

TWS API相关的教程

【TWS API使用教程1】—如何在自己创建的client和TWS之间创建一个连接，并请求当前的时间
【TWS API使用教程2】—如何使用 TWS API在ubuntu和windows上分别设置contract、获取contract详细信息、设置order、下单、获取持仓信息、获取账户信息
【TWS API使用教程3】—如何使用TWS API从盈透证券中设置contract及获取contract的信息？
【TWS API使用教程4】—如何使用TWS API在盈透证券中设置order？
【TWS API使用教程5】—如何使用TWS API在盈透证券中下单(place order)、获取订单信息、获取持仓、获取账户汇总信息?
【TWS API使用教程6】—如何使用TWS API在盈透证券中获取数据?
【TWS API 使用教程7】如何使用TWS API 从盈透证券中筛选满足一定条件的contract？
【TWS API 使用教程8】一个基于TWS API的简单的程序化策略