polyodds 0.1.0

PolyOdds SDK and CLI for agentic sports signal intelligence

PolyOdds Python SDK

Signal intelligence for sports prediction markets — Python client + CLI + MCP.

The PolyOdds SDK gives you programmatic access to the PolyOdds signal engine: ranked edge signals, fair-value context, market inefficiencies, and reported activity workflows across supported venues including Polymarket and Kalshi.

Current version: 0.1.0 · Python 3.10+ · One dependency: httpx

Note: This package assumes the PyPI release has been published. Install with python3 -m pip install polyodds.

---

Install

python3 -m pip install polyodds

---

Authentication

Get your API key from the PolyOdds Agent Terminal.

export POLYODDS_API_KEY=pip_yourkeyhere

---

Quick start

REST (curl)

curl -sS "https://polyodds.bet/api/polybot/signals/strongest?limit=3" \
  -H "Authorization: Bearer pip_yourkeyhere"

Python SDK

from polyodds import PolyOddsClient

client = PolyOddsClient(api_key="pip_yourkeyhere")
signals = client.get_strongest_signals(limit=3)
print(signals)

CLI

export POLYODDS_API_KEY=pip_yourkeyhere

polyodds doctor                        # verify auth + data health
polyodds signals strongest --limit 3   # primary signal surface
polyodds account                       # plan and account info
polyodds capabilities                  # no auth required

Local MCP server

export POLYODDS_API_KEY=pip_yourkeyhere
polyodds mcp serve

Or run directly:

python3 -m polyodds.mcp --api-key pip_yourkeyhere

Claude Desktop config

{
  "mcpServers": {
    "polyodds": {
      "command": "polyodds",
      "args": ["mcp", "serve"],
      "env": {
        "POLYODDS_API_KEY": "pip_yourkeyhere"
      }
    }
  }
}

Remote MCP

curl -sS -X POST "https://polyodds.bet/mcp" \
  -H "Authorization: Bearer pip_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

---

SDK Methods

Discovery (no auth required)

• get_capabilities() — service descriptor, plan tiers, x402 status
• get_examples() — machine-readable response shape examples

Account & plan

• get_account() → Account — identity and plan tier
• get_plan() — full plan entitlements dict
• get_data_health() → DataHealth — scan freshness and book snapshot age

Signals

• get_strongest_signals(limit=3, hours_fresh=8, one_per_event=True) — primary signal surface (hero board)
• get_sample_signals() — free first-use surface, hard-capped at 3 signals
• get_live_signals_v1(sport=None, min_edge=0.5, limit=25) — alpha engine feed
• get_alpha_candidates(sport=None, limit=50, hours_fresh=8) — scan loop candidates
• get_fair_values(sport=None, limit=50) — bookmaker consensus fair values
• get_inefficiencies(sport=None, min_edge=1.0, limit=20) — top market inefficiencies

Pro+ gated

• get_agent_signals(min_edge=1.0, limit=25) — machine-readable agent feed
• get_signal_intent(signal_id) — SignalIntent contract
• get_strategies() — strategy template catalog
• apply_signal_policy(signal_id, strategy_id) — policy verdict
• get_calibration_performance() — historical calibration buckets
• get_backtest_scorecard(sport=None) — historical backtest scorecard

Proof & diagnostics

• get_agent_proof() — live activity + backtest coverage + limits (all plans)
• get_backtest_summary() — derived backtest summary (all plans)
• get_signal_summary() — signal distribution by status and sport (all plans)
• get_scorecard() — scan funnel and per-sport breakdown (Pro+)

Execution reporting (external execution only)

• report_execution(venue, fill_price, ...) — report a fill from your external venue
• get_reported_executions(limit=100) — list reported executions

Utilities

• healthcheck() — composite liveness check, never raises
• raw_request(method, path, params=None, json=None) — direct authenticated request

---

CLI Commands

polyodds --help
polyodds doctor                          # composite liveness check
polyodds account                         # account identity and plan tier
polyodds plan                            # plan entitlements
polyodds capabilities                    # no auth required
polyodds examples                        # (via raw_request)
polyodds signals strongest --limit 3     # primary signal surface
polyodds signals strongest --json        # raw JSON output
polyodds signals live-v1                 # alpha engine feed
polyodds signals alpha-candidates        # scan loop candidates
polyodds signals intent <signal_id>      # SignalIntent contract (Pro+)
polyodds scorecard                       # scan funnel scorecard (Pro+)
polyodds backtest-summary                # historical backtest summary
polyodds signal-summary                  # live signal distribution summary
polyodds report-execution --venue polymarket --fill-price 0.65 --match-title "..." --side BUY --fill-size 100
polyodds executions list
polyodds mcp serve                       # start local MCP stdio server

Global options:

--api-key KEY        pip_... API key (or env POLYODDS_API_KEY)
--base-url URL       API base URL (default: https://polyodds.bet)
--json               Output raw JSON
--timeout SECS       HTTP timeout (default: 20.0)
--version            Show version

---

Error handling

from polyodds import PolyOddsClient
from polyodds import AuthError, PlanUpgradeRequired, RateLimitError, APIError

client = PolyOddsClient(api_key="pip_yourkeyhere")

try:
    signals = client.get_strongest_signals(limit=3)
except AuthError:
    print("Invalid API key")
except PlanUpgradeRequired as e:
    print(f"Upgrade required: {e.required_plan}")
except RateLimitError:
    print("Rate limit exceeded — wait before retrying")
except APIError as e:
    print(f"API error (HTTP {e.status_code}): {e}")

---

Links

• Platform: https://polyodds.bet
• Agent Terminal: https://polyodds.bet/agent-terminal
• Support: [e-mail]

---

License

MIT