Home
Version 1.0
A C# TD Ameritrade Broker Plug-In for Zorro.
Copyright © 2020. Clyde W. Ford. All rights reserved.
Significant financial risks accompany the use of this
plug-in to trade securities and other financial instruments.
USE AT YOUR OWN RISK.
TDAmTrade is a broker plug-in for Zorro, allowing the Zorro trading engine to communicate with TD Ameritrade through the TD Ameritrade REST API. This plug-in is free for non-commercial use. With it, you can use Zorro to automatically trade stocks, ETFs and options with a TD Ameritrade brokerage account.
Please note that you cannot trade indices (except through ETFs), futures, future options, or currency pairs (Forex) using this plug-in. The TD Ameritrade API does not allow for the trading of these financial instruments at the present time.
For the purpose of this plug-in and its license the term "non-commercial use" means any use of this plug-in, without monetary charge, by a single individual only for that individual's trading of stocks and other financial instruments through the TD Ameritrade REST API. The term "commercial use" means any use of this plug-in by one party (the first party), where a monetary fee is charged to other parties for using the plug-in separately, or as a component of other software provided by the first party, to trade stocks and other financial instruments through the TD Ameritrade REST API.
The following Zorro broker methods are implemented:
- BrokerOpen
- BrokerLogin
- BrokerBuy2
- BrokerSell2
- BrokerAsset
- BrokerAccount
- BrokerHistory2
- BrokerTrade
- BrokerTime
BrokerCommands:*
- GET_COMPLIANCE (Set NFA compliance, TD Ameritrade is fully NFA compliant)
- GET_POSITION (Required for some Z-strategies)
- GET_OPTIONS (Retrieve an option chain for an underlying asset)
- SET_SYMBOL (Set the current asset symbol)
- SET_COMBO_LEGS (For combination option orders)
*NOTE: The BrokerStop method is not implemented.
Supplemental BrokerCommands:
- SHOW_RESOURCE_STRING (Show a globalized resource string from the plug-in)
- REVIEW_LICENSE (Display the plug-in license and force re-acceptance)
- GET_ASSET_LIST (Retrieve a list of subscribed to assets)
- GET_TEST_ASSETS (Get the test assets included in the Settings file. See Setting file for more.)
- SET_VERBOSITY (Set the diagnostic verbosity level. See Verbosity level for more.)
- SET_TESTMODE (Set whether the plug-in is in testing mode.)
- SET_SELL_SELL_SHORT (Set what to do if selling more shares of an asset than owned)
- SET_LANGUAGE (Set the language used by the plug-in. See the section on globalization for more.)
See the section of this documentation on supplemental broker commands for a description of these commands.
In order to use this plug-in with Zorro, several DLLs need to be manually copied from the Lib folder of this GitHub project to the Zorro Plugin folder.
| In Lib Folder As | Copied to Zorro Plugin Folder As | Description |
|---|---|---|
| TDAmeritrade.dll | TDAmeritrade.dll | Main broker plug-in |
| Microsoft.Data.Sqlite* | Microsoft.Data.Sqlite | Microsoft Sqlite ADO.NET library |
| sqlite3.dll | sqlite3.dll | Native Sqlite 3 library |
*NOTE: Microsoft.Data.Sqlite must be version 1.1.1.
Below is a view of the Zorro plug-in folder after the required files have been copied there:
Please read through the entire documentation before attempting to use the plug-in.
The plug-in is written entirely in C#. The codebase is extensively documented making modifications easy for any programmer with a background in the C# language.
Prior to using this plug-in, the user should create a TD Ameritrade brokerage account funded with a minimum of USD $2000.00. See https://www.tdameritrade.com to open a new account. This account should have margin and option privileges.
Once a TD Ameritrade account is opened, the user needs to create a developer application and obtain a consumer key (secret key) for that developer application. This is an essential step. The plug-in will not operate without a consumer key, and a consumer key cannot be obtained without first creating a developer application.
Obtaining a consumer key is an essential step in using this Broker Plug-In. A consumer key is entered into the User ID input textbox of the LogIn section of the Zorro window. Without a consumer key this plug-in will not work. Follow these steps to create a consumer key.
Go to the TD Ameritrade Developer Home Page at: https://developer.tdameritrade.com/ and click the Register link on the right-hand side of the tool bar.
After clicking this link a pop-up window with a registration form will appear. Fill out all fields of that form. NOTE: The checkbox for accepting the Developer License Agreement may be invisible or hidden in the middle of the link to accept the agreement. In either case, clicking on the blue-highlighted link will also cause the checkbox to be checked.
After filing out the form, click on the blue button at the bottom left-hand part of the form that is labeled Create new account. You will next be taken to a login form that asks for your username and password. NOTE: The username and password asked for here is not the username and password of your TD Ameritrade brokerage account. It is the username and password of your developer account.
But at this point you do not have a password for your developer account. So, click Forgot your password? at the bottom of the form.
You will next be taken to a page with a form where you will enter your username or e-mail address and report the CAPTCHA image that you see. Click the blue button marked E-mail new password.
You will then receive an e-mail message with a link that, when clicked, takes you to your profile page on the TD Ameritrade Developer site. Enter a password of your choosing (that complies with the required guidelines) and add or modify any other information that you wish.
Once you have entered that password, and made any changes, click the blue button at the bottom left of the page marked Save and login as XXX, where XXX is your username.
You will then go to a page which confirms that the changes you just made have been saved. On the tool bar of this page click the link which reads My Apps.
The next page shows you have no apps but gives you a chance to Add a New App. Click that button.
On the Add App page you are next shown, enter information about you app.
NOTE: The name of the app can only be 15 characters with no spaces. Also, use the callback URL, http://127.0.0.1.
Place any descriptive information about your app in the textbox for the purpose. Then click the blue Create App button at the bottom left of the form.
You will now see a page which confirms that you have created you Developer App. Click on the name of the application you just created.
Finally, you will be shown a page with your Consumer Key. Copy that key and save it in a safe place. You will need your consumer key to use this TD Ameritrade Plug-In. Along with your TD Ameritrade account number, the consumer key allows access to your account to enter trades and move money. This is why you must keep this consumer key safe.
You need to create a Settings file to hold several application settings this broker plug-in requires. The settings file is located at: ../Zorro/Data/tda.json. Use Notepad or any text-editor of your choosing a create a new Settings file with the following data:
{
// Your TD Ameritrade account currency units
"currency" : "USD",
// Your TD Ameritrade account number
"tdaAccountNum" : "NNNNNNNNN",
// The default language resource file
"langResx" : "en-US",
// The testing asset symbols separated by commas (change to suit your needs)
"testAssets": "GRPN,HUSA,LLEX,ZOM"
}The following data that must be present in the Settings file:
- currency - The account current (USD, EUR, JPY, etc).
- tdaAccountNum - Your TD Ameritrade Account Number. This is not your consumer key.
- langResx - The default language resource file (see Globalization for a list of languages currently supported by the plug-in and for language specifications).
- testAssets - The ticker symbols for assets that are used by the plug-in for self-diagnostic testing. hh NOTE: You can use typical C# comments in the Settings file and those lines will be ignored. Any other files related to this plug-in found in the Data directory should not be removed or altered, or the plug-in might not operate.
If you have not done so already, copy all required DLLs to the Zorro plug-in directory at ../Zorro/Plugin. Open the Zorro executable to bring up the main trading window. See the previous section Copy DLLs for further information on which DLLs need to be present in the Zorro PlugIn folder.
Once the DLLs have been copied to the Zorro PlugIn folder, open the main Zorro trading window.
Make sure that you:
- Select the TD Ameritrade broker plug-in from the drop down list of plug-ins
- Select Demo the first time you run Zorro with this plug-in
- Enter your Consumer Key in the User ID field of the Login area of the window
- Select any trading script such as Z8
NOTE: TD Ameritrade does not have a true Demo mode. The API does not support "paper trading." Placing the Zorro trading engine in Demo mode, and selecting the TD Ameritrade broker plug-in, causes the plug-in to authenticate the user and run through a number of self-diagnostic tests. YOU MUST USE DEMO MODE THE FIRST TIME YOU RUN ZORRO WITH THIS PLUG-IN.
LANGUAGE SPECIFICATION: If you wish for the plug-in to provide messages in a language different from the default language enter the consumer key as: consumer key##language specification (the consumer key followed by two number signs followed by the language specification). For example 12345ABC##es represents as consumer key of 12345ABC and a language of es (standard Spanish). See Globalization for a list of languages currently supported by the plug-in and for language specifications.
After clicking the Trade button, you will be asked to accept the license for this plug-in. This plug-in is available free, as non-commercial open-source software. The license is governed by the GNU LPL 3.0 license, with the addition of the Commons Clause restriction for non-commercial use and several addenda found at the end of the license. If you would like to use the plug-in for commercial purposes please contact the developer via the Issues section of this GitHub project. Please scroll down to read the license, and all of its addenda, carefully before clicking the I Accept button.
After accepting the plug-in license, you will see a TD Ameritrade authentication login window pop-up on your screen.
Enter your username and password.
NOTE: This is the username and password of your TD Ameritrade brokerage account not the username and password of your Developer's App account. This small browser window is for entering your TD Ameritrade username and password only. If you forget your username or password DO NOT use the buttons on this small window in an attempt to retrieve them. Instead, go to https://www.tdameritrade.com attempt to log-in and retrieve your lost credentials from the full-size website.
Click the Log in button at the bottom left of the log-in form. The next screen you will see is part of a two-factor authentication system. You can choose to receive an authentication code on your cellphone, at the number you supplied when obtaining a TD Ameritrade trading account, or you can choose to answer a security question.
If you choose to receive an authentication code via your cellphone, click the Continue button and check your cellphone for that code.
If you choose to answer a security question click the Can't get the text message? link, then click the Answer a security question link. The following screen will now appear:
In the space provided, supply your answer to the security question, then click the Continue button at the bottom left of the form. An access screen will appear showing the capabilities you have on the TD Ameritrade site via the REST API.
Congratulations! You have now authenticated the Zorro TD Ameritrade plug-in. The Zorro trading engine, still in Demo mode, will continue to run through its self-diagnostic tests. When it is finished you may either consult the Zorro message window (you will probably need to expand it) or consult the log file at ../Zorro/Log/Zx_demo.log, where x is the number of the Z strategy you chose prior to pressing the Trade button.
If the self-diagnostic tests exit with a failure, try running the tests again. While testing, each plug-in method is only given one chance to succeed, while in a 'Real' trading situation it might be given several chances. Multiple failures of the self-diagnostic test implies that something is incorrect with the set-up of this plug-in. One place to check is that your SETTINGS file has been created correctly. See the Settings section of this documentation for more information about the structure of the Settings file. Another place to check is that your TD Ameritrade brokerage account is set-up correctly and has funds in it. You can also check that you have placed the three DLLs needed by the plug-in in the Zorro PlugIn folder. See the section of this documentation on copying DLLs files to the Zorro plug-in folder for more information.
NOTE: Each time you run the internal self-diagnostic test (not the script) you will be asked to log-in with your TD Ameritrade brokerage account username and password. This is normal, since part of the test process is to determine whether you can authenticate yourself with the TD REST API Developer site. For assistance with this log-in process, refer to the previous section of this documentation on authentication with your brokerage credentials.
If the self-diagnostic test was successful, you will receive an output log that looks similar to the following:
In the Scripts folder of this project you will find TDAmZorroTest.c, a Zorro script which runs another series of tests to determine how well Zorro communicates with this plug-in. The script is not a trading script nor is it sophisticated. Instead, it's a simple script that takes the testing assets you have placed in the SETTINGS file and cycles through BUYING shares of those assets at a distant LIMIT price, then exiting from those LONG positions, then SELLING shares of those assets at a distant LIMIT price, then exiting from those SHORT positions. Doing all of this twice.
Regardless of its simplicity, all of the major features of the plug-in are exercised in communication with the Zorro trading engine. This test script runs for about 10 minutes before automatically shutting down. Even when the test script is not buying or selling shares, for every tick it is still executing various broker methods To run the test script, do the following:
- Place TDAmZorroTest.c in the Zorro/Strategy folder.
- Select the Real mode for Zorro.
- Select the TDAmeritrade broker plug-in.
- Select the TDAmZorroTest script from the script drop-down.
- Examine the script in edit mode, and make any changes you deem necessary
- Press the Trade button to run the script.
- Depending upon the verbosity and diagnostics level (you can change both in the script), you will see a fair amount of information printed in the message window as the script runs.
- Make sure you allow the script to finish, or you could be in a situation where orders exist on TD Ameritrade that have not been canceled.
- When the script has finished running, check your TD Ameritrade account to double-check that no orders have been orphaned once the script ends, and that all orders have been canceled. If any orders have not been canceled, manually cancel them.
While the testing script is running, please be sure the box at the far right end of the status textbox is green. This will tell you that you are connected to TD Ameritrade.
Remember this is not a real trading script, even though many, if not most, of the plug-in's interfaces with Zorro's trading engine and TD Ameritrade will be tested.
Testing is set-up to use trades that minimize financial risk. For example, LIMIT orders at improbable limit prices are placed, then immediately canceled, to test the BUY and SELL functions of the plug-in. Assets with extremely low prices are used, so that if a trade is entered, and not canceled, it will be ordinarily for less than USD $2.00. That does not mean that testing is without financial risk. You should recognize the financial risk inherent in any use of this plug-in, and take steps, accordingly, to minimize that risk. Such steps include, but are not limited to: maintaining a low account balance while testing, making sure your account privileges are correct, and modifying the testing assets used in the SETTINGS file, so they reflect assets with acceptably low prices for you.
While both the self-diagnostic tests, and the testing script, may reveal no errors that does not guarantee that this broker plug-in will function without error or exception. Many factors (such as account privileges, account balance, asset type, and trade type) go into successful trading. It is your responsibility to determine that these factors are correct prior to entering into testing or into any live trading through this plug-in. Remember that significant financial risk may accompany the use of this plug-in to trade financial instruments, and that by using this plug-in you fully accept this risk as your responsibility alone.
Once the diagnostic tests are all successful, you may begin using this plug-in to trade in Real mode. Prior to using the plug-in in Real mode, if you are using any of the Z-strategies, be sure to read the Zorro documentation on what additional requirements, such as CSV files, those strategies need.
This plug-in implements the following broker commands which can be called from a Zorro script:
| Command Name | # | Parameters | Description |
|---|---|---|---|
| SHOW_RESOURCE_STRING | 4000 | Name of String | Show a globalized text string in the Zorro message window based on the current language. |
| REVIEW_LICENSE | 4002 | Display the plug-in license and ask for user acceptance. | |
| GET_ASSET_LIST | 4004 | Get list of assets the plug-in is currently subscribed to. | |
| GET_TEST_ASSETS | 4006 | Get the test assets included in the Settings file. See Setting file for more.) | |
| SET_VERBOSITY | 4008 | Verbosity Level | Set the diagnostic verbosity level. See Verbosity level for more. |
| SET_TESTMODE | 4010 | 1 = Enable 0 = Disable |
Entable or disable plug-in test mode. |
| SET_SELL_SELL_SHORT | 4012 | 1 = Cancel 2 = Adjust 3 = Do nothing |
Tell the plug-in what to do with a SELL order placed for more shares of an asset than user currently owns. Normally, TD Ameritrade will issue a SELL order for the shares currently owned and a SELL SHORT order for the balance of shares but will not return an order number for the SELL SHORT trade. Zorro will not be able to track this SHORT position. |
| SET_LANGUAGE | 4014 | Resource file name, i.e. "es-NZ" | Set the language used by the plug-in. The language file must exist. |
Supplemental commands are entered in a script as: brokerCommand(Command #, Parameter). See brokerCommand for more.
It is very unwise to manually trade from the same TD Ameritrade brokerage account that the Zorro trading engine is automatically trading from. Errors, with serious financial consequences, can result. For example, if you manually sell some of the shares that Zorro has bought, then Zorro issues a sell order for the shares it believes to be in your account, you will be faced with a situation where you are trying to sell more shares than you currently own. If SET_SELL_SELL_SHORT has been set at 3 (do nothing), TD Ameritrade will sell any shares that it can from the Zorro order, but it will short sell any remaining shares that are not in the account. Zorro does not receive notice of the secondary short sell order, and it may get fulfilled and the short position may be held undetected. If the underlying asset rises in value, you may be faced with significant financial losses.
If you want to manually trade on TD Ameritrade, open a new, separate brokerage account and do not allow Zorro to trade on that new account.
The TD Ameritrade/Zorro plug-in provides extensive diagnostics messaging and implements a broker command (#4008), SET_VERBOSITY, which allows the user to set the verbosity level of the diagnostic messages generated by the plug-in from a Zorro script. The verbosity level of the plug-in is similar to, but not the same as, the DIAGNOSTIC level of a script. The syntax of the SET_VERBOSITY command is:
define SET_VERBOSITY 4008
int vLevel;
.
.
.
brokerCommand(SET_VERBOSITY, vLevel)where vLevel is set to:
| Verbosity | Description of Verbosity Level |
|---|---|
| 1 | Basic. Info and Caution messages not shown. Critical, Error, and Warning messages written to log file. |
| 2 | Intermediate. Info messages not shown. Critical and Error messages shown in Zorro window. Warning and Caution messages written to log file. |
| 4 | Advanced. Critical, Error, and Warning messages shown in Zorro window. Caution and Info messsages written to log file. |
| 8 | Extensive. Other than Info messages, all messages shown in Zorro window. Info messages written to log file. |
| 16 | Extreme. All messages written to Zorro window and to log file. |
| +32 | Add time stamp of message. |
| +64 | Add originating method and line number of message. |
For example, the command brokerCommand(SET_VERBOSITY, 112) (vLevel = 16 + 32 + 64 = 112) would tell the plug-in to show all messages in the Zorro window and log file, and those messages would be prepended with a time stamp, line number, and method of origination.
This plug-in uses asset designators as described in the section IB Symbols of the Zorro Manual. Asset lists and CSV asset files must conform to these symbol designators for trades to be successful.
If you are planning to modify the plug-in, or wish to examine the plug-in's code, please first consult the section of this documentation entitled Details About the Plug-in.
This Zorro broker plug-in has the following features:
- Allow U.S. users to use a popular broker. TD Ameritrade is a well-known, large and popular broker. Many other brokers that work with Zorro do not allow U.S. customers to use their features.
- Written in C#. The code base is well-documented and free for non-commercial use to modify and adapt. Any competent C# programmer should be able to follow the code as written to modify or extend it when desired.
- Globalization. The plug-in features language support in English, German, French, and Spanish with existing language text easily modified, and new language support added through resource files.
In general, the TD Ameritrade REST API is a poorly documented interface, as any developer who writes against it soon discovers. The TD Ameritrade online guide provides few examples and the online documentation for the interface is inconsistent, incomplete, and sometimes incorrect. The ThinkOrSwim platform available to TD Ameritrade users does not employ the TD Ameritrade REST API also available to users. So, there is no opportunity to use it as a basis for understanding the REST API because the two are completely different systems. TD Ameritrade may answer questions concerning the REST API after weeks of waiting, or they may not answer questions at all. That said, this Zorro broker plug-in currently has the following limitations:
- Windows 10. The plug-in was developed and tested on a Windows 10 system. It was designed and developed to operate on a Windows system and it may not function on any other systems such as Linux, Android, or OSX.
- OPTIONS trading. TD Ameritrade imposes account requirements for OPTIONS trading. Consult your TD Ameritrade account profile to determine if it qualifies for OPTIONS trading, and to apply.
- COMBO LEG orders may only be placed for OPTIONS. Un-optioned stocks or ETFs do not qualify for COMBO LEG orders. All COMBO LEG orders must be at MARKET. No COMBO LEG OPTION orders can have any leg at LIMIT. COMBO LEG OPTION orders violating these rules will be rejected. Execute a SET_COMBO_LEGS broker command prior to placing trades for OPTIONS on a COMBO LEG order. Read more about the SET_COMBO_LEGS before trading OPTIONS in your script.
- INDEX OPTIONS cannot be traded through the TD Ameritrade REST API only options derived from single underlying equities. Those wishing to trade index options might consider trading options against ETFs related to a particular index.
- FOREX trading. Currently, the TD Ameritrade REST API does not allow for currency trading. From inspection of the JSON objects returned from API requests, it appears as though some FOREX trading capabilities are built-in. Actual FOREX trading through the API may be available at some future time.
- MUTUAL FUND trading. Many mutual funds have an initial minimum investment amount. In order to trade mutual funds your account, or your first trade order, must meet that minimum. If not, a trade order for the fund will fail. As of May 15, 2020, the plug-in does not support MUTUAL FUND trading. While the TD Ameritrade documentation states that mutual fund trading is possible, no order to BUY or SELL mutual funds has been accepted by the API. This may change at some point in the future.
- Can manage only one TD Ameritrade trading account (for multiple accounts, run multiple instances of Zorro).
- STOP MARKET and STOP LIMIT orders. The TD Ameritrade REST API appears to allow for STOP MARKET or STOP LIMIT. But as of 05/15/2020 no STOP or STOP LIMIT orders were accepted. TD Ameritrade has been notified and may resolve this matter. But as of this release of the plug-in STOP MARKET and STOP LIMIT orders will not be traded. Zorro notes on the BrokerBuy2 command state that the STOP DISTANCE included as a parameter for this command, "is not the real stop loss, which is handled by the trade engine. Placing the stop is not mandatory." Consequently, STOP MARKET and STOP LIMIT orders will not be placed by this version of the plug-in.
- FUTURES trading. Currently, the TD Ameritrade REST API does not allow for FUTURES or FUTURE OPTIONS trading. From inspection of the JSON objects returned from API requests, it appears as though some FUTURES trading capabilities are built-in. Actual FUTURES trading through the API may be available at some future time.
- Specific Exchanges. TD Ameritrade uses a SMART exchange system whereby orders are placed at the most readily available and appropriate exchange. This plug-in does not support orders directed to a specific exchange. All orders will be placed through TD Ameritrade's SMART exchange system.
This Zorro plug-in will successfully submit trade orders using the TD Ameritrade API but those orders may still fail. There are many reasons for this. Some common reasons a trade may fail are:
- Trade violates one of TD Ameritrade's many policies. Before using this plug-in, make sure you thoroughly review the TD Ameritrade documentation for your brokerage account. TD Ameritrade has a number of rules regarding the amount of money that should be present in an account at any time, for different kinds of assets, that control whether a trade order will be placed.
- Trade violates TD Ameritrade's LIMIT policies. TD Ameritrade has policies about how far away from the current Ask price a MARKET LIMIT order can be. It's not exactly clear what that distance is, but sometimes a trade order may be rejected because it falls outside of limit policies.
- Too frequent BUY and SELL orders for same asset. If you buy and sell the same asset too frequently, TD Ameritrade may flag your account as a "pattern trading" account and require a steep balance in that account along with a 90-day period during which your account will be closed to further trading. Consult the TD Ameritrade documentation for more information about "pattern trading."
- Trade placed for unsupported products. Only stocks, options, and ETFs are currently supported by the TD Ameritrade REST API. Trades placed for non-supported products will fail, even though Zorro supports such products for inclusion in asset lists.