Event Contracts in the Web API

Interactive Brokers models Event Contract instruments on options (for ForecastEx products) and futures options (for CME Group products).
Event Contracts can generally be treated as options products in the Web API, and most existing features and workflows will serve these instruments unaltered.
This guide will frequently make analogies to conventional index options for both ForecastEx and CME Group products.

IB’s Event Contract instrument records use the following fields inherited from the options model:

• An underlying reference index, which may or may not be artificial:
  • For CME products, a tradable Event Contract will have the relevant CME index as its underlier.
  • For ForecastEx products, IB has generated an artificial underlying index which serves as a container for related Event Contracts in the same product class. These artificial indices do not have any associated reference values and are purely an artifact of the option instrument model used to represent these Event Contracts. However, these artificial underlying indices can be used to search for groups of related Event Contracts, just as with index options.
• A Symbol value which matches the symbol of the underlying index and which reflects the issuer’s product code for the instrument and points to the underlying index that
• A Trading Class which reflects the issuer’s product code for the instrument and serves as human-readable identifier for a group of related Event Contracts.
  • Note that many CME Group Event Contracts, which resolve against CME Group indices, have product codes prefixed with “EC” and followed by the symbol of the relevant exchange, to avoid naming collisions with other derivatives on the same index.
• A Put or Call (Right) value, where Call = Yes and Put = No.
  • Note that ForecastEx instruments do not permit Sell orders. Instead, ForecastEx positions are flattened or reduced by buying the opposing contract. CME Group Event Contracts permit both buying and selling.
• An artificial Contract Month value, again used primarily for searching and filtering available instruments. Most Event Contract products do not follow monthly series as is common with index or equity options, so these Contract Month values are typically not a meaningful attribute of the instrument. Rather, they permit filtering of instruments by calendar month.
• A Last Trade Date, Time, and Millisecond values, which together indicate precisely when trading in an Event Contract will cease, just as with index options.
• A Strike value, which is the numerical value on which the event resolution hinges. Though numerical, this value need not represent a price.
• An instrument description (or “local symbol”) in the form "PRODUCT EXPIRATION STRIKE RIGHT", where:
  • PRODUCT is the issuer’s product identifier
  • EXPIRATION is the date of the instrument’s resolution in the form MmmDD'YY, e.g., “Sep26’24”
  • STRIKE is the numerical value that determines the contract’s moneyness at expiration
  • RIGHT is a value YES or NO

The Web API requires the use of IB’s contract ID (“conid”) to uniquely specify instruments. Knowledge of a particular instrument’s conid is required to retrieve intrument trading rules and market data, and also to submit orders.

Due to the novelty and variety of these instruments, the process of resolving Event Contract symbols and attributes into IB’s conids requires the most attention and is the primary focus of this guide. Once conids are obtained, other functionality operates as expected.

Note that IB conids are persistent for the life of an instrument. Therefore, we recommend retrieving conids and storing them locally prior to trading. Similarly, Event Contracts’ underlying indices possess their own conids which persist indefinitely. Once these underlier conids are captured, they can be used to retrieve a current set of tradable Event Contracts in that product class.

The Web API’s existing derivative discovery workflow can be used to find Event Contracts offered by both CME Group and ForecastEx, though the workflow differs slightly for each issuer, owing to the modeling of their products as futures options and (index) options, respectively.

In both cases, instrument discovery begins by selecting a product code of interest.

Event Contract product codes can be obtained from IB’s ForecastTrader, or directly from the exchange websites:

• IB ForecastTrader: https://forecasttrader.interactivebrokers.com/eventtrader/#/markets
• CME Group: https://www.cmegroup.com/activetrader/event-contracts.html
• ForecastEx: https://forecastex.com/markets/

CME Group’s Event Contract products are listed on the CME venues where their underlying indices reside.
For example, Event Contracts related to the closing price of Gold are listed on COMEX, while NQ-related Event Contracts are listed on CME.

Suppose we’d like to find CME’s NQ Event Contracts.

First, we’ll want to capture the conid of the underlying NQ index, along with a list of valid Contract Months for which tradable Event Contracts exist.

GET https://api.ibkr.com/v1/api/iserver/secdef/search?symbol=NQ&secType=IND
200 OK
[
  {
    "conid": "11004958",
    "companyName": "E-mini NASDAQ 100 ",
    "symbol": "NQ",
    "description": "CME",
    ...,
    "sections": [
      {
        "secType": "IND",
        "exchange": "CME;"
      },
      ...,
      {
        "secType": "FOP",
        "months": "AUG24;SEP24;OCT24;NOV24;DEC24;MAR25;JUN25;DEC25;DEC26;DEC27;DEC28",
        "exchange": "CME"
      },
      ...,
      {
        "secType": "EC"
      }
    ]
  }
]

The index conid can be stored, and it is possible to skip this query in the future once this conid is obtained, as the Contract Month values can simply be incremented. The index conid can be reused in the future to fetch tradable Event Contracts as needed.

The response will deliver instrument records matching the provided symbol and instrument type, and results may not be unique.

You’ll want to filter the returned list for the index record of interest.
This can be done by looking at the array of JSON objects in the “sections” field, which should contain (among others) three objects:

• One reflecting an index on the correct exchange: {"secType":"IND","exchange":"CME"}
• Another reflecting futures options on that index: {"secType":"FOP",...}
• A third object indicating the existence of Event Contract products on that index: {"secType":"EC"}

Together, these elements confirm we’ve found the necessary NQ index record.

From this response we should capture two new values:

1. The index’s conid:
   "conid":"11004958"
2. From the “FOP” object, the semicolon-separated list of futures options Contract Months:
   "months":"AUG24;SEP24;OCT24;NOV24;DEC24;MAR25;JUN25;DEC25;DEC26;DEC27;DEC28"

Note that this response will deliver other values related to derivative products which have been omitted above and can be ignored for the purposes of this workflow.

ForecastEx products, modeled as index options, require a slightly different discovery workflow.

Suppose we’d like to find ForecastEx’s “US Fed Funds Target Rate” (FF) Event Contracts.

Submission of orders for Event Contracts via the Web API functions like orders for any other instrument.

However, it is important to note the differing mechanics between CME Group products and ForecastEx instruments:

• CME Group instruments can be bought and sold and function as normal futures options.
• ForecastEx instruments cannot be sold, only bought. To exit or reduce a position, one must buy the opposing Event Contract, and IB will net the opposing positions together automatically.

In both cases, no short selling is permitted.

Retrieval of market data, both live and historical, also functions the same for Event Contracts as for other instruments.

Like other options instruments, historical data for Event Contracts is available only while the instrument is trading and not yet expired.

Instrument rules, portfolio positions, and other instrument-specific features of the Web API function for Event Contracts as they do for options in general.

Note however that Market Scanners are not currently available for Event Contracts.