# Goal402 — Football / Soccer Data API

> Pay-per-call football data powered by x402 micropayments (USDC on Base or Solana).
> No API keys. No subscriptions. Just pay per request.
> Facilitator: Dexter (https://x402.dexter.cash) — no signup needed.

## Base URL

https://goal402-x402.percha.workers.dev

## Authentication

This API uses the x402 protocol. Send a standard HTTP request; if payment is
required the server responds with HTTP 402 and a PAYMENT-REQUIRED header.
Sign the payment with a wallet holding USDC (on Base or Solana) and retry
with the PAYMENT-SIGNATURE header. Any x402-compatible client or SDK handles
this automatically. Both EVM and Solana wallets are supported.

## Coverage

- 52 leagues across 20+ countries (Argentina, Brazil, England, Spain,
  Germany, Italy, France, Portugal, Netherlands, USA, Mexico, and more)
- Full team rosters with players and coaching staff
- Live matches updated every 5 minutes
- Match detail: events, statistics, lineups, formations
- Standings with group/conference support
- Predictions, odds, and head-to-head records
- All data translated to English

## Endpoints & Pricing

### Leagues

GET /leagues  (FREE)
  List all leagues. Returns: { leagues: [{ id, name, country_name }] }
  No payment required. Use this to discover league IDs for other endpoints.

GET /leagues/{id}  ($0.001)
  Single league detail. Returns: { id, name, country_name }

GET /leagues/{id}/standings
  League standings table. Returns nested object grouped by table name and
  group name, each entry: { position, team, points, played, won, drawn,
  lost, goals_for, goals_against, goal_diff, trend }

GET /leagues/{id}/matches?status={live|finished|upcoming}&limit={n}&offset={n}
  League matches with optional filtering. Returns array of match summaries.

### Teams — $0.01 per call

GET /teams/{id}
  Team detail including stadium info, colors, founded year, city, nickname.

GET /teams/{id}/players
  Full roster: players (name, number, position, age, height, weight,
  country, birthdate) and coaching staff.

GET /teams/{id}/matches?status={live|finished|upcoming}&limit={n}&offset={n}
  Team match history with league info and optional filtering.

### Matches — $0.001 for lists, $0.01 for detail

GET /matches/live
  All currently live matches with scores and game time.

GET /matches/today
  Full schedule for today.

GET /matches/{id}  ($0.01)
  Complete match detail: events (goals, cards, substitutions, VAR),
  statistics (possession, shots, fouls, corners), and full lineups
  with formations and pitch positions.

GET /matches/{id}/predictions  ($0.001)
  Community vote predictions and betting odds.

GET /matches/{id}/h2h  ($0.001)
  Head-to-head historical record between the two teams.

### Free endpoints (no payment required)

GET /              API info, pricing, and response schemas
GET /leagues       List all leagues with IDs (discovery endpoint)
GET /health        Health check and database status
GET /.well-known/x402   x402 discovery manifest
GET /llms.txt      This file

## Example Queries

- "What are today's football matches?" → GET /matches/today
- "Show me the Premier League standings" → GET /leagues/{premier_league_id}/standings
- "Get Boca Juniors' last 5 results" → GET /teams/{boca_id}/matches?status=finished&limit=5
- "Full detail for match X" → GET /matches/{id}
- "Who plays for River Plate?" → GET /teams/{river_plate_id}/players
- "All live matches right now" → GET /matches/live
- "Head to head for this upcoming match" → GET /matches/{id}/h2h

## Sample League IDs

hc   Liga Profesional (Argentina)
bae  MLS (USA)
ha   Premier League (England)
hb   La Liga (Spain)
hd   Serie A (Italy)
he   Bundesliga (Germany)
hf   Ligue 1 (France)
hg   Primeira Liga (Portugal)
hh   Eredivisie (Netherlands)
hi   Serie A (Brazil)

## Networks

Payments accepted in USDC on either chain:
- Base (EVM): Chain ID eip155:8453
- Solana: Chain ID solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
Facilitator: Dexter (https://x402.dexter.cash) — no API key needed.

## Links

- API: https://goal402-x402.percha.workers.dev
- x402 Protocol: https://x402.org