Game4Blockchain #3 · x402 for agentic game flows

A small scaffold before x402 touches wallets, agents, or game state.

This packet is tailored to Game4Blockchain issue #3. The project already combines Algorand games, a React frontend, CLI, and LLM agent simulations; the next safe step is an x402 boundary that lets agents discover paid actions without mixing payment authorization into game logic.

Book this scaffold Markdown brief

1. Discovery first

Expose a dry-run catalogue of payable actions before any agent is allowed to sign: action id, game id, price, network, max spend, and replay/idempotency key.

2. Wallet boundary

Keep x402 payment headers outside contract/client state. The frontend or CLI passes a signed payment proof only after user/agent budget approval.

3. Game-state proof

Separate paid HTTP receipt from Algorand commit/reveal outcomes, so a paid agent call can be audited without leaking strategies, salts, or private wallet material.

Suggested scaffold

GET /.well-known/x402-agent-actions: public discovery for payable simulation/agent helper actions.
GET /api/x402/quote?action=simulation-run: returns a 402-ready quote with max price, expiry, game id, and dry-run payload hash.
POST /api/x402/agent-run: accepts X-Payment only after the caller approves; returns a receipt id plus non-secret output hash.
Frontend state machine: idle → quote-required → payment-approved → submitted → receipt-ready → failed/refundable.
CLI smoke path: quote fetch, no-spend dry-run, signed-header placeholder test, and receipt table output.

Acceptance table

The goal is not to add a live payment processor in one step. The goal is to make the x402 seam reviewable: indexers can discover it, agents can understand price and spend limits, and maintainers can test the state transitions with mocked 402 responses before real settlement.

Dry-run quote can be requested without wallet secrets.
Payment-required payload includes network, asset, amount, payTo, expiry, and resource id.
Frontend/CLI never auto-sign; approval is explicit and budget-bounded.
Receipts link paid HTTP call → game/simulation action → output hash, while secrets stay excluded.
Tests cover missing payment, expired quote, over-budget quote, accepted mock payment, and receipt rendering.

This packet deliberately avoids live settlement, wallet transactions, bridges, swaps, staking, and private-key handling.

Relevant proof

Stellar agent registry x402 helper
Typed payment helper and SDK tests without signing/spending funds. x402 payment response readback
Client-side receipt/header handling across browser and Node demo code. Browser-agent x402 headers
CORS/challenge/receipt header exposure with local HTTP smoke checks. Browser-agent middleware packet
Reusable 402/CORS/facilitator-readback checklist.