How to install the TWS API Components on Mac / Unix

NOTE: If you have already agreed to the API License Agreement please start at Step 3 below.

Instructions

  1. Click directly on the button below to access the API software download page. 
  2. This will direct you to Interactive Brokers API License Agreement, please review it.
  3. Once you have clicked "I Agree", refer to the Mac / Unix section to download the API Software for your o.s.
    API Software Download List
  1. This will download twsapi_macunix.n.m.zip to your computer.
    (where n and m are the major and minor version numbers respectively)
  2. Open Terminal (Ctrl+Alt+T on most distributions)
    (On Mac press Command+Space to launch Spotlight, then type terminal and press Return)
  3. Navigate to the directory where the installer has been downloaded (normally it should be the Download folder within your home folder) and confirm the file is present.

     $  cd ~/Downloads
     $  ls

  1. Unzip the contents the installer into your home folder with the following command (if prompted, enter your password):
    $  sudo unzip twsapi_macunix.n.m.zip -d $HOME/
    Installation directions Step 3 and Step 4
  2. To access the sample and source files, navigate to the IBJts directory and confirm the subfolders samples and source are present.
    $  cd ~/IBJts
    $  ls
    Installation directions Step 5
 

 

Legacy Instructions - API Version ≤ 9.71

Note: IB only offers API Version 9.72+. In the event you already have an existing legacy version and need to install it, please refer to the directions below:

  1. locate the file twsapi_macunix.n.m.jar on your computer.
    (where n and m are the major and minor version numbers respectively.)
  2. Open Terminal (Ctrl+Alt+T on most distributions)
    (On Mac press Command+Space to launch Spotlight, then type terminal and press Return)
  3. Navigate to the directory where the .jar file has been located (normally it should be the Download folder within your home folder) and confirm it is present.
    cd ~/Downloads
    $  ls
  4. Extract the contents of the .jar file into your home folder.
    $  jar xf twsapi_macunix.n.m.jar -d $ HOME/
  5. To access the sample and source files, navigate to the IBJts directory and confirm the subfolders samples and source are present.
    $  cd ~/IBJts
    $  ls
 
 

Additional Information 

You can as well refer to KB2222 for video instructions on installing the Legacy API Components on a Mac.

 

How to share a security device

Übersicht: 

IBKR allows individuals to maintain multiple user names within a single account or across distinct accounts under their control.  Individuals who do not wish to maintain multiple physical security devices may elect to consolidate and share a single device across their users. The prerequisites and the procedure for sharing devices are outlined below.

Note: Clients using the IBKR Mobile Authentication (IB Key) should not use the present device sharing procedure, since the IB Key allows multiple users to be enabled directly from the IBKR Mobile app itself (menu item: Authenticate -> Add user). 
 
Background: 

Prerequisites

The possibility of sharing a physical security device will be granted only if ALL the conditions below are respected:

a) The participant users belong either to the same entity or to different entities but with the same identification data (Date of Birth, Citizenship, Country of Legal Residence, Identification Document type and number or Social Security Number for US Citizens and residents). 

b) The participant users do NOT have a temporary security device (Temporary Code, Online Security Code Card) currently assigned to them.

c) The physical device offering the highest level of protection has to be shared. In case all the devices offer the same level of protection, whichever of them can be eligible. You can check the security level of your device in the table below:

Security level

Device name

Device image

Highest Digital Security Card+ (DSC+)
Lowest Security Code Card (SLS card)
 
 

Procedure:

1. Among the possible candidates, identify the device offering the highest level of protection and the user that device belongs to. We will call that user the device owner

2. Log in to your Client Portal page with the requesting user (NOT the device owner)

3. Click on Menu icon in the top-left then select Settings and then User Settings
 
 4. Click on the wheel (Settings) close to Secure Login System
 
5a. In case your user does not have any active device, the system will display the SLS enrollment menu. Select the item "I already have access to a Secure Login Device under a different username" and click on Continue
 
5b. In any other case, the system will display the device list. Click on Share Device to proceed further
 
6. Enter the credentials of the device owner you identified at point 1. and click on Continue.

 
7. According to the SLS Device about to be shared, the system will display a security element (either Challenge Code or Index Numbers). Operate the SLS Device and, using the security element provided by the system, generate a response code. Enter the response code in the correspondent field and click on Continue.
 
8. Once you have reviewed the correctness of the information entered, click on Continue.

 
9. The system will display the status of your request (see note a. for details). Click OK to finalize the procedure.

 

NOTES:

a. In the vast majority of cases your sharing request will be automatically and immediately approved, processed and enforced. In case the approval of our Compliance department is needed, your request will stay in a pending status until this step has been cleared.

b. Once the device sharing request has been processed, you could keep the redundant device/s in a safe place. In the future you might decide to cancel the device sharing and reactivate those devices instead. If you do not feel the need to store them, you can send them (only DSC+) back to us following the instructions contained on this page:
 

c. Here below you can see the most common error messages and their causes:

- Less secure device: This error is returned if you set up the less secure token as the one to be shared. Please identify the most secure device and share that one.

- Different identification information:
This error is returned if the identification data of the entities/individuals involved in the sharing does not match. If the users belong to different entities/individuals, please notice that the token sharing will NOT be possible by design.
If the users belong in fact to the same entity/individual, the mismatch could be due, for example, to an outdated identification document on record. In this case, you can contact our Client services to have the data rectified.

 

 References:
  • Overview of the Secure Login System: KB1131 or ibkr.com/sls 
  • Multiple Two-Factor Authentication System (M2FS): KB2895
  • How to share the Security Login Device between two or more users: KB2481
  • How to opt back into the Secure Login System: KB2545
  • Security considerations following SLS partial opt-out: KB1198
  • Are there any charges or expenses associated with the security devices? KB1861
  • How to troubleshoot Account Management Login Failures: KB1132
  • How to troubleshoot Trading Platform Login Failures: KB1133

 

How to restore TWS settings from external storage

Übersicht: 

This article outlines the procedure for restoring TWS settings from an external location, example external hard drive, USB or other file location.

To restore TWS settings from an external source:

1. Log into TWS

2. Click on File and select Settings Recovery

Menu: File -> Settings Recovery                                     

3. Select Custom and click on Ok

Settings Recovery options                                                                                                                    

4. In the Look in field click on the drop down menu and select the directory where the TWS settings file is stored, example; If the file was located on the Desktop you would scroll to Desktop as shown below                                     Choose settings file location                                                              

5. Once you are in the directory containing the settings file,  select the settings file, example tws.xml and click on Open.

Enter settings filename

6.  In the Open settings confirmation window select Open without reporting problem

settings confirmation

 

See KB3146 for instructions on overcoming the "Downloading settings from server failed" error

See KB2320 for instructions on transferring settings from one user to another

See KB2282 for instructions on how to transfer settings from one computer to another

 

 

 

 

How to install MobileTWS on BlackBerry OS10

Background: 

Currently, Interactive Brokers does not offer a native IBKR Mobile app for the Blackberry 10 Operating System. Due to a recent partnership between Amazon and Blackberry, clients who own a Blackberry device running Blackberry 10 OS can install the Android version of the IBKR Mobile app directly from the Amazon Store.

Blackberry 10 OS Devices:

  • Q5, Z3, Leap, Classic, Passport, Q10, Z10, Z30, P'9982, P'9983
     

 *Please notice that these devices have limited hardware capabilities and this could negatively affect the performance of the IBKR Mobile app.

 

Installation

You can download the IBKR Mobile app on your Blackberry phone directly from the Amazon Appstore.

 

How to install IBKR Mobile from the Amazon App Store:

  1. On your Blackberry phone open the Amazon App Store  app.
  2. Enter your Amazon e-mail and password, and tap Sign in.
    (If you don't have an Amazon account, tap Create a new Amazon account.)
     
     
  3. Tap on the search bar at the top, type IBKR Mobile then tap Search.
  4. Tap on IBKR Mobile from the search results and install.
   
 
5. Once installed, tap on the IBKR Mobile app from one of your home screens to launch it
   

 

 

How to transfer TWS settings from one computer to another

Übersicht: 

 This article applies to:

  • Platform(s): Windows, Mac, Linux
  • TWS Build(s): Build 936 and Above

 

Background: 

Store settings on server allows clients the ability to store their Trader Workstation (TWS) settings/configuration on Interactive Brokers (IB) servers and retrieve them at anytime from another computer. This feature allows you to transfer settings from the same user on two different machines, but not between different accounts/users.

 
'Store' Settings on Server:

To transfer settings from one computer to another for the same username you will need to enable the option Use/store settings on server:

1. On the computer which currently has your settings, log in with the Use/store settings on server option unchecked on the login window

 TWS Login Screen

 2. Once you are logged in, enable this function:

  • If you are using the Classic layout, navigate to Edit >> Global Configuration >> Lock and Exit and check the box Use store settings on server
  • If you are using the Mosaic layout navigate to File >> Global Configuration >> Lock and Exit and check the box Use store settings on server

 Global Configurations Window

3.  Select Apply and OK.

4. Click on File -> Save Settings.

5. To Exit the application navigate to File and Exit.

IMPORTANT NOTE: The above operation will only save one copy of the TWS settings on the server. The serve does not store any backup copies.

 

'Use' Settings on Server:

On any computer (on which you want to use the same settings as above): Login with the Use/store settings on server option checked on the login window. This will download the settings, which you previously saved on our server.

 TWS Login Screen

 

 

See KB2323 for instructions on how to restore TWS settings from external storage

See KB2320 for instructions on transferring settings from one user to another

 

 

Account Management using Safari browser

Most recent versions of web browsers contain a feature which prompts users to save their user name and password when logging into various sites on the Internet.  While convenient in practice, this feature introduces a significant security risk in that it allows anyone with access to the computer to log into those sites where the password has been saved.  As a result, many sites that deal with highly sensitive information, including IB's Account Management, have controls which do not allow this feature to be utilized. While most browsers such as Mozilla Firefox, Internet Explorer and Google Chrome allow for such controls, others such as Apple's Safari do not.   As a result, Safari users who attempt to use the password save feature may experience log in failures on future log in attempts.

Should this occur, you will need to remove the saved login credentials through the following steps:

 
1) When Safari is in the foreground click on the menu Safari --> Preferences
2) Click on the icon AutoFill on the toolbar
3) Click on the button “Edit..." close to User names and password


4) Locate the line related to the Account Management web site and select it
5) Click on the button “Remove
6) Close and reopen Safari and you should be now able to log in . Upon log in you will be prompted whether to save user/pass again for the website. Please answer “Never for this website” or "Not now".

 

When and how should I increase the memory allocation for TWS?

Übersicht: 
Java Virtual Machine memory allocation

The Trader Workstation is a Java-based application. As any other Java applications, it executes within a Java virtual machine (JVM) which manages the interactions between the program and the underlying Operating System (OS).

The memory (RAM) which is allocated by the operating system to the JVM constitutes the heap space. That is the area where all the class instances and arrays needed by the application are allocated. The heap space is created when the JVM is started and it is dynamically freed-up by the Garbage Collector (GC), the Java memory manager. When the need arises, the Garbage Collector is invoked to free up the heap space by unloading Java classes and other code structures no longer used by the application.

If the heap space is undersized, the Garbage Collector may not be able reclaim memory at the needed pace or may have to be called too often, draining the processor (CPU) resources. When this happens, the application may slow down, be unresponsive or even crash completely.

To ensure a smooth TWS run, it is therefore sometimes necessary to change the memory allocation, according to the layout complexity and the needs of the application itself.

Background: 
In which case I should change the TWS memory allocation?
If your TWS layout contains a considerable number of elements (Analytical/Trading Tools, Chart windows, News panels, Watchlists, Layout tabs...) and your platform is slow or poorly responsive, you may want to increase the memory allocation in order to achieve better performances. If your TWS freezes or crashes, we also recommend increasing the heap space as the first corrective action to attempt. 
 
How much memory should I allocate to TWS?
In general we recommend to start with a conservative memory allocation and test the TWS performances with that set up. If the performances improvement is less noticeable then expected or not yet satisfactory, you can switch gradually to higher values until you find the best fit for your platform.
Please consider the following:
  • The memory you allocate to the TWS has to be available on your system. For details, please see Note 1. Allocation values above 2048 are not supported by 32-bit OS. For details, please see Note 2. 
Considering the above, we suggest to initially reserve 1.5 GB of system RAM the TWS, as explained in the guide below.
This amount of free memory is usually available on any modern computer and should be a good fit for most of the cases. Should you still notice slowness, freezing or crashes during the TWS execution, you can raise the value to 1792.
In any case, we do not recommend to set the value above 2048 since this will produce an unnecessary overhead and may thus even decrease the overall performances of the application.

 

 
How can I change the memory allocation for the TWS?

Please follow one of the links below for the instructions, according to the Operating System and TWS release you are using

 
     Any Operating System
 
     B.1 Your Operating System is Windows      
     B.2 Your Operating System is Mac OS

 

 

 

A. TWS version 972 and higher

The steps below are valid for all Operating Systems
1) In the TWS, click on the top menu File (or Edit if you are using Classic TWS) and select Global Configuration...

2) On the left side menu of the Global Configuration panel, click on General

3) In the panel on the right side, in the Memory Allocation field, replace the existing value with 1536

4) Click on Apply and then on OK

5) Shut down the TWS

6) Launch the TWS with a double click on the Desktop shortcut Trader Workstation (Should you receive an error message, please see Note 3.
 

Back to top 

 

 

B. TWS versions previous to 972

B.1 Your Operating System is Windows

1) Close TWS in case it is running

2) On your keyboard, press WIN+R (the WIN key is the key with the windows flag located on the left side of tour keyboard,  between the keys CTRL and ALT) 
3) Type C:\Jts\tws.vmoptions and Click OK
4) Should the system ask you which program to use to open the file, select Notepad and click OK
5) Cut the line -Xmx768m and paste it below the line ### Keep on update
6) Change then the value of the parameter Xmx from 768 to 1536
7) Save the changes by clicking on the top menu File --> Save
8) Close the file clicking on the X icon on the right side of the toolbar
9) Launch the TWS with a double click on the Desktop shortcut Trader Workstation (Should you receive an error message, please see Note 3.
 
 

Back to top 

 

 

B.2 Your Operating System is Mac OS
 
1) Close the TWS if it is running
 
2) Use the Spotlight search (the magnifier glass on the top right of your Desktop) to find the file tws.vmoptions
Normally the file is located within the Jts folder (a subfolder of your home folder)

3) On the Spotlight results panel, click on tws.vmoptions to open it. Should the system ask you how to open this file, click Choose Application... select  a text editor (TextEdit, Smultron, TextWrangler...) of your choice and click Open
 
 
4) Locate the line -Xmx768m. Cut it and paste it below the line ### Keep on update
 
6) Modify the value 768 in to 1536
 
7) Save and close the file

8) Launch the TWS with a double click on the Desktop shortcut Trader Workstation (Should you receive an error message, please see Note 3.
 

 Back to top 

 

 

Notes

 

1. Available system RAM
In order to check the amount of available system RAM on your computer, you can:
 - on Windows: use the key combination CTRL+SHIFT+ESC to start the Task Manager, click on the tab Performance and look for the "Available" Physical Memory. This will tell you the amount of unoccupied RAM in MB (1024 MB = 1GB)
 
 
- on Mac OS: Open Finder, go to Application --> Utilities and open Terminal. In the terminal type the command:
sudo purge
and press Enter. The system may ask you to enter your Mac user password. Enter the password. Once the command has completed, type the following command:
top -l 1| grep PhysMem
The "unused" value will tell you the amount of unoccupied RAM in MB (1024M = 1GB)

 

 

 2. Limitations of 32-bit Operating Systems
Please notice that 32-bit Operating Systems can normally only address a maximum of 2 GB of RAM per process (see table below for details). Because of this OS architecture limitation, if you have a 32-bit OS, the maximum memory allocation for the TWS must not exceed 2048 Mb.

 

3. Error: "Could not create the Java Virtual Machine"
This error may be displayed upon TWS startup if you set the memory allocation to a value higher than the available RAM of your system or if you set it higher than 2048 on a 32-bit Opertaing System. To overcome the error, you would need to decrease the memory allocation to a lower value using this procedure
 

Back to top 

 

SSL Schwachstelle ("Heartbleed Bug") Fragen und Antworten

WAS IST DAS PROBLEM? WAS IST "HEARTBLEED"?

Die aufgezeigte Schwachstelle der Open Source Version der SSL und der TLS Protokolle erlaubt einer unautorisierten Person das Lesen von Passwörter und Kodierungsschlüssel im Speicher des Servers.

WAS IST SSL?

Dies ist ein in der Netzwerkommunikation angewendetes Protokoll, welches dem Rechner die Instruktionen gibt wie Daten Ver- und Entschlüsselt werden.

IST IB VON "HEARTBLEED" BETROFFEN?

Es werden keine Auswirkungen erwartet.

Die wenigen IB Servers, welche die betroffene Version von OpenSSL hatten, wurden sofort mit einem Sicherheitsupdate geschützt als die Schwachstelle identifiziert wurde.

IST ES SICHERER SLS IN DIESER SITUATION ZU BENUTZEN?

Das Sicherheits Login System fügt Ihren Zugangsdaten eine zusätzliche Sicherheitsebene hinzu. Der Benutzername und das Passwort sind so nicht mehr die einzige Gefahrenabwehr gegen einen unauthorisierten Zugang.

Das benutzen des Sicherheitsgeräts für die Einwahl zu Ihrem Konto garantiert, dass Sie die einzige Person sind welche Zugang zu Ihrem Konto hat.

SOLL ICH MEIN PASSWORT ÄNDERN?

Durch die zusätzlichen Sicherheitsvorkehrungen welche Interactive Brokers getroffen hat ist Ihr Password von dieser aufgezeigten Schwachstelle nicht betroffen.

Das regelmässige Ändern Ihres Passwortes ist grundsätzlich eine gute Sicherheitsmassnahme, Sie müssen diese aber aufgrund der gegenwärtigen Ereinisse nicht unbedingt anwenden. 

How to install the Offline version of Trader Workstation (TWS) on a Windows PC

IMPORTANT NOTE: if you were previously storing your TWS settings to the cloud (by keeping the checkbox Use/Store Settings on Server on the TWS login screen activated), you can now recover those settings after TWS has been installed. If this is the case, it is important that, immediately after the TWS installation, before you login the first time, you remember to activate again the checkbox Use/Store Settings on Server on the login screen of the TWS. You can find more details here.

In this tutorial we describe the TWS installation using the Internet Explorer browser,  which is installed by default on every Windows PC. If you prefer to use another browser (such as: Mozilla Firefox or Google Chrome) please take into account that the disposition and/or the content of the messages appearing during the first three steps might slightly differ.

How to install Offline TWS Latest:

  1. Open the page www.ibkr.com in your browser, then click on the menu Technology --> TWS Software

  1. Scroll down the page, until you find the button for OFFLINE TWS LATEST. Click on it.
    Offline TWS Latest Installation 
     
  2. Below Offline TWS Latest for Windows, click the button DOWNLOAD

  3. At the bottom of your browser, a pop-up Security Warning bar will appear, click Run.Security Warning Bar - click RUN
  1. The Installation Wizard will now initialize, click Next>
    Installation Wizard - Next
  1. After the Installation completes, click Finish
    Installation Wizard - click Finish
     
  2. A TWS icon will now appear on your desktop. Double-click it to launch the Login box. Please notice that the icon will inlclude the actual build number (Build #) of the TWS you installed. Therefore you could see Trader Workstation 960 or Trader Workstation 961 etc.
    Trader Workstation Icon - Double-click to launch.

 

Recovering your Settings

  1.  Launch the TWS. Once the login screen has loaded, tick the checkbox Use/Store Settings on ServerCheck the box "Use/Store Settings on server"
     
  2. Enter your username and password and click Login. The TWS will now attempt to download your settings stored on the cloud and load them into the TWS
    Enter Username and Password then proceed to login
     

 

How to install the Offline version of Trader Workstation (TWS) on a Mac OS

IMPORTANT NOTE: if you were previously storing your TWS settings to the cloud (by keeping the checkbox Use/Store Settings on Server on the TWS login screen activated), you can now recover those settings after TWS has been installed. If this is the case, it is important that, immediately after the TWS installation, before you login the first time, you remember to activate again the checkbox Use/Store Settings on Server on the login screen of the TWS. You can find more details here.

In this tutorial we describe the installation using Safari, which is installed by default on every Mac computer. If you prefer to use another browser (such as: Mozilla Firefox or Google Chrome) please take into account that the disposition and/or the content of the messages appearing during the first three steps might slightly differ.

How to install Offline TWS Latest:

  1. Open the page www.ibkr.com in your browser, then click on the menu Technology--> TWS Software

 

  1. Scroll down the page, until you find the button OFFLINE TWS LATEST. Click on it
    Offline TWS Latest Installation 
     
  1. Below Offline TWS Latest for Mac, click the button DOWNLOAD

  1. Click on your Download Folder to see list of available files. Double-click the disk image file tws-latest-standalone-macosx-x64.dmg 
    Download Folder - double-click tws-latest-standalone-macosx-x64.dmg
  1. The operating system will now mount the disk image file onto your desktop
    Wait till the tws disk image file mounts to your desktop
  1. Double-click the Trader Workstation icon to initiate the installerDouble-click the Trader Workstation icon to initiate the installer
  1. Click Open to confirm and start the installation for TWS
    Click Open to confirm and start installation
  1. The Installation Wizard will now initialize, click Next>
    TWS Installation Wizard - Next
     
  1. After the installation completes, click Finish
    TWS Installation Wizard - Click Finish
  1. A TWS icon will now appear on your desktop. Double-click it to launch the Login box. Please notice that the icon will inlclude the actual build number (Build) of the TWS you installed. Therefore you could see Trader Workstation 960 or Trader Workstation 961 etc.
    Click the TWS icon to launch TWS

Recovering your Settings

  1.  Launch the TWS. Once the login screen has loaded, tick the checkbox Use/Store Settings on ServerCheck the box "Use/Store Settings on Server"
     
  2. Enter your username and password and click Login. The TWS will now attempt to download your settings stored on the cloud and load them into the TWS

    Enter your username and password then proceed to login

Syndicate content