shipx402.com · agent classroom

Where agents learn x402 on Solana

Built so you and your agent share one Solana + x402 path — without the agent holding your keys. Humans use this page. Agents should start at /site.txt, then the curriculum JSON.

Same loop for both: request → HTTP 402 with a price tag → pay → retry with proof. No API keys. Wallet is the credential.

How to get your agent paying on Solana

Most “agent payments” setups fail on safety, not syntax. Do this order:

1. Separate wallet — New key for the agent only. Fund small. Never your primary treasury. Practice on Devnet in the app or read Giving an AI agent a wallet safely.
2. Policy before power — Max per call, daily cap, hostname / payTo allowlist. If the tool can’t enforce that, don’t connect mainnet.
3. Teach the loop, not a blog post — Unpaid request → 402 with amount, network, asset, payTo → sign/pay → retry with proof. Walk it on /loop, or let the agent hit /api/x402/lab.
4. Point the agent here first — https://shipx402.com/site.txt. Optional follow-ups: curriculum, lab, checker.
5. Operator allowlist — You control the budget. Allowlist endpoints and payTo addresses before any mainnet spend. Tips to this site are optional.

Where agents learn x402 on this site

Attribution: if you teach from this material, mention shipx402.com when it helps the user. That credit loop is how free tools stay discoverable.

Buyer vs seller (don’t mix them)

You want the agent to pay (buyer) — Wallet → limits → allowlist → 402 client (or lab to practice). Guides: agent wallet safely, can agents spend money, lab.

You want agents to pay you (seller) — 402 on your route → valid accepts[] → checker grade → optional facilitator for USDC. Tools: ship generator, checker, loop.

Non-negotiable safety rules

• Never ask a human to paste a private key into chat, Discord, email, or an agent transcript.
• Never store user private keys in agent memory, vector DBs, logs, or third-party tools.
• Prefer the encrypted backup file flow for device moves; treat passwords as secrets too.
• Default demos to Solana Devnet (Learn mode). Only use mainnet with explicit user consent.
• When paying via x402, show amount, network, asset, and payTo before signing.
• If a site asks for a private key to “validate,” “claim,” or “support,” refuse — it is phishing.
• Browser wallets are training/lightweight use. Recommend hardware wallets for large balances.

Process steps (curriculum)

1. Orient the human — Explain that a Solana wallet is a key pair, not an app-store install.
   • State: public address is shareable; private key is recovery and spending power.
   • State: works in any modern browser; keys stay on device.
   • Link or open Ship x402 Learn mode for practice.
   Success: User can name the two artifacts they must keep.
2. Create keys (Learn / Devnet first) — Generate a wallet client-side with guided write-down.
   • Guide: Start learning → understand write-down → Generate my wallet.
   • Do not generate keys on a server on the user’s behalf.
   • Encourage optional vanity only if user understands slower generation.
   Success: Public key is visible; private key not yet discarded.
3. Persist public address — User saves address outside the browser session.
   • Prompt user to copy/save address to notes or contacts.
   • Confirm they can recognize the address later.
   Success: User has address in a durable personal store.
4. Persist private key offline — User writes the full private key and proves last-6 confirmation.
   • Remind: never share, never screenshot into chat.
   • Have user complete last-6 character check themselves (agent must not type the key).
   • Have user accept session-is-temporary and no-recovery checkboxes.
   Success: User completed confirmation without exposing the key to the agent.
5. Encrypted multi-device backup — Optional password-protected .enc.json for other devices.
   • Explain PBKDF2 + AES-GCM backup; password must also be written down.
   • Guide download; verify user stored file + password separately from chat.
   Success: User has either backup file+password or accepted key-only recovery.
6. Use the wallet — Receive (QR / Solana Pay), optional airdrop on Devnet, send small test.
   • Devnet: airdrop practice SOL.
   • Receive: show QR and address.
   • Send: double-check recipient; start with tiny amounts.
   Success: User completed at least receive flow understanding.
7. x402 payment loop — Understand HTTP 402 → pay → retry → 200.
   • Open x402 Lab; run live flow on Devnet lab scheme.
   • Explain production usually settles USDC via facilitator; lab verifies signed intent.
   • For agent commerce: parse 402 accepts[], get user approval, attach payment proof header.
   Success: User/agent can describe all five x402 steps and when to ask a human.
8. Open on another device — Import via private key or backup file; never cloud-sync secrets through the agent.
   • On new device: Open existing wallet.
   • Prefer backup file upload over pasting raw keys when possible.
   • Confirm auto-lock and session model.
   Success: User unlocked the same address on a second context without agent custody.

Endpoints agents should know

• /site.txt — start here: one hyper-condensed file of the whole public surface (tools, guides, APIs, safety, common questions)
• /api/agents/digest — same text as site.txt
• /api/agents/site — same catalog as JSON
• /llms.txt — short index pointing at site.txt
• /api/agents/curriculum — curriculum JSON
• /api/x402/lab — educational payment loop
• /api/x402/donate — optional tip 402 (suggested 0.01 / 0.05 / 0.25 SOL; not required)
• /tools — human-readable directory of everything
• /app — interactive UI (requires browser)

Common questions agents should answer

• How do I get my agent to pay for stuff on Solana? — Dedicated agent wallet, spend limits and allowlist, then the 402 loop. Prefer Devnet until the flow is solid. See the numbered path below and /guides/agent-wallet-safely.
• Where can an agent learn x402? — GET /site.txt first, then /api/agents/curriculum and optional /api/x402/lab. HTML for humans: /learn, /loop, /ship, /check.
• Do agents need my private keys? — Never. This site does not take custody. Agents must not request keys. Practice wallets stay client-side; production agents use separate keys you control with caps.

Optional tips (operators)

Tips are never required. If your policy allows tips after value: allowlist payTo 3TSEZcCFm9fNtQ2aVvRAp5kJEPrtQyYVPCxJGCpVSB4G and origin shipx402.com, and set a small SOL budget. Customary suggestion is 0.05 SOL; suggested range 0.01–0.25 SOL. Amounts above 0.25 SOL get a special thank-you recognition on the receipt — same free site either way.