In this third lesson we begin by describing how to obtain access to the TWS Python API open source code repository on GitHub, and explain the differences between the public download site and the private GitHub repository which has bleeding-edge source. We then discuss what the source code actually consists of and what it does, with a high-level view of the API architecture, and mention some of the many different environments in which Python API programs are being run.
What does the API source consist of and what does it actually do?
The API source code serves the purpose of defining the available messages which can be exchanged between TWS and an external API application. The messages are exchanged via a TCP socket connection and most commonly use a subscribe-and-publish, or “pub/sub” pattern in which a message is sent from an API client to subscribe to a particular type of data, after which TWS will publish updates about that data type as it occurs in real-time. We will discuss this in more detail with specific examples in the following lessons. The API source code also helps to translate those lower level messages into a higher form which are more convenient for programmers.
The API is open source and maintained using the Git version control system and hosted on the online repository GitHub (GitHub.com). GitHub derives its name from the version control system Git which it uses. All updates made to the API source over time are tracked in using Git, and to make updates to the API source it is necessary to use the Git program.
The direct link to the API download site is interactivebrokers.GitHub.io. It can also be reached from the Interactive Brokers website through the ‘Technology’ menu where there is a ‘Trading APIs’ option which shows a list of available APIs. Clicking the ‘IB API’ link will take you to an TWS API overview section of the website which shows the different technologies in which the API is offered.
At the bottom are several important links. First, there is a link to the API download itself at “Get API Software”. Under ‘Additional Resources’ there is a link ‘Guides’ which takes you to the comprehensive TWS API reference guide online.
I would suggest bookmarking this site. In the reference guide there are snippets of sample code taken from the ‘Testbed’ sample projects distributed with the Beta API and installed to the samples folder under ‘TWS API’. After choosing a section on the left in the reference guide to show the description of a particular type of functionality, choose ‘Python’ from the menu at the top to display the associated sample code from Testbed.
From the API resources webpage is also a link to the API Release Notes which detail the changes in the most recent API downloads on the public website. These downloads are typically updated several times per year.
Clicking on “Get API Software” takes you to a license agreement for the API source. The default agreement is a non-commercial, which means the API can’t be provided with commercial software, however a commercial license agreement is also available upon request.
To download the Python API specifically, its necessary to choose version API 973 or higher.
You’ll notice that there are separate downloads on left and right for Windows and for Mac/Unix. Some API technologies such as ActiveX and DDE are only provided with the Windows installer. For Python in particular, the API source code is identical in the Windows and Mac/Linux distributions. Using the Python API does not require any Windows registry changes and so on Windows the Python source can be obtained using either the msi installer or zip file if you don’t have administer access.
There are different ways to load the Python API source. Some clients use an environment such as Anaconda, or choose to install the Python API as a wheel. In the examples in following lessons, we will load the Python source directly into the PyCharm editor. PyCharm is a free Integrated Development Environment (IDE) from IntelliJ. Other popular Python IDEs include Eclipse, Spyder, and IDLE.*
Loading the source into PyCharm requires no installation of the API source and nothing else has to be configured on the computer except from the Python interpreter and PyCharm. The same steps can be followed on any of the operating systems.
It is important to keep in mind that the interactivebrokers.GitHub.io site is the public API download site, however it is also possible to request access to the private GitHub repository if you have a GitHub account, which is free to open, by following the instructions under the ‘Beta’ link on the download page. The bleeding edge source available on the private GitHub repository is referred to as Beta version of the API. Once you have access to the private GitHub repository.
if you are familiar with Git version control it’s possible to make pull requests directly to the API sources and to raise new issues for the developers on the GitHub repository site.
On Windows, after running the API installer there should be a folder called C:\TWS API\ where the API is installed and folder for the Python source code at: C:\TWS API\source\pythonclient\. The API source code is open source and a great resource for understanding more about how the API works and what it offers.
Before developing a Python API application, it is suggested to take a bit of time to examine the source code. In examining the source you’ll notice the following important features about the API which we discuss further in the next lessons:
- First, the connection between the API client and TWS begins in the connect() function. The connection is necessarily asynchronous and so this makes programs look different than programs under a synchronous framework.
- Because of the asynchronous architecture there are typically (at least) two threads running. One thread reads messages from TWS to the API and places the messages in a queue. The other thread(s) send messages to TWS, or process messages in the incoming queue.
- Some API programs use the asyncio module included in Python 3.6. This module provides a framework that revolves around the event loop. An event loop basically waits for something to happen and then acts on the event. In the ib_insync from an unaffiliated third party) https://GitHub.com/erdewit/ib_insync there’s an example of using the API in this way.
- EClient is the class in the API that has the functions called to send messages to TWS. EWrapper is the class which has TWS callbacks defined that needs to be handled and implemented by the API client. Unlike other programming languages this is handled at runtime and does not require all callbacks in EWrapper are implemented.
*This software / IDE is in no way affiliated, endorsed, or approved by Interactive Brokers or any of its affiliates. It comes with absolutely no warranty and should not be used in actual trading unless the user can read and understand the source.
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.