README
x402 + Solana payments
Production-grade payment documentation for Agent Play: x402 settlement on Solana USDC, replacing the internal Redis wallet (balanceUsd, lazy $70 seed).
Status: planning / not shipped. For the system that runs today, see Payments, wallets, and talk billing.
Architecture anchor: x402 + Solana payments plan
Who should read what
| Role | Start here |
|---|---|
| New to x402 | 01 — x402 overview |
| Integrating wallet link | 02 — Solana wallet linking |
| Backend / pricing | 03 — Payment catalog, 04 — Settlement & idempotency |
| Agent-service host | 05 — Agent developer payouts |
| Play UI engineer | 06 — Overworld user flows |
| Ops / AQL | 07 — AQL & platform ops |
| Migrating existing hosts | 08 — Migration from internal wallet |
| Security review | 09 — Security & compliance |
| SRE | 10 — Observability |
Documentation map
| # | Document | Summary |
|---|---|---|
| 1 | 01-x402-overview.md | Protocol, 402 flow, facilitator, Solana USDC, Agent Play fit |
| 2 | 02-solana-wallet-linking.md | SIWS, link/unlink API, settlement profiles, Redis keys |
| 3 | 03-payment-catalog.md | SKUs, payee routing, prices, resource ids |
| 4 | 04-settlement-and-idempotency.md | Payment intents, atomic commit, retries, failure modes |
| 5 | 05-agent-developer-payouts.md | Receive talk/service revenue on main node wallet |
| 6 | 06-overworld-user-flows.md | Connect wallet, pay agents, buy items, acquire spaces |
| 7 | 07-aql-and-platform-ops.md | Env vars, facilitator config, AQL ops, runbooks |
| 8 | 08-migration-from-internal-wallet.md | dual mode, cutover, deprecations |
| 9 | 09-security-and-compliance.md | Threat model, SIWS replay, facilitator trust |
| 10 | 10-observability.md | Metrics, alerts, reconciliation, tracing |
Quick reference
Environment
AGENT_PLAY_PAYMENTS_MODE=internal # today | dual | x402
AGENT_PLAY_SETTLEMENT_NETWORK=solana:devnet
X402_FACILITATOR_URL=https://...
AGENT_PLAY_TREASURY_SOLANA=<base58>
AGENT_PLAY_USDC_MINT=<spl-mint>
SOLANA_RPC_URL=https://api.devnet.solana.com
Identity model
- Auth: main node passphrase (
x-node-id,x-node-passw) — unchanged. - Settlement: Solana pubkey linked to main node via SIWS — new.
- Payer: overworld user’s linked wallet.
- Payee (agent): agent operator’s main node linked wallet.
- Payee (amenity sales): space owner
owner.nodeId→ linked wallet.
External spec
Production checklist (summary)
Before mainnet: