TDA API CLIENT

v1.1.0

Summary

This library is a client to use the API exposed by TD Ameritrade at https://developer.tdameritrade.com This project can also be cloned from github to use as a command line utility.

Other README files (also referenced in relevant sections below):

Installation

npm i tda-api-client

What's New

v 1.1.2 - Fixed the Get Price History API call. The query param names were wrong.

v 1.1.1 - You can now use this library without a config file, instead passing in a lightweight config object with each request.

Full version review in the Version History section at the bottom.

When testing the Saved Orders API, a 400 response code was received as well as a message that said: "Saved Orders are not supported for this account." Using the feature Ask Ted on the main website, Ted said: "If you have upgraded trading features, you're unable to save orders on the website. However, there are equivalent tools on thinkorswim Desktop, thinkorswim Web, and thinkorswim Mobile." It isn't clear if this is related to the Saved Orders API. Saved orders worked fine when tested on the other platforms.

UPDATE in v1.0.2: I now understand the above to be because I have Advanced Features turned on in my account. This will also preclude you from placing complex orders, like 1 TRG OCO. This boggles my mind. So again, you have to turn OFF Advanced Features in your account in order to unlock some API capabilities. I haven't yet completely mapped that.

Watchlists are a little wonky. When creating a watchlist, it can be retrieved with the API, but it doesn't appear in Thinkorswim unless it is restarted.

Usage

You may make unauthenticated requests (which typically give delayed data) for some endpoints, but generally requests must be authenticated.

DO THIS FIRST: You must know your authentication information

For a primer on Auth, see authREADME.md.

For making unauthenticated requests, you must know your client_id, also known as apikey, which looks like: FIEJ33342@AMER.OAUTHAP

For making authenticated requests, you must additionally have a refresh_token.

Using this library, there are three ways to make requests:

1. Unauthenticated requests

For the methods that support it, apikey can be passed in as a config option. Example:

const tdaclient = require('tda-api-client');

const configGetMarketHrs = {
        market: 'OPTION',
        date: '2021-03-02',
        apikey: 'FIEJ33342@AMER.OAUTHAP'
};

const hrs = await tdaclient.markethours.getSingleMarketHours(configGetMarketHrs);

A list of methods allowing unauthenticated requests are listed below.

2. Authenticated requests with a config object

The difference here is that you'd pass in your client_id and refresh_token in as config.authConfig like this:

const tdaclient = require('tda-api-client');

const configGetMarketHrs = {
        market: 'OPTION',
        date: '2021-03-02',
        authConfig: {
            "refresh_token": "SrgS0QJK",
            "client_id": "FIEJ33342@AMER.OAUTHAP",
        }
};

const hrs = await tdaclient.markethours.getSingleMarketHours(configGetMarketHrs);

3. Authenticated requests with a config file

To use this method, you must have a file at {project root}/config/tdaclientauth.json. Please copy the example file from this library's config/ folder using the below command:

cp ./node_modules/tda-api-client/config/tdaclientauth.json ./config/tdaclientauth.json

OR copy this json and replace the values with your own:

{
    "refresh_token":"REPLACEME",
    "client_id":"EXAMPLE@AMER.OAUTHAP"
}

Now that you've got your auth file ready...

Here's a little sample code for a taste of how to use this thing. This is using auth from a file.

const tdaclient = require('tda-api-client');

await tdaclient.orders.cancelOrder({orderId: 123, accountId: 456});
await tdaclient.watchlists.deleteWatchlist({watchlistId: 4242, accountId: 456});
const hours = await tdaclient.markethours.getSingleMarketHours({index: tdaclient.markethours.MARKETS.EQUITY, date: '2020-09-20'});

The hierarchy is pretty flat. Under the root object, named "tdaclient" in the above example, we have (asterisks indicate unauthenticated requests are possible):

accounts
- getAccount
- getAccounts
authentication
- getAuthentication
- refreshAuthentication
instruments
- getInstrument **
- searchInstrument **
markethours
- getSingleMarketHours **
- getMultipleMarketHours **
movers
- getMovers **
optionchain
- getOptionChain **
orders
- placeOrder
- replaceOrder
- cancelOrder
- getOrder
- getOrdersByAccount
- getOrdersByQuery
pricehistory
- getPriceHistory **
quotes
- getQuote **
- getQuotes **
savedorders
- createSavedOrder
- deleteSavedOrder
- getSavedOrderById
- getSavedOrders
- replaceSavedOrder
transactions
- getTransaction
- getTransactions
userinfo
- getUserPreferences
- getStreamerSubKeys
- getUserPrincipals
- updateUserPreferences
watchlists
- createWatchlist
- deleteWatchlist
- getWatchlist
- getWatchlistsSingleAcct
- getWatchlistsMultiAcct
- replaceWatchlist
- updateWatchlist

Each of the 13 first-level objects has their functions, as listed, which correspond 1-to-1 with an API endpoint, and possibly some useful ENUMS.

These aren't strictly organized like the API on the TD Developer site. For example, their site has Accounts, Orders, and Saved Orders grouped together.

Documentation

Mine

I've used JSDoc to add comments to each enum and function that wraps an API. I also converted this to TypeScript and will be adding in better and better type support.

You can look in the samples/ folder to see code samples, which has a simple usage of each of the functions. That folder also has an inputJSON folder with sample inputs.

Theirs

You can find the documentation for how the API endpoints work at https://developer.tdameritrade.com

Copies of those pages are also available locally in apidocsarchive/

Command Line Tool

You can run this as a standalone command line tool by cloning the project and running

node ./cli_index.js

< > indicates a required positional argument

[ ] indicates an optional positional argument

Delve into each command to see the command options.

# This will show all top-level commands
$ node ./cli_index.js
cli_index.js <command>

Commands:
  cli_index.js accounts <command>      Get your account info for one or all linked accounts
  cli_index.js auth <command>          Perform some authentication operations
  cli_index.js instruments <command>   Search for an instrument with a text string, or get an instrument by CUSIP
  cli_index.js hours <command>         Get market hours
  cli_index.js movers <command>        Get market movers
  cli_index.js options <command>       Get option chain info
  cli_index.js orders <command>        Manage your trades
  cli_index.js pricehistory <command>  Get price history info in the form of candles data
  cli_index.js quotes <command>        Get quotes for one or more symbols
  cli_index.js savedorders <command>   Manage your saved orders
  cli_index.js trans <command>         Retrieve transaction history
  cli_index.js userinfo <command>      Get and update user information such as preferences and keys
  cli_index.js watchlist <command>     Manage your watchlists

Options:
  --version  Show version number                                                                                           [boolean]
  --help     Show help                                                                                                     [boolean]

Not enough non-option arguments: got 0, need at least 1

# This will show all commands nested under hours
$ node ./cli_index.js hours
cli_index.js hours <command>

Get market hours

Commands:
  cli_index.js hours get <date> <markets> [apikey]    Get market open hours for a specified date <date> (e.g. 2020-09-18) and a
                                                      comma-separated set of <markets> from EQUITY, OPTION, FUTURE, BOND, or FOREX,
                                                      e.g. "EQUITY,OPTION". Including your optional <apikey> makes an
                                                      unauthenticated request.
  cli_index.js hours getone <date> <market> [apikey]  Get market open hours for a specified date <date> and a single <market> from
                                                      EQUITY, OPTION, FUTURE, BOND, or FOREX. Including your optional <apikey> makes
                                                      an unauthenticated request.

Options:
  --version  Show version number                                                                                           [boolean]
  --help     Show help                                                                                                     [boolean]

Not enough non-option arguments: got 0, need at least 1

# This will show how to use the particular command
$ node ./cli_index.js hours get
cli_index.js hours get <date> <markets> [apikey]

Get market open hours for a specified date <date> (e.g. 2020-09-18) and a comma-separated set of <markets> from EQUITY, OPTION,
FUTURE, BOND, or FOREX, e.g. "EQUITY,OPTION". Including your optional <apikey> makes an unauthenticated request.

Options:
  --version  Show version number                                                                                           [boolean]
  --help     Show help                                                                                                     [boolean]

Not enough non-option arguments: got 0, need at least 2

For now, all responses get logged to the console, for better or for worse, so you may want to pipe the output to a file, especially for big output. Here is an example:

node ./cli_index.js hours get 2020-12-02 FUTURES > hours.json

Version History

v1.1.0 - (Feb 27, 2021) Converted to TypeScript, added in ability to make authenticated requests through the config object for each method, instead of requiring a config file.

v1.0.3 - (Feb 24, 2021) Removed logging statements and fixed auth

v1.0.2 - (Feb 23, 2021) Fixed issues in 1.0.1 as well as fixed unauthenticated requests both through regular api and cli api

v1.0.1 - (Feb 21, 2021) Attempt to fix http issues by using axios; unpublished due to bugs in auth

v1.0.0 - (Sept 18, 2020) Initial publish of library

Roadmap (no particular order)

This was originally built for a particular set of use cases, and those will continue to be the driver for future project direction. In no particular order:

Improved type support for Typescript
Data structures for the input and output types, like Order, for easy parsing
Helper methods for creating a properly formatted JSON input object (order, watchlist, etc.) given input params.
Streaming data support for daemon apps.

Another project is planned which will leverage this library in order to make a command line app, a shell, for trading. The goal is to be able to type "buy 10 F" instead of clicking a bunch of things in Thinkorswim or having to write a clunky Order JSON object.

Support

Visit the github page https://www.github.com/Sainglend/tda-api-client, write a comment, or open a pull request! Find me on Reddit: u/sainglend Email: sainglend@gmail.com

License and Disclaimer

tda-api-client : a client library for the TD Ameritrade API

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

I am not a licensed financial advisor, and use of this software, as well as any interactions with me or comments made by me, whether in private or public, should not constitute financial advice or trading advice.

gpearson100/tda-api-client