2 Installation and licensing

IB-Matlab requires the following in order to run:

An active account at IB

IB-Matlab will also work with IB’s Demo account, but this is not recommended: it is limited in comparison with the functionalities of a live account. To properly test IB-Matlab, we recommend using the paper-trade (simulated trading) account that you get when you open an IB account. Paper-trade accounts resemble a live account more closely than the Demo account.7

An installation of TWS and/or the IB Gateway – (normally installed together)

An installation of Matlab R2006a or a newer release

If you have an earlier release of Matlab, some API functionality may still be available on your system. Contact us (info@UndocumentedMatlab.com) for details.

The installation procedure for IB-Matlab is as follows:

Ensure that you have read and accepted the IB-Matlab license agreement.8 This step is required even for IB-Matlab trials. If you do not accept the license agreement, you cannot use IB-Matlab.

Extract the files within the installation zip file (esp. IBMatlab.jar, IBMatlab.p, IBMatlab.m) into a dedicated folder (for example: C:\IB-Matlab\). Do not place the files in one of Matlab’s installation folders.

Add the new IB-Matlab folder to your Matlab path using the path tool (in the Matlab Desktop’s toolstrip, click HOME - ENVIRONMENT - Set path… and save).9 The folder needs to be in your Matlab path whenever you run IBMatlab.

Ensure that either TWS or IB Gateway is working and logged-in to IB.

In TWS’s main menu’s Edit à Global Configuration… à API à Settings, make the following changes (the specifics depend on your TWS version):10

Enable the “Enable ActiveX and Socket Clients” checkbox

Validate the Socket port used by IB for API communication: normally 7496 or 7497 for TWS; 4001 or 4002 for Gateway. Other values can be set, but then you will need to specify the Port parameter when you use IBMatlab for the first time after each Matlab restart (see §13 below).

Specifying a Master ClientID (positive integer number) will enable IB-Matlab to access to all orders created by any API client. You could then use this in IBMatlab by specifying a ClientId parameter.11

Set the checkbox to “Create API message log file” if you wish to access such log files later on (see §14.1 below).

Ensure that the settings allow connections from localhost. If you wish to use IB-Matlab on a different computer than the one that runs TWS, add IB-Matlab machine’s IP address to the list of trusted IP addresses.

If you have recently upgraded from a 32-bit system (e.g., Windows XP) to 64 bits (e.g., Windows 7), then if you encounter some problems running IB-Matlab, this could be due to a 32-64 bit mixup in TWS.12

Unset the “Read-Only API” checkbox if you wish IB-Matlab to be able to send trade orders to IB (rather than just access IB’s data-feed).

Set the checkbox to “Send Forex market data in compatibility mode in integer units”, to avoid error messages on fractional size rules support.13

IB Gateway configuration (main menu Configure à Settings à API à Settings) is similar to the TWS configuration above. The main difference is that the “Enable ActiveX and Socket Clients” checkbox is not available in IB Gateway’s configuration, since it is always enabled for trusted IPs (this is good).14

If you are running the non-trial version of IB-Matlab, you will need to activate your license at this point, by sending us the output of the IBMatlab('license') command. See §2.1 below for licensing details.

You can now run IBMatlab within Matlab. To verify that IB-Matlab is properly installed, retrieve your current IB account information, using the following commands (which are explained in §4 below):

>> data = IBMatlab('action','account_data')
>> data = IBMatlab('action','portfolio')

If you get an error such as “IBMatlab is not activated on this computer. To fix this, send the following data…”, email us this message as plain text (not a screenshot) so we could activate your license on this computer, then retry step #8.

If you get an error such as “IBMatlab.jar not found in static Java classpath.
Please add IBMatlab.jar to classpath.txt”, then follow the steps in §2.3 below carefully, restart Matlab and retry step #8. If you still get the error, contact us.

2.1 Licensing and activation

IB-Matlab’s license uses an activation that is specific to the installed computer. This uses a unique fingerprint hash-code that is reported by the Operating System, which includes the Windows ID (on Windows systems), computer name, and the list of MAC addresses used by the computer.

Once the computer’s license is activated, the activation key is stored on the UndocumentedMatlab.com webserver. This activation key validates online whenever IB-Matlab connects to IB (i.e., at the beginning of an IB/TWS session), and once every few hours while connected. Validating the license online only takes a second or two. Since it is only done at the initial connection to TWS and once every few hours, it does not affect IB-Matlab’s run-time performance. If you have a special concern regarding the online activation, please contact us for clarifications.

A corollary of the computer fingerprint is that whenever you modify any component that affects the fingerprint, IB-Matlab will stop working. This could happen if you reinstall the operating system (OS), modify the computer name, change network adapters (e.g., switch between wifi/cellular/wired connection, or use a new USB networking device), manually modify MAC addresses, or use software that creates dynamic MACs. In such cases, you might see an error message such as the following when you try to use IB-Matlab:

Error using IBMatlab/ensureConnected
IBMatlab is not activated on this computer.

Some additional information may be presented to help you diagnose the problem.

To fix such cases, simply revert back to the original hardware/networking configuration, and then IB-Matlab will resume working. If you wish to make the configuration change permanent, then you can contact us for an activation switch to the new configuration (see the following section §2.2 for details).

Computer fingerprints are typically stable, and are not supposed to change dynamically. However, some software programs (especially on MacOS, but also sometimes on Linux/Windows) create dynamic MAC addresses and/or dynamically modify the computer name (hostname). This is then reflected in the OS-reported fingerprint, possibly causing IB-Matlab to stop working. The solution in such cases is to find a way to keep the MAC addresses and computer name static, with the same values as the activated fingerprint. The hostname can be set using the OS’s hostname command, and you can determine the nature of the OS-reported MACs as follows:

>> IBMatlab('license', 'debug',1); % partial sample output below
84A6C8EEAFED - net5 Intel(R) Centrino(R) Wireless-N 2230
B888E3E1EDD4 - eth4 Realtek PCIe GBE Family Controller

Using this output, you can determine which MAC address was changed / added / deleted, and then take the appropriate action to fix it so that the reported MACs will match the activated fingerprint. If you decide that the MACs/hostname changes are permanent, contact us to change the activated fingerprint (see §2.2 below).

The standard IB-Matlab license is for a single year from date of purchase. Additional licensing options are available; contact us for pricing information:

2- or 6-months license: these short-term licenses can be repeatedly renewed, for product evaluation or program development beyond the free trial.

1-year license: this is the standard, most popular license term.

Multi-year license: 2-year, 3-year, or 5-year extended license terms will work for much longer than the standard license year, as long as you keep your hardware and software stable and IB continues to provide its API service.

Volume (multi-computer) license: the same license as for a single computer, but when you purchase multiple licenses at once, you get a volume discount.

Site license: enables to run IB-Matlab on an unlimited number of computers within the same Windows Domain. This license does not require activation by end-users, only a single centralized activation. It supports cloud deployment, where computer hardware fingerprints (but not the domain) often change.

Deployment (compiled) license: enables to use IB-Matlab within a compiled program that runs on an unlimited number of computers. This license does not require separate activations by end-users, only a single centralized activation.

Source-code license: unlimited in duration, can be installed on an unlimited number of computers in the organization, and requires no activation. This license requires signing a dedicated NDA (non-disclosure agreement).

Bundle license: a discounted bundle of IB-Matlab and IQML (IQFeed-Matlab connector) or EODML (EODHistoricalData-Matlab connector) licenses.

You can view information about the installed IB-Matlab version as follows:

>> IBMatlab('version')
ans =
Version: 2.19
Expiry: '15-Nov-2023'
Release: '02-Dec-2022'
Install: 'C:\IB-Matlab\IBMatlab.m'

2.2 Switching activated computers

You can switch the IB-Matlab license activation between computers or computer hardware configurations (i.e., fingerprint hash-code) whenever you purchase a license renewal. For license terms of 1 year or longer, up to 2 activation switches per year are also included, at no extra cost. A handling fee will be incurred for other re-activations.

In order to change the activation fingerprint, simply email us the new configuration’s fingerprint and we will make the switch on the server-side.

Activation switches can take up to two business days to process, but typically complete within a few hours during European business hours. You will receive a confirmation email when the activation switch is complete.

2.3 Updating the static Java classpath

In IB-Matlab v1.97 and earlier, installation required adding the IBMatlab.jar file to Matlab’s static Java classpath. This is done automatically since v1.98 (1/2018). However, in very rare cases it might be needed to manually set the classpath, as detailed below:

Type the following in your Matlab command prompt:

>> edit('classpath.txt');

This will open the classpath.txt file for editing in the Matlab editor. This file includes the Java static classpath that is used in Matlab and is typically located in the %matlabroot%/toolbox/local/ folder (e.g., C:\Program Files\MATLAB\ R2011b\toolbox\local\).

Add the full path to the IBMatlab.jar file into the classpath.txt file (you may need to repeat this step whenever you install a new Matlab release on your computer). For example, on a Windows computer if the IB-Matlab files are in C:\IB-Matlab\, then the new line in the classpath.txt file should be as follows:

C:\IB-Matlab\IBMatlab.jar

You must use the full absolute filepath. So on MacOS, for example, enter /Users/John/IB-Matlab/IBMatlab.jar rather than ~/IB-Matlab/IBMatlab.jar. Similarly, you cannot use something like $matlabroot/../../IB-Matlab.jar.

When saving classpath.txt, you may get an error message saying the file is read-only. To solve this, enable write-access to this file: In Linux/Unix, run chmod a+w classpath.txt. In Windows open Windows Explorer right-click classpath.txt, select “Properties”, and unselect the “Read-only” attribute. In Windows 7/8/10 run Matlab as Administrator (right click the Matlab icon and select “Run as Administrator”) in order to be able to save the file, even when it is not read-only.

If you cannot get administrator access to modify classpath.txt, place a copy of it in your Matlab startup folder. This is the folder used when you start Matlab (type the pwd command at the Matlab command prompt to get it). Note that placing the modified classpath.txt file in your Matlab startup folder enables you to run IB-Matlab whenever you use this startup folder – so if you ever use a different Matlab startup folder, you’d will need to copy the classpath.txt file to the new startup folder. Also note that the classpath.txt file depends on the Matlab release – it will only work on your current release of Matlab, if you try to use a different Matlab release with this same startup folder, then Matlab itself (not just IB-Matlab) may fail to load. For these reasons, it is safer to update the classpath.txt file in Matlab’s default location, namely the %matlabroot%/toolbox/local/ folder.

As an alternative on some Matlab releases, create a javaclasspath.txt file in the startup folder, which just contains a single line, IBMatlab.jar’s full path.

Note: IB-Matlab may not be able to receive IB data if Java’s classpath is not set.

Restart Matlab (no need to restart the computer or to run as administrator)