Mode API Python SDK

A Python SDK for interacting with the Mode API.

Installation

You can install it directly from the GitHub repository.

Using pip

pip install git+https://github.com/ZeroGuacamole/mode-python-sdk.git

Install with backtesting helpers (pandas/numpy) via extras:

pip install "git+https://github.com/ZeroGuacamole/mode-python-sdk.git#egg=mode-sdk[backtest]"

Quickstart

Here's a quick example of how to use the client to fetch historical data.

1. Configuration

The client can be configured via environment variables. Create a .env file in your project root:

MODE_API_BASE_URL="http://localhost:8080" # Optional, defaults to this
MODE_API_EMAIL="your_email@example.com"
MODE_API_PASSWORD="your_secret_password"

2. Example Usage

importosfromdotenvimportload_dotenvfrommode_sdk.clientimportModeAPIClientfrommode_sdk.exceptionsimportModeAPIError# Load environment variables from .envload_dotenv()
try:
# Initialize the client. It will automatically use environment variables.client=ModeAPIClient()
# Fetch historical data for a symbolsymbol="AAPL"historical_data=client.market_data.get_historical_data(
symbol=symbol,
start_time="2023-01-01",
end_time="2023-12-31",
interval="daily"
)
print(f"Successfully fetched {len(historical_data.data_points)} data points for {symbol}.")
forpointinhistorical_data.data_points:
print(f"Date: {point.timestamp.date()}, Close: {point.close}")
exceptModeAPIErrorase:
print(f"An API error occurred: {e}")

Helpers

The models include utilities commonly used in research/backtesting pipelines.

1. Convert historical data to a pandas DataFrame (UTC index):

frommode_sdk.clientimportModeAPIClientclient=ModeAPIClient()
hist=client.market_data.get_historical_data("AAPL", "2024-01-01", "2024-01-31", "daily")
# Requires: pip install pandasdf=hist.to_dataframe()
print(df.head())

2. Convert historical data to NumPy arrays for vectorized processing:

# Requires: pip install numpyts, open_, high, low, close, volume=hist.to_numpy()

3. Quote convenience properties:

quotes=client.market_data.get_quotes(["AAPL"]).quotesq=quotes["AAPL"]
print(q.mid_price, q.spread)

Data validation and normalization

• Symbols are normalized to uppercase in Asset and HistoricalDataResponse.
• Timestamps are normalized to UTC in all models that include time fields.
• OHLCV values are validated (non-negative; high/low consistency) for HistoricalDataPoint.
• Quote validation ensures non-negative prices and ask >= bid when both are present.

Development

1. Clone the repository.
2. Create a virtual environment:

   uv venv

3. Activate the virtual environment:

   source .venv/bin/activate

4. Install dependencies:

   uv pip install -e ".[dev]"

5. Run tests:

   pytest