Streaming Client

A wrapper around the TD Ameritrade Streaming API. This API is a websockets-based streaming API that provides to up-to-the-second data on market activity. Most impressively, it provides realtime data, including Level Two and time of sale data for major equities, options, and futures exchanges.

Here’s an example of how you can receive book snapshots of GOOG (note if you run this outside regular trading hours you may not see anything):

from tda.auth import easy_client
from tda.client import Client
from tda.streaming import StreamClient

import asyncio
import json

client = easy_client(
        api_key='APIKEY',
        redirect_uri='https://localhost',
        token_path='/tmp/token.json')
stream_client = StreamClient(client, account_id=1234567890)

async def read_stream():
    await stream_client.login()
    await stream_client.quality_of_service(StreamClient.QOSLevel.EXPRESS)

    def print_message(message):
      print(json.dumps(message, indent=4))

    # Always add handlers before subscribing because many streams start sending
    # data immediately after success, and messages with no handlers are dropped.
    stream_client.add_nasdaq_book_handler(print_message)
    await stream_client.nasdaq_book_subs(['GOOG'])

    while True:
        await stream_client.handle_message()

asyncio.run(read_stream())

This API uses Python coroutines to simplify implementation and preserve performance. As a result, it requires Python 3.8 or higher to use. tda.stream will not be available on older versions of Python.

Use Overview

The example above demonstrates the end-to-end workflow for using tda.stream. There’s more in there than meets the eye, so let’s dive into the details.

Logging In

Before we can perform any stream operations, the client must be logged in to the stream. Unlike the HTTP client, in which every request is authenticated using a token, this client sends unauthenticated requests and instead authenticates the entire stream. As a result, this login process is distinct from the token generation step that’s used in the HTTP client.

Stream login is accomplished simply by calling StreamClient.login(). Once this happens successfully, all stream operations can be performed. Attemping to perform operations that require login before this function is called raises an exception.

async StreamClient.login(websocket_connect_args=None)

Official Documentation

Performs initial stream setup:

Fetches streaming information from the HTTP client’s get_user_principals() method
Initializes the socket
Builds and sends and authentication request
Waits for response indicating login success

All stream operations are available after this method completes.

Parameters:: websocket_connect_args – dict of additional arguments to pass to the websocket connect call. Useful for setting timeouts and other connection parameters. See the official documentation for details.

Setting Quality of Service

By default, the stream’s update frequency is set to 1000ms. The frequency can be increased by calling the quality_of_service function and passing an appropriate QOSLevel value.

async StreamClient.quality_of_service(qos_level)

Official Documentation

Specifies the frequency with which updated data should be sent to the client. If not called, the frequency will default to every second.

Parameters:: qos_level – Quality of service level to request. See QOSLevel for options.

class StreamClient.QOSLevel(value)

Quality of service levels

EXPRESS = '0': 500ms between updates. Fastest available

REAL_TIME = '1': 750ms between updates

FAST = '2': 1000ms between updates. Default value.

MODERATE = '3': 1500ms between updates

SLOW = '4': 3000ms between updates

DELAYED = '5': 5000ms between updates

Subscribing to Streams

These functions have names that follow the pattern SERVICE_NAME_subs. These functions send a request to enable streaming data for a particular data stream. They are not thread safe, so they should only be called in series.

When subscriptions are called multiple times on the same stream, the results vary. What’s more, these results aren’t documented in the official documentation. As a result, it’s recommended not to call a subscription function more than once for any given stream.

Some services, notably Equity Charts and Futures Charts, offer SERVICE_NAME_add functions which can be used to add symbols to the stream after the subscription has been created. For others, calling the subscription methods again seems to clear the old subscription and create a new one. Note this behavior is not officially documented, so this interpretation may be incorrect.

Un-Subscribing to Streams

These functions have names that follow the pattern SERVICE_NAME_unsubs. These functions send a request to disable the symbols of a streaming data for a particular data stream. They are not thread safe, so they should only be called in series.

When unsubscribing to services with symbols, the service behaves such that the initial set of subscribe symbols minus the set of unsubscribe symbols – as a result you get set difference and the set of symbols that were subscribe but is not in unsubscribe will continue to publish to your handler.

It’s known but not confirmed that if you unsubscribe from all streams, TD will close your stream if there are no other activities in 20 seconds. Please refer to this comment : https://github.com/alexgolec/tda-api/pull/256#issuecomment-939194648 for Case: When no services are subscribed for 20 seconds - verify the last 2 messages from td

Registering Handlers

By themselves, the subscription functions outlined above do nothing except cause messages to be sent to the client. The add_SERVICE_NAME_handler functions register functions that will receive these messages when they arrive. When messages arrive, these handlers will be called serially. There is no limit to the number of handlers that can be registered to a service.

Handling Messages

Once the stream client is properly logged in, subscribed to streams, and has handlers registered, we can start handling messages. This is done simply by awaiting on the handle_message() function. This function reads a single message and dispatches it to the appropriate handler or handlers.

If a message is received for which no handler is registered, that message is ignored.

Handlers should take a single argument representing the stream message received:

import json

def sample_handler(msg):
    print(json.dumps(msg, indent=4))

Data Field Relabeling

Under the hood, this API returns JSON objects with numerical key representing labels:

{
    "service": "CHART_EQUITY",
    "timestamp": 1590597641293,
    "command": "SUBS",
    "content": [
        {
            "seq": 985,
            "key": "MSFT",
            "1": 179.445,
            "2": 179.57,
            "3": 179.4299,
            "4": 179.52,
            "5": 53742.0,
            "6": 339,
            "7": 1590597540000,
            "8": 18409
        },
    ]
}

These labels are tricky to decode, and require a knowledge of the documentation to decode properly. tda-api makes your life easier by doing this decoding for you, replacing numerical labels with strings pulled from the documentation. For instance, the message above would be relabeled as:

{
    "service": "CHART_EQUITY",
    "timestamp": 1590597641293,
    "command": "SUBS",
    "content": [
        {
            "seq": 985,
            "key": "MSFT",
            "OPEN_PRICE": 179.445,
            "HIGH_PRICE": 179.57,
            "LOW_PRICE": 179.4299,
            "CLOSE_PRICE": 179.52,
            "VOLUME": 53742.0,
            "SEQUENCE": 339,
            "CHART_TIME": 1590597540000,
            "CHART_DAY": 18409
        },
    ]
}

This documentation describes the various fields and their numerical values. You can find them by investigating the various enum classes ending in ***Fields.

Some streams, such as the ones described in Level One Quotes, allow you to specify a subset of fields to be returned. Subscription handlers for these services take a list of the appropriate field enums the extra fields parameter. If nothing is passed to this parameter, all supported fields are requested.

Interpreting Sequence Numbers

Many endpoints include a seq parameter in their data contents. The official documentation is unclear on the interpretation of this value: the time of sale documentation states that messages containing already-observed values of seq can be ignored, but other streams contain this field both in their metadata and in their content, and yet their documentation doesn’t mention ignoring any seq values.

This presents a design choice: should tda-api ignore duplicate seq values on users’ behalf? Given the ambiguity of the documentation, it was decided to not ignore them and instead pass them to all handlers. Clients are encouraged to use their judgment in handling these values.

Unimplemented Streams

This document lists the streams supported by tda-api. Eagle-eyed readers may notice that some streams are described in the documentation but were not implemented. This is due to complexity or anticipated lack of interest. If you feel you’d like a stream added, please file an issue here or see the contributing guidelines to learn how to add the functionality yourself.

Enabling Real-Time Data Access

By default, TD Ameritrade delivers delayed quotes. However, as of this writing, real time streaming is available for all streams, including quotes and level two depth of book data. It is also available for free, which in the author’s opinion is an impressive feature for a retail brokerage. For most users it’s enough to sign the relevant exchange agreements and then subscribe to the relevant streams, although your mileage may vary.

Please remember that your use of this API is subject to agreeing to TDAmeritrade’s terms of service. Please don’t reach out to us asking for help enabling real-time data. Answers to most questions are a Google search away.

OHLCV Charts

These streams summarize trading activity on a minute-by-minute basis for equities and futures, providing OHLCV (Open/High/Low/Close/Volume) data.

Equity Charts

Minute-by-minute OHLCV data for equities.

async StreamClient.chart_equity_subs(symbols)

Streaming Client

Use Overview

Logging In

Setting Quality of Service

Subscribing to Streams

Un-Subscribing to Streams

Registering Handlers

Handling Messages

Data Field Relabeling

Interpreting Sequence Numbers

Unimplemented Streams

Enabling Real-Time Data Access

OHLCV Charts

Equity Charts

Futures Charts

Level One Quotes

Equities Quotes

Options Quotes

Futures Quotes

Forex Quotes

Futures Options Quotes

Level Two Order Book

Equities Order Books: NYSE and NASDAQ

Options Order Book

Time of Sale

Equity Trades

Futures Trades

Options Trades

News Headlines

Account Activity

Troubleshooting

ConnectionClosedOK: code = 1000 (OK), no reason Immediately on Stream Start

Streaming Account ID Doesn’t Match Token Account

Multiple Concurrent Streams

ConnectionClosedError: code = 1006 (connection closed abnormally [internal])

Your Handler is Too Slow

JSONDecodeError

`ConnectionClosedOK: code = 1000 (OK), no reason` Immediately on Stream Start

`ConnectionClosedError: code = 1006 (connection closed abnormally [internal])`