# Arbitrage

Tools and data for exploring **sports betting odds** and (eventually) **arbitrage opportunities** across bookmakers.

## Project status

| Area | Status |
|------|--------|
| Odds API sample data (boxing) | Included under `odds/data/samples/` |
| Odds fetch script | `odds/scripts/fetch_odds.py` |
| Arbitrage detection engine | Not implemented yet |

## Repository layout

```
arbitrage/
├── docs/                    # Architecture and data schema
├── odds/
│   ├── data/samples/        # Cached API responses (JSON)
│   └── scripts/             # fetch_odds.py
├── requirements.txt
└── .env.example             # ODDS_API_KEY template
```

## Quick start

### 1. Clone and create a virtual environment

```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
```

### 2. Configure The Odds API (for live pulls)

1. Sign up at [The Odds API](https://the-odds-api.com/).
2. Copy `.env.example` to `.env` and set `ODDS_API_KEY`.
3. Fetch fresh odds:

```bash
python odds/scripts/fetch_odds.py --sport boxing_boxing --out odds/data/samples/boxing_odds.json
```

## Documentation

- [Architecture](docs/ARCHITECTURE.md) — how modules fit together
- [Odds data schema](docs/DATA_SCHEMA.md) — JSON structure from The Odds API
- [Odds module](odds/README.md) — fetching and sample data

## What is not in this repo

- Virtual environments (`arb-venv/`, `.venv/`) — create locally; see `.gitignore`
- API keys — use `.env` (never commit)

## License

Add a license file before publishing if you intend open-source distribution.