# Sirius Prediction Market API

Python wrapper for the **Sirius Prediction Market API** on RapidAPI.

Access real-time prediction markets, AI-generated trading signals, market sentiment, sports odds, weather data, and cross-platform odds comparison — all from a single, zero-dependency package.

[![PyPI version](https://img.shields.io/pypi/v/sirius-prediction-api.svg)](https://pypi.org/project/sirius-prediction-api/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://pypi.org/project/sirius-prediction-api/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install sirius-prediction-api
```

## Quick Start

```python
from sirius_prediction_api import SiriusAPI

api = SiriusAPI("your-rapidapi-key")

# Check API status
print(api.health())

# Get active prediction markets
markets = api.markets()
for market in markets:
    print(market["question"], market["odds"])
```

## Get Your API Key

1. Go to [RapidAPI - Sirius Prediction Market API](https://rapidapi.com/sirius-prediction-market-api)
2. Subscribe to a plan (free tier available)
3. Copy your `X-RapidAPI-Key` from the dashboard

## Endpoints

### Free Tier

```python
api = SiriusAPI("your-key")

# Active prediction markets with odds
markets = api.markets()

# Trading signals with optional filters
signals = api.signals(limit=10, layer="L1", min_gap=0.10)

# Historical signals with outcomes
history = api.signals_history()

# Market sentiment — Fear & Greed + long/short ratios
sentiment = api.sentiment()

# Sports odds (ESPN + Kalshi)
sports = api.sports()

# Weather-related prediction data
weather = api.weather()

# Cross-platform odds comparison
odds = api.odds()
```

### Basic Tier

```python
# Bot performance — win rate, PnL, track record
performance = api.performance()

# Full trade history with entry/exit details
trades = api.trades()
```

### Pro Tier

```python
# AI brain — optimization decisions and reasoning
brain = api.brain()
```

## Signal Layers

The API provides signals from multiple detection layers:

| Layer | Source | Description |
|-------|--------|-------------|
| L1 | Price lag | Cross-platform price discrepancies |
| L2 | News | News-driven market moves |
| L3 | Weather | Weather-based predictions |
| L4 | Kalshi | Kalshi platform arbitrage |
| L5 | Sports | ESPN + Kalshi sports signals |

Filter by layer:

```python
# Only price-lag signals with at least 10% gap
signals = api.signals(layer="L1", min_gap=0.10)
```

## Error Handling

The library raises specific exceptions for different error types:

```python
from sirius_prediction_api import (
    SiriusAPI,
    SiriusAuthError,
    SiriusForbiddenError,
    SiriusRateLimitError,
    SiriusAPIError,
)

api = SiriusAPI("your-key")

try:
    brain = api.brain()
except SiriusAuthError:
    print("Invalid API key")
except SiriusForbiddenError:
    print("Upgrade your plan for this endpoint")
except SiriusRateLimitError:
    print("Rate limited — slow down or upgrade")
except SiriusAPIError as e:
    print(f"API error [{e.status_code}]: {e.message}")
```

| Exception | HTTP Code | Meaning |
|-----------|-----------|---------|
| `SiriusAuthError` | 401 | Invalid or missing API key |
| `SiriusForbiddenError` | 403 | Endpoint not in your tier |
| `SiriusNotFoundError` | 404 | Resource not found |
| `SiriusRateLimitError` | 429 | Rate limit exceeded |
| `SiriusServerError` | 5xx | Server-side error |
| `SiriusAPIError` | any | Base class for all errors |

## Configuration

```python
api = SiriusAPI(
    api_key="your-key",
    timeout=60,       # request timeout in seconds (default: 30)
)
```

## Requirements

- Python 3.8+
- **Zero dependencies** — uses only `urllib.request` from the standard library

## License

MIT
