Initial Setup

The TWS API is an interface to LYNX's standalone trading applications, TWS and LYNX 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 LYNX 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 LYNX Gateway. To use version 9.72+ of the API, it is necessary to have TWS version 952 or higher.

The LYNX Gateway

As an alternative to TWS for API users, LYNX also offers LYNX Gateway. From the perspective of an API application, LYNX 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 LYNXGW), the user must manually enter their username and password into a login window. For security reasons, a headless session of TWS or LYNXGW without a GUI is not supported. From the user's perspective, LYNX Gateway may be advantageous because it is a lighter application which consumes about 40% fewer resources. LYNX 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 LYNXGW on the website periodically (note this does not require uninstalling the previous version of LYNXGW, nor installing a different API version if not desired.)

Both TWS and LYNXGW 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 LYNXGW 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 LYNXGW 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 LYNXGW.

[!NOTE|style:flat|label:Note] For simplicity, this guide will mostly refer to the TWS although the reader should understand that for the TWS API's purposes, TWS and LYNX 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 LYNXGW 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 LYNXGW 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/LYNXGW session.

How to add additional usernames in Account Management?

[!WARNING|style:flat|label:Important] 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. LYNXGW 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.

[!WARNING|style:flat|label: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 LYNXGW Global Configuration. The clientID is specified from an API client application in the initial function call to LYNXApi.EClientSocket.eConnect .

Installing the API source

The API itself can be downloaded and installed from the download page.

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). 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" and delete it.

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