PTL Trader Manual
Contents |
Introduction
PTL Trader is a free, open source automated trading system solution for pair trading. See more information here. You can use it to execute your pair trading strategy portfolios you have built using the Pair Trading Lab website Portfolio Manager.
Requirements
- 64bit operating system (Microsoft Windows, Linux or macOS) compatible with Java 8 (or newer) is required
- 64-bit Java 8 (1.8) or newer is required. The installer checks this.
- PTL Trader requires Interactive Brokers TWS or IB Gateway, providing an API access. Server IB API version 66 or newer is required.
Installation & Setup
In order to use PTL Trader application, you must obtain PTL Trader API keys first. They are used to authenticate the application running at your side against our server, so the application is able to retrieve your portfolio and settings and send back your trading stats (unless confidential mode is used). There are two keys needed - the Access Key and the Secret Key
Steps to do:
- Go to the Pair Trading Lab website and login to your account
- Go to Menu -> PTL Trader -> Setup & Download (if you don't see this, you are not a Premium Member or your membership has expired) (see the screenshot)
- Error creating thumbnail: Unable to save thumbnail to destination
- If you don't have API access keys yes, you will see a button Generate PTL Trader keys for me now. Press it, it will generate your keys and setup your PTL Trader access immediately
- When you already have API keys generated, you can see your Access Key already. In order to see your Secret Key press the link saying "click here to see my Secret Key".
- Now, you can download the PTL Trader MSI installer by clicking the button Download PTL Trader. You download should start.
- Check software requirements above
- Run the installer to install the PTL Trader application. The installer checks the Java version, so it won't allow you to install if you don't have Java or if it is outdated
- Run PTL Trader from your start menu
- Go to the Settings tab and fill in your access keys. By pressing Connect button it should authenticate and connect to our website and download your portfolios you created in Portfolio Manager
- Start IB Trading Workstation or IB gateway, enable socket-base API access in settings
- In PTL Trader settings, check the IB ABI Client Id and Port if matches what you need. Client Id can be 1 if PTL Trader is the only application connecting to your API. Default port numbers are 7496 for TWS connection and 4001 for IB Gateway connection.
- Press Connect. It should connect to your IB API now.
- You are ready now to setup your portfolios and account bindings.
Firewall Remark: PTL Trader communicates with PTL server using two TCP ports - 443 (https) and 5671 (amqps). If you use a firewall, please make sure that outbound connections are enabled for these ports, otherwise PTL Trader will not work!
Multiple Instances & Autostart
PTL Trader supports running in multiple instances on the same machine, but each instance must run under a different configuration profile and must connect to different IB account. The default configuration profile name is default, which is used when no command line arguments are used. If you want to start the application using different profile, you have to manually specify the profile in command line arguments. Argument syntax is this:
<profile name> [autostart]
If autostart is specified, PTL Trader will automatically connect to both Pair Trading Lab site and IB account, as long all credentials are already configured in the Settings panel. You can use autostart feature e.g. for automatic system start after your VPS reboots. Please note that the autostart is always the second argument, so if you want to use autostart with default profile, command line arguments will look like this:
default autostart
Good practice is to create file shortcuts, where you can specify command line arguments directly like on the screenshot on the right. PTL Trader installation comes with two default application shortcuts:
- PTL Trader - profile: default, no autostart
- PTL Trader (second instance) - profile: secondary, no autostart
For instance, you can use the first one for regular trading, the second one for paper trading. You can of course edit those default shortcuts yourself, e.g. to enable autostart feature.
Again - you need to worry about profiles only if you use two or more PTL Trader instances on the same computer. If you run them on different machines, you can stick with default profile.
Remark: if you run multiple instances on the same computer, each instance must connect to a different IB TWS/Gateway instance!
Confidential Mode
By default, PTL Trader is sending the complete trade history to Pair Trading Lab. Although we guarantee we never disclose any of that data to any 3rd side and we try to maintain as highest level of security as possible, we fully understand this may still be a concern for same users.
So if you really won't want to disclose your trading results to our side, you can use the Confidential Mode. While enabled, your sensitive data never leaves the PTL Trader application and your computer. However, there are certain implied limitations:
- whenever you restart PTL Trader, you trading history is gone
Confidential Mode can be enabled in the Setting tab.
Interface
Portfolios
The purpose of PTL Trader is to allow you to execute portfolios of pair trading strategies in real-time. Those portfolios are not defined in PTL Trader itself - they are stored on the Pair Trading Lab website under your account. You manage your strategy portfolios using the Portfolio Manager application which is available from the menu as long you log in and as long you are a Premium Member.
Please read more about portfolios here: Pair Trading Lab Portfolios and about strategies & algorithms here: Pair Trading Lab Algorithms & Strategies
Binding Portfolio To IB Account
When connected to your account, PTL Trader has an access to you portfolios and loads them from your PTL Trader account. Then you can bind particular portfolio to your IB account and start the autotrading of all pair strategies. There is no way to define portfolios or strategies inside PTL Trader - you have to manage them at the website. There is some limited management functionality on PTL Trader though - you can delete strategies and edit some portfolio and strategy properties also from the PTL Trader side.
In order to auto-trade the portfolio, you have to bind it to the IB account. You do this in the PTL Trader:
- start PTL Trader and connect to both PTL and IB API
- portfolio list will appear in the left section
- click on the portfolio you want to bind
- in the right side, go to the Settings tab
- you can see the Bind to account section with select and Bind button
- select the IB account you want to trade with and press the Bind button
- after confirmation, the portfolio will bind to the account you selected and the automated trading will start right away
Beware: Trading may start immediately after you bind the portfolio to an account!
Remark: Standard license allows you to trade two IB accounts using PTL Trader software and your account. So you can bind just two of your portfolios to an IB account.
Unbinding Portfolio
If you don't want to auto-trade some portfolio anymore on a particular IB account (e.g. you want to move the portfolio from paper account to live account), you may want to unbind it. There is a button for that in the portfolio management section.
Important: If you unbind a portfolio from an IB account, nothing happens to positions already opened on the account! They will just become ignored by the PTL Trader. You are responsible to deal with those positions in TWS yourself!
Updating Portfolios in PTL Trader
Very important: every time you make changes in portfolio at the website (change parameters, add pairs to portfolio), the update is never automatically synchronized to PTL Trader. You must explicitly synchronize them yourself by going into File menu and selecting Update Portfolios From PTL.
On the other hand, if you make changes on the PTL Trader side, these updates are synced to the website automatically. If you have the Portfolio Manager opened in the browser, you have to press F5 to see the changes, because the web application UI is not refreshed in real-time.
Monitoring
Pair Trading Lab website offers an unique feature - it can watch your PTL Trader instances automatically for you and send a warning e-mail to you if there is something suspicious going on. How it does work? PTL Trader sends every minute its status to our website. Another software running on our side analyzes this information and may send a warning message to you if decided. Situations detected are these:
- PTL Trader instance did not report itself for more than 15 minutes - your instance does not run, your VPS is down or lost an Internet connection
- PTL Trader instance lost connection to IB API (TWS crashed and not recovered in time limit?)
- manual intervention is required for at least one pair strategy (see below for an explanation)
In order to enable monitoring for any PTL Trader instance, please follow these steps:
- Make sure you have at least once started your PTL Trader instance, for at least one minute (connected to PTL).
- Go to PTL website and login to your account
- in menu, go to PTL Trader > Monitoring.
- You should see a table of your known PTL Trader instances, identified by your computer hostname and instance profile.
- If you check the checkbox next to your instance and press Save Settings button, monitoring will start and you may get messages.
- Below you can configure an e-mail address for sending you monitoring messages, by default it is the same e-mail you have used for your registration.
Manual Intervention Requests
There are some situations which may happen on your IB account side, which cannot be automatically dealt with by PTL Trader, although it is doing the best. Some examples are these:
- you change direction of existing pair leg positions manually in TWS
- reverse split occurs on any opened instrument and the split ratio is not "clean"
In these situations, PTL Trader gets confused and does not know, what to do with the pair anymore. So it just marks the pair strategy as "requires manual intervention" and ignores the pair since then. You should just solve the situation manually (e.g. close or alter pair positions in TWS) and then you can resume trading by pressing Resume Trading button in PTL Trader.
