Skip to main content

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:

  • 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

Metadata

Release files for thetadata 1.0.18

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for thetadata 1.0.18
File Size Uploaded Provenance Actions
thetadata-1.0.18.tar.gz 43.9 kB With provenance Details for thetadata-1.0.18.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for thetadata 1.0.18
File Interpreter ABI Platform Actions
thetadata-1.0.18-py3-none-any.whl Python 3 none any Details for thetadata-1.0.18-py3-none-any.whl

Total release size: 89.0 kB

Release files / thetadata-1.0.18.tar.gz

Download URL thetadata-1.0.18.tar.gz
Size 43.9 kB
Tags Source
SHA-256 checksum
How to use checksums
3381de43468d580da60a2ec6ee446553b459ac82c7b885fc6ef4a5984f45f75b
BLAKE2b-256 checksum
How to use checksums
9613d9b271a25fe085bd2887153faaae0173bf7e93a6e05fd59a3d815e8d353d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 17, 2026.

Transparency log

Release files / thetadata-1.0.18-py3-none-any.whl

Download URL thetadata-1.0.18-py3-none-any.whl
Size 45.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5ee4d60d81149437b306a2a152047a6303fe203a399ba44b452d8ddaaf39b94d
BLAKE2b-256 checksum
How to use checksums
754d9d10d875ed66082bda39752c7e3b3a0829fadef3a177e49dbf7dc159086f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 17, 2026.

Transparency log

Security for thetadata 1.0.18

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for thetadata-1.0.18.tar.gz

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 Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.18 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page