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.17

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.17
File Size Uploaded Provenance Actions
thetadata-1.0.17.tar.gz 43.3 kB With provenance Details for thetadata-1.0.17.tar.gz

Built distribution (wheel)

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

Total release size: 87.9 kB

Release files / thetadata-1.0.17.tar.gz

Download URL thetadata-1.0.17.tar.gz
Size 43.3 kB
Tags Source
SHA-256 checksum
How to use checksums
048884e7dc28e304b668698b6a321717b6ec6525a7fef57cfa83ee84e148ff39
BLAKE2b-256 checksum
How to use checksums
8c0b9fa53c010c335a200aaf683b1f278cd6141f9893b2c20c94acef175dbd09
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 Oct 30, 2026.

Transparency log

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

Download URL thetadata-1.0.17-py3-none-any.whl
Size 44.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a43a2fe0fc4896047b9287a9cbf725214386566e3adf930523e5f8aeabf81fea
BLAKE2b-256 checksum
How to use checksums
fe5c24aaae12bc2bde3e66dda1bfed0c03dc26b5a00c2058402e6174b6cb1799
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 Oct 30, 2026.

Transparency log

Security for thetadata 1.0.17

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.17.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 Oct 30, 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.17 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