sharpapi 0.1.0__tar.gz

sharpapi-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: sharpapi
+Version: 0.1.0
+Summary: Official Python SDK for the SharpAPI real-time sports betting odds API
+Project-URL: Homepage, https://sharpapi.io
+Project-URL: Documentation, https://docs.sharpapi.io/sdks/python
+Project-URL: Repository, https://github.com/sharpapi/sharpapi-python
+Project-URL: Changelog, https://github.com/sharpapi/sharpapi-python/releases
+Author-email: SharpAPI <support@sharpapi.io>
+License-Expression: MIT
+Keywords: api,arbitrage,ev,odds,pinnacle,real-time,sports-betting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5.0; extra == 'pandas'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+# SharpAPI Python SDK
+
+Official Python client for the [SharpAPI](https://sharpapi.io) real-time sports betting odds API.
+
+Get pre-computed +EV opportunities, arbitrage detection, middles, and live odds from 20+ sportsbooks — with Pinnacle as the sharp reference.
+
+## Install
+
+```bash
+pip install sharpapi
+```
+
+## Quick Start
+
+```python
+from sharpapi import SharpAPI
+
+client = SharpAPI("sk_live_xxx")
+
+# --- Arbitrage opportunities ---
+arbs = client.arbitrage.get(min_profit=1.0, league="nba")
+for arb in arbs.data:
+    print(f"{arb.profit_percent:.2f}% profit — {arb.event_name}")
+    for leg in arb.legs:
+        print(f"  {leg.sportsbook}: {leg.selection} @ {leg.odds_american} ({leg.stake_percent:.1f}%)")
+
+# --- +EV opportunities ---
+evs = client.ev.get(min_ev=3.0, sport="basketball")
+for opp in evs.data:
+    print(f"+{opp.ev_percent:.1f}% EV on {opp.selection} @ {opp.sportsbook}")
+    if opp.kelly_fraction:
+        print(f"  Kelly: {opp.kelly_fraction:.1%} of bankroll")
+
+# --- Best odds across books ---
+odds = client.odds.best(league="nba", market="moneyline")
+for line in odds.data:
+    print(f"{line.home_team} vs {line.away_team}: {line.selection} {line.odds_american}")
+```
+
+## Streaming
+
+Real-time SSE streaming for odds updates and opportunity alerts (requires WebSocket add-on):
+
+```python
+stream = client.stream.opportunities(league="nba")
+
+@stream.on("ev:detected")
+def on_ev(data):
+    for opp in data:
+        print(f"+EV: {opp['selection']} {opp['ev_percent']}% @ {opp['sportsbook']}")
+
+@stream.on("arb:detected")
+def on_arb(data):
+    for arb in data:
+        print(f"Arb: {arb['profit_percent']}% — {arb['event_name']}")
+
+stream.connect()  # Blocks, processing events
+```
+
+Or iterate over events:
+
+```python
+for event_type, data in stream.iter_events():
+    if event_type == "ev:detected":
+        print(data)
+```
+
+## All Resources
+
+```python
+# Odds
+client.odds.get(sport="basketball", league="nba")
+client.odds.best(league="nfl", market="moneyline")
+client.odds.comparison(event_id="abc123")
+client.odds.batch(event_ids=["abc123", "def456"])
+
+# Opportunities
+client.ev.get(min_ev=2.0, sportsbook="draftkings")
+client.arbitrage.get(min_profit=0.5, sport="football")
+client.middles.get(sport="football", min_size=3.0)
+client.low_hold.get(max_hold=2.0)
+
+# Reference data
+client.sports.list()
+client.leagues.list(sport="basketball")
+client.sportsbooks.list()
+client.events.list(league="nba", live=True)
+client.events.search("Lakers")
+
+# Account
+client.account.me()       # Tier, limits, features
+client.account.usage()    # Request counts
+
+# Streaming
+client.stream.odds(league="nba")
+client.stream.opportunities(min_ev=3.0)
+client.stream.all(sport="basketball")
+client.stream.event("event_id_here")
+```
+
+## Data Quality
+
+Every opportunity response includes staleness metadata to avoid acting on stale odds:
+
+```python
+arbs = client.arbitrage.get()
+for arb in arbs.data:
+    if arb.possibly_stale:
+        print(f"  Skipping — odds may be stale ({arb.oldest_odds_age_seconds}s old)")
+        continue
+    if "LIVE_HIGH_PROFIT_SUSPICIOUS" in arb.warnings:
+        print(f"  Skipping — likely phantom arb")
+        continue
+    print(f"Actionable: {arb.profit_percent}%")
+```
+
+## Rate Limits
+
+Rate limit info is available after every request:
+
+```python
+response = client.odds.get()
+print(f"Remaining: {client.rate_limit.remaining}/{client.rate_limit.limit}")
+print(f"Tier: {client.rate_limit.tier}")
+```
+
+## Error Handling
+
+```python
+from sharpapi import (
+    SharpAPI,
+    AuthenticationError,
+    TierRestrictedError,
+    RateLimitedError,
+)
+
+client = SharpAPI("sk_live_xxx")
+
+try:
+    evs = client.ev.get()
+except AuthenticationError:
+    print("Invalid API key")
+except TierRestrictedError as e:
+    print(f"Upgrade to {e.required_tier} tier for this feature")
+except RateLimitedError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+```
+
+## Odds Conversion Utilities
+
+```python
+from sharpapi import american_to_decimal, american_to_probability, decimal_to_american
+
+american_to_decimal(-110)       # 1.909
+american_to_decimal(150)        # 2.5
+american_to_probability(-110)   # 0.524
+decimal_to_american(2.5)        # 150
+```
+
+## Requirements
+
+- Python 3.9+
+- httpx
+- pydantic v2
+
+## Links
+
+- [API Docs](https://docs.sharpapi.io)
+- [Dashboard](https://sharpapi.io/dashboard)
+- [Discord](https://discord.gg/sharpapi)

sharpapi-0.1.0/README.md

@@ -0,0 +1,170 @@
+# SharpAPI Python SDK
+
+Official Python client for the [SharpAPI](https://sharpapi.io) real-time sports betting odds API.
+
+Get pre-computed +EV opportunities, arbitrage detection, middles, and live odds from 20+ sportsbooks — with Pinnacle as the sharp reference.
+
+## Install
+
+```bash
+pip install sharpapi
+```
+
+## Quick Start
+
+```python
+from sharpapi import SharpAPI
+
+client = SharpAPI("sk_live_xxx")
+
+# --- Arbitrage opportunities ---
+arbs = client.arbitrage.get(min_profit=1.0, league="nba")
+for arb in arbs.data:
+    print(f"{arb.profit_percent:.2f}% profit — {arb.event_name}")
+    for leg in arb.legs:
+        print(f"  {leg.sportsbook}: {leg.selection} @ {leg.odds_american} ({leg.stake_percent:.1f}%)")
+
+# --- +EV opportunities ---
+evs = client.ev.get(min_ev=3.0, sport="basketball")
+for opp in evs.data:
+    print(f"+{opp.ev_percent:.1f}% EV on {opp.selection} @ {opp.sportsbook}")
+    if opp.kelly_fraction:
+        print(f"  Kelly: {opp.kelly_fraction:.1%} of bankroll")
+
+# --- Best odds across books ---
+odds = client.odds.best(league="nba", market="moneyline")
+for line in odds.data:
+    print(f"{line.home_team} vs {line.away_team}: {line.selection} {line.odds_american}")
+```
+
+## Streaming
+
+Real-time SSE streaming for odds updates and opportunity alerts (requires WebSocket add-on):
+
+```python
+stream = client.stream.opportunities(league="nba")
+
+@stream.on("ev:detected")
+def on_ev(data):
+    for opp in data:
+        print(f"+EV: {opp['selection']} {opp['ev_percent']}% @ {opp['sportsbook']}")
+
+@stream.on("arb:detected")
+def on_arb(data):
+    for arb in data:
+        print(f"Arb: {arb['profit_percent']}% — {arb['event_name']}")
+
+stream.connect()  # Blocks, processing events
+```
+
+Or iterate over events:
+
+```python
+for event_type, data in stream.iter_events():
+    if event_type == "ev:detected":
+        print(data)
+```
+
+## All Resources
+
+```python
+# Odds
+client.odds.get(sport="basketball", league="nba")
+client.odds.best(league="nfl", market="moneyline")
+client.odds.comparison(event_id="abc123")
+client.odds.batch(event_ids=["abc123", "def456"])
+
+# Opportunities
+client.ev.get(min_ev=2.0, sportsbook="draftkings")
+client.arbitrage.get(min_profit=0.5, sport="football")
+client.middles.get(sport="football", min_size=3.0)
+client.low_hold.get(max_hold=2.0)
+
+# Reference data
+client.sports.list()
+client.leagues.list(sport="basketball")
+client.sportsbooks.list()
+client.events.list(league="nba", live=True)
+client.events.search("Lakers")
+
+# Account
+client.account.me()       # Tier, limits, features
+client.account.usage()    # Request counts
+
+# Streaming
+client.stream.odds(league="nba")
+client.stream.opportunities(min_ev=3.0)
+client.stream.all(sport="basketball")
+client.stream.event("event_id_here")
+```
+
+## Data Quality
+
+Every opportunity response includes staleness metadata to avoid acting on stale odds:
+
+```python
+arbs = client.arbitrage.get()
+for arb in arbs.data:
+    if arb.possibly_stale:
+        print(f"  Skipping — odds may be stale ({arb.oldest_odds_age_seconds}s old)")
+        continue
+    if "LIVE_HIGH_PROFIT_SUSPICIOUS" in arb.warnings:
+        print(f"  Skipping — likely phantom arb")
+        continue
+    print(f"Actionable: {arb.profit_percent}%")
+```
+
+## Rate Limits
+
+Rate limit info is available after every request:
+
+```python
+response = client.odds.get()
+print(f"Remaining: {client.rate_limit.remaining}/{client.rate_limit.limit}")
+print(f"Tier: {client.rate_limit.tier}")
+```
+
+## Error Handling
+
+```python
+from sharpapi import (
+    SharpAPI,
+    AuthenticationError,
+    TierRestrictedError,
+    RateLimitedError,
+)
+
+client = SharpAPI("sk_live_xxx")
+
+try:
+    evs = client.ev.get()
+except AuthenticationError:
+    print("Invalid API key")
+except TierRestrictedError as e:
+    print(f"Upgrade to {e.required_tier} tier for this feature")
+except RateLimitedError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+```
+
+## Odds Conversion Utilities
+
+```python
+from sharpapi import american_to_decimal, american_to_probability, decimal_to_american
+
+american_to_decimal(-110)       # 1.909
+american_to_decimal(150)        # 2.5
+american_to_probability(-110)   # 0.524
+decimal_to_american(2.5)        # 150
+```
+
+## Requirements
+
+- Python 3.9+
+- httpx
+- pydantic v2
+
+## Links
+
+- [API Docs](https://docs.sharpapi.io)
+- [Dashboard](https://sharpapi.io/dashboard)
+- [Discord](https://discord.gg/sharpapi)

sharpapi-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sharpapi"
+version = "0.1.0"
+description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "SharpAPI", email = "support@sharpapi.io" }]
+keywords = ["sports-betting", "odds", "arbitrage", "ev", "api", "real-time", "pinnacle"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.5.0"]
+test = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[project.urls]
+Homepage = "https://sharpapi.io"
+Documentation = "https://docs.sharpapi.io/sdks/python"
+Repository = "https://github.com/sharpapi/sharpapi-python"
+Changelog = "https://github.com/sharpapi/sharpapi-python/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sharpapi"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.pyright]
+pythonVersion = "3.9"
+typeCheckingMode = "standard"

sharpapi-0.1.0/src/sharpapi/__init__.py

@@ -0,0 +1,93 @@
+"""SharpAPI Python SDK — Real-time sports betting odds, +EV, and arbitrage detection.
+
+Example::
+
+    from sharpapi import SharpAPI
+
+    client = SharpAPI("sk_live_xxx")
+
+    # Arbitrage opportunities
+    arbs = client.arbitrage.get(min_profit=1.0)
+    for arb in arbs.data:
+        print(f"{arb.profit_percent}% — {arb.event_name}")
+
+    # +EV opportunities
+    evs = client.ev.get(min_ev=3.0, league="nba")
+    for opp in evs.data:
+        print(f"+{opp.ev_percent}% on {opp.selection} @ {opp.sportsbook}")
+"""
+
+from .async_client import AsyncSharpAPI
+from .client import SharpAPI
+from .exceptions import (
+    AuthenticationError,
+    RateLimitedError,
+    SharpAPIError,
+    StreamError,
+    TierRestrictedError,
+    ValidationError,
+)
+from .models import (
+    APIResponse,
+    AccountInfo,
+    ArbitrageLeg,
+    ArbitrageOpportunity,
+    EVOpportunity,
+    Event,
+    GameState,
+    League,
+    LowHoldOpportunity,
+    LowHoldSide,
+    MiddleOpportunity,
+    MiddleSide,
+    OddsLine,
+    OddsValue,
+    Pagination,
+    RateLimitInfo,
+    ResponseMeta,
+    Sport,
+    Sportsbook,
+)
+from .streaming import EventStream
+from ._utils import american_to_decimal, american_to_probability, decimal_to_american
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "SharpAPI",
+    "AsyncSharpAPI",
+    # Models
+    "APIResponse",
+    "AccountInfo",
+    "ArbitrageLeg",
+    "ArbitrageOpportunity",
+    "EVOpportunity",
+    "Event",
+    "GameState",
+    "League",
+    "LowHoldOpportunity",
+    "LowHoldSide",
+    "MiddleOpportunity",
+    "MiddleSide",
+    "OddsLine",
+    "OddsValue",
+    "Pagination",
+    "RateLimitInfo",
+    "ResponseMeta",
+    "Sport",
+    "Sportsbook",
+    # Streaming
+    "EventStream",
+    # Exceptions
+    "AuthenticationError",
+    "RateLimitedError",
+    "SharpAPIError",
+    "StreamError",
+    "TierRestrictedError",
+    "ValidationError",
+    # Utilities
+    "american_to_decimal",
+    "american_to_probability",
+    "decimal_to_american",
+]

sharpapi-0.1.0/src/sharpapi/_base.py

@@ -0,0 +1,121 @@
+"""Shared logic for sync and async clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    RateLimitedError,
+    SharpAPIError,
+    TierRestrictedError,
+    ValidationError,
+)
+from .models import APIResponse, RateLimitInfo, ResponseMeta
+
+DEFAULT_BASE_URL = "https://api.sharpapi.io"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "sharpapi-python/0.1.0"
+
+
+def parse_response(raw: dict, model_class: type) -> APIResponse:
+    """Parse raw API JSON into a typed APIResponse."""
+    data_raw = raw.get("data", [])
+    if isinstance(data_raw, list):
+        items = [model_class.model_validate(item) for item in data_raw]
+    else:
+        items = [model_class.model_validate(data_raw)]
+
+    meta = None
+    meta_raw = raw.get("meta")
+    if meta_raw:
+        meta = ResponseMeta.model_validate(meta_raw)
+
+    return APIResponse(
+        success=raw.get("success"),
+        data=items,
+        meta=meta,
+        timestamp=raw.get("timestamp"),
+        tier=raw.get("tier"),
+    )
+
+
+def parse_rate_limit(response: httpx.Response) -> RateLimitInfo:
+    """Extract rate limit info from response headers."""
+    headers = response.headers
+    return RateLimitInfo(
+        limit=_int_or_none(headers.get("x-ratelimit-limit")),
+        remaining=_int_or_none(headers.get("x-ratelimit-remaining")),
+        reset=_float_or_none(headers.get("x-ratelimit-reset")),
+        tier=headers.get("x-tier"),
+    )
+
+
+def handle_errors(response: httpx.Response) -> None:
+    """Raise typed exceptions for error responses."""
+    if response.is_success:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        body = {}
+
+    error_obj = body.get("error", body)
+    if isinstance(error_obj, dict):
+        error_msg = error_obj.get("message", error_obj.get("error", f"HTTP {response.status_code}"))
+        code = error_obj.get("code", body.get("code", "unknown_error"))
+    else:
+        error_msg = str(error_obj) if error_obj else f"HTTP {response.status_code}"
+        code = body.get("code", "unknown_error")
+    status = response.status_code
+
+    if status == 401:
+        raise AuthenticationError(error_msg, code=code, status=status)
+    elif status == 403:
+        raise TierRestrictedError(
+            error_msg,
+            code=code,
+            status=status,
+            required_tier=body.get("required_tier"),
+        )
+    elif status == 429:
+        raise RateLimitedError(
+            error_msg,
+            code=code,
+            status=status,
+            retry_after=body.get("retry_after"),
+        )
+    elif status == 400:
+        raise ValidationError(error_msg, code=code, status=status)
+    else:
+        raise SharpAPIError(error_msg, code=code, status=status)
+
+
+def make_headers(api_key: str) -> dict[str, str]:
+    """Build default request headers."""
+    return {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
+    }
+
+
+def _int_or_none(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _float_or_none(value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return None

sharpapi-0.1.0/src/sharpapi/_utils.py

@@ -0,0 +1,39 @@
+"""Internal utilities."""
+
+from __future__ import annotations
+
+
+def american_to_decimal(american: int | float) -> float:
+    """Convert American odds to decimal odds."""
+    if american > 0:
+        return american / 100 + 1
+    return 100 / abs(american) + 1
+
+
+def decimal_to_american(decimal: float) -> int:
+    """Convert decimal odds to American odds."""
+    if decimal >= 2.0:
+        return round((decimal - 1) * 100)
+    return round(-100 / (decimal - 1))
+
+
+def american_to_probability(american: int | float) -> float:
+    """Convert American odds to implied probability (0-1)."""
+    if american > 0:
+        return 100 / (american + 100)
+    return abs(american) / (abs(american) + 100)
+
+
+def _clean_params(params: dict) -> dict:
+    """Remove None values and join lists with commas."""
+    cleaned = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            cleaned[key] = str(value).lower()
+        elif isinstance(value, list):
+            cleaned[key] = ",".join(str(v) for v in value)
+        else:
+            cleaned[key] = value
+    return cleaned