Duration: 5:27
Level: Intermediate

In this lesson, we’ll show you where to find the software applications Trader Workstation (TWS) and IB Gateway on the IBKR website for download and installation. TWS and IB Gateway are the standalone software applications which integrates with our API that can be used with custom or third party trading applications. We’ll then discuss the settings in TWS/IB Gateway which are necessary to connect an API client and those which can affect order placement.

Study Notes:

Interactive Brokers’ flagship desktop trading application – Trader Workstation – is free to download from the website and run. The download can be found at www.interactivebrokers.com under the menu Trading > Platforms.

On the download site 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. The IB Gateway download can be found on the website under the Trading > APIs menu.

From an API perspective, IB Gateway is nearly identical to TWS.

An application that connects to and uses the API with TWS can also use IB Gateway.

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.18.1c, then the current IB Gateway Latest build is also 10.18.1c.

Installing TWS

After running the installer, TWS will be installed locally and a new icon will be created on the desktop . Double-clicking on the icon will bring up the TWS login screen which has inputs to manually enter 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.

Demo accounts are compatible with the TWS API, though they will not have live data available for most instrument types. To receive live or historical candlestick 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 under API  Settings.

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:

  • “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.
  • “Allow Connections from Localhost Only” – Checking this box configures TWS to (1) only accept incoming connections from API applications on the same computer, and (2) avoids the need to manually accept incoming API connections.
  • 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.
  • For more information visit the reference guide link below.
  • Some settings in Global Configuration which will affect if orders from the API are accepted:
  • 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.
  • The ‘Precautions’ setting under API in Global Configuration menu will cause certain orders to not transmit by default if they exceed certain precautionary settings until they are manually confirmed in TWS.
  • Some order attributes which can’t be set from the API are set from TWS. For instance there is a setting in TWS Global Configuration called “Active order in pre-open session” which is not available to be set by the API but is in TWS and will also affect API orders.
  • In the next lesson we’ll examine the API source code itself and discuss the major classes of the API.

API Reference Guide

IB Gateway

Intial Set-up

4 thoughts on “Installing & Configuring TWS for the API”

  1. Hi, I am now trying to connect python with TWS. Everything went smoothly until the last bit: I got an error when running the test code: ERROR -1 2157 Sec-def data farm connection is broken:secdefhk. I am using Spyder and I am currently in mainland China. I tried using VPN but it doesn’t help either. Could you please help me to solve this error? Thank you very much!

    1. Hi Wanlu, we appreciate your question. For this inquiry, please open a web ticket in Client Portal (click the “Help?” in the upper right menu, then “Secure Message Center”). The best category to choose is “API.” Our API experts will be able to help you out from there!

Join the Discussion

Thank you for engaging with IBKR Campus. If you have a general question, it may already be covered in our FAQs. If you have an account-specific question or concern, please reach out to Client Services.

Your email address will not be published. Required fields are marked *

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.

The views and opinions expressed herein are those of the author and do not necessarily reflect the views of Interactive Brokers, its affiliates, or its employees.