schwabdev Python Wrapper

Schwabdev is a lightweight Python wrapper for the Charles Schwab API. It is designed to simplify authentication and data access while handling complex tasks like token lifecycle management.

Key features include:

• Automatic Token Management: Handles authentication and automatic token refreshes.
• Flexible Programming Models: Supports both Synchronous and Asynchronous programming patterns.
• Real-time Data Streaming: Provides streaming capabilities with customizable response handlers and automatic restarts if the streamer crashes.
• Order Management: Capabilities to place orders and retrieve order details.
• Security: Supports optional encryption for the token database.
• Market Awareness: Optional automatic starting/stopping of the streamer based on market open/close times.

The complete, detailed documentation for the schwabdev library, including setup guides, API references, and feature explanations, is hosted externally at the following URL:

https://tylerebowers.github.io/Schwabdev/

The Account Activity stream emits several key event types within the content[n]['2'] field. These events track the lifecycle of an order:

• OrderCreated: The initial creation of an order.
• OrderAccepted: The order has been accepted by the system.
• ExecutionRequested: The order is being routed for execution.
• ExecutionRequestCreated: The routing request has been initialized.
• ExecutionRequestCompleted: The routing request has finished (e.g., RouteStatus: RouteVenueAccepted).
• OrderFillCompleted: The order has been fully or partially filled.

Concurrency and Threading

• Multiple clients can run simultaneously if they share the same tokens_db file, but only one streamer can be active at a time.
• Clients are not guaranteed to be thread-safe. Use a threading lock if accessing a client from multiple threads.

API Requirements and Limits

• Required Scopes: You must have both Accounts and Trading Production and Market Data Production added to your Schwab app.
• Rate Limits (Exceeding these results in HTTP 429):
  • 120 API requests per minute.
  • 4000 order-related API calls per day.
  • 500 concurrently streamed tickers.

Logging

Schwabdev uses the standard Python logging module. Configure it using: logging.basicConfig(level=logging.INFO)

Different Schwab products deliver streaming data using different logic. Understanding this is critical for maintaining accurate local state:

• Changes (Delta updates): LEVELONE_EQUITIES, LEVELONE_OPTIONS, LEVELONE_FUTURES, LEVELONE_FUTURES_OPTIONS, and LEVELONE_FOREX. These services only stream the fields that have changed. You must merge incoming updates into your existing local data object to maintain a complete view.
• Whole Data: NYSE_BOOK, NASDAQ_BOOK, OPTIONS_BOOK, SCREENER_EQUITY, and SCREENER_OPTION. These services stream all fields for the subscribed symbols in every update.
• All-Sequence Data: CHART_EQUITY, CHART_FUTURES, and ACCT_ACTIVITY. These provide a sequence number with each response (e.g., the i'th sequence number represents the i'th candle of the day).

If you encounter SSL: CERTIFICATE_VERIFY_FAILED - self-signed certificate in certificate chain, you must install the Python certificates for your macOS installation.

Fix: Run the following command in your terminal (adjust the version number if necessary): open /Applications/Python\ 3.12/Install\ Certificates.command

You can use a Python interactive session to quickly test code snippets. The repository provides two versions:

1. Standard Playground: Run python -i playground.py for a synchronous interactive session.
2. Asynchronous Playground: Run python -i async_playground.py for an asynchronous interactive session.

To use all available API calls in schwabdev, your Schwab application must have both of the following APIs enabled:

1. Accounts and Trading Production
2. Market Data Production

The first time you run your code, you must perform an interactive login:

1. Run your script. A link will be generated in the terminal.
2. Open the link and sign in to your Schwab account.
3. Agree to the terms and select your account(s).
4. Copy the URL from your browser's address bar after the redirect and paste it back into the terminal.

To avoid hardcoding sensitive credentials in your scripts, use a .env file located in the same directory as your script. This file should store your app_key, app_secret, and callback_url.

Security Warning: Always add your .env file to your .gitignore to prevent leaking credentials when pushing code to version control systems like GitHub.

# .env file content
app_key = "Your app key"
app_secret = "Your app secret"
callback_url = "https://127.0.0.1"

For concurrent API calls, use schwabdev.ClientAsync. This client is designed to be used with asyncio.

In addition to the standard parameters available to the synchronous client, ClientAsync includes a parsed option to control whether API responses are automatically converted into Python dictionaries/lists.

import schwabdev

client = schwabdev.ClientAsync(
    app_key, 
    app_secret, 
    callback_url="https://127.0.0.1",
    tokens_db="~/.schwabdev/tokens.db",
    encryption=None,
    timeout=10,
    call_on_auth=None,
    parsed=False
)