How to Query Contract Details for Derivatives in the Web API

Articles From: Interactive Brokers
Website: Interactive Brokers

For derivative contracts such as Futures and Options you would initially use the endpoint /iserver/secdef/search to query the underlying. This will relay back a ‘sections’ which lists all derivative contract(s) it has.

Please be sure to authenticate first in order to resolve the below URLs.
For authentication details, visit https://interactivebrokers.github.io/cpwebapi/index.html#login

POST https://localhost:5000/v1/api/iserver/secdef/search?symbol=SPX&sectype=IND

Request Body :

  • string          symbol         symbol or name to be searched
                         required
  • boolean      name           should be true if the search is to be performed by name, false by default.
  • string           sectype       if search is done by name, only the assets provided in this field will be returned. Currently, only STK is supported.

Response :

Array () [

  • integer               conid                                              contract identifier
  • string                  companyHeader                         company name – Exchange
  • string                  companyName            
  • string                  symbol
  • string                  description                                    Exchange
  • string                  restricted                        
  • string                  fop                                                   List of Future Option expirations in YYYYMMDD format separated by semicolon
  • string                  opt                                                   List of Stock Option or Index Option expirations in YYYYMMDD format separated by semicolon
  • string                  war                                                  List of Warrants expirations in YYYYMMDD format separated by semicolon
  • Array()                sections                                         Array of objects
    • string                  secType                                         Asset class
    • string                  months                                          List of expiration month(s) and year(s) in MMMYY format separated by semicolon
    • string                  symbol                            
    • string                  exchange                                      Listing Exchange
    • string                  legSecType                                   For combo’s defines the asset class for each leg

]

After you’ve sent the endpoint /iserver/secdef/search, if you wish, you can query to know all the strikes of an option contract for the corresponding month by sending the endpoint /iserver/secdef/strikes

GET https://localhost:5000/v1/api/iserver/secdef/strikes?conid=416904&sectype=OPT&month=DEC22&exchange=SMART

Request Body:

  • string                                conid                                contract id of the underlying contract you received from /iserver/secdef/search
                                             required
  • string                                sectype                            OPT for Options. WAR for Warrants.
                                              required
  • string                                month                              contract month
                                              required
  • string                                exchange                        optional, default is SMART

Response :

  • Array()                             call                                    list of call strikes
  • Array()                              put                                    list of put strikes

Once you’ve sent the endpoint /iserver/secdef/strike, then use the endpoint /iserver/secdef/info to query all the expirations for a corresponding month and strikes (including weeklies).

GET https://localhost:5000/v1/api/iserver/secdef/info?conid=416904&sectype=OPT&month=DEC22&right=C&exchange=SMART&strike=1200

Request Body

  • string                                conid                                contract id of the underlying contract
                                             required
  • string                                sectype                            FUT for futures, OPT for options, WAR for warrants, CASH for forex, CFD for contract for difference.
                                              required
  • string                                month                              contract month, only required for FUT/OPT/WAR in the format MMMYY, example JAN00
                                             
  • string                                exchange                        optional, default is SMART
  • string                                strike                                optional, only required for OPT/WAR
  • string                                right                                   C for call, P for put

Response :

Array () [

  • integer                             conid                                contract identifier
  • string                                symbol                             IB symbology
  • string                                secType                           asset class      
  • string                                exchange
  • string                                listingExchange                          
  • string                                right                                  C= Call Option, P = Put Option
  • string                                strike                                 The strike price also known as exercise price
  • string                                currency                          Currency the contract trades in
  • string                                cusip                                 Committee on Uniform Securities Identification Procedures number
  • string                                coupon                            Annual interest rate paid on a bond
  • string                                desc1                               Formatted symbol
  • string                                desc2                               Formatted expiration, strike and right
  • string                                maturityDate                  The date on which the underlying transaction settles if the option is exercised in the format YYYYMMDD
  • string                                multiplier                         Total premium paid or received for an option contract
  • string                                tradingClass
  • string                                validExchanges             Comma separated list of exchanges contract supports

]

If you have any further questions or issues querying contract details for derivatives please reach out to the API Group, ref: https://www.interactivebrokers.com/en/index.php?f=47047.

Visit the IBKR API Center for Downloads, Resources, and Technical Details:
https://www.interactivebrokers.com/en/trading/ib-api.php.

See the previous installments in this series: 

Disclosure: Interactive Brokers

The analysis in this material is provided for information only and is not and should not be construed as an offer to sell or the solicitation of an offer to buy any security. To the extent that this material discusses general market activity, industry or sector trends or other broad-based economic or political conditions, it should not be construed as research or investment advice. To the extent that it includes references to specific securities, commodities, currencies, or other instruments, those references do not constitute a recommendation by IBKR to buy, sell or hold such investments. This material does not and is not intended to take into account the particular financial conditions, investment objectives or requirements of individual customers. Before acting on this material, you should consider whether it is suitable for your particular circumstances and, as necessary, seek professional advice.

The views and opinions expressed herein are those of the author and do not necessarily reflect the views of Interactive Brokers, its affiliates, or its employees.

Disclosure: Order Types / TWS

The order types available through Interactive Brokers LLC’s Trader Workstation are designed to help you limit your loss and/or lock in a profit. Market conditions and other factors may affect execution. In general, orders guarantee a fill or guarantee a price, but not both. In extreme market conditions, an order may either be executed at a different price than anticipated or may not be filled in the marketplace.

Disclosure: Forex

There is a substantial risk of loss in foreign exchange trading. The settlement date of foreign exchange trades can vary due to time zone differences and bank holidays. When trading across foreign exchange markets, this may necessitate borrowing funds to settle foreign exchange trades. The interest rate on borrowed funds must be considered when computing the cost of trades across multiple markets.

Disclosure: Options Trading

Options involve risk and are not suitable for all investors. Multiple leg strategies, including spreads, will incur multiple commission charges. For more information read the “Characteristics and Risks of Standardized Options” also known as the options disclosure document (ODD) or visit ibkr.com/occ

Disclosure: Futures Trading

Futures are not suitable for all investors. The amount you may lose may be greater than your initial investment. Before trading futures, please read the CFTC Risk Disclosure. A copy and additional information are available at ibkr.com.