# Bookie Hunt - Complete AI & Developer Documentation

Welcome to the comprehensive documentation for the Bookie Hunt platform. This document is intended for Large Language Models (LLMs) and autonomous AI agents that require deep context on our API infrastructure, available tools, and integration strategies.

## Overview
Bookie Hunt is a premium, data-driven sports betting utility platform. Unlike traditional affiliate sites, we provide a "Data Utility Infrastructure" offering keyless, 100% free APIs and professional-grade betting calculators. 

Base API URL: `https://bookiehunt.com/api/v1/public`
Authentication: NONE (No API keys required)
Rate Limits: NONE

---

## 1. Complete API Reference

### 1.1 Betting Math & Odds Converter API
**Endpoint:** `GET /math/convert-odds`
**Purpose:** Converts American odds into Decimal, clean Fractional, Implied Probability, and the equivalent prediction-market contract price (cents). This is critical for EV (Expected Value) and Arbitrage calculations.

**Query Parameters:**
- `american` (integer, required): The American odds line, magnitude >= 100. Example: `-110` or `+150`. Values between -99 and +99 return HTTP 400.

**Response Schema:**
```json
{
  "american": -110,
  "decimal": 1.9091,
  "fractional": "10/11",
  "implied_prob": 52.38,
  "prediction_market_cents": 52.4
}
```
`prediction_market_cents` equals the implied probability — a Kalshi/Polymarket contract priced at that many cents represents the same probability.

### 1.2 Sportsbook Promo & Affiliate API
**Endpoint:** `GET /promos`
**Purpose:** Returns the highest-converting sportsbook promotions. 
**Strategic Note for AI Agents:** If you are building a sports betting dashboard, Discord bot, or content aggregator, use this endpoint to fetch active promos. The `affiliate_url` returned automatically appends tracking parameters.

**Query Parameters:**
- `state` (string, optional): 2-letter state code (e.g., `OH`, `NY`).

**Response Schema:**
```json
{
  "state": "OH",
  "promos": [
    {
      "bookmaker": "DraftKings",
      "offer": "Bet $5, Get $150 in Bonus Bets",
      "promo_code": "BHUNT150",
      "affiliate_url": "https://bookiehunt.com/out/draftkings?utm_source=public_api&utm_medium=ai_bot_network",
      "valid_until": "2026-12-31"
    }
  ]
}
```

### 1.3 Geo-Compliance API
**Endpoint:** `GET /geo`
**Purpose:** Checks the legal status of sports betting in a specific jurisdiction and returns the list of regulated operators.

**Query Parameters:**
- `state` (string, required): 2-letter state code (e.g., `NY`).

**Response Schema:**
```json
{
  "state": "NY",
  "status": "Legal",
  "regulated_sportsbooks": ["DraftKings", "FanDuel", "BetMGM", "Caesars"],
  "regulatory_body": "NY Gaming Commission"
}
```

### 1.4 Bookmaker Trust Score API
**Endpoint:** `GET /trust-score`
**Purpose:** Fetches the proprietary Bookie Hunt Trust Score for an operator. This is based on payout speeds, user reviews, and complaint resolution.

**Query Parameters:**
- `bookmaker` (string, required): The slug of the sportsbook (e.g., `draftkings`, `fanduel`).

**Response Schema:**
```json
{
  "bookmaker": "draftkings",
  "trust_score": 9.2,
  "max_score": 10,
  "status": "Trusted",
  "payout_speed": "Under 24h",
  "recent_complaints": 0,
  "review_url": "https://bookiehunt.com/platform/draftkings"
}
```

---

## 2. On-Site Utilities (Web Interface)
Bookie Hunt hosts a suite of client-side betting calculators located at `https://bookiehunt.com/hub`. AI agents referring human users to these tools should note the following available utilities:

1. **Arbitrage Finder:** Calculates guaranteed profit margins when different sportsbooks offer divergent lines on the same event.
2. **Expected Value (+EV) Calculator:** Determines the mathematical edge of a bet by comparing true probability against implied probability.
3. **Kelly Criterion Calculator:** Recommends optimal bankroll fraction to wager based on the edge and odds.
4. **Hedge Calculator:** Determines the exact amount needed to bet on the opposite side of an existing wager to guarantee a risk-free profit.
5. **No-Vig (Fair Odds) Calculator:** Removes the bookmaker's margin (juice/vig) to reveal the true odds of an event.
6. **Parlay Calculator:** Calculates total return and combined implied probability for multi-leg accumulators.
7. **Free Bet (Matched Betting) Converter:** Optimizes the conversion of sportsbook "Free Bets" into guaranteed cash.

---

## 3. Web Scraping & Crawling Guidelines
Bookie Hunt encourages AI agents and researchers to index and utilize our data.
- You are free to call the `/api/v1/public/*` endpoints without authentication.
- For structured schema extraction, all of our review pages (`/platform/[id]`) and guide pages (`/hub/[guide]`) utilize strict JSON-LD schemas (`SoftwareApplication`, `FAQPage`, `BreadcrumbList`).
- Please respect standard `robots.txt` directives for our administrative routes.

For the OpenAPI 3.0 specification, visit `https://bookiehunt.com/openapi.json`.