Initial commit: Arbitrage

README.md

@@ -0,0 +1,62 @@
+# 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.