Build an arbitrage Discord betting bot

I’m building a Discord bot that finds arbitrage bets using odds-api.net.

The project will be built in three stages:

1. Pull odds from odds-api.net
2. Compare odds and identify arbitrage opportunities
3. Send filtered arbitrage alerts to Discord

For this task, only build Stage 1.

Goal:
Build a clean Python requesting system that pulls upcoming events and all available bookmaker odds from odds-api.net, then normalises the data into a consistent structure that can later be used to compare opposing lines and detect arbitrage.

Requirements:
- Use the official odds-api.net Python package if available in this repo/project.
- If the package is not already installed or documented, inspect the project files first and use the cleanest existing integration pattern.
- API keys must come from environment variables. Do not hardcode secrets.
- Add or update a .env.example file with:
  - ODDS_API_KEY=
  - DISCORD_WEBHOOK_URL=
- Create a reusable client/service layer, not throwaway script code.
- Pull odds for all available bookmakers by default unless a bookmaker filter is provided.
- Pull odds for configurable sports/leagues and markets.
- Add a simple shared config file or config module for:
  - sports/leagues
  - markets
  - bookmaker filters
  - odds format
  - max odds age
  - default stake
  - minimum profit percentage
- Use decimal odds only. If odds-api.net returns odds in another format, convert them to decimal before normalising.
- Support at least:
  - event ID / event key
  - sport / league
  - commence time
  - home team
  - away team
  - bookmaker
  - market
  - selection / outcome name
  - line / handicap / point value if applicable
  - decimal odds price
  - last update timestamp if available
- Normalise equivalent opposing selections so later code can compare both sides of the same market.
- For two-way markets, make it easy to identify the opposing side.
- For line markets, group outcomes by event + market + line so only equivalent lines are compared.
- Avoid arbitrage calculations for now. This stage should only fetch, clean, normalise, and group odds.
- Add basic error handling for failed API requests, missing fields, empty odds, rate limits, malformed responses, and missing API keys.
- Add logging that makes it clear how many events, bookmakers, markets, and odds entries were pulled.
- Add simple tests or sample fixtures if the repo already has a test setup.
- Include a small example script or command that fetches odds and prints a grouped comparison-ready structure.

Important:
Do not build the Discord bot yet.
Do not build arbitrage alerting yet.
Do not calculate arbitrage yet.
Do not over-engineer the architecture.
Keep the code simple, modular, and easy to extend in Stage 2.

Before writing code:
1. Inspect the repo structure.
2. Identify the right place to add the odds requesting system.
3. Briefly explain the files you plan to create or modify.
4. Then implement the changes.

After implementing, run the relevant tests/linting if available. If no tests exist, add a minimal test for the normalisation/grouping logic using mocked odds data.

We have completed Stage 1 of a Python Discord bot project that uses odds-api.net.

Stage 1 should already fetch, clean, normalise, and group bookmaker odds into a comparison-ready structure.

Now build Stage 2 only.

Goal:
Create the arbitrage detection layer.

The system should take the normalised odds data from Stage 1, compare opposing outcomes across bookmakers, and identify true arbitrage opportunities.

Requirements:
- Do not rewrite the Stage 1 requesting system unless absolutely necessary.
- Use the existing normalised/grouped odds structure.
- Use decimal odds only. If any odds are not decimal, convert them before arbitrage calculations.
- Support two-way markets first.
- Skip any market unless it has exactly two valid opposing outcomes for now.
- Do not attempt three-way arbitrage yet.
- For each event and market, find the best available price for each opposing outcome.
- Convert decimal odds into implied probability:
  implied_probability = 1 / decimal_odds
- For each complete two-way outcome set, add the implied probabilities together.
- If the total implied probability is below 1.0, classify it as an arbitrage opportunity.
- Calculate:
  - event
  - sport / league
  - market
  - selections
  - bookmaker for each selection
  - odds for each selection
  - implied probability total
  - arbitrage percentage
  - expected locked profit percentage
  - stake split for a configurable total stake, default $1,000
  - expected payout
  - expected profit
- Calculate stake split using:
  stake_i = total_stake * implied_probability_i / total_implied_probability
- Support line markets only when both sides are on the same equivalent line.
- Do not compare mismatched lines.
- Do not compare stale odds if timestamp data is available.
- Add a configurable minimum profit percentage filter.
- Add a configurable maximum odds age filter if timestamps exist.
- Use the shared config file/module from Stage 1 if it exists.
- Return clean structured objects, not only printed text.
- Add clear logging showing:
  - number of grouped markets checked
  - number of complete markets checked
  - number of arbitrage opportunities found
  - number skipped due to incomplete sides, stale odds, mismatched lines, or unsupported outcome counts
- Add unit tests using mocked odds data:
  - one valid two-way arbitrage
  - one non-arbitrage
  - one mismatched line that must not be treated as an arbitrage
  - one incomplete market that must be skipped
  - one three-way market that must be skipped for now
- Include a small example script or command that runs Stage 1 data through Stage 2 and prints the arbitrage opportunities in a readable format.

Important:
Do not build the Discord bot yet.
Do not send alerts yet.
Do not place bets.
Do not add complicated strategy filters yet.
This stage is only about reliable arbitrage detection.

Before writing code:
1. Inspect the existing Stage 1 code.
2. Explain how the arbitrage detector will connect to it.
3. List the files you plan to create or modify.
4. Then implement the changes.

After implementing, run relevant tests/linting if available.

We have a Python project for a Discord bot that uses odds-api.net.

Stage 1 fetches and normalises bookmaker odds.
Stage 2 compares odds and identifies arbitrage opportunities.

Now build Stage 3 only.

Goal:
Create a Discord alerting layer that sends arbitrage opportunities to a Discord server/channel when they meet configurable filters.

Requirements:
- Do not rewrite Stage 1 or Stage 2 unless absolutely necessary.
- Use the existing arbitrage opportunity objects from Stage 2.
- Add Discord integration using a simple, reliable approach.
- Prefer Discord webhooks for sending alerts unless the existing project already uses a Discord bot framework.
- Discord webhook URL must come from environment variables. Do not hardcode secrets.
- Ensure .env.example includes:
  - ODDS_API_KEY=
  - DISCORD_WEBHOOK_URL=
- Use the shared config file/module where possible.
- Add configurable filters before sending alerts:
  - minimum profit percentage
  - minimum expected profit amount
  - maximum odds age if timestamp data is available
  - allowed sports/leagues
  - allowed markets
  - excluded bookmakers
  - minimum odds
  - maximum odds
  - total stake amount for stake split display
- Avoid duplicate alerts.
- Add a simple deduplication system based on:
  - event ID/key
  - market
  - line if applicable
  - selections
  - bookmakers
  - odds prices
- Deduplication can be in-memory for now unless the repo already has a persistence layer.
- Add a deduplication time window so the same opportunity can alert again later if it remains valid or changes materially.
- Format Discord alerts clearly.

Each alert should include:
- Event name
- Sport / league
- Market
- Start time
- Arbitrage percentage
- Expected profit
- Stake split
- Bookmaker and odds for each selection
- Implied probability total
- Timestamp / odds last updated if available

Example alert format:

ARBITRAGE FOUND

Event: Team A vs Team B
League: NBA
Market: Moneyline
Profit: 2.4%
Stake: $1,000
Expected Profit: $24.00

Bet 1:
Team A @ 2.10
Bookmaker: Bookmaker 1
Stake: $492.00

Bet 2:
Team B @ 2.05
Bookmaker: Bookmaker 2
Stake: $508.00

Important:
- Do not place bets.
- Do not scrape bookmakers.
- Do not build a full UI.
- Keep the alerting system simple and reliable.
- Add logging for sent alerts, skipped alerts, and duplicate alerts.
- Add basic error handling for Discord webhook failures, rate limits, missing webhook URL, and malformed opportunity objects.
- Add a dry-run mode that prints alerts without sending them to Discord.
- Add a small runner script or command that:
  1. Fetches odds
  2. Finds arbitrage
  3. Applies filters
  4. Sends or prints Discord alerts

Before writing code:
1. Inspect the existing Stage 1 and Stage 2 code.
2. Explain how the Discord alerting layer will connect to the arbitrage detector.
3. List the files you plan to create or modify.
4. Then implement the changes.

After implementing, run relevant tests/linting if available. If no tests exist, add a minimal test for filtering and deduplication.