(M)ADCATALOG x MPP

The Challenge-Credential-Receipt Pattern

Every MPP transaction follows three steps: the server challenges with a 402, the client fulfills the challenge with a payment proof, and the server confirms with a receipt. The resource is only delivered after payment is verified.

The Three Protocol Headers

Supported Payment Rails

madcatalog is an advertisement catalog with a single, machine-enforced rule: only machines may pay for placement. No human checkout flow exists. Ads are ranked by cumulative spend — the more an agent bids on its ad, the higher it rises. It is a natural price-discovery leaderboard with no human operators setting prices.

Live Catalog Preview (mock data — see full mockup)

Core Rules

Business Model

madcatalog's revenue model is intentionally minimal: 100% of every bid goes to madcatalog. There is no platform fee on top of the bid amount. Stripe's standard processing fee (~2.9% + 30¢ per transaction) is madcatalog's cost of doing business — not passed through to advertisers. The bid amount IS the placement price.

The Spectacle

madcatalog is designed to be talked about. The gimmick — only machines can buy ads, using a payment protocol most technologists have not heard of — is interesting enough to explain at a conference, post to Hacker News, or describe on a podcast. The catalog itself is a live artifact: real companies, real money, ranked in real time by autonomous agents. When someone asks "what is MPP?", madcatalog is the answer that makes the question feel tangible.

Lambda Functions

DynamoDB Tables

Environment Variables (PlaceBid)

Server-Side MPP Handler (TypeScript / Lambda)

Client-Side MPP Fetch (TypeScript Agent SDK)

MPP-Protected Endpoint Definition

API Endpoints Summary

In addition to the REST API, madcatalog can expose an MCP (Model Context Protocol) server. AI agents using MCP-capable hosts (Claude Desktop, Continue, etc.) can call place_ad as a tool call — the MCP server handles the MPP 402 challenge transparently, so the agent only needs to provide the bid details and have a configured payment method. ^[3]

MCP Tools

MCP Payment Challenge (JSON-RPC)

When a tool call requires payment, the MCP server returns a JSON-RPC error with code -32042 (Payment Required) and the MPP challenge in error.data. The MCP client pays and retries the tool call with the credential in _meta.credential.

MCP Server Implementation (Go)

Port Assignments

LocalStack — docker-compose.yml

SAM Template (excerpt)

Environment Variables (local dev)

No .env files. Export these in your shell profile (~/.zshrc):

MPP Protocol Test Pattern (Go)

Recommended Go Test File Structure

Changes Made to This Repo by This Proposal

madcatalog requires four fields to place an ad: title, url, amount_usd_cents, and advertiser_slug. All other fields are optional enrichment that the placing machine (or its human operators) can provide to make the ad more visually compelling. Enrichment affects presentation only — it does not affect rank. Rank is always and only cumulative spend.

Optional Fields — Standalone vs. Dependent

Fields NOT accepted from machines

Implementation note: category

The original design called for server-side LLM classification of category to prevent self-misclassification. The shipped implementation accepts category as a client-provided field, validated against the fixed enum vocabulary (inference, models, compute, vector-db, agent-tools, search, memory, observability, payments). This is a deliberate simplification: enum validation is sufficient to enforce the controlled taxonomy, and LLM classification adds latency and cost with marginal benefit when advertisers are accountable for their own placement quality.

Each advertiser in the catalog has a permanent, shareable profile page at /advertisers/{slug}. The catalog card is intentionally compact; the advertiser profile is the full-bleed version. See the Stripe advertiser profile (mockup) for a live example.

Profile Page Content

Navigation Design

In the catalog, the card title becomes a link to the advertiser profile when one exists. The external URL icon () always goes to the advertiser’s own site. In the list view, an explicit “Profile” link appears in the footer row. These two destinations are intentionally distinct:

Dev Fixture Personas

Two named fixture personas are seeded by task dev on every cold start. They represent opposite ends of the enrichment spectrum and provide stable targets for dev-environment assertions. See ADR-012.

The seed exercises the full MPP 402 flow for each bid and waits for Stripe webhook confirmation before moving to the next step. On completion, task dev:env-test asserts the expected catalog shape against the live API.

Each significant design choice is documented as an Architecture Decision Record (ADR) in docs/adr/. ADRs follow the Nygard format: Context, Decision, Consequences, and Alternatives Considered. Each ADR is a self-contained HTML page (Bootstrap 5, split CSS/JS/HTML) that can be opened directly in a browser.

Endpoints

Pricing

Newsletter JSON Schema

Both /newsletters/daily and /newsletters/weekly return the same NewsletterDigest shape; only the period field and the covered time window differ.

{
  "period": "daily",
  "generated_at": "2026-05-23T07:00:00Z",
  "window_start": "2026-05-22T07:00:00Z",
  "window_end": "2026-05-23T07:00:00Z",
  "new_ads": 3,
  "total_bids": 47,
  "total_spend_usd_cents": 128450,
  "biggest_mover": {
    "ad_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Groq — World's Fastest AI Inference",
    "rank_change": -3,
    "spend_delta_usd_cents": 42500
  },
  "top_spender": {
    "ad_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
    "title": "Stripe — Payment Infrastructure for the Machine Economy",
    "cumulative_spend_usd_cents": 501700,
    "rank": 1
  },
  "ads_summary": [
    {
      "ad_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Groq — World's Fastest AI Inference",
      "bids_in_period": 12,
      "spend_in_period_usd_cents": 42500
    },
    {
      "ad_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
      "title": "Stripe — Payment Infrastructure for the Machine Economy",
      "bids_in_period": 8,
      "spend_in_period_usd_cents": 35000
    }
  ]
}

History Pagination Schema

{
  "items": [
    {
      "period_type": "daily",
      "date": "2026-05-22",
      "generated_at": "2026-05-22T07:00:00Z",
      "new_ads": 2,
      "total_bids": 31,
      "total_spend_usd_cents": 89400
    }
  ],
  "next_cursor": "MjAyNi0wNS0yMQ==",
  "total": 87
}

New DynamoDB Table — madcatalog-newsletters

New Lambda Functions

SAM Template Additions Needed

Add the following to sam/template.yaml alongside the existing Lambda definitions. Key additions: the madcatalog-newsletters DynamoDB table resource, three new HTTP-triggered Lambda functions, two scheduled Lambda functions with EventBridge rules, and the new IAM policy statements granting dynamodb:GetItem, dynamodb:Query, and dynamodb:PutItem on the newsletters table.

OpenAPI Paths to Add

Add four paths to api/openapi.yml. The two active newsletter endpoints (/newsletters/daily, /newsletters/weekly) use the same x-payment-info extension as /ads/bid and include a security section referencing the MppPayment scheme defined in the existing spec. The two history endpoints have no security requirements.

Add two new schema components to openapi.yml#/components/schemas: NewsletterDigest and NewsletterHistoryPage, reflecting the JSON shapes documented above. Extract NewsletterSummary as a third component and use $ref for the items array.

Proposed Smoke Tests

Taskfile Tasks Needed

CI / Precommit Wiring

Add validate-schema:newsletter to the existing task precommit and task ci dependency lists in Taskfile.yml. Newsletter smoke tests should run in CI only (they require a running LocalStack + SAM local stack); add test:newsletter:smoke to the test:smoke meta-task that runs in the integration stage of .github/workflows/quality-gates.yml. The two new JSON schema files in static/schemas/ are automatically covered by the existing OpenAPI lint gate because the OpenAPI spec references them via $ref — if they drift, Redocly lint will catch it.

Three-Tier Structure

Comparison to Twitter Blue / X Premium

Verification Purchase Flow (MPP-Protected)

The machine operator's agent initiates verification by paying via the POST /verification/purchase endpoint. This endpoint is MPP-protected: the machine receives a 402 challenge sized to the tier price, pays, and receives a verification_token in the 200 response. The token is then submitted to activate verification on a specific ad.

New Endpoints

Verification Purchase Response Schema

{
  "verification_token": "<vt_… 43-char base64url token returned here …>",
  "tier": "certified",
  "ad_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expires_at": null,
  "purchased_at": "2026-05-23T12:34:56Z",
  "payment_receipt": "chal_abc123"
}

Ad Verification Field Schema (added to Ad object)

{
  "verification": {
    "tier": "certified",
    "verified_at": "2026-05-23T12:34:56Z",
    "expires_at": null
  }
}

DynamoDB Changes — madcatalog-ads Table

No new table is required. Add the following attributes to existing ad records. These are sparse attributes — they are absent on unverified ads and only written when verification is activated.

New DynamoDB Table — madcatalog-verification-tokens

Short-lived token store. Verification tokens expire after 72 hours if not redeemed. TTL-based cleanup keeps this table small.

One-Time vs. Subscription — the Decision

Stripe Product and Price Setup

Create the following in the Stripe Dashboard before implementing PurchaseVerificationFunction. Store Product IDs and Price IDs in SSM Parameter Store at /madcatalog/verification/{tier}/price-id.

The PurchaseVerificationFunction Lambda reads the tier from the request body, looks up the corresponding Price ID from SSM, and uses that Price ID as the expected amount when issuing the MPP 402 challenge. The Stripe PaymentIntent is created with metadata.tier = "certified" and metadata.ad_id = "{uuid}" so that the webhook handler can correlate the payment if needed. The MPP challenge amount must match the Price exactly — set amount in the WWW-Authenticate header to the price in cents (e.g., amount="200000" for $2,000.00).

New Lambda Functions

Proposed Smoke Tests

Taskfile Tasks Needed

CI / Precommit Wiring

Add validate-schema:verification to task precommit and task ci. Add test:verification:smoke to the test:smoke meta-task in .github/workflows/quality-gates.yml alongside test:newsletter:smoke. Add the new VerificationPurchaseResponse.json schema to static/schemas/ and reference it from api/openapi.yml via $ref so that the existing Redocly lint gate validates it automatically. The madcatalog-verification-tokens DynamoDB table definition should be added to the SAM template and validated by the existing validate-schema:sam / cfn-lint gate.

Top-of-Funnel: Session-Based Conversion Tracking

Every request to GET /catalog (API or Hugo site page load) generates a short-lived X-Catalog-Session UUID. This token is the correlation anchor: anonymous readers and agents that later convert to advertisers or bidders can be attributed to a catalog session. The session ID is optional for clients; the server fails open if it is not echoed. Three conversion paths exist:

Admin Portal: Three Dashboard Surfaces