AlgoTraderAlgoTrader Documentation

Appendix C. Example Strategy "Pairs Trading"

The Pairs Trading strategy uses the web service to trade pairs of US equities

The main artifacts needed for the Implementation of a new Strategy are described in Chapter 4, Strategy Development.

The following list will give an overview of the specific artifacts implemented by the Pairs Trading Strategy (Note: Most of the functionality is documented via Javadoc or Esper comments):


The strategy service class providing the main trading logic


Import utility to download pairs from Pair Trading Lab and configure them in AlgoTrader


Contains all strategy configuration items


Contains the logic of the ratio model


Esper Module containing all statements for this strategy:

  • PAIR_WINDOW: Contains all current pair definitions

  • SIGNAL_WINDOW: Contains current signals (will be updated on each tick)

  • LAST_TICK, INSERT_LATEST_TICK, UPDATE_LATEST_TICK_1 & UPDATE_LATEST_TICK_2: keep track of current prices for all pairs

  • UPDATE_HISTORICAL_BARS & DAILY_RECALC: daily triggers for downloading historical data and updating entry thresholds

  • INSERT_ZSCORE: calculates the z-score for each new price update

  • INSERT_INTO_SIGNAL_EVENT & ON_SIGNAL: create and propagate SignalEvents in case an entry or exit trigger is reached


Contains default parameters used by the strategy


Contains event-types definitions (i.e. PairEvent and SignalEvent)


Contains pairsTradingParams, pairsTradingConfig, pairsTradingEngine, pairsTradingService as well as the strategy specific beans csvImporter, orderSubmissionService and pairsTradingLabNavigator.


Contains the H2 database records needed to simulate the strategy with the embedded in-memory database H2.


Contains the MySQL database records. Needs to be imported into the database before running the strategy with the MySQL database.


HTML5 and JavaScript files needed for the strategy custom web UI

To start the Strategy please see the explanations in Chapter 3, Starting AlgoTrader.

Before using the strategy please execute the following steps:

Pair Trading Lab account sign-up

Sign up for a free account at Pair Trading Lab

Create a pair portfolio

create a pair portfolio and add some pairs

Extract Portfolio ID

csvImportPortfolio needs to be extracted from the URL when clicking on pair in the PTL Trader / Portfolio Manager

To start the strategy in live trading mode on a development workstation please execute the following steps:

Git Clone

Perform a Git clone from the command line:

git clone

Import the projects pairstrading into Eclipse via File / Import / Maven / Existing Maven Projects:

Deploy MySQL data

Load the file /src/main/resources/db/mysql/mysql-data.sql into MySQL

Configure Pair Trading Lab Credentials

Inside the file the following items need to be configured. Alternatively the properties can be changed via Section 2.3, “VM Arguments”:

#{"type":"String","required":"false","label":"Pair Trading Lab Portfolio ID"}
csvImportPortfolio = xyz

#{"type":"String","required":"false","label":"Pair Trading Lab Username"}
csvImportUser = user

#{"type":"String","required":"false","label":"Pair Trading Lab Password"}
csvImportPassword = password

csvImportPortfolio needs to be extracted from Pair Trading Lab (see above)

Start the Strategy in Live Trading Mode

launch the Eclipse Run Configuration: EmbeddedStarter-pairstrading

To start the strategy in live trading mode on a productive server please execute the following steps:

Copy docker compose file

Copy the following file to the server and make changes as needed:

Configure Pair Trading Lab Credentials

inside the docker-compose.yml file update the VM_ARGUMENTS environment variable and set the correct values for csvImportPortfolio, csvImportUser & csvImportPassword:

VM_ARGUMENTS: "-DcsvImportPortfolio= -DcsvImportUser= -DcsvImportPassword="

csvImportPortfolio needs to be extracted from Pair Trading Lab (see above)

Run docker compose

Invoke the following command inside the directory where the docker-compose.yml file is located:

docker-compose up -d


Prior to starting the strategy for the very first time please start the AlgoTrader server by itself by executing the following command inside /bootstrap/launch. this will load the MySQL sample data

docker-compose up -d mysql ibgateway algotrader

The Pairs Trading strategy is equipped with a separate HTML5 management page . The page is available through the path /pairstrading.html, e.g.:



It might be necessary to fully reload the browser on first startup to show the custom widget using Ctrl + Shift + R.

The HTML5 management page provides the following controls:

  • PairInfo & Pairs: current pair definitions as downloaded from Pair Trading Lab. movingAvg and standardDev are calculated on a daily basis (by the Esper statement UPDATE_HISTORICAL_BARS) using historical closing prices

  • Signals: intraday pair values based on live data. ratio shows the current price ratio between individual instruments of a pair. zScore shows the current ratio relative to the Bollinger band around the ratio time series. When the zScore hits the zScoreEntry threshold a position is entered, and when the zScore hits the zScoreExit threshold the position is closed. If the zScore happens to be above zScoreMax (e.g. after a large overnight gap) no new position will be opened. The signal field shows the current state of a pair (i.e. LONG, SHORT, EXIT & HOLD)

  • The action Import Historical Bars is used to import historical closing prices of all instruments for the relevant look back period. This action is automatically executed once a day. In addition it can be invoked manually at any time.

  • The action Re-Calc Entry Thresholds is used to update movingAvg and standardDev based on historical data in the database. This action is automatically executed once a day. In addition it can be invoked manually at any time.

  • The action Import Pairs imports and/or update pairs from Pair Trading Lab.