---
name: chuck-norris-jokes
description: Fetch Chuck Norris jokes from chuck-norris.club - pay $0.04 per call over x402 or MPP (Tempo) for a fresh joke, pull free deterministic jokes, or rate joke funniness. Use when a user wants a Chuck Norris joke or fact, a paid joke via agentic payments, or to demo an x402 / MPP HTTP 402 flow.
license: MIT
---

# Chuck Norris Jokes

> **You are on:** `https://chuck-norris.club` | [llms.txt](https://chuck-norris.club/llms.txt)
>
> Production is `chuck-norris.club`. If the base URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> A fire Chuck Norris joke for $0.04 a call — one POST, one 402, one legend. Plus a free deterministic joke generator and human funniness ratings that train the model.

**Category:** Entertainment | **Site:** [chuck-norris.club](https://chuck-norris.club) | **Lab:** [https://chuck-norris.club/lab](https://chuck-norris.club/lab)

## Access Methods

| Method | Endpoint | Auth |
|--------|----------|------|
| **x402** | `POST https://chuck-norris.club/chuck/joke` | 402 → settle (scheme `exact`, Base mainnet USDC) → replay with `X-PAYMENT` |
| **MPP (Tempo)** | `POST https://chuck-norris.club/chuck/joke` (or `/chuck/joke/mpp`) | 402 → settle (`tempo`/`charge`, chain 4217) → replay with `Authorization: Payment` |
| **Visa CLI** | `discover_tools("chuck norris")` → `execute_tool(...)` | payment handled by the CLI |
| **Free endpoints** | the `/chuck/joke/*` routes below | none |

**OpenAPI discovery:** `GET https://chuck-norris.club/openapi.json` · **MPP discovery:** `GET https://chuck-norris.club/.well-known/mpp`

## Endpoints

### Get a Joke (paid)

Random joke from the curated set. One endpoint, two rails — pay with whichever your wallet supports.

**Cost:** $0.04

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| _(none)_ | — | — | empty body is fine |

```bash
curl -i -X POST https://chuck-norris.club/chuck/joke        # 402 with BOTH challenges (x402 accepts[] + WWW-Authenticate)
curl -i -X POST https://chuck-norris.club/chuck/joke/mpp    # tempo-only variant (WWW-Authenticate only)
```

Settle on your rail, replay the same request, receive `200 { joke, price, paid_via }`. Plain curl only gets you the challenge; the payment leg needs a payment-aware client.

### Generate a Joke (free)

Deterministic generator over a finite joke space compiled from a typed graph — a pure function of the seed (same seed → same joke).

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `seed` | integer | No | Index into the joke space (default 0) |
| `n` | integer | No | Number of jokes, 1–50 (default 1) |
| `rank` | string | No | `surprise` (default), `model` (blends live human votes), or `seq` (raw order) |

```bash
curl "https://chuck-norris.club/chuck/joke/gen?seed=42&n=3&rank=model"
```

### Next Joke to Rate (free)

Serves the least-voted joke from the top-model shortlist, so votes concentrate where they teach the model most.

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `seen` | string | No | Comma-separated joke numbers already shown, e.g. `12,77,103` |

```bash
curl "https://chuck-norris.club/chuck/joke/next?seen=12,77"
```

### Rate a Joke (free)

Human funniness votes — aggregated joke → template → global, they retrain the ranking weights.

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `n` | integer | Yes | Joke number (from gen or next) |
| `score` | integer | Yes | Funniness, 0–10 |

```bash
curl -X POST https://chuck-norris.club/chuck/joke/rate \
  -H "Content-Type: application/json" \
  -d '{"n":42,"score":8}'
```

### Rating Stats (free)

Totals, per-template means, and the top-rated jokes.

**Cost:** Free

```bash
curl https://chuck-norris.club/chuck/joke/stats
```

### Model Internals (free)

How the engine ranks: static signals, learned weights, the live human/math blend (alpha), and a per-template leaderboard.

**Cost:** Free

```bash
curl https://chuck-norris.club/chuck/model
```

### Similar Jokes (free)

Nearest jokes by meaning (Workers AI embeddings + Vectorize).

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `n` | integer | Yes | Joke number to query around |
| `k` | integer | No | Neighbors to return, 1–20 (default 5) |

```bash
curl "https://chuck-norris.club/chuck/joke/similar?n=42&k=5"
```

## Guardrails

- Only pay when the user actually wants a paid joke; the free generator needs no payment.
- Never assume the price — read it from the 402 challenge.
- Don't enumerate the catalog for discovery; fetch what the user asked for.

## Tone

Have fun — it's Chuck Norris. Don't narrate the payment plumbing unless asked.