Hello, and welcome to this lesson discussing contract discovery and how to define a contract using the TWS API. Please note that our starting file content will mirror the previous video on essential API components. As a result, I would encourage viewers to review the last lesson before going further in this lesson. To explore contract definitions, we can utilize the EClient.reqContractDetails and EWrapper.contractDetails, as this provides the baseline of contract discovery before moving into other functionality like market data or order placement.<\/p>\n\n\n\n
Starting out with last lesson\u2019s template, without the currentTime references, we can start by writing out the EWrapper.contractDetails function. All we need to do is define the function, contractDetails, inside of our TestApp class. This function takes three arguments, self, reqId, and contractDetails. The first two we are familiar with, but contractDetails is a unique class, ContractDetails, which contains all of the contract\u2019s information in a dictionary structure. Including things like the underlying contract details, the supported exchanges, and trading hours.<\/p>\n\n\n\n
Users are welcome to print this value directly; however, since we\u2019ll be printing and reading the value, we can utilize some of Python\u2019s dictionary handling. With that in mind, I will create a variable, attrs, and set it equal to the vars() method, taking our contractDetails as an argument. This will produce the key-value pair of our contractDetails object. Then, I\u2019ll look to print a string-joined lambda set. This will appear as print(\u201c\\n\u201d.join(f\u201d{name}: {value}\u201d for name, value in attrs.items())). <\/p>\n\n\n\n
I will also add another EWrapper function, contractDetailsEnd. This function simply indicates when there is no data remaining for a request that may return several responses to a single request. The method only takes self and reqId as an argument to help with request tracking. I will use this method to announce contract details has ended, and also disconnect our API session, similar to how we did for the currentTime method before.<\/p>\n\n\n\n
Now we can move on to the request side of things. Let\u2019s keep things simple to start with and focus on requesting stock contract details, then we can build out futures or options contracts later, since those are a bit more complex. We can create a variable, such as mycontract and set it equal to a Contract object. Now, I can start establishing my contract. As a test case, maybe all I know about my trading is that I want to trade AAPL stock. Therefore, I can set mycontract.symbol to \u201cAAPL\u201d and then mycontract.secType = \u201cSTK\u201d. Please be aware that nearly all secType values are 3 or 4 character representations of a given security type. For example, we might see STK for Stocks, OPT for Options, or FUT for Futures.<\/p>\n\n\n\n
We can then send out our EClient.reqContractDetails request to find information on this contract. This request only takes the arguments for a request ID, which we\u2019ll use our app.nextId() function for, and then a Contract object, which we\u2019ll use mycontract for. With these simple additions set, we can run our code, and we should see a large amount of data returned. That is because the contractDetails method can be used to receive any contract that approximately matches our Contract object. The best way to distinguish between your conracts is to look at the actual \u201ccontract\u201d value returned. This will return essential values like the conid, symbol, security type, trading exchange, and listing exchange.<\/p>\n\n\n\n
Before moving on, let\u2019s take a moment to look at the overall response of the contractDetails object. I can see the extended detail of our contract object, but also values like orderTypes, which show the supported order types with the instrument, liquidHours, time zone ID, and even market rule information. But this was not exactly what I intended to receive, so let\u2019s further truncate this request.<\/p>\n\n\n\n
I can set my contract\u2019s currency value to USD, since I only care to trade in my own base currency. Then, I can also set my exchange value to SMART, because I want to trade using the Interactive Brokers SmartRouting feature. If we request data now, we\u2019ll see that adding two additional parameters returns a single contract for our use and is just the contract I wanted. These four values, symbol, sectype, exchange, and currency; are the basis of any contract we\u2019d like to use.<\/p>\n\n\n\n
Users should look to include the primaryExchange value where possible. This is the item just after our trading exchange in the contract object and can be used to distinguish between multiple companies that have otherwise matching symbols and require more distinction. Adding the primary exchange can help resolve most ambiguous contracts.<\/p>\n\n\n\n
With our baseline stocks settled, we can move on to Futures contracts. Before requesting our contract, I\u2019ll adjust my EWrapper.contractDetails method to just print the contractDetails.contract value, to help conserve space, at least while we are exploring. contractDetails.contract is identical to the Contract object we are creating in our request. As a result, the parameters we send can be mirrored in the parameters we receive. We can uncomment the lambda print value once we have narrowed down our contract.<\/p>\n\n\n\n
We can tweak our existing contract to another contract we\u2019re looking for. I want to look into ES Futures trading, so I\u2019ll adjust my contract symbol and security type to ES and FUT accordingly. For those unaware, SMART Routing is only supported for stocks, options, and combinations. As a result, I would not be able to use SMART for my ES future.<\/p>\n\n\n\n
So, in this case, I will comment out the exchange field, and send my request. <\/p>\n\n\n\n
This will return numerous contracts, though we\u2019ll notice that a lot of the contracts coming back are either CME or QBALGO. Given I don\u2019t want to trade the algo, and I simply want to trade the CME exchange, I\u2019ll uncomment my exchange value, and set this to \u201cCME\u201d. We can also find the date values, which correlate to the lastTradeDateOrContractMonth value. I will add this to my own contract month for December, and I can receive only the ES contracts traded by CME in December of 2024. If we uncomment our lambda function and run our script, we\u2019ll find all of the relevant information we want.<\/p>\n\n\n\n
Before diving into the options contract, I\u2019ll once again comment out the contractDetails lambda function, and simply print the contract object. I will also tweak my existing contract object again, because now I\u2019m thinking about trading SPX options. This will only require a few modifications from the ES contract, and would be an almost identical set of values if we were looking to trade Futures Options. I will adjust my symbol to SPX, secType to OPT, and my exchange back to SMART. If we run the script now, we\u2019ll receive hundreds of results back, as there are several expiries, rights, and strikes traded throughout the month of December, even with our existing filtering.<\/p>\n\n\n\n
To filter out our options contract further, I\u2019ll set my right to Put, using mycontract.right = \u201cP\u201d. In the case of rights, you may use P or Put for puts, or C or Call for call options. With our right set, there is still a lot to filter. Near the end of our contract object, we\u2019ll notice these \u201cSPX\u201d and \u201cSPXW\u201d values. These values are known as the TradingClass of the contract and distinguish between multiple matching derivatives. In this scenario, this distinguishes between the monthly SPX contracts and the weekly contracts. This is especially relevant, as these two contracts can overlap their expiration date, and the trading class may be the only distinct value.<\/p>\n\n\n\n
If we make the request now, we will still find tons of results. This is because all of the potential strike values are being returned, which is particularly large, especially for an index like SPX. As a result, it\u2019s best to further truncate our request by including a strike in our contract. I will narrow my focus to a strike of 5300, which gives us one last contract. I will uncomment our lambda function before running the script, so we can see all these values that were being requested and returned.<\/p>\n\n\n\n
There are several additional security types with their own unique parameters. I\u2019d like to briefly discuss some additional resources users should consult to find these details. With regard to the API specific fields, the TWS API Contract class reference is listed in our documentation on IBKR Campus that provides context to each parameter for review.<\/p>\n\n\n\n
Similarly, we also maintain an entire Contracts page, which users should consult to find which parameters are needed for each contract type. This will provide an API-Agnostic structure which displays what values, such as symbol, secType, and exchange, are required for special contract types. This will even include information on building futures spreads or option combos, all of which are built on the foundation discussed throughout this lesson.<\/p>\n\n\n\n
Finally, users should look to utilize Trader Workstation\u2019s Description page for more insight on retrieving contract-specific details. To accomplish this, search for any contract you typically consult in your day-to-day trading. After adding the contract to your watchlist, or if it is already in your Portfolio, right click the instrument, click the drop-down arrow, then \u201cFinancial Instrument Details\u201d and finally \u201cDescription\u201d. This will bring up a window in Trader Workstation which provides nearly all of the contract information discussed here. It is an essential tool while you are learning to search for contracts through the API independently.<\/p>\n\n\n\n
This concludes our lesson on defining contracts in the TWS API. Thank you for watching. If you have any questions, please be sure to review our documentation or leave a comment below this video. We look forward to having you in the next lesson of our TWS API series.<\/p>\n\n\n\n
from ibapi.client import *\nfrom ibapi.wrapper import *\nimport time\nimport threading\n\nclass TestApp(EClient, EWrapper):\n def __init__(self):\n EClient.__init__(self, self)\n \n def nextValidId(self, orderId):\n self.orderId = orderId\n \n def nextId(self):\n self.orderId += 1\n return self.orderId\n\n def error(self, reqId, errorCode, errorString, advancedOrderReject):\n print(f\"reqId: {reqId}, errorCode: {errorCode}, errorString: {errorString}, orderReject: {advancedOrderReject}\")\n\n def contractDetails(self, reqId, contractDetails):\n attrs = vars(contractDetails)\n print(\"\\n\".join(f\"{name}: {value}\" for name,value in attrs.items()))\n # print(contractDetails.contract)\n\n def contractDetailsEnd(self, reqId):\n print(\"End of contract details\")\n self.disconnect()\n\napp = TestApp()\napp.connect(\"127.0.0.1\", 7497, 0)\nthreading.Thread(target=app.run).start()\ntime.sleep(1)\n\nmycontract = Contract()\n# Stock\n# mycontract.symbol = \"AAPL\"\n# mycontract.secType = \"STK\"\n# mycontract.currency = \"USD\"\n# mycontract.exchange = \"SMART\"\n# mycontract.primaryExchange = \"NASDAQ\"\n\n# Future\n# mycontract.symbol = \"ES\"\n# mycontract.secType = \"FUT\"\n# mycontract.currency = \"USD\"\n# mycontract.exchange = \"CME\"\n# mycontract.lastTradeDateOrContractMonth = 202412\n\n# Option\nmycontract.symbol = \"SPX\"\nmycontract.secType = \"OPT\"\nmycontract.currency = \"USD\"\nmycontract.exchange = \"SMART\"\nmycontract.lastTradeDateOrContractMonth = 202412\nmycontract.right = \"P\"\nmycontract.tradingClass = \"SPXW\"\nmycontract.strike = 5300\n\napp.reqContractDetails(app.nextId(), mycontract)<\/pre>\n","protected":false},"excerpt":{"rendered":"In this lesson we’ll explore contract discovery and how to define a contract using the TWS API.<\/p>\n","protected":false},"author":850,"featured_media":195694,"parent":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"_acf_changed":true,"footnotes":""},"contributors-categories":[149],"traders-academy":[92,101,103,105],"class_list":{"0":"post-195693","1":"trading-lessons","2":"type-trading-lessons","3":"status-publish","4":"has-post-thumbnail","6":"contributors-categories-interactive-brokers","7":"traders-academy-api","8":"traders-academy-intermediate-trading","9":"traders-academy-level","10":"traders-academy-trading-lesson"},"pp_statuses_selecting_workflow":false,"pp_workflow_action":"current","pp_status_selection":"publish","acf":[],"yoast_head":"\n
Archives | Traders' Academy | IBKR Campus<\/title>\n<meta name=\"description\" content=\"Welcome to this lesson discussing contract discovery and how to define a contract using the TWS API.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/www.interactivebrokers.com\/campus\/wp-json\/wp\/v2\/trading-lessons\/195693\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Defining Contracts in the TWS API\" \/>\n<meta property=\"og:description\" content=\"Welcome to this lesson discussing contract discovery and how to define a contract using the TWS API.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/\" \/>\n<meta property=\"og:site_name\" content=\"IBKR Campus EU\" \/>\n<meta property=\"article:modified_time\" content=\"2024-07-02T19:17:21+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/www.interactivebrokers.eu\/campus\/wp-content\/uploads\/sites\/3\/2024\/07\/less5-py.jpg\" \/>\n\t<meta property=\"og:image:width\" content=\"1920\" \/>\n\t<meta property=\"og:image:height\" content=\"1080\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/jpeg\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"8 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\n\t \"@context\": \"https:\\\/\\\/schema.org\",\n\t \"@graph\": [\n\t {\n\t \"@type\": \"WebPage\",\n\t \"@id\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/trading-lessons\\\/defining-contracts-in-the-tws-api\\\/\",\n\t \"url\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/trading-lessons\\\/defining-contracts-in-the-tws-api\\\/\",\n\t \"name\": \"Defining Contracts in the TWS API - IBKR Campus EU\",\n\t \"isPartOf\": {\n\t \"@id\": \"https:\\\/\\\/ibkrcampus.eu\\\/campus\\\/#website\"\n\t },\n\t \"primaryImageOfPage\": {\n\t \"@id\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/trading-lessons\\\/defining-contracts-in-the-tws-api\\\/#primaryimage\"\n\t },\n\t \"image\": {\n\t \"@id\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/trading-lessons\\\/defining-contracts-in-the-tws-api\\\/#primaryimage\"\n\t },\n\t \"thumbnailUrl\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/wp-content\\\/uploads\\\/sites\\\/3\\\/2024\\\/07\\\/less5-py.jpg\",\n\t \"datePublished\": \"2024-07-02T16:01:24+00:00\",\n\t \"dateModified\": \"2024-07-02T19:17:21+00:00\",\n\t \"description\": \"Welcome to this lesson discussing contract discovery and how to define a contract using the TWS API.\",\n\t \"breadcrumb\": {\n\t \"@id\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/trading-lessons\\\/defining-contracts-in-the-tws-api\\\/#breadcrumb\"\n\t },\n\t \"inLanguage\": \"en-US\",\n\t \"potentialAction\": [\n\t {\n\t \"@type\": \"ReadAction\",\n\t \"target\": [\n\t \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/trading-lessons\\\/defining-contracts-in-the-tws-api\\\/\"\n\t ]\n\t }\n\t ]\n\t },\n\t {\n\t \"@type\": \"ImageObject\",\n\t \"inLanguage\": \"en-US\",\n\t \"@id\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/trading-lessons\\\/defining-contracts-in-the-tws-api\\\/#primaryimage\",\n\t \"url\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/wp-content\\\/uploads\\\/sites\\\/3\\\/2024\\\/07\\\/less5-py.jpg\",\n\t \"contentUrl\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/wp-content\\\/uploads\\\/sites\\\/3\\\/2024\\\/07\\\/less5-py.jpg\",\n\t \"width\": 1920,\n\t \"height\": 1080,\n\t \"caption\": \"Working on laptop, graphic\"\n\t },\n\t {\n\t \"@type\": \"BreadcrumbList\",\n\t \"@id\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/trading-lessons\\\/defining-contracts-in-the-tws-api\\\/#breadcrumb\",\n\t \"itemListElement\": [\n\t {\n\t \"@type\": \"ListItem\",\n\t \"position\": 1,\n\t \"name\": \"Home\",\n\t \"item\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/\"\n\t },\n\t {\n\t \"@type\": \"ListItem\",\n\t \"position\": 2,\n\t \"name\": \"Academy Lessons\",\n\t \"item\": \"https:\\\/\\\/www.interactivebrokers.eu\\\/campus\\\/trading-lessons\\\/\"\n\t },\n\t {\n\t \"@type\": \"ListItem\",\n\t \"position\": 3,\n\t \"name\": \"Defining Contracts in the TWS API\"\n\t }\n\t ]\n\t },\n\t {\n\t \"@type\": \"WebSite\",\n\t \"@id\": \"https:\\\/\\\/ibkrcampus.eu\\\/campus\\\/#website\",\n\t \"url\": \"https:\\\/\\\/ibkrcampus.eu\\\/campus\\\/\",\n\t \"name\": \"IBKR Campus EU\",\n\t \"description\": \"\",\n\t \"potentialAction\": [\n\t {\n\t \"@type\": \"SearchAction\",\n\t \"target\": {\n\t \"@type\": \"EntryPoint\",\n\t \"urlTemplate\": \"https:\\\/\\\/ibkrcampus.eu\\\/campus\\\/?s={search_term_string}\"\n\t },\n\t \"query-input\": {\n\t \"@type\": \"PropertyValueSpecification\",\n\t \"valueRequired\": true,\n\t \"valueName\": \"search_term_string\"\n\t }\n\t }\n\t ],\n\t \"inLanguage\": \"en-US\"\n\t }\n\t ]\n\t}<\/script>\n<!-- \/ Yoast SEO Premium plugin. -->","yoast_head_json":{"title":"Archives | Traders' Academy | IBKR Campus","description":"Welcome to this lesson discussing contract discovery and how to define a contract using the TWS API.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/www.interactivebrokers.com\/campus\/wp-json\/wp\/v2\/trading-lessons\/195693\/","og_locale":"en_US","og_type":"article","og_title":"Defining Contracts in the TWS API","og_description":"Welcome to this lesson discussing contract discovery and how to define a contract using the TWS API.","og_url":"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/","og_site_name":"IBKR Campus EU","article_modified_time":"2024-07-02T19:17:21+00:00","og_image":[{"width":1920,"height":1080,"url":"https:\/\/www.interactivebrokers.eu\/campus\/wp-content\/uploads\/sites\/3\/2024\/07\/less5-py.jpg","type":"image\/jpeg"}],"twitter_card":"summary_large_image","twitter_misc":{"Est. reading time":"8 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/","url":"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/","name":"Defining Contracts in the TWS API - IBKR Campus EU","isPartOf":{"@id":"https:\/\/ibkrcampus.eu\/campus\/#website"},"primaryImageOfPage":{"@id":"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/#primaryimage"},"image":{"@id":"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/#primaryimage"},"thumbnailUrl":"https:\/\/www.interactivebrokers.eu\/campus\/wp-content\/uploads\/sites\/3\/2024\/07\/less5-py.jpg","datePublished":"2024-07-02T16:01:24+00:00","dateModified":"2024-07-02T19:17:21+00:00","description":"Welcome to this lesson discussing contract discovery and how to define a contract using the TWS API.","breadcrumb":{"@id":"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/#primaryimage","url":"https:\/\/www.interactivebrokers.eu\/campus\/wp-content\/uploads\/sites\/3\/2024\/07\/less5-py.jpg","contentUrl":"https:\/\/www.interactivebrokers.eu\/campus\/wp-content\/uploads\/sites\/3\/2024\/07\/less5-py.jpg","width":1920,"height":1080,"caption":"Working on laptop, graphic"},{"@type":"BreadcrumbList","@id":"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/defining-contracts-in-the-tws-api\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/www.interactivebrokers.eu\/campus\/"},{"@type":"ListItem","position":2,"name":"Academy Lessons","item":"https:\/\/www.interactivebrokers.eu\/campus\/trading-lessons\/"},{"@type":"ListItem","position":3,"name":"Defining Contracts in the TWS API"}]},{"@type":"WebSite","@id":"https:\/\/ibkrcampus.eu\/campus\/#website","url":"https:\/\/ibkrcampus.eu\/campus\/","name":"IBKR Campus EU","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/ibkrcampus.eu\/campus\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"}]}},"_links":{"self":[{"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/trading-lessons\/195693","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/trading-lessons"}],"about":[{"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/types\/trading-lessons"}],"author":[{"embeddable":true,"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/users\/850"}],"replies":[{"embeddable":true,"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/comments?post=195693"}],"version-history":[{"count":0,"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/trading-lessons\/195693\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/media\/195694"}],"wp:attachment":[{"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/media?parent=195693"}],"wp:term":[{"taxonomy":"contributors-categories","embeddable":true,"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/contributors-categories?post=195693"},{"taxonomy":"traders-academy","embeddable":true,"href":"https:\/\/ibkrcampus.eu\/campus\/wp-json\/wp\/v2\/traders-academy?post=195693"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}