Metadata-Version: 2.4
Name: polyodds
Version: 0.1.1
Summary: PolyOdds SDK and CLI for agentic sports signal intelligence
Project-URL: Homepage, https://polyodds.bet
Project-URL: Documentation, https://polyodds.bet
Project-URL: Repository, https://github.com/polyodds/polyodds-sdk
Author-email: PolyOdds <support@polyodds.bet>
License: MIT
Keywords: kalshi,mcp,polymarket,prediction-markets,signals,sports
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# 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 consensus, market inefficiencies, and portfolio data, backed by a live bookmaker-consensus model scanning 20+ sports on 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

```bash
python3 -m pip install polyodds
```

---

## Authentication

Get your API key from the [PolyOdds Agent Terminal](https://polyodds.bet/agent-terminal).

```bash
export POLYODDS_API_KEY=pip_yourkeyhere
```

---

## Quick start

### REST (curl)

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

### Python SDK

```python
from polyodds import PolyOddsClient

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

### CLI

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

```bash
export POLYODDS_API_KEY=pip_yourkeyhere
polyodds mcp serve
```

Or run directly:

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

#### Claude Desktop config

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

### Remote MCP

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

```python
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: support@polyodds.bet

---

## License

MIT
