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.
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!
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!
API support is not available for accounts that support commission free trading.
Hello, we appreciate your question. At this time, APIs are not available for IBKR Lite accounts. Please view the link below to determine which plan is best for you:
https://www.interactivebrokers.com/en/index.php?f=45500
We hope this helps.