Installing & Configuring TWS for the API

In order to use the TWS API, clients must download and install the Trader Workstation or IB Gateway. All Interactive Brokers resources are linked in our documentation. If a user visits our IBKR Campus documentation, navigate to the TWS API directory. On this page, we will see a designated section for Download TWS or IB Gateway. Clicking the affiliated link will bring you to an affiliated downloads page.

On the download page for Trader Workstation you’ll notice that there are ‘Online’ versions which update automatically with new releases, as well as ‘Offline’ versions at the bottom which never update. When you go to the site, the server will automatically detect the operating system of your browser and provide the corresponding download automatically, however all versions of TWS are available for use with Windows, Linux, or Mac.

IB Gateway

The alternative to using TWS for API users is to use a program called IB Gateway. From an API perspective, IB Gateway is nearly identical to TWS. Any application that connects to and uses the API with TWS can also use IB Gateway. Please be aware that in this tutorial series, we will be working with and referencing Trader Workstation. However, please note that the two are synonymous, and the whole series can be followed using either application.

The major difference of IB Gateway is that it is entirely geared towards API functionality and does not provide access to account information via a GUI in the same way as TWS does. Because of this, it is a smaller application that requires fewer resources.

Equivalent versions of TWS and IB Gateway are always released together. For instance, if the current TWS Latest version is 10.19.1c, then the current IB Gateway Latest build is also 10.19.1c.

After deciding which application to run, users can download their given platform. Please be aware for Windows, MacOS, and Linux, after selecting your download option, Interactive will display exact platform specific instructions for this installation process.

Installing TWS for Windows or MacOS

For all platforms, we will assume the download will appear in our respective Downloads folder. For Windows, we should have a .exe file while MacOS will be provided with a .dmg. Clicking these executables should launch an identical Install Wizard. In our case, we can simply follow our default values and click “Next” throughout the program. This will install the Trader Workstation to a directory on C:\Jts. TWS will be installed locally, and a new icon will be created on the desktop.  

Installing TWS for Linux

The process to install the Trader Workstation on Linux is only slightly different compared to the Windows and MacOS counterparts. For Linux distributions, after downloading the software, users will need to navigate to the corresponding Downloads directory in their terminal to find the program installer. Then, we can call chmod u+x on the sh file to allow the user to execute it. After updating the file’s permissions, we can call sudo ./tws-stable-standalone-linux.sh to run the executable and display an identical install wizard. Once again, we will follow the default install directory. In my case, it should be installed under my user directory.

Assuming I do not have a corresponding GUI for launching my applications, I can manually run the Trader Workstation by calling the launcher located with ./Jts/1019/tws. Users may find a different version number aside from 1019 in their installation.

Configuring Trader Workstation

Launching the Trader Workstation will bring up the TWS login screen which has inputs for a username and password. There is also an option where you can select to login to either your live or paper account. Paper accounts are compatible to use with the TWS API, and it is recommended to test all programs in a paper environment before moving to production trading.

If you don’t have an IB account, it’s possible to login to a demo account by clicking the link “Try the Demo” and using an email address instead.

To receive live or historical data from the API, it is necessary to first have live data permissions enabled in TWS. For most instrument types, this requires first having a live funded account with active market data subscriptions.

After you fully logged into TWS and it has loaded completely for the first time, there is a setting which must be enabled to allow the API connection, and several others which some users decide to configure differently for their applications. The API settings can be configured in the Global Configuration. For Trader Workstation, select the cog wheel in the top right corner. IB Gateway users should see an option for “Configure” and “Settings” to launch the same window.

After entering the Global Configuration, users can navigate to API then Settings on the left. The setting necessary to enable the socket client connections for Python is the first checkbox labelled “Enable ActiveX and Socket Clients”. The other settings which affect the initial connection are:

• The setting ‘Read-Only’ is enabled by default and will block all API orders. It must be unchecked to allow any orders from the API.
• “Socket Port”- By default, TWS uses socket port 7496 for live sessions and 7497 for paper sessions. IB Gateway by contrast uses 4001 for live sessions and 4002 for paper sessions. However these are just defaults, and can be modified as desired- the socket port in TWS must be configured to match the socket port used in the API clients’ connect() function.

Some additional settings that are necessary for escalating issues with Customer Support revolve around API Logging. To enable logging of API messages for troubleshooting specific API issues there are three notable settings:

• “Create API Message Log” – Used to create an API log file which will record all API messages.
• “Include market data in API log file” will include all market data returned by this request in the log.
• “Logging Level” is a dropdown menu to adjust the information present in the logs. If this is set to the highest level called “Detail”, the API logs will document all API Traffic to and from the Trader Workstation.

After enabling these settings, users can click Apply then OK at the bottom to confirm and save these changes.

TWS Settings