Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(ux-flows): correct when a topic chip re-quotes, since the 402 challenge is issued per request
nirholas0f8e2810152a
diff --git a/docs/ux-flows/08-coin-launch-wallets.md b/docs/ux-flows/08-coin-launch-wallets.mdindex a10718ed7..d285d7714 100644--- a/docs/ux-flows/08-coin-launch-wallets.md+++ b/docs/ux-flows/08-coin-launch-wallets.md@@ -156,17 +156,17 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.---### Agent Wallet x402 Pay (3D demo) — `/play/agent-wallet`-- **Source:** `pages/play/agent-wallet.html` → `src/play-agent-wallet.js`. Uses `src/game/avatar-rig.js` + `src/game/play-handoff.js`. Bridge: hosted `api/agent-wallet-bridge` (prod) or local `scripts/agent-wallet-x402-bridge.mjs` on `127.0.0.1:4402` (dev).+- **Source:** `pages/play/agent-wallet.html` → `src/play-agent-wallet.js`. Uses `src/game/avatar-rig.js` + `src/game/play-handoff.js`. Bridge: hosted `api/agent-wallet-bridge` (prod) or local `scripts/agent-wallet-x402-bridge.mjs` on `127.0.0.1:4402` (dev). A dev machine only *prefers* the local bridge: the first unreachable status call promotes the page to the hosted bridge, so `npm run dev` shows the live wallet instead of a permanent "bridge offline".- **Entry point:** `#stage3d` 3D scene (avatar + kiosk + stage board) + side panel with topic chips, endpoint card, and a Pay button.-- **Prerequisites / gates:** Bridge must be **online** (status poll). On the **hosted** bridge a real spend requires a signed-in session (402→401 surfaces "Sign in to pay"); rate-limited (429) handled. Agent wallet must hold USDC.+- **Prerequisites / gates:** Bridge must be **online** (status poll). On the **hosted** bridge a real spend requires a signed-in session (402→401 surfaces "Sign in to pay"); rate-limited (429) handled. The agent wallet must hold at least the quoted amount in USDC; below that the Pay button is disabled and reads "Wallet needs $0.01 USDC to pay" beside the low-balance banner, rather than offering a payment that can only fail.- **Steps (N):**1. Boot loads the saved `/play` avatar (`CC_AVATAR_KEY` / `?avatar=`), builds the 3D rig, and calls `refreshStatus()` → bridge `?status=1` for wallet address/mode + USD balance. Status repolls every 30s.2. `loadQuote()` → bridge `?quote=1&endpoint=…&method=POST&body={topic}` → fills endpoint name, price, pay-to, tags.- 3. (optional) User selects a topic chip (BTC/ETH/SOL) — re-quotes implicitly on next pay.+ 3. (optional) User selects a topic chip (BTC/ETH/SOL), which re-quotes immediately: the 402 challenge is issued per request, so price and pay-to belong to the topic being bought.4. User clicks **Send avatar to pay — $0.01 USDC**. Avatar walks to the kiosk (stage `walk`); pay ring pulses.5. `POST` bridge `?pay=1` (SSE, `accept: text/event-stream`) streams stages: `challenge` (402) → `signing` (agent wallet signs the SPL USDC transfer) → `signed`/`submitting` (X-PAYMENT submitted, facilitator settles) → `done` (settled on Solana mainnet). Board, kiosk, and side-panel stepper animate in lockstep.6. On `done` → receipt: amount, payer (agent wallet) → payTo (endpoint), Solscan tx link, and the purchased crypto-intel payload (signal/headline/rationale). Avatar plays a celebrate emote, then walks home. Status refreshes; session total accrues.-- **Decision points / branches:** local dev bridge vs hosted prod bridge (different URL shapes + auth model); `?bridge=`/`?endpoint=` overrides; 401 needs-auth vs 429 rate-limit vs generic failure; bridge online/offline/connecting.+- **Decision points / branches:** local dev bridge vs hosted prod bridge (different URL shapes + auth model, with a one-shot promotion from local to hosted when the local one is unreachable); `?bridge=`/`?endpoint=` overrides, which are honored verbatim and never promoted; sponsored vs self-pay Solana accept (the bridge signs as its own fee payer when the endpoint advertises no `extra.feePayer`); 401 needs-auth vs 429 rate-limit vs generic failure; bridge online/offline/connecting.- **External calls / dependencies:** bridge `status`/`quote`/`pay` (`/api/agent-wallet-bridge` or local `:4402`); the paid endpoint `https://three.ws/api/x402/crypto-intel` (the hosted bridge calls it through the shared upstream fetch: the 402 probe is bounded and retried on a dropped connection, while the re-send that carries the signed payment is a single attempt with a timeout only, because a retry could double-spend); Solana mainnet settlement via the x402 facilitator; Solscan (tx link). External payment is **real** ($0.01 USDC leaves the wallet).- **Success state:** "✓ $0.01 USDC settled on Solana" board + receipt card with tx link and purchased intel; avatar celebrates.- **Empty / error states:** "Bridge offline" banner (dev hint to run the bridge) with Retry; low-balance banner; "Sign in to pay" (needs-auth); rate-limit message; "Payment failed — no funds moved" with the stepper marking the failed stage red.diff --git a/docs/ux-flows/09-x402-agent-commerce.md b/docs/ux-flows/09-x402-agent-commerce.mdindex dd34630ce..23cb9aa8f 100644--- a/docs/ux-flows/09-x402-agent-commerce.md+++ b/docs/ux-flows/09-x402-agent-commerce.md@@ -334,6 +334,6 @@ choreographed two-agent narrative driven by Server-Sent Events.- **Server-payer vs user-payer:** the "agent economy" narratives (`/agent-exchange`, `/agent-trade`, `/agent-economy`, `/demo`, `/live`) pay from **server-held agent wallets** and stream the choreography over SSE — the user only triggers/selects, then watches. The "showcase" apps (`/shopper`, `/fact-checker`, `/tutor`, `/bazaar`, `/arbitrage`, `/ibm`) make the **user** pay via the `/x402.js` modal.- **Auto-play demos:** `/agent-exchange`, `/agent-trade`, `/agent-economy`, `/demo` need one user click to start, then auto-play. `/live` adds an auth gate for real settlement. `/play/arena` is fully autonomous (agents trade themselves; user only watches/moves/inspects) and uses **no x402** — real pre-funded Solana trades.- **Forever** is the only **non-x402** payment in the cluster: native Bitcoin (or Lightning) to an OrdinalsBot charge address, inscribing a real Taproot text inscription on Bitcoin mainnet.-- **Adjacent economy surfaces (2026-08-01, not yet traced as full sections):** `/economy-lab` (Runway Lab, a live digital twin of the x402 payment rail; backend `api/x402/runway-lab.js`), `/pay-simulator` (Spend Policy Simulator: dry-run an agent spending policy against real x402 prices), `/flow` (Money Flow Map, see `docs/money-flow-map.md`), `/play/solver` (see `docs/economy-solver.md`), and `/conversions`.+- **Adjacent economy surfaces (2026-08-01, not yet traced as full sections):** `/economy-lab` (Runway Lab, a live digital twin of the x402 payment rail; backend `api/x402/runway-lab.js`), `/pay/simulator` (Spend Policy Simulator: dry-run an agent spending policy against real x402 prices), `/flow` (Money Flow Map, see `docs/money-flow-map.md`), `/play/solver` (see `docs/economy-solver.md`), and `/conversions`.- **Inline handlers are gone:** every HTML response in this cluster ships a CSP whose `script-src` lists SHA-256 hashes of the inline scripts in the bytes actually sent, so no page here may carry an `onclick=`/`onerror=` attribute (not even inside a template literal). The card markup these flows render declares intent with `data-fallback`, `data-action="reload"` or `data-stop-propagation` and `public/inline-behaviors.js` delegates it; `scripts/audit-inline-handlers.mjs` fails the build if one comes back.- **Source coverage:** all 19 routes located and traced from real source. `/tutor` resolves to `public/tutor.html` + `public/tutor.js` (served statically; no explicit vite map entry needed). No source was missing.