# Game4Blockchain x402 Agentic Flow Scaffold

Target: https://github.com/BeLorenzo/Game4Blockchain/issues/3

Offer:
- A$390 readback packet: route map, payment states, x402 boundary notes, test matrix.
- A$1,900 implementation sprint: typed x402 client seam, mock 402 fixtures, frontend/CLI docs, and maintainer-ready PR.

Settlement rail after scope confirmation: USDC on Base or Polygon to `0x17D7251A8a8d60ab74d7D2B2d20D2a0389871729`, or invoice. No wallet signing, transfer, bridge, swap, staking, or live paid call is included without explicit approval.

## Recommended scaffold

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

## Acceptance checks

- 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.

## Boundary

This is intentionally mock-first. It does not move funds, sign wallets, touch private keys, or bridge/swap/stake anything.