# NFL Fantasy x402 API

Pay-per-call NFL/fantasy football analytics for AI agents. Payment via the
x402 protocol (USDC on Base) — no accounts, no API keys. Unpaid requests to
paid endpoints return HTTP 402 with machine-readable payment requirements;
retry with an x402 payment header to receive a 200 response.

Data derived from nflverse (https://github.com/nflverse/nflverse-data),
licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).
Modified: filtered weekly rows; custom fantasy scoring/aggregation.
Weekly stats + Next Gen Stats, 2015–present (see /api/meta/health for latest).

## Endpoints

### GET /api/player/stats — $0.01
Weekly or season-aggregated fantasy stats, scored to any scoring config.
Params: player_id (nflverse GSIS id) OR name; seasons (CSV; default =
previous+latest season in DB); weeks (e.g. 5 or 3-8); season_type
(REG|POST|ALL, default REG); preset (ppr|half_ppr|standard|ppr_6pt_pass|
te_premium, default ppr); scoring (JSON overrides, e.g. {"pass_td":6,"rec":0.5});
agg (weekly|season).
Returns: player, resolved scoring config, rows with fantasy_points_scored,
attribution.
Ambiguous names return HTTP 400 with a candidates[] list — pass player_id.

### GET /api/player/usage — $0.02
Usage/opportunity metrics with recent-week trend deltas.
Params: player_id OR name; season (default = latest season in DB); last_n
(default 4, max 18).
Returns: per-metric {season_avg, last_N_avg, trend} for target_share,
air_yards_share, wopr, and NGS fields, plus attribution.

### GET /api/meta/scoring-presets — FREE
Inspect available scoring presets and the override format before paying.

### GET /api/meta/health — FREE
Row count, latest season/week in the dataset, uptime.

### POST /api/draft/value-board — $0.10
Draft value board ranked by marginal value to YOUR roster (not BPA).
Body: league {teams, roster, flex_positions?, flex_slots?} (required);
scoring {preset?, overrides?}; my_roster (ids/names); drafted (ids/names);
pick {overall?, next_pick?, future_picks?, snake?}; adp + adp_format
(ffc_v1|normalized); projections + projections_format
(fantasypros_v1|sleeper_v1|normalized); bench_weights; candidates (default 25, max 50).
Returns: board (ranked BoardEntry[] with marginal_value, replacement_delta,
fills_slot, survival, opportunity_cost, urgency_adjusted_value, reason),
replacement_levels, warnings, meta, attribution.
No third-party data (ADP/ECR/projections) is ever stored — caller-supplied only.
Ambiguous roster/draft names are skipped with a warning (board still returns).

### GET /api/meta/data-sources — FREE
Orchestration manual: where to fetch ADP (FantasyFootballCalculator) and
projections (FantasyPros, Sleeper) yourself, and the two-call recipe to submit
them to /api/draft/value-board. This API never proxies third-party data.

## Notes for agents
- Call /api/meta/scoring-presets first to confirm scoring options; it's free.
- Prefer player_id (nflverse GSIS) over name. Ambiguous name queries on
  /api/player/* return 400 with candidates[]; value-board skips them with warnings.
- When redistributing responses, retain the attribution field / CC BY 4.0 credit.