x402 Payment Flow
                          ─────────────────

   ┌────────────┐                ┌──────────────────┐                ┌────────────────────┐
   │ Client CLI │  1. GET /api   │  Resource Server  │                │ Facilitator Server │
   │            │ ──────────────>│                   │                │                    │
   │            │                │  "No payment      │                │                    │
   │            │  2. HTTP 402   │   header found"   │                │                    │
   │            │ <──────────────│                   │                │                    │
   │            │  + PAYMENT-    │                   │                │                    │
   │            │    REQUIRED    │                   │                │                    │
   │            │                │                   │                │                    │
   │  Signs     │                │                   │                │                    │
   │  EIP-3009  │  3. GET /api   │                   │  4. POST       │                    │
   │  or        │ ──────────────>│  Parses header,   │ ──/verify────> │  Recovers signer,  │
   │  Permit2   │  + PAYMENT-    │  forwards to      │                │  checks balance,   │
   │  payload   │    SIGNATURE   │  facilitator      │  5. POST       │  simulates call    │  ┌───────────┐
   │            │                │                   │ ──/settle────> │                    │  │ EVM Chain │
   │            │                │                   │                │  Builds EIP-1559   │  │           │
   │            │                │                   │                │  tx, settles via   │──│ USDC      │
   │            │                │                   │  6. tx hash    │  EIP-3009 or       │  │ transfer  │
   │            │  7. HTTP 200   │  Returns API data │ <─────────────│  Permit2 Proxy     │  │           │
   │            │ <──────────────│  + PAYMENT-       │                │                    │  │           │
   │            │  + response    │    RESPONSE       │                │                    │  └───────────┘
   └────────────┘                └──────────────────┘                └────────────────────┘

POST /verify

Validates a payment payload off-chain. Checks signature, balance, timestamps, nonce.

// Request
{ "x402Version": 2, "paymentPayload": { ... }, "paymentRequirements": { ... } }

// Response
{ "isValid": true, "payer": "0x47322Ca2..." }

POST /settle

Executes payment on-chain. Auto-detects EIP-3009 vs Permit2 payload type.

{ "success": true, "transaction": "0x99e49093...", "network": "eip155:84532", "payer": "0x47322Ca2..." }

GET /supported

{ "kinds": [{ "x402Version": 2, "scheme": "exact", "network": "eip155:84532" }], "signers": { "eip155:*": ["0x23fbdE5A..."] } }

GET /health

{ "status": "ok", "service": "facilitator", "network": "eip155:84532", "address": "0x23fbdE5A..." }

HTTP Headers (V2)

EIP-3009 Mode (default)

1. Client signs EIP-712 typed data authorizing a token transfer
2. Facilitator calls transferWithAuthorization(from, to, value, validAfter, validBefore, nonce, v, r, s)
3. Nonces are random 32-byte values (not sequential)
4. Facilitator pays gas; USDC goes directly Client → PAY_TO

Permit2 Mode

1. Client signs EIP-712 for Permit2 PermitWitnessTransferFrom (domain = Permit2 contract)
2. Facilitator calls x402Permit2Proxy.settle() → Permit2.permitWitnessTransferFrom()
3. Requires one-time approve(Permit2, amount) from Client wallet
4. Works with any ERC-20 token

x402-playground/
├── cmd/
│   ├── facilitator/main.go    Facilitator HTTP server
│   ├── resource/main.go       Resource HTTP server
│   ├── client/main.go         Client CLI
│   ├── explorer/main.go       Bubbletea TUI explorer (--mode, --flow flags)
│   └── balance/main.go        Wallet balance checker
├── internal/
│   ├── config/                Environment variable loading + validation
│   ├── demo/                  Protocol logic + LiveExecutor for real payment execution
│   ├── quiz/                  Quiz engine: questions (Go + Solidity), runner (go test + forge test)
│   ├── facilserver/           Facilitator HTTP handlers (/verify, /settle, /supported)
│   ├── server/                Resource Server routes + API handlers
│   ├── signer/                FacilitatorEvmSigner (EIP-1559, EIP-712)
│   └── tui/                   TUI framework
│       ├── app.go             Root model + page routing + help overlay + min size check
│       ├── components/        Reusable UI (menu, panel, jsonview, fieldexplorer, progress...)
│       ├── home/              Main menu (4 modes)
│       ├── learn/             Interactive coding quiz with editor integration
│       ├── explore/           Data structure inspector (headers, EIP-712, on-chain)
│       ├── practice/          Live payment flow execution (EIP-3009, Permit2, side-by-side)
│       └── dashboard/         Live wallet balances
├── pkg/health/                Shared health check type
├── .github/workflows/ci.yml  GitHub Actions CI (build + test + vet)
├── .env.example               Environment variable template
├── Dockerfile                 Multi-stage build
├── docker-compose.yml         Facilitator + Resource orchestration
├── CONTRIBUTING.md            Contributor guidelines
├── LICENSE                    MIT License
└── Makefile                   Build, test, run targets