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:
email@example.com
your-password
from thetadata import ThetaClient
client = ThetaClient()
2. Explicit credentials
from thetadata import ThetaClient
client = ThetaClient(email="email@example.com", 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:
AuthenticationErrorNoDataFoundError
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: strwhile others expectsymbol: list[str]. - Snapshot endpoints may return rapidly changing data.
- Time-based requests use
datetime.dateanddatetime.timevalues.
License
Apache-2.0
1 maintainer
Metadata
1 maintainer
Release files for thetadata 1.0.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| thetadata-1.0.12.tar.gz | 39.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| thetadata-1.0.12-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 79.2 kB
Release files / thetadata-1.0.12.tar.gz
| Download URL | thetadata-1.0.12.tar.gz |
|---|---|
| Size | 39.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5c038a36f9b44a4b17dab63a352c5754f31a7a296d21230f96df9cecab8b7f87
|
|
BLAKE2b-256 checksum How to use checksums |
de9fa8e1abcd8c771518a9d617b347193e065e4303d36d9d117c5ee920ef8fcf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / thetadata-1.0.12-py3-none-any.whl
| Download URL | thetadata-1.0.12-py3-none-any.whl |
|---|---|
| Size | 40.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d9a5f4d19d0a6e7abc9861e8aee6bba3838e3551105babf76c4e361ff233d565
|
|
BLAKE2b-256 checksum How to use checksums |
1562b7f18d6aa9f42572eb075d0d711a8fb4dd7e0578ea378f3d0a9c059f109b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency log
