polypoll-sdk 0.3.0

Unified SDK for prediction market data aggregation across Polymarket, Kalshi, Manifold, Metaculus, and PredictIt

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

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

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

# 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

# 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:

# 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

# 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)

# 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)

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

CLI Tool

Use polypoll directly from the terminal. All output is JSON for easy parsing by scripts and AI agents.

# List all markets
polypoll markets
polypoll markets --platform polymarket --limit 5

# Search markets by keyword
polypoll search "Trump"
polypoll search "bitcoin price" --limit 10 --platform kalshi

# Detect cross-platform arbitrage
polypoll arbitrage
polypoll arbitrage --min-profit 1.0 --min-similarity 80

# Group markets by event across platforms
polypoll groups
polypoll groups --min-similarity 85

# Find similar markets
polypoll similar <market_id> --platform polymarket

# Get a specific market
polypoll market <market_id> --platform kalshi

# Other
polypoll version
polypoll platforms

MCP Server

Let AI agents (Claude, etc.) query prediction market data directly via Model Context Protocol.

Start the server:

polypoll-mcp

Available Tools:

Tool	Description
get_markets	Get markets from one or all platforms
search_markets	Search markets by keyword
get_arbitrage	Detect cross-platform arbitrage
get_groups	Get markets grouped by event
get_similar_markets	Find similar markets across platforms

Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "polypoll": {
      "command": "polypoll-mcp"
    }
  }
}

Once configured, Claude can directly query live prediction market data during conversations.

REST API Server

Deploy the SDK as a standalone REST API service:

# 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

# 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:

@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

# 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

# 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