This website uses cookies to collect usage information in order to offer a better browsing experience. By browsing this site or by clicking on the "ACCEPT COOKIES" button you accept our Cookie Policy.

Duration: 5:30

Level: Intermediate

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

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

Request Body :

string  symbol   
symbol or name to be searched

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    ompany 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

string sectype  OPT for Options. WAR for Warrants.

string month  contract month

string exchange ptional, 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

string   sectype  FUT for futures, OPT for options, WAR for warrants, CASH for forex, CFD for contract for difference.

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:

Visit the IBKR API Center for Downloads, Resources, and Technical Details:

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.

Supporting documentation for any claims and statistical information will be provided upon request.

Any stock, options or futures symbols displayed are for illustrative purposes only and are not intended to portray recommendations.

Disclosure: Options Trading

Options involve risk and are not suitable for all investors. For more information read the “Characteristics and Risks of Standardized Options” also known as the options disclosure document (ODD). To receive a copy of the ODD call 312-542-6901 or click here. Multiple leg strategies, including spreads, will incur multiple commission charges.

Disclosure: API Examples Discussed

Throughout the lesson, please keep in mind that the examples discussed are purely for technical demonstration purposes, and do not constitute trading advice. Also, it is important to remember that placing trades in a paper account is recommended before any live trading.

trading top
Translate »