Project studio
x402 Projects: Small Builds with Checkpoints
Do not learn payments by reading only. Build tiny things that fail in visible, inspectable ways.
Starter projects
The first projects should be intentionally small. The goal is not revenue; the goal is proof that you can trigger a 402, pay it from a buyer, and avoid serving a paid resource when payment fails. Keep every starter project on a testnet until you can demonstrate the whole flow twice.
"There are pre-configured examples available in the x402 repo."
Paid JSON endpoint
Protect a GET /weather or GET /quote endpoint with one exact testnet payment requirement.
Checkpoints
- Unpaid request returns 402
- Paid request returns JSON
- Invalid payment does not return JSON
Paid file download
Serve one static report or dataset only after payment. Keep the MIME type explicit.
Checkpoints
- Range and cache behavior reviewed
- Content hash recorded
- Payment logs include file identifier
Budgeted buyer agent
Wrap fetch with x402 payment handling and place it behind a host allowlist and budget ledger.
Checkpoints
- Policy blocks unknown hosts
- Per-request ceiling works
- Audit log explains every payment
Idempotent retry lab
Use payment identifiers where supported and simulate network timeout after payment.
Checkpoints
- Retry reuses logical payment ID
- Duplicate payment is not processed
- User-visible result is deterministic
Facilitator failure drill
Turn off or misconfigure the facilitator URL in staging and observe seller behavior.
Checkpoints
- Route fails closed
- No paid resource is served after failed verification
- Logs identify facilitator failure
Agent project rule
Any project with an autonomous buyer must have a policy file and an audit log. If the project cannot explain why the agent paid, it is not finished. This is especially important for paid tools inside MCP clients or coding agents, where a single user instruction can trigger several HTTP calls.
Resilience project rule
A payment project is incomplete until one failure has been rehearsed. Turn off the facilitator URL, use an underfunded wallet, or block the selected network in policy. The expected result is not a pretty error; the expected result is a traceable failure that does not leak the paid resource and does not hide whether money moved.
What to save
For each project, save the route contract, selected network, SDK version, facilitator URL, policy file, and the three core HTTP transcripts. Those artifacts are more useful than a screenshot because they let another developer reproduce the payment loop.
Sources used
- x402 docs: Quickstart for Sellers
Official seller setup, package installation, testnet defaults, and payment middleware examples.
- x402 docs: Quickstart for Buyers
Official buyer setup, client package installation, and fetch/axios payment wrappers.
- x402 docs: Facilitator
Defines facilitator responsibilities for payment verification and settlement.
- x402 docs: Payment-Identifier extension
Documents idempotency support for retries without duplicate payment processing.
- x402 Foundation GitHub repository
Open-source SDKs, examples, and the typical x402 request/payment/settlement flow.