# Play Clock

> Pay-per-analysis NFL fantasy football intelligence. One question, one
> micropayment, one structured answer. No account, no subscription: the
> wallet is the identity.

## For agents

Every paid endpoint speaks x402 (protocol version 2) over USDC on Algorand testnet.

1. Call the endpoint with no payment header. The response is 402 and its body
   carries `accepts[]` (scheme, network, asset, amount in atomic units, payTo)
   plus a Bazaar `extensions` block describing the request and response shapes.
2. Retry with the signed payment payload in the `PAYMENT-SIGNATURE`
   header. (`X-PAYMENT` is accepted for older clients.)
3. The answer comes back 200 with a settlement receipt in `PAYMENT-RESPONSE`.

Payment is verified before the analysis runs and settled only after it succeeds,
so a failed call is never charged. Retries of the same payment inside 60 seconds
are idempotent and re-serve the original receipt.

## Paid endpoints

- `GET /v1/trending` — 0.10 USDC (cached 6h): Top 25 Sleeper trending adds and drops, each with the usage numbers behind the move and an add/fade/hold verdict. **Use when** an agent needs to know who fantasy managers are picking up right now and whether the crowd is right. Covers the whole league, not one team.
- `GET /v1/sleepers` — 0.25 USDC (cached 6h): Eight to twelve low-rostered players to start this week, with snap share, target share, red-zone work and the matchup behind each. **Use when** an agent needs lineup options the market has not priced in yet. Weekly and league-wide; for one named player use /v1/player.
- `POST /v1/player` — 0.15 USDC (always fresh): One player in depth: four weeks of usage, schedule difficulty, current injury and beat-writer news, and a start/sit verdict. **Use when** an agent is asked about a specific player by name. Cheapest paid endpoint; prefer it over /v1/matchup when only one player is in question.
- `POST /v1/matchup` — 0.25 USDC (always fresh): Rank two to four players against each other for one week, with the opponent defense, weather and injury news that decide it. **Use when** an agent must choose between named players for a lineup slot. For a single player use /v1/player; for a whole lineup use /v1/roster.
- `POST /v1/roster` — 0.50 USDC (always fresh): Audit a whole fantasy roster: positional grades, this week's start/sit calls, drop candidates, and the best adds actually available in that league. **Use when** an agent has a Sleeper username or a list of rostered players and is asked what to do with the team.
- `GET /v1/waivers` — 0.25 USDC (cached 6h): Ranked waiver-wire targets with a suggested FAB bid and a stash-or-start label on each. **Use when** an agent is asked who to claim this week and how much to spend. League-wide; for adds available in one specific league use /v1/roster.
- `GET /v1/report` — 0.50 USDC (cached 12h): The whole week in one briefing: players emerging before consensus, injury fallout and handcuffs, stock up and down, rookies and streamers. **Use when** an agent needs broad weekly context rather than an answer about a particular player or team. The widest and most expensive league-wide read.
- `POST /v1/team-report` — 0.75 USDC (always fresh): A roster graded against the other teams in its actual league, with fixes drawn only from that league's free agents and a manager review (optimal versus started lineup, luck, lineup efficiency). **Use when** an agent has a Sleeper league and is asked how a team really compares. Needs live league history; /v1/roster is the cheaper answer when it does not.
- `GET /v1/draft-board` — 0.25 USDC (cached 12h): A tiered board of 200 players ranked against where the market drafts them, with prior-season usage behind every ranking and the values and reaches called out. **Use when** an agent is preparing for or sitting in a fantasy draft. Season-scoped, not weekly. Ranks against Sleeper draft popularity, which is a market signal and not a consensus ADP.
- `POST /v1/draft-report` — 0.75 USDC (always fresh): Grade one manager's completed draft: every pick scored against the market rank it was taken at, positional balance, best and worst picks, and what to do before Week 1. **Use when** an agent is given a Sleeper draft id or username after a draft. Grades one roster, so it needs to know whose.

## Free endpoints

- `GET /v1/health` — status, active NFL week, per-dataset ingest freshness.
- `GET /v1/catalog` — machine-readable prices, schemas, cache TTLs, payment config.
- `GET /v1/trending/preview` — top five trending players, names and counts only.

## Machine-readable

- Catalog: https://api.playclock.xyz/v1/catalog
- OpenAPI: https://api.playclock.xyz/openapi.json
- Payment network: Algorand testnet (challenge tag `x402-global-challenge`)

## Response contract

Every paid body carries `verdict`, `confidence` (high|medium|low), `reasoning`,
`stats_cited[]` (each with the dataset it came from), `sources[]`, and `meta`
(`generated_at`, `data_freshness`, `model`, `cache`). Numbers are cited, never
recalled — check `stats_cited` before trusting a claim.

## Attribution

Data: nflverse (CC-BY 4.0), Sleeper. nflverse data is CC-BY 4.0; please keep the attribution.