Metadata-Version: 2.4
Name: puntersedge
Version: 0.1.0
Summary: Official Python SDK for the PuntersEdge Australian Sports Odds API
Home-page: https://puntersedge.online/developers
Author: PuntersEdge
Author-email: PuntersEdge <hello@puntersedge.online>
Project-URL: Homepage, https://puntersedge.online
Project-URL: Documentation, https://puntersedge.online/developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# PuntersEdge Python SDK

Official Python client for the PuntersEdge Australian Sports Odds API.

PuntersEdge gives developers simple REST access to Australian sports odds, best-price comparisons, next-to-go racing and arbitrage signals from local bookmakers.

## Install

```bash
pip install puntersedge
```

For local development from this repository:

```bash
pip install -e sdk/python
```

## Quick start

```python
from puntersedge import PuntersEdgeClient
client = PuntersEdgeClient("YOUR_API_KEY")
sports = client.get_sports()
odds = client.get_odds("nrl", markets=["h2h"])
print(odds[:1])
client.close()
```

## Authentication

Pass your API key when creating the client. The SDK sends it as the `X-API-Key` header.

```python
client = PuntersEdgeClient(api_key="YOUR_API_KEY")
```

You can override the API base URL for testing:

```python
client = PuntersEdgeClient("YOUR_API_KEY", base_url="http://localhost:8010")
```

## Methods

| Method | Description | Returns | Endpoint |
| --- | --- | --- | --- |
| `get_sports()` | List active sports and competitions | `list` | `GET /v1/sports` |
| `get_odds(sport_key, markets=None, bookmakers=None)` | Get bookmaker odds for a sport. Defaults to `h2h` market. | `list` | `GET /v1/sports/{sport_key}/odds` |
| `get_best_odds(sport_key)` | Get best available prices by outcome for a sport | `list` | `GET /v1/best-odds/{sport_key}` |
| `get_racing(categories=None, num_races=10)` | Get next-to-go racing markets | `list` | `GET /v1/racing/next-to-go` |
| `get_arb(sport_key=None, min_profit_pct=0.5)` | Scan for arbitrage opportunities | `dict` | `GET /v1/arb/sports` |
| `get_usage()` | View plan, credits, endpoint usage and recent activity | `dict` | `GET /v1/usage` |
| `get_health()` | Connector health and freshness | `dict` | `GET /v1/health` |
| `close()` | Close the underlying HTTP connection pool | `None` | - |

## Async usage

```python
import asyncio
from puntersedge import AsyncPuntersEdgeClient

async def main():
    async with AsyncPuntersEdgeClient("YOUR_API_KEY") as client:
        sports = await client.get_sports()
        odds = await client.get_odds("afl", markets=["h2h"])
        usage = await client.get_usage()
        print(len(sports), len(odds), usage["credits_remaining"])

asyncio.run(main())
```

## Error handling

```python
from puntersedge import PuntersEdgeClient
from puntersedge.exceptions import AuthError, RateLimitError, NotFoundError, ServerError

client = PuntersEdgeClient("YOUR_API_KEY")
try:
    print(client.get_odds("nrl"))
except AuthError:
    print("Invalid API key")
except RateLimitError as exc:
    print(f"Credit limit reached. Resets at {exc.reset_at}")
except NotFoundError:
    print("Unknown sport or endpoint")
except ServerError:
    print("PuntersEdge API is temporarily unavailable")
finally:
    client.close()
```

All SDK exceptions inherit from `PuntersEdgeError`.

## Examples

See the `examples/` directory:

- `basic_usage.py` — list sports, fetch NRL odds and check usage
- `arb_scanner.py` — scan all sports for arbitrage opportunities
- `racing_ntg.py` — print next-to-go racing runners and prices

Run an example with:

```bash
PUNTERSEDGE_API_KEY=YOUR_API_KEY python sdk/python/examples/basic_usage.py
```

## Documentation

- API docs: https://puntersedge.online/api/docs
- Developer docs: https://puntersedge.online/developers
- Website: https://puntersedge.online

18+ only. Please gamble responsibly.
