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

Authentication ​

The library authenticates with your thetadata.net account. You can authenticate with an API key or with your account email and password.

API Key ​

Minimum Version Required

API key authentication requires the Python library to be version 1.0.9 or later.

You can generate an API key from your user portal.

There are three ways to provide your API key.

Option 1: Pass the API Key Directly ​

python
from thetadata import ThetaClient

client = ThetaClient(api_key="your_api_key_here")

Option 2: Environment Variable ​

Set your API key as an environment variable named THETADATA_API_KEY:

bash
# On Linux/macOS
export THETADATA_API_KEY="your_api_key_here"

# On Windows (Command Prompt)
set THETADATA_API_KEY=your_api_key_here

# On Windows (PowerShell)
$env:THETADATA_API_KEY="your_api_key_here"
python
from thetadata import ThetaClient

client = ThetaClient()

Option 3: .env File ​

Create a .env file containing your API key:

text
THETADATA_API_KEY="your_api_key_here"

The client loads .env from the current directory by default, or you can point it at a specific file with dotenv_path:

python
from thetadata import ThetaClient

client = ThetaClient(dotenv_path="/path/to/.env")

Priority Order

When more than one authentication method is available, the client uses this order: an explicitly passed creds_file, then the API key (the api_key argument or the THETADATA_API_KEY environment variable, including values loaded from a .env file), then email and password arguments, then the default creds.txt credentials file.

Credentials (Email and Password) ​

If you prefer to authenticate with your account email and password, 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 ThetaClient

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

Option 3: Specify a Credentials File Path ​

python
from thetadata import ThetaClient

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

TIP

Passing creds_file explicitly overrides API key discovery, so use it only when you want to force email/password authentication from a specific file.

Quick Start ​

python
from datetime import date

from thetadata import ThetaClient

client = ThetaClient()

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 ThetaClient

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

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

python
from thetadata import ThetaClient

polars_client = ThetaClient()
pandas_client = ThetaClient(
    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:

  • ThetaClient(dataframe_type="polars") returns polars.DataFrame
  • ThetaClient(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.

Staging Environment ​

To connect to the staging environment instead of production, pass mdds_type="STAGE":

python
from thetadata import ThetaClient

client = ThetaClient(mdds_type="STAGE")

You can also set it via environment variable, without changing your code:

bash
export THETADATA_MDDS_TYPE=STAGE

Sharing a session across environments

A client created with existing_authorized_client inherits the environment of that client automatically. You can still override it by passing mdds_type explicitly.

Logging ​

Enable logging to see authentication details and request information:

python
import logging

from thetadata import ThetaClient

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

What's Next? ​

Browse the Python Library section to see all available endpoints.