How to Query Contract Details for Derivatives in the Web API

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: 

• Tutorial: Web API – Connect to Brokerage Session
• How to Code an IB Algo Order in the Web API