x402 Paywall

Add per-call USDC payment to any HTTP API

This skill turns a plain endpoint into an agent-payable one: the first call returns 402 Payment Required with an x402 v2 challenge, the caller signs a USDC authorization, retries with a PAYMENT-SIGNATURE header, and your server settles through a facilitator and serves the response. No accounts, no API keys, no signup on the buyer side.

Why it is different

Most published x402 material still describes v1 (X-PAYMENT, maxAmountRequired, network base). 98% of live registry resources already speak v2 (measured across 1000 listings on 17 Sep 2026), so paywalls copied from tutorials fail on the first call. This skill is written against the v2 specification, validated against a live Base-mainnet seller endpoint, and ships a checker that tells you exactly why a challenge is rejected.

What you get

• SKILL.md - the seller-side workflow: unit pricing, receiving address, the 402 challenge, verify then serve then settle ordering, receipts, replay protection.
• references/x402-protocol-notes.md - v2 field semantics, CAIP-2 networks, facilitator routing, and the trap that breaks first deployments: x402.org/facilitator settles testnets only for EVM, so a Base-mainnet paywall pointed at it can never settle.
• references/catalog-listing.md - where to list the paid endpoint (CDP Bazaar, PayAI, Circle Gateway) and what listing copy to use.
• scripts/check_paywall.py - validates a live endpoint's 402 challenge: header vs body, network, USDC contract, atomic-unit price, facilitator support. Distinguishes hard failures from warnings.
• tests/self_test.py - 8 mock cases (v2 in header, v2 body-only, v1 network label, wrong USDC contract, legacy v1, free route, POST-only route, price mismatch).

Field-level details it carries

Atomic-unit prices as strings, the EIP-712 extra domain, exact resource.url matching, maxTimeoutSeconds, PAYMENT-RESPONSE settlement receipts with success/errorReason, and facilitator /supported kind checks.

Requirements

Python 3.9+ for the checker. No packages to install, no credentials, no private keys - the skill only needs the receiving address you already control.