The TWS API is an interface to IB's standalone trading applications, TWS and IB Gateway. These are both standalone, Java-based trading applications which were designed to require the use of a graphical user interface for secure user authentication. For that reason "headless" operation of either application without a GUI is not supported.

The Trader Workstation

Our market maker-designed IB Trader Workstation (TWS) lets traders, investors, and institutions trade stocks, options, futures, forex, bonds, and funds on over 100 markets worldwide from a single account. The TWS API is a programming interface to TWS, and as such, for an application to connect to the API there must first be a running instance of TWS or IB Gateway. To use version 9.72+ of the API, it is necessary to have TWS version 952 or higher.

The IB Gateway

As an alternative to TWS for API users, IB also offers IB Gateway (IBGW). From the perspective of an API application, IB Gateway and TWS are identical; both represent a server to which an API client application can open a socket connection after the user has authenticated. With either application (TWS or IBGW), the user must manually enter their username and password into a login window. For security reasons, a headless session of TWS or IBGW without a GUI is not supported. From the user's perspective, IB Gateway may be advantageous because it is a lighter application which consumes about 40% fewer resources. IB Gateway is only provided in an 'offline' version, similar to 'offline TWS', which does not update automatically. It is recommended to upgrade to a current version of IBGW on the website periodically (note this does not require uninstalling the previous version of IBGW, nor installing a different API version if not desired.)

Both TWS and IBGW were designed to be restarted daily. This is necessary to perform functions such as re-downloading contract definitions in cases where contracts have been changed or new contracts have been added. Beginning in version 974+ both applications offer an autorestart feature that allows the application to restart daily without user intervention. With this option enabled, TWS or IBGW can potentially run from Sunday to Sunday without re-authenticating. After the nightly server reset on Saturday night it will be necessary to again enter security credentials.

The advantages of TWS over IBGW is that it provides the end user with many tools (Risk Navigator, OptionTrader, BookTrader, etc) and a graphical user interface which can be used to monitor an account or place orders. For beginning API users, it is recommended to first become acquainted with TWS before using IBGW.

For simplicity, this guide will mostly refer to the TWS although the reader should understand that for the TWS API's purposes, TWS and IB Gateway are synonymous.

Logging into multiple applications

It is not possible to login to multiple trading applications simultaneously with the same username. However, it is possible to create additional usernames for an account with can be used in different trading applications simultaneously, as long as there is not more than a single trading application logged in with a given username at a time. There are some additional cases in which it is also useful to create additional usernames:

If TWS or IBGW is logged in with a username that is used to login to Client Portal during that session, that application will not be able to automatically reconnect to the server after the next disconnection (such as the server reset).
A TWS or IBGW session logged into a paper trading account will not to receive market data if it is sharing data from a live user which is used to login to Client Portal.

If a different username is utilized to login to Client Portal in either of these cases, then it will not affect the TWS/IBGW session.

How to add additional usernames in Account Management

It is important to note that market data subscriptions are setup independently for each live username.

Enable API connections

Before any client application can connect to the Trader Workstation, the TWS needs to be configured to listen for incoming API connections on a very specific port. By default when TWS is first installed it will not allow API connections. IBGW by contrast accepts socket-based API connections by default. To enable API access in TWS, navigate to the TWS' API settings at Edit -> Global Configuration -> API -> Settings and make sure the "Enable ActiveX and Socket Clients" option is activated as shown below:

Also important to mention is the "Socket port". By default a production account TWS session will be set for socket port 7496, and a paper account session will listen on socket port 7497. However these are just default values chosen because they are almost always available on any computer. They can be changed to any open socket port, as long as the socket ports specified in the API client and TWS settings match. If there are multiple TWS sessions on one computer, the socket port is used to distinguish the TWS session. Since only one application can listen on one port at a time you will need to assign different ports to each running TWS.

Important: when running paper and live TWS on the same computer, make sure your client application is connecting to the right TWS!

Read Only API

The API Settings dialogue allows you to configure TWS to note accept API orders with the "Read Only" setting. By default, "Read Only" is enabled as an additional precautionary measure. Information about orders is not available to the API when read-only mode is enabled.

Master Client ID

By default the "Master Client ID" field is unset. To specify that a certain client should automatically receive updates about all open orders, as well as commission reports from orders placed from all clients, the client's ID should be set as the Master Client ID in TWS or IBGW Global Configuration. The clientID is specified from an API client application in the initial function call to IBApi::EClientSocket::eConnect.

Installing the API source

The API itself can be downloaded and installed from:

http://interactivebrokers.github.io/

Many third party applications already have their own version of the API which is installed in the process of installing the third party application. If using a third party product, it should first be verified if the API must be separately installed and what version of the API is needed- many third party products are only compatible with a specific API version.

Running the Windows version of the API installer creates a directory "C:\\TWS API\" for the API source code in addition to automatically copying two files into the Windows directory for the DDE and C++ APIs. It is important that the API installs to the C: drive, as otherwise API applications may not be able to find the associated files. The Windows installer also copies compiled dynamic linked libraries (DLL) of the ActiveX control TWSLib.dll, C# API CSharpAPI.dll, and C++ API TwsSocketClient.dll. Starting in API version 973.07, running the API installer is designed to install an ActiveX control TWSLib.dll, and TwsRTDServer control TwsRTDServer.dll which are compatible with both 32 and 64 bit applications.

Changing the installed API version

(On Windows Only)

If a different version of the ActiveX (v9.71 or lower) or C++ API is required than the one currently installed on the system, there are additional steps required to uninstall the previous API version to manually remove a file called "TwsSocketClient.dll":

1) Uninstall the API from the "Add/Remove Tool" in the Windows Control Panel as usual

2) Delete the C:\TWS API\ folder if any files are still remaining to prevent a version mismatch.

3) Locate the file "C:\Windows\SysWOW64\TwsSocketClient.dll". Delete this file.

4) Restart the computer before installing a different API version.