ThetaData v3
Search K

Appearance

Python Library ​

The thetadata Python library provides direct access to Theta Data market data without requiring the Theta Terminal to be running. It authenticates over HTTPS, makes requests over gRPC, and returns Polars or Pandas dataframes.

No Terminal Required

Unlike the REST API, the Python library connects directly to Theta Data servers. You do not need to download or run the Theta Terminal.

Installation ​

Requires Python 3.12 or higher.

Install with pip:

bash
pip install thetadata

Or with uv:

bash
uv add thetadata

Credentials ​

The library authenticates with your thetadata.net account credentials. You can provide them in three ways.

Option 1: Credentials File ​

Create a creds.txt file with your email on the first line and password on the second:

text
your-email@example.com
your-password

The client looks for creds.txt in the current directory by default, or you can set the THETADATA_CREDENTIALS_FILE environment variable:

bash
export THETADATA_CREDENTIALS_FILE=/path/to/creds.txt

Option 2: Pass Credentials Directly ​

python
from thetadata import Client

client = Client(email="your-email@example.com", password="your-password")

Option 3: Specify a Credentials File Path ​

python
from thetadata import Client

client = Client(creds_file="/path/to/creds.txt")

Quick Start ​

python
from datetime import date

from thetadata import Client

client = Client()

symbols = client.stock_list_symbols()
print(symbols)

eod = client.stock_history_eod(
    symbol="AAPL",
    start_date=date(2024, 1, 1),
    end_date=date(2024, 1, 31),
)
print(eod)

quote = client.stock_snapshot_quote(symbol=["AAPL"])
print(quote)

Choosing Polars vs Pandas ​

The library defaults to polars.DataFrame. To use Pandas instead:

python
from thetadata import Client

polars_client = Client(dataframe_type="polars")
pandas_client = Client(dataframe_type="pandas")

You can also create two clients that share the same authenticated session:

python
from thetadata import Client

polars_client = Client()
pandas_client = Client(
    existing_authorized_client=polars_client,
    dataframe_type="pandas",
)

Why Polars?

Polars is generally the better default for larger analytical workloads because it is faster, more memory-efficient, and multithreaded.

Return Types ​

Every request method returns a dataframe rather than a raw JSON payload:

  • Client(dataframe_type="polars") returns polars.DataFrame
  • Client(dataframe_type="pandas") returns pandas.DataFrame

Each endpoint page in the Python docs shows:

  • the Python return type for the selected dataframe backend
  • the dataframe row schema derived from the API spec
  • example dataframe output when sample data has been generated

Some lower-coverage endpoints still do not have generated dataframe examples yet. Those pages still show the correct return type and schema.

Logging ​

Enable logging to see authentication details and request information:

python
import logging

from thetadata import Client

logging.basicConfig(level=logging.INFO)
client = Client()

What's Next? ​

Browse the Python Library section to see all available endpoints.