numin-client 0.1.0
Python SDK for the Numin Financial Market Analysis API
License: MIT
Requires Python: >=3.9

# Numin Python SDK

Python client library for the [Numin](https://numin.com) Financial Market Analysis API.

## Installation

```bash
pip install numin
```

## Quick Start

```python
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:

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

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

## Usage

### Projections

```python
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

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

### Market Data

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

### Reports

```python
# 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

```python
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

```python
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

```python
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

```python
# 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`