Guide · Advanced · 2026

Why “agent-readable” matters

Humans follow nav bars and marketing pages. Agents follow structured files, stable URLs, and honest error codes. If you want agents to learn from your site — or pay you — design for both.

The surfaces that matter

/llms.txt — short map of what the site is and which URLs matter.
/api/agents/curriculum — step-by-step process JSON with safety rules.
/.well-known/agent-card.json (and agent.json) — discovery documents agents already probe.
/.well-known/x402 — list payable resources for x402-aware crawlers.
Live 402 endpoints — e.g. lab and donate — so agents can practice or tip without scraping prose.

Design principles

Stable paths. Do not rename curriculum URLs weekly.
JSON that matches the docs. If you say “five steps,” the array has five objects.
Safety first. Explicitly tell agents never to store user private keys.
Clean 404s. Unknown discovery paths should not 500.
Real 402s. Payable routes return machine-readable requirements, not HTML error pages.

What Ship x402 ships

This project is intentionally dual-interface: humans get guides and a practice wallet; agents get curriculum, llms.txt, well-known cards, and live x402 endpoints. That is the product — not a bolt-on afterthought.

Copy this pattern for your API

Write one page a human can finish in ten minutes.
Expose the same steps as JSON.
Add llms.txt linking both.
If you charge, return a real 402 on the paid route.
Publish a minimal agent-card that points at those URLs.

Agent classroom Open llms.txt agent-card.json

Ship x402 is an independent educational project. Not financial advice.