thetadata 1.0.2

Python client library for ThetaData market data APIs

thetadata-python

Python client library for accessing ThetaData market data APIs over gRPC.

This package provides a ThetaClient for querying US stock, option, and index market data from ThetaData. Results can be returned as either Polars or Pandas DataFrames.

Features

• Direct client access to ThetaData services
• Stock, option, and index endpoints
• Return data as Polars or Pandas DataFrames
• Built-in response decompression
• Simple authentication with a credentials file or explicit credentials

Requirements

• Python 3.12+
• An active ThetaData subscription

Installation

pip install thetadata

Authentication

You can authenticate in three ways.

1. Default credentials file

By default, ThetaClient() looks for ./creds.txt.

File format:

[e-mail]
your-password

from thetadata import ThetaClient

client = ThetaClient()

2. Explicit credentials

from thetadata import ThetaClient

client = ThetaClient(email="[e-mail]", password="your-password")

3. Environment variable

Set THETADATA_CREDENTIALS_FILE to point to your credentials file.

export THETADATA_CREDENTIALS_FILE=/path/to/creds.txt

$env:THETADATA_CREDENTIALS_FILE = "C:\path\to\creds.txt"

Quick Start

Default Polars output

from datetime import date
from thetadata import ThetaClient

client = ThetaClient()

bars = client.stock_history_eod(
    symbol="AAPL",
    start_date=date(2024, 1, 2),
    end_date=date(2024, 1, 5),
)

print(bars)

Pandas output

from datetime import date
from thetadata import ThetaClient

client = ThetaClient(dataframe_type="pandas")

quotes = client.stock_history_quote(
    symbol="AAPL",
    date=date(2024, 1, 2),
    interval="1m",
)

print(quotes.head())

Reuse authentication across clients

from thetadata import ThetaClient

polars_client = ThetaClient(dataframe_type="polars")
pandas_client = ThetaClient(
    existing_authorized_client=polars_client,
    dataframe_type="pandas",
)

Common Examples

Stock symbols

from thetadata import ThetaClient

client = ThetaClient()
df = client.stock_list_symbols()

Stock intraday OHLC

from datetime import date, time
from thetadata import ThetaClient

client = ThetaClient()
df = client.stock_history_ohlc(
    symbol="AAPL",
    date=date(2024, 1, 2),
    interval="1m",
    start_time=time(9, 30),
    end_time=time(16, 0),
)

Option chain snapshot greeks

from datetime import date
from thetadata import ThetaClient

client = ThetaClient()
df = client.option_snapshot_greeks_all(
    symbol="SPY",
    expiration=date(2025, 3, 21),
    strike="*",
    right="both",
)

Index history

from datetime import date
from thetadata import ThetaClient

client = ThetaClient()
df = client.index_history_eod(
    symbol="SPX",
    start_date=date(2024, 1, 2),
    end_date=date(2024, 1, 10),
)

DataFrame Output

ThetaClient supports two output modes:

• dataframe_type="polars" (default)
• dataframe_type="pandas"

Logging

import logging

logging.basicConfig(level=logging.INFO)

This will surface library logging, including authentication and request-related messages.

Errors

The package exposes custom exceptions in thetadata.errors:

• AuthenticationError
• NoDataFoundError

Example:

from datetime import date
from thetadata import ThetaClient
from thetadata.errors import AuthenticationError, NoDataFoundError

try:
    client = ThetaClient()
    df = client.stock_history_eod(
        symbol="AAPL",
        start_date=date(2024, 1, 1),
        end_date=date(2024, 1, 31),
    )
except AuthenticationError:
    print("Authentication failed")
except NoDataFoundError:
    print("No data returned for query")

Notes

• Some methods accept symbol: str while others expect symbol: list[str].
• Snapshot endpoints may return rapidly changing data.
• Time-based requests use datetime.date and datetime.time values.

License

Apache-2.0