pip install schwaby

Every endpoint Schwab publishes, an order builder that produces JSON Schwab accepts, and a streaming client that turns this:

{'key': 'AAPL', '1': 421.55, '2': 421.60, '3': 421.58}

into this:

{'key': 'AAPL', 'BID_PRICE': 421.55, 'ASK_PRICE': 421.60, 'LAST_PRICE': 421.58}

Synchronous and asyncio over the same interface. Python 3.10+.

What is schwaby?

Charles Schwab publishes a trading API: REST endpoints for quotes, option chains, price history, accounts and orders, plus a websocket for real-time data. It is a capable API, and a raw one.

Raw in specific ways:

schwaby is the Python layer over all of that. One method per endpoint, with the legal parameter values as enums. An order builder that assembles Schwab's JSON from named parts, plus ready-made templates for the orders and option strategies most people place. A streaming client that logs in, matches responses to requests, and relabels every message before your handler sees it. Token refresh handled and written to disk.

Everywhere it can, it gets out of the way: you pass raw values and get back the raw httpx2 response, to interpret however you like. Anything you can do with hand-rolled HTTP you can do here, with less of it.

Why use it

Wrapping the tedious parts is table stakes. What follows is what schwaby does differently — and, more to the point, what each one costs you when it is missing.

The detail behind each:

Prices go out exactly as written

set_price takes a string or a decimal.Decimal and refuses a float, because a float cannot represent most prices exactly and converting one has to round somewhere. 8.2 * 100 is 819.9999999999999; truncate that and you have sent an order a cent low, with nothing anywhere to say so. Making the caller decide the rounding is the only version of this that cannot be silently wrong.

A token file that survives a crash

Token writes go to a temporary file and are renamed into place, so a process killed mid-refresh leaves either the old token or the new one — never a half-written file that can only be repaired by sitting down at a browser.

client.token_age() tells you how long you have before Schwab's seven-day refresh window closes, counted from the original authorization rather than the last refresh, which is the number that actually governs expiry.

A stream that reports what it swallowed

A websocket client has to absorb some failures: a handler that raised, a response to a request nobody is waiting for any more, a frame that will not parse. Absorbing them quietly makes a broken feed look like a slow one.

add_error_handler hands you every one of them as an exception object, so a stalled strategy can tell the difference between a quiet market and a stream that stopped working an hour ago.

Errors that name the actual fault

A rejected order carries Schwab's own explanation, not just a status code. A missing package is reported as a missing package, not as a callback server that exited. A stream request the server accepts but never answers raises ResponseTimeoutError instead of waiting forever behind a keepalive that is still cheerfully replying to pings.

Enums for every parameter

Every endpoint Schwab publishes has a method, and every endpoint's legal parameter values are enums on the client — so a misspelled projection or an invalid order duration fails immediately in Python, where you can see which line did it.

Sixty seconds in

1. Authenticate. A browser opens, you log in, and the token is written to disk and refreshed for you from then on.

from schwaby.auth import easy_client

c = easy_client(
        api_key='YOUR_API_KEY',
        app_secret='YOUR_APP_SECRET',
        callback_url='https://127.0.0.1:8182',
        token_path='/path/to/token.json')

2. Ask for data. You get back the raw httpx2 response.

r = c.get_price_history_every_day('AAPL')
r.raise_for_status()
candles = r.json()['candles']

3. Place an order from a template, without touching Schwab's order JSON.

from schwaby.orders.equities import equity_buy_limit
from schwaby.utils import find_account_hash

account_hash = find_account_hash(c.get_account_numbers().json(), '123456789')
c.place_order(account_hash, equity_buy_limit('AAPL', 10, '210.50'))

The price is a string on purpose — see Prices go out exactly as written.

4. Stream quotes, with fields you can read.

import asyncio
from schwaby.streaming import StreamClient

async def main():
    stream = StreamClient(c)
    await stream.login()

    stream.add_level_one_equity_handler(
            lambda msg: print(msg['content'][0]['ASK_PRICE']))
    await stream.level_one_equity_subs(['AAPL', 'MSFT'])

    while True:
        await stream.handle_message()

asyncio.run(main())

New here? The getting started guide walks through registering an app with Schwab and getting your first token.

What it covers

The documentation is worth reading even if you end up calling the API directly. Schwab's own portal is behind a login, so for much of this API those pages are the most accessible description of how it actually behaves.

Installing

pip install schwaby

That is the whole install. Python 3.10 and up, no extras to remember.

The distribution and the package are both schwaby.

import schwaby

schwaby and schwab-py install side by side without interfering. They ship different packages, so you can have both installed and import whichever you mean --- useful if you want to compare the two against the same account.

One exception: if you are upgrading from schwaby 3.0.3 or earlier and schwab-py is also installed, run pip install --force-reinstall schwab-py afterwards. Those versions shipped a package called schwab as well, so uninstalling one takes files the other needs --- silently, and import schwab goes on succeeding until the first submodule you use.

Getting help and contributing

Bug reports, questions, suggestions and patches all go to the repository: open an issue or a pull request.

Where this came from

schwaby began from alexgolec/schwab-py, an excellent MIT-licensed library by Alex Golec that gave this project its shape — the endpoint coverage, the order builder, the streaming field tables. Most of the code here is still his, his copyright notice is retained unchanged, and the licence is the same MIT one he chose.

It became a separate project for a practical reason rather than a philosophical one. This client runs systematic strategies against funded accounts, and that use imposes requirements a general-purpose wrapper has no particular reason to prioritise — the guarantees under Why use it above, most of which needed changes to existing behaviour rather than additions on top of it.

Those changes were offered upstream first. They were not taken up, so rather than run an ever-growing private patch set against someone else's release schedule, they were consolidated here and this became its own project with its own release line.

License

schwaby is released under the MIT license.

Copyright is shared: © 2023 Alex Golec for the original work, © 2026 Tom Hirt for the changes since. Alex's notice is retained in full, as the licence requires and as the work deserves.

Disclaimer. schwaby is an unofficial API wrapper, in no way endorsed by or affiliated with Charles Schwab or any associated organization. Read and understand the terms of service of the underlying API before using it.

The software is provided as is, without warranty of any kind. The author, the maintainer and every contributor accept no responsibility or liability for any loss, damage, missed trade, unintended order, or any other consequence whatsoever arising from its use — financial or otherwise, foreseeable or not. Using it against a funded account is entirely at your own risk. See LICENSE for the binding text, and the caution at the top of this file for what it means in practice.