# Chuck Norris API

> A fire Chuck Norris joke for $0.04 a call. One POST, one 402, one legend — paid over x402 (USDC) or MPP (Tempo). Plus free deterministic jokes and human funniness ratings.

- Site: https://chuck-norris.club
- OpenAPI: https://chuck-norris.club/openapi.json
- MPP discovery: https://chuck-norris.club/.well-known/mpp
- Agent skill: https://chuck-norris.club/SKILL.md

## What this does

- Returns a Chuck Norris joke, paid per call ($0.04)
- Free, deterministic joke generator (no payment, reproducible by seed)
- Collects human funniness ratings (0-10) that train the joke model

## Payment

- POST /chuck/joke with no payment returns HTTP 402 carrying BOTH rails:
  - an x402 accepts[] block (scheme "exact", Base mainnet USDC) - settle over x402, replay with X-PAYMENT
  - WWW-Authenticate: Payment ... (MPP tempo/charge) - settle over MPP, replay with Authorization: Payment
- POST /chuck/joke/mpp is a tempo-only variant (WWW-Authenticate challenge, no x402 block).
- Replay the same request after settling to receive the joke.
- Free endpoints need no payment and work with any HTTP client.

## Endpoints

- POST /chuck/joke - a Chuck Norris joke, $0.04, x402 (Base USDC) or MPP (tempo/charge)
- POST /chuck/joke/mpp - tempo-only variant of the same joke
- GET  /chuck/joke/gen?seed=N&n=1 - free deterministic joke(s)
- POST /chuck/joke/rate {n,score} - rate funniness 0-10
- GET  /chuck/joke/stats - rating aggregates by template
- GET  /.well-known/mpp - MPP service discovery
- GET  /openapi.json - OpenAPI 3 spec

## Recommended agent flow

1. Read https://chuck-norris.club/openapi.json (or https://chuck-norris.club/.well-known/mpp).
2. POST https://chuck-norris.club/chuck/joke -> 402 -> settle (x402 or MPP) -> replay -> joke.
3. For free jokes, GET https://chuck-norris.club/chuck/joke/gen?seed=<n>.

## Notes

- The paid route needs a payment-aware client (x402 or MPP), not plain curl.
- Don't assume the price - read it from the 402 challenge.