polypoll-sdk 0.2.3
Unified SDK for prediction market data aggregation across Polymarket, Kalshi, Manifold, Metaculus, and PredictIt
License: MIT
Requires Python: >=3.9
Keywords: forecasting, kalshi, manifold, metaculus, polymarket, prediction-markets, predictit, sdk, trading

# PolyPoll SDK

Unified SDK for prediction market data aggregation across multiple platforms.

## Supported Platforms

- **Polymarket** - Crypto prediction markets on Polygon
- **Kalshi** - US regulated prediction markets
- **Manifold Markets** - Play-money forecasting
- **Metaculus** - Expert forecasting
- **PredictIt** - US political markets

## Installation

```bash
pip install polypoll-sdk

# With REST API server support
pip install polypoll-sdk[server]

# With all optional dependencies
pip install polypoll-sdk[all]
```

## Quick Start

```python
import asyncio
from polypoll_sdk import PolyPollSDK

async def main():
    # Initialize SDK (no API keys needed for core features)
    sdk = PolyPollSDK()

    # Get markets from all platforms
    markets = await sdk.get_all_markets()
    print(f"Found {len(markets)} markets")

    # Get markets from specific platform
    polymarket = await sdk.get_markets(platform="polymarket")

    # Search for markets
    trump_markets = await sdk.search_markets("trump")

    # Group markets by event across platforms
    groups = await sdk.get_grouped_markets(min_similarity=80.0)
    print(f"Found {len(groups)} unique events across platforms")

    # Detect arbitrage opportunities
    arbitrage = await sdk.get_arbitrage_opportunities()
    for opp in arbitrage[:5]:
        print(f"Arbitrage: {opp.profit_pct:.1f}% profit")
        print(f"  {opp.strategy}")

asyncio.run(main())
```

## Features

### Layer 1: Data Aggregation

```python
# Get all markets from all platforms
markets = await sdk.get_all_markets()

# Get markets from specific platform
kalshi = await sdk.get_markets(platform="kalshi")

# Search markets by keyword (uses fuzzy matching)
crypto = await sdk.search_markets("bitcoin", platforms=["polymarket", "kalshi"])
```

### Layer 2: Cross-Platform Matching

```python
# Find markets on other platforms similar to a given market
similar = await sdk.get_similar_markets(
    market_id="abc123",
    platform="polymarket",
    min_similarity=70
)

for match in similar:
    print(f"{match.market.platform}: {match.similarity_score:.0f}%")
```

### Layer 3: Market Grouping (Group ID System)

Automatically group markets representing the same event across different platforms:

```python
# Get all markets grouped by event (80% similarity threshold)
groups = await sdk.get_grouped_markets(min_similarity=80.0)

for group_id, markets in groups.items():
    platforms = set(m.platform for m in markets)
    if len(platforms) > 1:  # Cross-platform group
        print(f"\nGroup: {group_id}")
        for m in markets:
            print(f"  [{m.platform}] {m.title} ({m.yes_price:.0%})")

# Get markets by specific group ID
trump_markets = await sdk.get_markets_by_group("politics_2024_trump_election_a3f2c1")

# Get grouping statistics
stats = sdk.get_grouping_stats()
print(f"Cross-platform groups: {stats['cross_platform_groups']}")
```

**Group ID Format:** `{category}_{year}_{topic_slug}_{hash[:6]}`
- Example: `politics_2024_trump_election_a3f2c1`

### Layer 4: Arbitrage Detection

```python
# Find cross-platform arbitrage opportunities
opportunities = await sdk.get_arbitrage_opportunities(
    min_profit=1.0,  # Minimum 1% profit
    min_similarity=80  # High similarity threshold
)

for opp in opportunities:
    print(f"{opp.profit_pct:.1f}% profit: {opp.strategy}")
```

### Layer 5: AI Research (Coming Soon)

```python
# Coming in future release:
# research = await sdk.deep_research("Will GPT-5 be released?")
# ai_odds = await sdk.get_ai_odds(market_id="...")
```

### Layer 6: Validation (Coming Soon)

```python
# Coming in future release:
# validation = await sdk.validate(question="Will BTC hit $100k?")
# status = await sdk.check_status(market_id="...")
```

## REST API Server

Deploy the SDK as a standalone REST API service:

```bash
# Install with server support
pip install polypoll-sdk[server]

# Run the server
polypoll-server

# Or with uvicorn directly
uvicorn polypoll_sdk.server:app --host 0.0.0.0 --port 8080
```

### API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /` | API info |
| `GET /health` | Health check |
| `GET /markets` | Get all markets |
| `GET /markets/{platform}` | Get markets from platform |
| `GET /search?q={query}` | Search markets |
| `GET /groups` | Get grouped markets |
| `GET /groups/{group_id}` | Get markets by group ID |
| `GET /groups/stats` | Get grouping statistics |
| `GET /similar/{market_id}` | Find similar markets |
| `GET /arbitrage` | Detect arbitrage opportunities |

### Example API Calls

```bash
# Get all markets
curl http://localhost:8080/markets

# Search for markets
curl "http://localhost:8080/search?q=trump&limit=10"

# Get grouped markets
curl "http://localhost:8080/groups?min_similarity=80"

# Find arbitrage opportunities
curl "http://localhost:8080/arbitrage?min_profit=1.0"
```

## UnifiedMarket Schema

All markets are normalized to a common schema:

```python
@dataclass
class UnifiedMarket:
    # Core
    platform: str       # polymarket, kalshi, etc.
    market_id: str
    title: str
    url: str

    # Pricing (0-1)
    yes_price: float
    no_price: float

    # Cross-Platform Grouping
    group_id: Optional[str]  # e.g., "politics_2024_trump_election_a3f2c1"

    # Volume
    volume: float
    volume_24h: float
    liquidity: Optional[float]

    # Status
    status: MarketStatus  # open, closed, resolved
    is_resolved: bool
    close_time: Optional[datetime]

    # Metadata
    category: Optional[str]
    description: Optional[str]
    image_url: Optional[str]
```

## Environment Variables

```bash
# Optional API keys
EXA_API_KEY=your-exa-key        # For AI research (coming soon)
GROQ_API_KEY=your-groq-key      # For AI research (coming soon)
KALSHI_API_KEY=your-kalshi-key  # For Kalshi private data

# Server configuration
HOST=0.0.0.0
PORT=8080
```

## Development

```bash
# Clone repository
git clone https://github.com/OpenOracleWeb3/polypoll-sdk.git
cd polypoll-sdk

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install with all dev dependencies
pip install -e ".[all]"

# Run tests
pytest

# Run server in development
uvicorn polypoll_sdk.server:app --reload
```

## License

MIT