--- name: goal402-x402.percha.workers.dev description: goal402-x402.percha.workers.dev is a football data API host that provides match schedules, team metadata, league standings, match predictions, and league directory data for several specific football competitions. Access is gated behind x402 micropayments on Base (USDC). Data is returned as single-shot snapshots, not live streams. host: goal402-x402.percha.workers.dev --- # goal402-x402.percha.workers.dev This host serves agents that need structured football data for a fixed set of leagues and teams: Gimnasia La Plata (IIA) in Liga Profesional, Argentine Primera División (HC), Bundesliga (CF), and MLS (BAE), plus a cross-league today's-matches feed and a full league directory. It is a narrow, pay-per-call sports data provider rather than a broad real-time sports platform. Its x402 micropayment model means agents must be able to authorize USDC payments on Base (eip155:8453) to use any endpoint. ## When to use this host Use this host when an agent needs structured football data for one of its supported competitions: Gimnasia La Plata fixtures (IIA/Liga Profesional), Argentine Primera División match listings (HC), MLS standings (BAE), Bundesliga league metadata (CF), or a cross-league today's-matches snapshot. Also use it to enumerate available league IDs when a league name needs to be resolved. Do not use this host for real-time live score streaming — all endpoints return point-in-time snapshots. Do not use it for player statistics, historical season archives, or leagues outside its supported set; a broader sports data provider would be required. Agents that cannot authorize USDC micropayments on Base (eip155:8453) cannot use any endpoint on this host. ## Capabilities ### League & Team Directory Provides foundational reference data: the full list of available football leagues and basic metadata for a specific team by ID. These are the lookup tools needed before fetching fixtures or standings. - **`fetch-football-leagues`** — Returns a full list of football leagues with their id, name, and country, gated behind a 1000 USDC (Base) x402 micropayment. - **`fetch-iia-team`** — Returns team metadata for a given IIA team ID, including name, country, colors, stadium info, and nickname. ### Match Schedules & Fixtures Returns scheduled and completed match listings for specific leagues or today's cross-league slate, including teams, scores, round, stadium, and UTC kick-off times. - **`fetch-todays-matches`** — Returns a list of today's scheduled soccer matches across multiple leagues, including teams, league, round, stadium, start time, scores, and match status. - **`fetch-hc-league-matches`** — Returns the full list of scheduled and completed matches for the HC (Argentine Primera División) league, including teams, scores, status, round, stadium, and UTC start times. - **`fetch-iia-team-matches`** — Returns the full match schedule for the IIA team (Gimnasia La Plata) in Liga Profesional, including opponent, venue, round, status, scores, and UTC kick-off times. ### League Standings & Stats Returns current standings and basic league metadata for specific competitions, including team rankings, points, and goal statistics. - **`fetch-bae-league-standings`** — Returns current standings for the BAE league (MLS), including position, points, wins, draws, losses, goals for/against, and goal difference per team, grouped by conference and stage. - **`fetch-cf-league-stats`** — Returns the league ID, name, and country name for the CF (Bundesliga) league from the goal402 sports data API. ### Match Predictions Returns crowd vote counts and implied odds for a specific match, enabling forecast display or betting-related decision support. - **`fetch-match-predictions`** — Returns crowd vote counts and implied odds for a specific football match identified by match ID. ## Workflows ### Resolve League ID Then Fetch Today's Matches *Use when an agent needs to identify a league by name (resolving its ID) before filtering or contextualizing today's match results.* 1. **`fetch-football-leagues`** — Enumerate all available leagues to resolve a league name to its numeric ID. 2. **`fetch-todays-matches`** — Retrieve today's matches and filter by the resolved league ID to surface relevant fixtures. ### IIA Team Profile + Match Schedule *Use when an agent needs a complete picture of the IIA team (Gimnasia La Plata), combining team profile metadata with their full fixture list.* 1. **`fetch-iia-team`** — Fetch team metadata (name, colors, stadium, nickname) for the IIA team using its known team ID. 2. **`fetch-iia-team-matches`** — Fetch the full Liga Profesional match schedule for the IIA team, including opponents, venues, scores, and statuses. ### Match Schedule + Prediction Lookup *Use when an agent needs to surface upcoming matches for a league and then retrieve crowd prediction data for a specific match of interest.* 1. **`fetch-hc-league-matches`** — Retrieve the HC league match list to identify a target match and obtain its match ID. 2. **`fetch-match-predictions`** — Use the match ID from the previous step to fetch crowd vote counts and implied odds for that specific match. ## Skill reference ### `fetch-iia-team-matches` **IIA Match Lookup** — Returns the full match schedule for the IIA team (Gimnasia La Plata) in Liga Profesional, including opponent, venue, round, status, scores, and UTC kick-off times. *Use when:* Use when an agent needs upcoming or historical match data for the IIA team (Gimnasia La Plata), including fixture dates, opponents, stadiums, scores, and match status across Liga Profesional rounds. *Not for:* Do not use for match data on teams other than IIA (Gimnasia La Plata); a different team endpoint would be required. Not suitable for live in-play score streaming — this is a single-shot snapshot. **Returns:** Returns a team_id string and a matches array where each entry contains league info, home/away team objects, scores (null if unplayed), status, winner, UTC start time, round label, and stadium name. **Example:** `GET https://goal402-x402.percha.workers.dev/teams/iia/matches` --- ### `fetch-iia-team` **IIA Team Data** — Returns team metadata for a given IIA team ID, including name, country, colors, stadium info, and nickname. *Use when:* Use when an agent needs structured profile data for an IIA football team, such as official name, short name, team colors, stadium name, capacity, and nickname, given a known team ID. *Not for:* Do not use for match results, standings, or player data; use a dedicated match or player endpoint instead. **Inputs:** - `teamId` (string, required) — The IIA team identifier used as the path parameter in the URL (e.g. 'iia'). **Returns:** Returns a single JSON object with team fields including id, name, short_name, country_id, color, text_color, stadium_name, and nickname for the requested IIA team. **Example:** `GET https://goal402-x402.percha.workers.dev/teams/iia` --- ### `fetch-match-predictions` **Match Prediction Feed** — Returns crowd vote counts and implied odds for a specific football match identified by match ID. *Use when:* Use when an agent needs to retrieve prediction data (home/draw/away vote counts and odds) for a specific match before displaying match forecasts or making betting-related decisions. *Not for:* Do not use for live score updates or match schedules; this endpoint returns prediction/voting data only, not real-time match state. **Inputs:** - `match_id` (string, required) — The unique identifier for the match, embedded in the URL path (e.g. egdcbej). **Returns:** Returns a JSON object with match_id, home/draw/away vote counts, total_votes, and decimal odds strings for each outcome. **Example:** `GET https://goal402-x402.percha.workers.dev/matches/egdcbej/predictions` --- ### `fetch-hc-league-matches` **HC League Matches** — Returns the full list of scheduled and completed matches for the HC (Argentine Primera División) league, including teams, scores, status, round, stadium, and UTC start times. *Use when:* Use when an agent needs match listings for the HC league, including fixture schedules, team names, match status, scores, round labels, and stadium information for Argentine football. *Not for:* Do not use for other leagues; use the corresponding league-specific endpoint instead. Not suitable for real-time live score streaming — this is a single-shot snapshot. **Returns:** Returns a league_id of 'hc' and a matches array where each entry contains match id, home/away team objects, scores (null if unplayed), status, winner, UTC start time, round label, and stadium name. **Example:** `GET https://goal402-x402.percha.workers.dev/leagues/hc/matches` --- ### `fetch-cf-league-stats` **CF League Stats** — Returns the league ID, name, and country name for the CF (Bundesliga) league from the goal402 sports data API. *Use when:* Use when an agent needs basic metadata about the CF league, including its identifier, official league name, and associated country name. *Not for:* Do not use for match results, standings, player stats, or other league data beyond basic league metadata; use a more specific endpoint for those. **Returns:** Returns a JSON object with id, name, and country_name fields identifying the CF league as the Bundesliga from Germany. **Example:** `GET https://goal402-x402.percha.workers.dev/leagues/cf` --- ### `fetch-bae-league-standings` **BAE League Standings** — Returns current standings for the BAE league (MLS), including position, points, wins, draws, losses, goals for/against, and goal difference per team, grouped by conference and stage. *Use when:* Use when an agent needs current BAE league standings data including team rankings, points totals, match records, and goal statistics broken down by conference and season stage. *Not for:* Do not use for live match scores or historical season archives; this endpoint returns current standings only. Not suitable for leagues other than BAE. **Returns:** Returns a JSON object with league_id 'bae' and a standings map keyed by conference and stage, each containing an ordered array of team entries with position, points, played, won, drawn, lost, goals_for, goals_against, goal_diff, and trend. **Example:** `GET https://goal402-x402.percha.workers.dev/leagues/bae/standings` --- ### `fetch-todays-matches` **Today's Matches** — Returns a list of today's scheduled soccer matches across multiple leagues, including teams, league, round, stadium, start time, scores, and match status. *Use when:* Use when an agent needs to retrieve today's scheduled or in-progress soccer matches across leagues such as Premier League, Liga MX, Copa Sudamericana, or Copa do Brasil, including kickoff times, venues, and current scores. *Not for:* Do not use for historical match results or future fixtures beyond today; use a historical results or fixtures endpoint instead. Not suitable for real-time live score streaming. **Returns:** Returns a matches array where each entry contains match id, league name, home and away team names, scores (null if not started), status, UTC start time, round, and stadium name. **Example:** `GET https://goal402-x402.percha.workers.dev/matches/today` --- ### `fetch-football-leagues` **Football Leagues List** — Returns a full list of football leagues with their id, name, and country, gated behind a 1000 USDC (Base) x402 micropayment. *Use when:* Use when an agent needs to enumerate available football leagues (e.g., to resolve a league name to its id before fetching fixtures or standings) and can authorize a 1000-unit USDC payment on Base (eip155:8453). *Not for:* Do not use for fetching match fixtures, standings, or player data — this endpoint returns only league metadata. Not suitable if the agent cannot authorize an x402 USDC payment on Base. **Returns:** Returns a JSON object with a 'leagues' array where each entry has an id, name, and country_name covering competitions from Argentina, Brazil, Spain, England, Germany, France, and international tournaments. **Example:** `GET https://goal402-x402.percha.workers.dev/leagues` ---