numin-client 0.1.0

Python SDK for the Numin Financial Market Analysis API

Numin Python SDK

Python client library for the Numin Financial Market Analysis API.

Installation

pip install numin

Quick Start

from numin import Numin

client = Numin(api_key="numin_xxxxx")

# Get a projection for SPY
projection = client.projections.single_ticker(
    ticker="SPY",
    timeframe="daily",
    start_date="2026-01-15",
)
print(projection)

client.close()

Authentication

Pass your API key directly or set it as an environment variable:

# Option 1: Pass directly
client = Numin(api_key="numin_xxxxx")

# Option 2: Environment variable
# export NUMIN_API_KEY=numin_xxxxx
client = Numin()

Usage

Projections

from numin import Numin

client = Numin(api_key="numin_xxxxx")

# Single ticker
result = client.projections.single_ticker(
    ticker="SPY",
    timeframe="daily",
    start_date="2026-01-15",
)

# Multiple tickers, same timeframe
results = client.projections.multi_ticker(
    tickers=["SPY", "QQQ", "AAPL"],
    timeframe="daily",
    start_date="2026-01-15",
)

# Multiple tickers, multiple timeframes
results = client.projections.multi_ticker_multi_timeframe(
    tickers=["SPY", "AAPL"],
    timeframes=["daily", "1hour", "5min"],
    start_date="2026-01-15",
)

Harmonics

harmonics = client.harmonics.single_ticker(
    ticker="SPY",
    timeframe="daily",
    start_date="2026-01-15",
    bars=20,
    comprehensive=True,
    use_harmonic=False,
)

Market Data

bars = client.market_data.get(ticker="SPY", timeframe="daily")

Reports

# Download report and save to file
report_bytes = client.reports.download(
    ticker="SPY",
    timeframe="daily",
    start_date="2026-01-15",
    file_path="reports/SPY_daily.docx",
)

# Or just get the bytes
report_bytes = client.reports.download(
    ticker="SPY",
    timeframe="daily",
)

Async Usage

import asyncio
from numin import AsyncNumin

async def main():
    async with AsyncNumin(api_key="numin_xxxxx") as client:
        projection = await client.projections.single_ticker(
            ticker="SPY",
            timeframe="daily",
            start_date="2026-01-15",
        )
        print(projection)

asyncio.run(main())

Error Handling

from numin import Numin, NotFoundError, BadRequestError, AuthenticationError

client = Numin(api_key="numin_xxxxx")

try:
    result = client.projections.single_ticker(
        ticker="INVALID",
        timeframe="daily",
        start_date="2026-01-15",
    )
except NotFoundError as e:
    print(f"Data not found: {e.message}")
except BadRequestError as e:
    print(f"Invalid request: {e.message}")
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")

Configuration

client = Numin(
    api_key="numin_xxxxx",
    base_url="http://localhost:8000",  # Custom base URL
    timeout=180.0,                     # Request timeout in seconds (default: 120)
    max_retries=3,                     # Max retries on failure (default: 2)
)

Context Manager

# Sync
with Numin(api_key="numin_xxxxx") as client:
    result = client.projections.single_ticker(...)

# Async
async with AsyncNumin(api_key="numin_xxxxx") as client:
    result = await client.projections.single_ticker(...)

Valid Timeframes

daily, weekly, monthly, 1min, 5min, 10min, 15min, 30min, 1hour, 2hour, 4hour