overtime-api 0.1.0__tar.gz

overtime_api-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,27 @@
+name: Tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v

overtime_api-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.eggs/
+*.egg
+.env

overtime_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 overtime-api contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

overtime_api-0.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: overtime-api
+Version: 0.1.0
+Summary: Unofficial Python client for the Overtime Markets API. Access sports betting odds, live scores, and market data without an API key.
+Project-URL: Homepage, https://github.com/glowww/overtime-api
+Project-URL: Documentation, https://github.com/glowww/overtime-api#readme
+Project-URL: Issues, https://github.com/glowww/overtime-api/issues
+Author: overtime-api contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,crypto,odds,overtime,sports-betting,web3
+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.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
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# overtime-api
+
+Unofficial Python client for the [Overtime Markets](https://www.overtimemarkets.xyz/) API. Grab odds, live scores, and market data without an API key.
+
+No API key required for most endpoints. For odds data, you need a [CapSolver](https://dashboard.capsolver.com/passport/register?inviteCode=WBGRP77j2drv) account to handle Cloudflare Turnstile captchas.
+
+## Install
+
+```bash
+pip install overtime-api
+```
+
+To access odds data (`get_markets`, `get_live_markets`), you need a [CapSolver API key](https://dashboard.capsolver.com/passport/register?inviteCode=WBGRP77j2drv) for automatic Turnstile captcha solving.
+
+## Quick start
+
+```python
+import asyncio
+from overtime import OvertimeClient
+
+async def main():
+    async with OvertimeClient() as client:
+        # No API key needed
+        sports = await client.get_sports()
+        scores = await client.get_live_scores()
+        games = await client.get_games_info()
+        players = await client.get_players_info()
+        market_types = await client.get_market_types()
+
+asyncio.run(main())
+```
+
+## Get odds data
+
+The `/markets` and `/live-markets` endpoints are protected by Cloudflare Turnstile. You can either solve it automatically with [CapSolver](https://dashboard.capsolver.com/passport/register?inviteCode=WBGRP77j2drv), or set a session ID manually.
+
+### Option 1: Automatic (recommended)
+
+```python
+from overtime import OvertimeClient
+
+async with OvertimeClient(capsolver_api_key="CAI-...") as client:
+    # Turnstile is solved automatically behind the scenes
+    markets = await client.get_markets()
+
+    for market in markets.markets:
+        home = market.home_team
+        away = market.away_team
+        odds = market.result_odds.odds  # implied probabilities
+        print(f"{home} vs {away}: {odds}")
+
+    # Live odds with scores
+    live = await client.get_live_markets()
+    for m in live:
+        print(f"{m.home_team} {m.home_score}-{m.away_score} {m.away_team}")
+```
+
+### Option 2: Manual session
+
+```python
+from overtime import OvertimeClient
+
+async with OvertimeClient() as client:
+    client.set_session("your-session-id-here")
+    markets = await client.get_markets()
+```
+
+## Delta updates
+
+Avoid re-fetching all markets every time. Pass the `response_hash` from a previous response to only get markets that changed:
+
+```python
+result = await client.get_markets()
+print(f"Full: {len(result.markets)} markets")
+
+# Later, only get changes:
+result2 = await client.get_markets(response_hash=result.response_hash)
+print(f"Changed: {len(result2.markets)} markets")
+```
+
+## Proxy support
+
+```python
+# Simple proxy URL
+async with OvertimeClient(proxy="http://user:pass@host:port") as client:
+    sports = await client.get_sports()
+
+# SOCKS5
+async with OvertimeClient(proxy="socks5://host:port") as client:
+    markets = await client.get_markets()
+```
+
+## Bring your own HTTP client
+
+If you need to configure TLS, connection pooling, or retries yourself, pass your own `httpx.AsyncClient`:
+
+```python
+import httpx
+from overtime import OvertimeClient
+
+http = httpx.AsyncClient(
+    proxy="socks5://host:port",
+    verify=False,
+    timeout=60,
+    limits=httpx.Limits(max_connections=10),
+)
+
+async with OvertimeClient(http_client=http) as client:
+    markets = await client.get_markets()
+
+# You manage the lifecycle of your own client
+await http.aclose()
+```
+
+## Raw JSON responses
+
+Every convenience method returns parsed dataclasses. If you want the raw JSON dict instead, use `client.request()`:
+
+```python
+async with OvertimeClient() as client:
+    # Raw dict, no parsing
+    raw = await client.request("GET", "/overtime-v2/sports")
+
+    # Also works for any undocumented endpoint
+    raw = await client.request("GET", "/some/other/endpoint?foo=bar")
+```
+
+## Use from any language (standalone headers)
+
+You can also skip the client entirely and just generate the auth headers for use with curl, Node.js, Go, or whatever you prefer.
+
+```python
+from overtime import make_auth_headers, build_request
+
+# Option A: just the TOTP auth headers
+headers = make_auth_headers("GET", "/overtime-v2/sports")
+# Returns: {"x-client-totp": "...", "x-client-timestamp": "...", ...}
+
+# Option B: full URL + all headers, ready to copy-paste
+url, headers = build_request("GET", "/overtime-v2/sports")
+# url = "https://api.overtime.io/overtime-v2/sports"
+# headers = {user-agent, accept, origin, referer, totp, timestamp, ...}
+
+# Use with curl:
+import subprocess
+header_args = []
+for k, v in headers.items():
+    header_args.extend(["-H", f"{k}: {v}"])
+subprocess.run(["curl", *header_args, url])
+
+# Use with requests (sync):
+import requests
+response = requests.get(url, headers=headers)
+```
+
+### Implementing TOTP in other languages
+
+The auth algorithm is simple HMAC-SHA256. Here's the logic to port to any language:
+
+```
+TOTP_KEY  = "BEST_DECENTRALIZED_ONCHAIN_SPORTSBOOK"
+TOTPM_KEY = "A_RANDOM_SELECTION_OF_WORDS"
+
+timestamp_seconds = floor(now())
+timestamp_millis  = floor(now() * 1000)
+window            = timestamp_seconds / 5  (integer division)
+
+x-client-totp       = HMAC-SHA256(TOTP_KEY,  "C5S|{window}|{METHOD}|{path+query}")
+x-client-timestamp   = str(timestamp_seconds)
+x-client-totpm      = HMAC-SHA256(TOTPM_KEY, "C1MS|{timestamp_millis}|{METHOD}|{path+query}")
+x-client-timestampm = str(timestamp_millis)
+```
+
+The `{path+query}` is the full path including query string, e.g. `/overtime-v2/networks/42161/markets?status=open`.
+
+## All endpoints
+
+| Method | Session? | Description |
+|--------|:--------:|-------------|
+| `get_sports()` | | All sports and leagues |
+| `get_market_types()` | | Market type definitions (spread, total, etc.) |
+| `get_collaterals(network)` | | Supported tokens per chain |
+| `get_games_info()` | | All games with status, teams, tournament |
+| `get_game_info(game_id)` | | Single game info |
+| `get_live_scores()` | | Live scores for all in-progress games |
+| `get_live_score(game_id)` | | Live score for single game |
+| `get_players_info()` | | All player name mappings |
+| `get_player_info(player_id)` | | Single player info |
+| `get_user_history(address)` | | Betting history for a wallet |
+| `get_markets(network, response_hash)` | Yes | All prematch odds |
+| `get_live_markets(network)` | Yes | All live/in-play odds |
+| `get_quote(trade_data, buy_in, collateral)` | | Price quote for a bet |
+| `request(method, endpoint)` | | Raw JSON for any endpoint |
+
+## Networks
+
+Overtime is deployed on multiple chains. Default is Arbitrum.
+
+```python
+from overtime import OvertimeClient, Network
+
+async with OvertimeClient(network=Network.OPTIMISM) as client:
+    markets = await client.get_markets()
+
+# Or per-request:
+markets = await client.get_markets(network=Network.BASE)
+```
+
+Available networks: `Network.ARBITRUM` (42161), `Network.OPTIMISM` (10), `Network.BASE` (8453).
+
+## Understanding odds
+
+Overtime returns odds as implied probabilities (values between 0 and 1). To convert:
+
+```python
+implied_prob = 0.45  # from the API
+
+# To decimal odds:
+decimal_odds = 1 / implied_prob  # 2.22
+
+# To American odds:
+if implied_prob >= 0.5:
+    american = -100 * implied_prob / (1 - implied_prob)  # negative
+else:
+    american = 100 * (1 - implied_prob) / implied_prob   # positive
+```
+
+## Error handling
+
+```python
+from overtime import OvertimeClient, AuthenticationError, SessionError, RateLimitError
+
+async with OvertimeClient(capsolver_api_key="...") as client:
+    try:
+        markets = await client.get_markets()
+    except AuthenticationError:
+        print("TOTP keys may have changed. Update the package.")
+    except SessionError as e:
+        print(f"Captcha solving failed: {e}")
+    except RateLimitError:
+        print("Too many requests. Slow down.")
+```
+
+## Who built this
+
+I'm the founder of [Bet Hero](https://www.betherosports.com), a sports betting analytics platform. We use Overtime's odds data in production alongside 400+ other sportsbooks. When they cut off API access, I open-sourced how it works.
+
+## License
+
+MIT

overtime_api-0.1.0/README.md

@@ -0,0 +1,250 @@
+# overtime-api
+
+Unofficial Python client for the [Overtime Markets](https://www.overtimemarkets.xyz/) API. Grab odds, live scores, and market data without an API key.
+
+No API key required for most endpoints. For odds data, you need a [CapSolver](https://dashboard.capsolver.com/passport/register?inviteCode=WBGRP77j2drv) account to handle Cloudflare Turnstile captchas.
+
+## Install
+
+```bash
+pip install overtime-api
+```
+
+To access odds data (`get_markets`, `get_live_markets`), you need a [CapSolver API key](https://dashboard.capsolver.com/passport/register?inviteCode=WBGRP77j2drv) for automatic Turnstile captcha solving.
+
+## Quick start
+
+```python
+import asyncio
+from overtime import OvertimeClient
+
+async def main():
+    async with OvertimeClient() as client:
+        # No API key needed
+        sports = await client.get_sports()
+        scores = await client.get_live_scores()
+        games = await client.get_games_info()
+        players = await client.get_players_info()
+        market_types = await client.get_market_types()
+
+asyncio.run(main())
+```
+
+## Get odds data
+
+The `/markets` and `/live-markets` endpoints are protected by Cloudflare Turnstile. You can either solve it automatically with [CapSolver](https://dashboard.capsolver.com/passport/register?inviteCode=WBGRP77j2drv), or set a session ID manually.
+
+### Option 1: Automatic (recommended)
+
+```python
+from overtime import OvertimeClient
+
+async with OvertimeClient(capsolver_api_key="CAI-...") as client:
+    # Turnstile is solved automatically behind the scenes
+    markets = await client.get_markets()
+
+    for market in markets.markets:
+        home = market.home_team
+        away = market.away_team
+        odds = market.result_odds.odds  # implied probabilities
+        print(f"{home} vs {away}: {odds}")
+
+    # Live odds with scores
+    live = await client.get_live_markets()
+    for m in live:
+        print(f"{m.home_team} {m.home_score}-{m.away_score} {m.away_team}")
+```
+
+### Option 2: Manual session
+
+```python
+from overtime import OvertimeClient
+
+async with OvertimeClient() as client:
+    client.set_session("your-session-id-here")
+    markets = await client.get_markets()
+```
+
+## Delta updates
+
+Avoid re-fetching all markets every time. Pass the `response_hash` from a previous response to only get markets that changed:
+
+```python
+result = await client.get_markets()
+print(f"Full: {len(result.markets)} markets")
+
+# Later, only get changes:
+result2 = await client.get_markets(response_hash=result.response_hash)
+print(f"Changed: {len(result2.markets)} markets")
+```
+
+## Proxy support
+
+```python
+# Simple proxy URL
+async with OvertimeClient(proxy="http://user:pass@host:port") as client:
+    sports = await client.get_sports()
+
+# SOCKS5
+async with OvertimeClient(proxy="socks5://host:port") as client:
+    markets = await client.get_markets()
+```
+
+## Bring your own HTTP client
+
+If you need to configure TLS, connection pooling, or retries yourself, pass your own `httpx.AsyncClient`:
+
+```python
+import httpx
+from overtime import OvertimeClient
+
+http = httpx.AsyncClient(
+    proxy="socks5://host:port",
+    verify=False,
+    timeout=60,
+    limits=httpx.Limits(max_connections=10),
+)
+
+async with OvertimeClient(http_client=http) as client:
+    markets = await client.get_markets()
+
+# You manage the lifecycle of your own client
+await http.aclose()
+```
+
+## Raw JSON responses
+
+Every convenience method returns parsed dataclasses. If you want the raw JSON dict instead, use `client.request()`:
+
+```python
+async with OvertimeClient() as client:
+    # Raw dict, no parsing
+    raw = await client.request("GET", "/overtime-v2/sports")
+
+    # Also works for any undocumented endpoint
+    raw = await client.request("GET", "/some/other/endpoint?foo=bar")
+```
+
+## Use from any language (standalone headers)
+
+You can also skip the client entirely and just generate the auth headers for use with curl, Node.js, Go, or whatever you prefer.
+
+```python
+from overtime import make_auth_headers, build_request
+
+# Option A: just the TOTP auth headers
+headers = make_auth_headers("GET", "/overtime-v2/sports")
+# Returns: {"x-client-totp": "...", "x-client-timestamp": "...", ...}
+
+# Option B: full URL + all headers, ready to copy-paste
+url, headers = build_request("GET", "/overtime-v2/sports")
+# url = "https://api.overtime.io/overtime-v2/sports"
+# headers = {user-agent, accept, origin, referer, totp, timestamp, ...}
+
+# Use with curl:
+import subprocess
+header_args = []
+for k, v in headers.items():
+    header_args.extend(["-H", f"{k}: {v}"])
+subprocess.run(["curl", *header_args, url])
+
+# Use with requests (sync):
+import requests
+response = requests.get(url, headers=headers)
+```
+
+### Implementing TOTP in other languages
+
+The auth algorithm is simple HMAC-SHA256. Here's the logic to port to any language:
+
+```
+TOTP_KEY  = "BEST_DECENTRALIZED_ONCHAIN_SPORTSBOOK"
+TOTPM_KEY = "A_RANDOM_SELECTION_OF_WORDS"
+
+timestamp_seconds = floor(now())
+timestamp_millis  = floor(now() * 1000)
+window            = timestamp_seconds / 5  (integer division)
+
+x-client-totp       = HMAC-SHA256(TOTP_KEY,  "C5S|{window}|{METHOD}|{path+query}")
+x-client-timestamp   = str(timestamp_seconds)
+x-client-totpm      = HMAC-SHA256(TOTPM_KEY, "C1MS|{timestamp_millis}|{METHOD}|{path+query}")
+x-client-timestampm = str(timestamp_millis)
+```
+
+The `{path+query}` is the full path including query string, e.g. `/overtime-v2/networks/42161/markets?status=open`.
+
+## All endpoints
+
+| Method | Session? | Description |
+|--------|:--------:|-------------|
+| `get_sports()` | | All sports and leagues |
+| `get_market_types()` | | Market type definitions (spread, total, etc.) |
+| `get_collaterals(network)` | | Supported tokens per chain |
+| `get_games_info()` | | All games with status, teams, tournament |
+| `get_game_info(game_id)` | | Single game info |
+| `get_live_scores()` | | Live scores for all in-progress games |
+| `get_live_score(game_id)` | | Live score for single game |
+| `get_players_info()` | | All player name mappings |
+| `get_player_info(player_id)` | | Single player info |
+| `get_user_history(address)` | | Betting history for a wallet |
+| `get_markets(network, response_hash)` | Yes | All prematch odds |
+| `get_live_markets(network)` | Yes | All live/in-play odds |
+| `get_quote(trade_data, buy_in, collateral)` | | Price quote for a bet |
+| `request(method, endpoint)` | | Raw JSON for any endpoint |
+
+## Networks
+
+Overtime is deployed on multiple chains. Default is Arbitrum.
+
+```python
+from overtime import OvertimeClient, Network
+
+async with OvertimeClient(network=Network.OPTIMISM) as client:
+    markets = await client.get_markets()
+
+# Or per-request:
+markets = await client.get_markets(network=Network.BASE)
+```
+
+Available networks: `Network.ARBITRUM` (42161), `Network.OPTIMISM` (10), `Network.BASE` (8453).
+
+## Understanding odds
+
+Overtime returns odds as implied probabilities (values between 0 and 1). To convert:
+
+```python
+implied_prob = 0.45  # from the API
+
+# To decimal odds:
+decimal_odds = 1 / implied_prob  # 2.22
+
+# To American odds:
+if implied_prob >= 0.5:
+    american = -100 * implied_prob / (1 - implied_prob)  # negative
+else:
+    american = 100 * (1 - implied_prob) / implied_prob   # positive
+```
+
+## Error handling
+
+```python
+from overtime import OvertimeClient, AuthenticationError, SessionError, RateLimitError
+
+async with OvertimeClient(capsolver_api_key="...") as client:
+    try:
+        markets = await client.get_markets()
+    except AuthenticationError:
+        print("TOTP keys may have changed. Update the package.")
+    except SessionError as e:
+        print(f"Captcha solving failed: {e}")
+    except RateLimitError:
+        print("Too many requests. Slow down.")
+```
+
+## Who built this
+
+I'm the founder of [Bet Hero](https://www.betherosports.com), a sports betting analytics platform. We use Overtime's odds data in production alongside 400+ other sportsbooks. When they cut off API access, I open-sourced how it works.
+
+## License
+
+MIT

overtime_api-0.1.0/examples/live_odds.py

@@ -0,0 +1,45 @@
+"""Fetch live and prematch odds (requires capsolver API key)."""
+
+import asyncio
+import os
+from overtime import OvertimeClient
+
+
+async def main():
+    api_key = os.environ.get("CAPSOLVER_API_KEY")
+    if not api_key:
+        print("Set CAPSOLVER_API_KEY environment variable to use this example.")
+        print("  export CAPSOLVER_API_KEY=CAI-...")
+        return
+
+    async with OvertimeClient(capsolver_api_key=api_key) as client:
+
+        # Fetch all open prematch markets
+        result = await client.get_markets()
+        print(f"Prematch markets: {len(result.markets)}")
+        print(f"Response hash (for delta updates): {result.response_hash[:20]}...")
+
+        for market in result.markets[:10]:
+            odds_str = " / ".join(f"{o:.4f}" for o in market.result_odds.odds)
+            print(f"  {market.home_team} vs {market.away_team}: {odds_str}")
+            print(f"    Lines available: {len(market.child_markets)}")
+
+        # Fetch live markets
+        live = await client.get_live_markets()
+        print(f"\nLive markets: {len(live)}")
+
+        for market in live[:5]:
+            odds_str = " / ".join(f"{o:.4f}" for o in market.odds)
+            print(f"  {market.home_team} vs {market.away_team}: {odds_str}")
+            print(f"    Score: {market.home_score}-{market.away_score}")
+            print(f"    Lines available: {len(market.child_markets)}")
+
+        # Delta update: pass previous hash to only get changed markets
+        result2 = await client.get_markets(response_hash=result.response_hash)
+        if result2.markets:
+            print(f"\nDelta update: {len(result2.markets)} markets changed")
+        else:
+            print("\nDelta update: no changes since last fetch")
+
+
+asyncio.run(main())

overtime_api-0.1.0/examples/quickstart.py

@@ -0,0 +1,35 @@
+"""Quick start: fetch sports, scores, and game info (no API key needed)."""
+
+import asyncio
+from overtime import OvertimeClient
+
+
+async def main():
+    async with OvertimeClient() as client:
+
+        # Get all sports and leagues
+        sports = await client.get_sports()
+        print(f"Available sports: {len(sports)}")
+        for sport in sports[:5]:
+            print(f"  {sport.name}: {len(sport.leagues)} leagues")
+
+        # Get market type definitions
+        market_types = await client.get_market_types()
+        print(f"\nMarket types: {len(market_types)}")
+        for mt in market_types[:5]:
+            print(f"  [{mt.id}] {mt.name}: {mt.description}")
+
+        # Get live scores
+        scores = await client.get_live_scores()
+        print(f"\nLive games: {len(scores)}")
+        for score in scores[:5]:
+            print(f"  {score.game_id[:20]}... {score.home_score}-{score.away_score} ({score.status})")
+
+        # Get all game info
+        games = await client.get_games_info()
+        print(f"\nAll games: {len(games)}")
+        for game in games[:5]:
+            print(f"  {game.home_team} vs {game.away_team} ({game.sport})")
+
+
+asyncio.run(main())