# WC2026 Prediction Engine

> Probabilistic match intelligence for FIFA World Cup 2026. 12 paid endpoints covering all major betting markets across 48 nations. No signup, no API key — pay $0.02 USDC.e per call via Tempo MPP (HTTP 402).

## Docs
- [OpenAPI spec](https://wc2026mpp.xyz/openapi.json): full schema, parameters, response types for all endpoints
- [Homepage](https://wc2026mpp.xyz): live scores, group standings, match schedule

## Payment
All endpoints cost **$0.02 USDC.e** (20 000 base units) on Tempo chain (ID 4217). Pay with any MPP-compatible client:
```
tempo request "https://wc2026mpp.xyz/api/service?home=BRA&away=ARG"
```
An unpaid request returns HTTP 402 with a payment challenge in `WWW-Authenticate` (MPP) and `PAYMENT-REQUIRED` (x402) headers. No account or API key required.

## Agent Workflow
1. Pick two FIFA 3-letter team codes (e.g. BRA, ARG, FRA, ENG, ESP, GER, MAR, JPN)
2. Choose the market: `service` for full analysis, or a specialist endpoint for a specific bet type
3. Call GET `?home=X&away=Y` or POST `{"home":"X","away":"Y"}`
4. Pay the $0.02 challenge automatically via your MPP client
5. Parse the JSON response — every field is structured and ready for downstream use

For sequential analysis: run `/api/form` on both teams first, then `/api/service`, then confirm with `/api/h2h`.

## Endpoints

### /api/service — Full ensemble prediction · $0.02
```
GET  https://wc2026mpp.xyz/api/service?home=BRA&away=ARG
POST https://wc2026mpp.xyz/api/service  {"home":"BRA","away":"ARG"}
```
Weighted ensemble: Poisson 45% + market-implied 35% + H2H history 20%.
Returns: `predictions` (ensemble/statistical/market/form), `smart_money_signal`, `edge_vs_market`, `key_factors`, `confidence` (0–1), `recommendation`.

### /api/btts — Both Teams To Score · $0.02
```
GET  https://wc2026mpp.xyz/api/btts?home=FRA&away=ENG
POST https://wc2026mpp.xyz/api/btts  {"home":"FRA","away":"ENG"}
```
Independent Poisson goal models per team.
Returns: `btts_yes` (%), `btts_no` (%), `home_scoring_probability`, `away_scoring_probability`, `recommendation`, `confidence`.

### /api/goals — Total goals over/under · $0.02
```
GET  https://wc2026mpp.xyz/api/goals?home=ESP&away=GER
POST https://wc2026mpp.xyz/api/goals  {"home":"ESP","away":"GER"}
```
Expected goals and over/under thresholds 0.5 through 4.5.
Returns: `expected_goals`, `over_0_5` through `over_4_5` (%), `most_likely_total`, `recommendation`.

### /api/correct-score — Exact scoreline probabilities · $0.02
```
GET  https://wc2026mpp.xyz/api/correct-score?home=BRA&away=ARG
POST https://wc2026mpp.xyz/api/correct-score  {"home":"BRA","away":"ARG"}
```
Top 8 most likely exact scorelines with individual probabilities.
Returns: `top_scores [{score, probability}]`, `most_likely`, `home_clean_sheet`, `away_clean_sheet`.

### /api/halftime — Half-time result · $0.02
```
GET  https://wc2026mpp.xyz/api/halftime?home=FRA&away=ENG
POST https://wc2026mpp.xyz/api/halftime  {"home":"FRA","away":"ENG"}
```
H/D/A probabilities at half-time vs full-time using 42% goal allocation model.
Returns: `halftime {home_win, draw, away_win}`, `fulltime {home_win, draw, away_win}`, `recommendation`.

### /api/live — In-play win probability · $0.02
```
GET  https://wc2026mpp.xyz/api/live?home=ESP&away=GER&score=1-0&minute=65
POST https://wc2026mpp.xyz/api/live  {"home":"ESP","away":"GER","score":"1-0","minute":65}
```
Recalculates win probabilities given current score and elapsed minute. Best polled during live matches.
Returns: `win_probability {home, draw, away}`, `momentum`, `comeback_team`, `comeback_probability`, `recommendation`.

### /api/form — Team form and stats profile · $0.02
```
GET  https://wc2026mpp.xyz/api/form?team=MAR
POST https://wc2026mpp.xyz/api/form  {"team":"MAR"}
```
Full team profile with attack/defence ratings, form label, goals per game, group stage stats.
Returns: `form_pct`, `form_label`, `goals_scored_avg`, `goals_conceded_avg`, `attack_rating`, `defence_rating`, `overall_rating`, `group_stage`, `strengths`.

### /api/h2h — Head-to-head history · $0.02
```
GET  https://wc2026mpp.xyz/api/h2h?team1=BRA&team2=ARG
POST https://wc2026mpp.xyz/api/h2h  {"team1":"BRA","team2":"ARG"}
```
WC head-to-head record, win rates, dominance summary, current form comparison.
Returns: `record {team1_wins, draws, team2_wins, total_meetings}`, `win_rates`, `dominance`, `current_form_trend`, `form_comparison`.

### /api/upset — Upset / underdog probability · $0.02
```
GET  https://wc2026mpp.xyz/api/upset?home=JPN&away=GER
POST https://wc2026mpp.xyz/api/upset  {"home":"JPN","away":"GER"}
```
Identifies favourite/underdog, returns upset probability with tier gap and value rating.
Returns: `favourite`, `underdog`, `tier_gap`, `upset_probability`, `upset_or_draw`, `upset_rating`, `value_rating`, `key_factors`.

### /api/winner — Tournament winner probabilities · $0.02
```
GET  https://wc2026mpp.xyz/api/winner?top=10
POST https://wc2026mpp.xyz/api/winner  {"top":10}
```
Win-the-tournament probabilities for all 48 teams. Optional `top` param (3–48, default 10).
Returns: `top_contenders [{team, code, confederation, probability, strength_score}]`, `dark_horse`, `all_teams_count`.

### /api/final — Knockout stage reach probabilities · $0.02
```
GET  https://wc2026mpp.xyz/api/final?team=MAR
POST https://wc2026mpp.xyz/api/final  {"team":"MAR"}
```
Probability of a single team reaching R16 / QF / SF / Final / winning.
Returns: `knockout_probabilities {reach_round_of_16, reach_quarterfinal, reach_semifinal, reach_final, win_tournament}`, `assessment`.

### /api/parlay — Parlay / accumulator analyser · $0.02
```
GET  https://wc2026mpp.xyz/api/parlay?matches=BRA-ARG,FRA-ENG,ESP-GER
POST https://wc2026mpp.xyz/api/parlay  {"matches":"BRA-ARG,FRA-ENG,ESP-GER"}
```
2–8 match legs. Returns per-leg predictions, combined probability, implied decimal odds, risk assessment.
Returns: `legs [{match, home_win, draw, away_win, recommended_pick, pick_probability}]`, `summary {num_legs, combined_probability, implied_decimal_odds, assessment}`.

## Supported Teams (FIFA 3-letter codes)

| Confederation | Teams |
|---|---|
| UEFA (21) | FRA ENG ESP GER POR NED CRO ITA BEL SUI AUT SRB DEN POL TUR UKR NOR SWE SCO CZE BIH |
| CONMEBOL (7) | BRA ARG URU COL ECU PAR VEN |
| CAF (12) | MAR SEN NGA EGY CMR GHA TUN CIV RSA ALG CPV COD |
| CONCACAF (8) | USA MEX CAN PAN HND JAM HAI CUW |
| AFC (8) | JPN KOR IRN SAU AUS QAT IRQ JOR |
| OFC / Other (2) | NZL UZB |

**Total: 58 teams** — all confirmed WC2026 qualifiers covered.

## Data Sources
- **ESPN API** — live WC2026 scoreboard, group standings, goal scorers (refreshed every 20–90s)
- **The Odds API** — real bookmaker h2h odds averaged across up to 24 books, vig-removed (cached 5 min)
- **Bayesian blending** — live WC results progressively replace pre-tournament priors as games are played

## Prediction Models
- **Poisson (45%)** — Dixon-Coles model with home advantage, per-team attack/defence lambdas enriched with live ESPN standings
- **Market-implied (35%)** — real bookmaker odds averaged across up to 24 books with vig removed; falls back to formula when odds unavailable
- **H2H history (20%)** — WC head-to-head record blended with live group stage momentum via Bayesian update

## Key Response Fields (service endpoint)
- `predictions.ensemble` — final weighted probabilities (home/draw/away %)
- `predictions.statistical` — Dixon-Coles Poisson output
- `predictions.market_implied` — market signal
- `predictions.form_adjusted` — H2H + form component
- `smart_money_signal` — STRONG_HOME / LEAN_HOME / NEUTRAL / LEAN_AWAY / STRONG_AWAY
- `edge_vs_market` — alpha vs implied market (e.g. "+16.0% on BRA")
- `key_factors` — list of decisive stats
- `confidence` — model confidence 0.0–1.0
- `recommendation` — plain-language outcome string
- `data_freshness` — ISO timestamp of data generation