Streaming Client

A wrapper around the Schwab streaming data 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 schwab.auth import easy_client
from schwab.client import Client
from schwab.streaming import StreamClient

import asyncio
import json

# Assumes you've already created a token. See the authentication page for more
# information.
client = easy_client(
        api_key='YOUR_API_KEY',
        app_secret='YOUR_APP_SECRET',
        callback_url='https://127.0.0.1',
        token_path='/path/to/token.json')
stream_client = StreamClient(client, account_id=1234567890)

async def read_stream():
    await stream_client.login()

    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())

Use Overview

The example above demonstrates the end-to-end workflow for using schwab.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.

Logging Out

For a clean exit, it’s recommended to log out of the stream when you’re done.

async StreamClient.logout(): Performs a logout operation on the stream. After this method is called, no further stream operations are possible. The client must be re-initialized with login() to perform further operations.

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.

Add symbols to Streams

These functions have names that follow the pattern SERVICE_NAME_add. These functions send a request to add to the list of subscribed symbols for a particular data stream.

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, symbols which were not explicitly unsubscribed remain subscribed.

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": 1715908546054,
  "command": "SUBS",
  "content": [{
        "seq": 0,
        "key": "MSFT",
        "1": 779,
        "2": 421.65,
        "3": 421.79,
        "4": 421.65,
        "5": 421.755,
        "6": 26.0,
        "7": 1715903940000,
        "8": 19859
    }]
}

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

{
  "service": "CHART_EQUITY",
  "timestamp": 1715908546054,
  "command": "SUBS",
  "content": [{
        "seq": 0,
        "key": "MSFT",
        "SEQUENCE": 779,
        "OPEN_PRICE": 421.65,
        "HIGH_PRICE": 421.79,
        "LOW_PRICE": 421.65,
        "CLOSE_PRICE": 421.755,
        "VOLUME": 26.0,
        "CHART_TIME_MILLIS": 1715903940000,
        "CHART_DAY": 19859
    }]
}

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.

Stream Statuses

Schwab’s streaming functionality is very similar to that of the former TDAmeritrade. So similar, in fact, that this module is largely a direct adaptation of the implementation developed for the older tda-api library.

As a result of this nearly direct copy-pasting, some streams may have been carried over which don’t actually work. What’s more, some streams never worked, even in tda-api, but were only implemented because some old, now-defunct documentation referred to them.

The community is in the process of making sense of this new world. You are encouraged to try and use this streaming library and report what you find back to our Discord server. We’ll be updating this page as we discover new things.

The following streams are confirmed working:

OHLCV Charts
Level One Quotes
Level Two Order Book
Screener
Account Activity

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

Logging Out

Subscribing to Streams

Add symbols to Streams

Un-Subscribing to Streams

Registering Handlers

Handling Messages

Data Field Relabeling

Stream Statuses

OHLCV Charts

Equity Charts

Futures Charts

Level One Quotes

Equities Quotes

Options Quotes

Futures Quotes

Futures Options Quotes

Forex Quotes

Level Two Order Book

Equities Order Books: NYSE and NASDAQ

Options Order Book

Screener

Screener Equity

Screener Option

Account Activity