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
fix(wallet): show real balances on /wallet and stop telling people a completed transfer failed
nirholasb7b587208309
diff --git a/api/_lib/agent-wallet.js b/api/_lib/agent-wallet.jsindex bb3cba5c3..a5eb4eab8 100644--- a/api/_lib/agent-wallet.js+++ b/api/_lib/agent-wallet.js@@ -448,8 +448,12 @@ export async function getSolanaAddressBalances(address, cluster = 'mainnet') {} catch {usdc = 0; // no ATA yet → zero USDC}- } catch {- // RPC failure — report nulls rather than throw.+ } catch (err) {+ // RPC failure: report nulls rather than throw, so a caller that only needed+ // the address still succeeds. Log it, because a null here is indistinguishable+ // from a genuinely empty wallet everywhere downstream, and a silent swallow+ // leaves an operator no way to tell an outage from a zero balance.+ console.warn('[agent-wallet] solana balance read failed', net, err?.message);}return { sol, usdc };}diff --git a/docs/user-wallet.md b/docs/user-wallet.mdindex 9f835d9cb..69f15cfa7 100644--- a/docs/user-wallet.md+++ b/docs/user-wallet.md@@ -77,7 +77,7 @@ curl -sX POST https://three.ws/api/user/wallet \## Reading balances-`GET /api/user/wallet` returns the addresses plus live balances. Nothing is cached, and nothing blocks: the Solana read and the Base USDC read run in parallel and a failure of either yields `null` for that field rather than a failed request, so the page still renders.+`GET /api/user/wallet` returns the addresses plus live balances. Nothing is cached, and nothing blocks: the Solana read, the Base USDC read, and the SOL price lookup run in parallel, and a failure of any one yields `null` for the fields it feeds rather than a failed request, so the page still renders.```bashcurl -s -b cookies.txt https://three.ws/api/user/wallet@@ -100,7 +100,8 @@ curl -s -b cookies.txt https://three.ws/api/user/wallet```- `sol` is the native balance, `sol_usdc` the USDC balance on Solana, `evm_usdc` the USDC balance on Base (read with a direct `balanceOf` call through the EVM RPC failover chain).-- `total_usd` is the priced Solana total plus the Base USDC figure, and is `null` when the price feed is unavailable. Treat a `null` as "unknown", never as zero.+- **`null` means the network did not answer, `0` means the wallet is empty.** They are different answers and the page renders them differently ("unavailable" versus "0"). Never read a `null` as zero.+- `total_usd` sums only the legs that answered: the SOL balance priced at the live SOL/USD rate, plus each USDC figure at par. A leg that came back `null` is left out rather than counted as zero. The one case that voids the total outright (`null`) is a **non-zero** SOL balance with no price available, because counting real SOL at zero would under-report the wallet; a zero SOL balance needs no price and still totals cleanly.## Sending SOL or an SPL token (this spends real funds)diff --git a/prompts/swarm-100/route-wallet.md b/prompts/swarm-100/route-wallet.mddeleted file mode 100644index 1efa7c599..000000000--- a/prompts/swarm-100/route-wallet.md+++ /dev/null@@ -1,119 +0,0 @@-# Route audit: /wallet (Your master wallet)--How to run: paste this file's repo path into a fresh Claude Code chat in this-repository and say "run this work order". This file is fully self-contained:-it depends on no other prompt file anywhere. If neighboring files in-prompts/swarm-100/ are gone, that work is done; if present, ignore them.-Every claim below rots; step 0 re-measures, and what you measure wins.--## Operating clause (binding)--- Read CLAUDE.md first. Its rules override everything, including this file.-- Finish 100% in this session. Never end the turn with a question, an option- list, or an unexecuted plan. A judgment call goes in one line of the final- report; it never becomes a question that halts work.-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real- funds or any irreversible on-chain write, git push or a production deploy,- committing content that references a crypto project other than $THREE, and- destroying unrecoverable data.-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no- commented-out code. Real APIs and real integrations only.-- The em-dash and en-dash characters are banned in everything you write.-- Concurrent agents share this worktree: stage explicit paths only (never a- bare add-everything), and commit finished work promptly.-- Before committing, run: npm run check:rules -- --paths <files you touched>.- It must exit 0.--## Step 0: re-derive the current state--1. This route's declared entry (path, description, added date):-- node -e "const p=require('./data/pages.json');for(const s of p.sections)for(const g of s.pages)if(g.path==='/wallet')console.log(JSON.stringify(g,null,2))"--2. Find the serving implementation: grep "/wallet" in vercel.json (the live- route table server/index.mjs boots from), then list matching files in- pages/ and src/. STRUCTURE.md maps every surface to its directory if the- grep is ambiguous.-3. Production right now:-- curl -so /dev/null -w '%{http_code}\n' https://three.ws/wallet--4. Start (or reuse) the local dev server: npm run dev (vite, port 3000).--## Task: audit this one route end to end, then fix everything found--Route: /wallet ("Your master wallet", section "crypto").-Declared purpose: One custodial wallet for your account, separate from your agents'. Hold SOL and USDC across Solana and Base, top up any agent you own, send to any Solana address, and read every transaction straight from chain.--Drive the page in a real headless browser. Playwright is already a dev-dependency; keep your probe script in the session scratchpad, never in the-repo.--1. Load http://localhost:3000/wallet. Record the HTTP status, every console- error and warning, and every failed network request.-2. Exercise it like a first-time user: click the primary actions, run the- primary flow if one exists, follow the page's internal links. Every button- must do something real; every link must resolve. If the page renders data,- prove in the network log that it came from a live endpoint, not a baked-in- fallback array.-3. States: verify populated, empty, loading, and error states are designed and- reachable. Block the page's primary fetch in Playwright and confirm an- actionable error state appears, not a blank void or a raw exception.-4. Responsive: render at 320, 768, and 1440 px. No horizontal page scroll, no- overlapping or clipped controls.-5. Accessibility basics: one h1; interactive elements are real buttons or- links with visible focus states; images carry alt text; form fields have- labels.-6. Head: a specific title tag and meta description that match the declared- purpose above.-7. Fix every defect at its root in the page's real source files and re-run the- probe until clean. Defects in shared modules are in scope when this route- exercises them.--## Definition of done--- [ ] Local load of /wallet: HTTP 200, zero console errors, zero unhandled- failed requests (a third-party outage must land in a designed fallback,- not a broken page).-- [ ] No dead interactive element on the page: no stub href="#", no button- without a handler, no link to a missing path.-- [ ] Empty, loading, error, and populated states verified.-- [ ] 320 / 768 / 1440 px renders verified clean.-- [ ] Title and meta description present and specific.-- [ ] npm test passes; npm run check:rules -- --paths <touched files> exits 0.-- [ ] Production status from step 0 recorded in the report; if production- needs a deploy to pick up a fix, the report says so (deploys stay- owner-gated).--## Never blocked--| Blocker | Resolution (act, do not ask) |-|---|---|-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |-| Playwright browser missing | npx playwright install chromium |-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |--## Close out (required)--1. Verify every Definition of done line with the actual command output in- front of you. Never claim a line you did not verify.-2. Commit with explicit paths and a subject that describes the diff (house- style: type(scope): what changed and why a reader cares).-3. Delete this prompt file in that same commit:-- git rm prompts/swarm-100/route-wallet.md-- The shrinking directory is this campaign's only progress ledger; there is- no progress log to update.-4. Final report: what step 0 measured, what changed (file list), evidence per- Definition of done line, and any one-line judgment calls. No trailing- questions, no unexecuted plans.--If a line genuinely cannot pass inside this session (an external party must-respond, or an owner-gated action is the final step), finish everything else,-leave this file in place, and state exactly which line remains and who owns-it. Never delete this file on a partial.diff --git a/public/master-wallet.css b/public/master-wallet.cssindex d468efc3f..5c3b0fb06 100644--- a/public/master-wallet.css+++ b/public/master-wallet.css@@ -821,6 +821,35 @@ input.wlt-input {translate: -50% 0;}+/* On a phone there is no room to centre a 19rem panel over a 1rem button: the+ * balance-card explainer ran ~54px past the right edge of a 320px viewport, so+ * a keyboard or touch user opened it and could not read the end of a sentence.+ * Below 30rem it stops chasing the button and becomes a pinned sheet, which is+ * the only position guaranteed to fit whichever explainer was opened. */+@media (max-width: 30rem) {+ .wlt-tip-body {+ position: fixed;+ inset: auto var(--space-sm) var(--space-sm) var(--space-sm);+ width: auto;+ max-width: none;+ translate: 0 4px;+ }+ .wlt-tip:hover .wlt-tip-body,+ .wlt-tip:focus-within .wlt-tip-body {+ translate: 0 0;+ }+}++/* The heading and its explainer sit on one line without the "?" living inside+ * the <h1>: a tooltip body nested in a heading becomes part of that heading's+ * accessible name, so a screen reader announced the whole paragraph as the+ * page title. */+.wlt-title-row {+ display: flex;+ align-items: center;+ flex-wrap: wrap;+}+.wlt-head-actions {display: flex;align-items: center;diff --git a/src/master-wallet.js b/src/master-wallet.jsindex 73ea6cb14..2897fb411 100644--- a/src/master-wallet.js+++ b/src/master-wallet.js@@ -118,10 +118,28 @@ const ERROR_COPY = {rate_limited: 'Too many requests. Wait a few seconds and try again.',not_found: 'No master wallet yet. Create one first.',network_error: 'You appear to be offline. Nothing was sent.',+ // The five envelopes api/_lib/http.js produces on its own. Without these the+ // page printed the raw operator text ("internal error, quote ref 515ac8… to+ // support") as the entire explanation, which tells a user nothing they can act+ // on. The reference is still shown, as a reference, by humanError below.+ internal_error: 'Something broke on our side. Nothing was charged. Try again in a moment.',+ service_unavailable: 'Our database is briefly unavailable. Nothing was charged. Try again in a moment.',+ not_configured: 'This part of the wallet is not switched on for this deployment yet.',+ validation_error: 'Something in that request was not accepted. Check the values and try again.',+ unauthorized: 'Your session expired. Sign in again to continue.',+ csrf_missing: 'That request expired before it was sent. Reload the page and try again.',+ csrf_invalid: 'That request expired before it was sent. Reload the page and try again.',};+/**+ * Plain-language copy for an API failure, with the server's support reference+ * appended when there is one. A `ref` only ever accompanies a 5xx, and it is the+ * exact string support will ask for, so it earns its place next to the sentence+ * rather than in place of it.+ */function humanError(res) {- return ERROR_COPY[res?.code] || res?.message || 'Something went wrong.';+ const copy = ERROR_COPY[res?.code] || res?.message || 'Something went wrong.';+ return res?.ref ? `${copy} (reference ${res.ref})` : copy;}/**@@ -131,10 +149,12 @@ function humanError(res) {* appear is one that disappears when the JavaScript does.*/let tipSeq = 0;-function tip(text) {+function tip(subject, text) {const id = `wlt-tip-${++tipSeq}`;+ // The label names its subject: three buttons all announcing "Explain this"+ // give a screen-reader user no way to tell which one they landed on.return `<span class="wlt-tip"- ><button class="wlt-tip-btn" type="button" aria-describedby="${id}" aria-label="Explain this"+ ><button class="wlt-tip-btn" type="button" aria-describedby="${id}" aria-label="Explain ${esc(subject)}">?</button><span class="wlt-tip-body" role="tooltip" id="${id}">${esc(text)}</span></span>`;@@ -223,12 +243,14 @@ function balanceCards(b) {sub: 'Solana + Base',accent: true,tip: 'Both chains added together, priced live. A balance the network did not answer for is left out rather than counted as zero.',+ tipSubject: 'total value',},{label: 'SOL',value: fmtAmount(b?.sol, 6),sub: 'Solana',tip: 'Solana charges every transaction a fee in SOL, so a wallet holding only USDC cannot send anything. Around 0.01 SOL covers a lot of activity.',+ tipSubject: 'your SOL balance',},{ label: 'USDC', value: fmtAmount(b?.sol_usdc, 2), sub: 'Solana' },{ label: 'USDC', value: fmtAmount(b?.evm_usdc, 2), sub: 'Base' },@@ -237,7 +259,7 @@ function balanceCards(b) {.map((c) => `<div class="wlt-bal${c.accent ? ' wlt-bal--accent' : ''}">- <span class="wlt-bal-label">${esc(c.label)}${c.tip ? tip(c.tip) : ''}</span>+ <span class="wlt-bal-label">${esc(c.label)}${c.tip ? tip(c.tipSubject, c.tip) : ''}</span><span class="wlt-bal-value">${c.value == null? '<span class="wlt-bal-na" title="This balance could not be read just now">unavailable</span>'@@ -476,9 +498,13 @@ function readyState() {<header class="wlt-head"><div><span class="wlt-eyebrow">Master wallet</span>- <h1 class="wlt-title">Your wallet${tip(- 'Your account holds this one. Each agent has its own separate wallet, funded from here, so an agent can only ever spend what you moved into it.',- )}</h1>+ <div class="wlt-title-row">+ <h1 class="wlt-title">Your wallet</h1>+ ${tip(+ 'how this wallet relates to your agents',+ 'Your account holds this one. Each agent has its own separate wallet, funded from here, so an agent can only ever spend what you moved into it.',+ )}+ </div></div><div class="wlt-head-actions"><button class="wlt-btn wlt-btn--primary" type="button" data-act="deposit">Add funds</button>diff --git a/src/wallet-api.js b/src/wallet-api.jsindex 5967448fc..5e8cdc947 100644--- a/src/wallet-api.js+++ b/src/wallet-api.js@@ -10,7 +10,7 @@* can render an error state instead of dying on an unhandled rejection:** { ok: true, status, data }- * { ok: false, status, code, message }+ * { ok: false, status, code, message, ref }** `code` is the machine-readable `error` the API returns (`insufficient_balance`,* `invalid_destination`, ...), which the page maps to human copy. Shape mirrors@@ -53,6 +53,10 @@ async function call(url, { method = 'GET', body = null } = {}) {status: r.status,code: j?.error || 'error',message: j?.error_description || j?.message || `request failed (${r.status})`,+ // The server's support reference for a 5xx. Kept separate from the+ // message so the page can show a sentence a person understands and+ // still hand them the string support will ask for.+ ref: typeof j?.ref === 'string' ? j.ref : null,};}return { ok: true, status: r.status, data: j };@@ -62,6 +66,7 @@ async function call(url, { method = 'GET', body = null } = {}) {status: 0,code: 'network_error',message: err?.message || 'network error',+ ref: null,};}}