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
/**
* Agent Wallet hub: page entry.
*
* Routes: /agents/:id/wallet and /agents/:id/wallet (agent named in the path),
* plus /agent-wallet with an optional ?id=<uuid>.
*
* When no agent is named, the page resolves the signed-in user's own agents
* from GET /api/agents: exactly one agent mounts its hub straight away, several
* render a picker, and none (or a signed-out visitor) gets a designed next step
* instead of a dead end.
*
* Every page state is designed: loading skeleton, picker, signed out, no agents
* yet, agent not found, fetch error (with retry), and the live hub. Owner vs
* visitor is decided server-side by the agent record's `is_owner`.
*/
import { mountAgentWalletHub } from './agent-wallet-hub/index.js';
import { addressHtml } from './shared/address.js';
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
function resolveAgentId() {
const fromQuery = new URLSearchParams(location.search).get('id');
if (fromQuery) return fromQuery;
// /agents/:id/wallet or /agents/:id/wallet
const m = location.pathname.match(/\/agents?\/([^/]+)\/wallet/);
return m ? decodeURIComponent(m[1]) : null;
}
const root = document.getElementById('awh-root');
/**
* Write a dynamic page title (an agent's name, the picker heading) and hold it.
*
* The document's <title> carries a data-i18n key, so the i18n runtime's catalog
* pass reverts it to the declared "Agent Wallet · three.ws" whenever /api/locale
* resolves after this page has already rendered, a race the title lost roughly
* one load in three. `data-i18n-owned="1"` is that runtime's documented opt-out
* for an element whose content is live data rather than translatable copy.
*
* States that show the page's declared default never call this: leaving the
* title unclaimed is what lets a non-English visitor keep a localized one.
*/
const titleEl = document.querySelector('title');
function setPageTitle(text) {
document.title = text;
titleEl?.setAttribute('data-i18n-owned', '1');
}
function escapeHtml(s) {
return String(s ?? '').replace(
/[&<>"']/g,
(c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c],
);
}
function renderLoading(label = 'Loading agent wallet') {
root.innerHTML = `
<div class="awh-page-skel" aria-busy="true" aria-label="${escapeHtml(label)}">
<div class="awh-page-skel-row"></div>
<div class="awh-page-skel-tabs"></div>
<div class="awh-page-skel-card"></div>
</div>`;
}
/**
* A designed terminal state: heading, one line of guidance, and up to two real
* actions. `retry` adds a button that re-runs the page load.
*
* `tone` decides how assistive tech announces the state. Only a genuine failure
* gets role="alert", which interrupts a screen-reader user mid-sentence. The
* states that are simply this page's answer for a visitor who is signed out or
* has no agents yet are a labelled region, read in turn like any other content.
*/
function renderMessage({ title, body, actions = [], retry, tone = 'error' }) {
root.innerHTML = `
<div class="awh-page-msg" ${
tone === 'error' ? 'role="alert"' : 'role="region" aria-labelledby="awh-page-msg-h"'
}>
<h1 id="awh-page-msg-h">${escapeHtml(title)}</h1>
<p>${escapeHtml(body)}</p>
<div class="awh-page-msg-actions">
${actions
.map(
(a) =>
`<a class="awh-page-btn${a.primary ? ' awh-page-btn--primary' : ''}" href="${escapeHtml(a.href)}">${escapeHtml(a.label)}</a>`,
)
.join('')}
${retry ? '<button class="awh-page-btn" type="button" data-act="retry">Try again</button>' : ''}
</div>
</div>`;
if (retry) root.querySelector('[data-act="retry"]')?.addEventListener('click', () => load());
}
/** Picker shown when the signed-in user owns more than one agent. */
function renderPicker(agents) {
root.innerHTML = `
<section class="awh-pick" aria-labelledby="awh-pick-h">
<h1 id="awh-pick-h" class="awh-pick-h">Your agent wallets</h1>
<p class="awh-pick-lede">Each agent holds its own self-custodied Solana wallet. Pick one to see its balance, fund it, and review its activity.</p>
<ul class="awh-pick-list">
${agents
.map((a) => {
const ready = !!(a.wallet_ready ?? a.walletReady);
const addr = a.solana_address || '';
const sub = addr
? addressHtml(addr, { label: 'Wallet address' })
: escapeHtml('Wallet is being prepared');
return `<li>
<a class="awh-pick-row" href="/agents/${encodeURIComponent(a.id)}/wallet">
${
a.avatar_thumbnail_url
? `<img class="awh-pick-av" src="${escapeHtml(a.avatar_thumbnail_url)}" alt="" loading="lazy" />`
: '<span class="awh-pick-av" aria-hidden="true"></span>'
}
<span class="awh-pick-id">
<span class="awh-pick-name">${escapeHtml(a.name || 'Untitled agent')}</span>
<span class="awh-pick-sub">${sub}</span>
</span>
<span class="awh-pick-state" data-state="${ready ? 'ready' : 'preparing'}">${ready ? 'Ready' : 'Preparing'}</span>
<span class="awh-pick-go" aria-hidden="true">→</span>
</a>
</li>`;
})
.join('')}
</ul>
<div class="awh-page-msg-actions awh-pick-foot">
<a class="awh-page-btn" href="/my-agents">Manage agents</a>
<a class="awh-page-btn" href="/create-agent">Create an agent</a>
</div>
</section>`;
setPageTitle('Your agent wallets · three.ws');
}
/** Fetch one agent by id. Returns { agent } or { state } for a designed stop. */
async function fetchAgent(agentId) {
const res = await fetch(`/api/agents/${encodeURIComponent(agentId)}`, {
credentials: 'include',
headers: { accept: 'application/json' },
});
if (res.status === 404) return { state: 'not_found' };
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
if (!data?.agent) throw new Error('empty agent payload');
return { agent: data.agent };
}
/**
* Fetch the caller's own agents. Returns { agents } or { state: 'signed_out' }.
*
* The session is resolved first through /api/auth/me, which answers 200 with a
* null user for anonymous visitors. GET /api/agents answers 401 for them, and
* the browser logs every 401 response as a console error, so the signed-out
* path stops before it fires one.
*/
async function fetchOwnAgents() {
const me = await fetch('/api/auth/me', {
credentials: 'include',
headers: { accept: 'application/json' },
});
if (!me.ok) throw new Error(`HTTP ${me.status}`);
const session = await me.json();
if (!session?.user?.id) return { state: 'signed_out' };
const res = await fetch('/api/agents', {
credentials: 'include',
headers: { accept: 'application/json' },
});
if (res.status === 401 || res.status === 403) return { state: 'signed_out' };
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
return { agents: Array.isArray(data?.agents) ? data.agents : [] };
}
function mountHub(agent) {
setPageTitle(`${agent.name || 'Agent'} wallet · three.ws`);
mountAgentWalletHub({ mount: root, agent, initialTab: new URLSearchParams(location.search).get('tab') || undefined });
}
/** No agent in the URL: resolve the signed-in user's own agents. */
async function loadOwnWallets() {
renderLoading('Loading your agent wallets');
let result;
try {
result = await fetchOwnAgents();
} catch {
renderMessage({
title: "Couldn't load your wallets",
body: 'We could not reach the agent service. This is usually temporary, so check your connection and try again.',
retry: true,
});
return;
}
if (result.state === 'signed_out') {
renderMessage({
title: 'Sign in to open an agent wallet',
body: 'Agent wallets are private to their owner. Sign in to see your agents and their balances, or create an account to get an agent with its own Solana wallet.',
actions: [
{ href: '/login?next=/agent-wallet', label: 'Sign in', primary: true },
{ href: '/register', label: 'Create account' },
],
tone: 'info',
});
return;
}
const agents = result.agents;
if (!agents.length) {
renderMessage({
title: 'No agents yet',
body: 'Every agent you create gets a self-custodied Solana wallet it can fund, trade, and pay from. Create your first agent to open its wallet.',
actions: [{ href: '/create-agent', label: 'Create an agent', primary: true }],
tone: 'info',
});
return;
}
if (agents.length === 1) {
mountHub(agents[0]);
return;
}
renderPicker(agents);
}
/** An agent is named in the URL: load and mount its hub. */
async function loadNamedWallet(agentId) {
if (!UUID_RE.test(agentId)) {
renderMessage({
title: 'That agent link is not valid',
body: 'An agent wallet link carries the agent id. Open the wallet from the agent profile, or pick one of your own agents.',
actions: [
{ href: '/agent-wallet', label: 'Your agent wallets', primary: true },
{ href: '/agents', label: 'Browse agents' },
],
});
return;
}
renderLoading();
let result;
try {
result = await fetchAgent(agentId);
} catch {
renderMessage({
title: "Couldn't load this wallet",
body: 'We could not reach the agent service. This is usually temporary, so check your connection and try again.',
retry: true,
});
return;
}
if (result.state === 'not_found') {
renderMessage({
title: 'Agent not found',
body: 'This agent does not exist or has been removed. It may have been deleted by its owner.',
actions: [{ href: '/agents', label: 'Browse agents', primary: true }],
});
setPageTitle('Agent not found · three.ws');
return;
}
mountHub(result.agent);
}
async function load() {
const agentId = resolveAgentId();
if (agentId) return loadNamedWallet(agentId);
return loadOwnWallets();
}
load();