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
/**
* Server-rendered metadata page for on-chain agents
* -------------------------------------------------
* GET /api/a-page?chain=<chainId>&id=<agentId>
*
* Wired to /a/:chainId/:agentId via vercel.json. Returns an HTML page with
* Open Graph + Twitter Player Card + oEmbed discovery + Farcaster Frame tags
* so social crawlers get a rich preview. Real browsers run the inline script
* and navigate to the SPA viewer.
*/
import { env } from './_lib/env.js';
import { cors, method, wrap } from './_lib/http.js';
import { resolveOnChainAgent, shortenAddr, isTokenId, SERVER_CHAIN_META } from './_lib/onchain.js';
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
if (!method(req, res, ['GET'])) return;
const url = new URL(req.url, 'http://x');
const chainId = Number(url.searchParams.get('chain'));
const agentId = url.searchParams.get('id');
if (!Number.isFinite(chainId) || !agentId) {
return notFound(res, 'Invalid agent URL');
}
if (!SERVER_CHAIN_META[chainId]) {
return notFound(res, `Chain ${chainId} is not supported`);
}
// An ERC-721 id is a uint256. The /a/:chain/:id route only matches digits,
// but this handler is reachable directly, and a non-numeric id used to reach
// the chain read and blow up as an unhandled 500 instead of the designed 404.
if (!isTokenId(agentId)) {
return notFound(res, 'That is not a valid agent id');
}
const agent = await resolveOnChainAgent({ chainId, agentId });
// A `chain_read` error is ambiguous: it fires both for a genuinely
// nonexistent token (ERC-721 reverts on tokenURI) AND for a transient RPC
// read failure. We must NOT hard-404 the second case — the SPA viewer
// resolves the agent client-side and renders fine, so a server-side RPC
// hiccup would otherwise turn a working agent into a dead 404. Instead we
// degrade: render the card with fallback metadata, mark it `noindex` so a
// truly-phantom agent never pollutes search, and let the inline script send
// real browsers on to the viewer. Crawlers get a shareable (un-indexed) card.
const unverified = !!(agent.error && agent.error.startsWith('chain_read'));
const origin = env.APP_ORIGIN;
const pageUrl = `${origin}/a/${chainId}/${agentId}`;
const embedUrl = `${origin}/a/${chainId}/${agentId}/embed`;
const viewerUrl = `${origin}/app#onchain=${chainId}:${agentId}`;
const ogUrl = `${origin}/api/a-og?chain=${chainId}&id=${encodeURIComponent(agentId)}`;
const oembedJs = `${origin}/api/agent-oembed?url=${encodeURIComponent(pageUrl)}&format=json`;
const title = agent.name || `Agent #${agentId}`;
const chainLabel = agent.chainName || `Chain ${chainId}`;
const ownerShort = agent.owner ? shortenAddr(agent.owner) : '';
const desc =
agent.description ||
`An embodied three.ws on ${chainLabel}${ownerShort ? ` · owned by ${ownerShort}` : ''}.`;
res.statusCode = 200;
res.setHeader('content-type', 'text/html; charset=utf-8');
res.setHeader('cache-control', 'public, max-age=60, s-maxage=600, stale-while-revalidate=3600');
res.end(
renderHtml({
title,
desc,
chainLabel,
chainId,
agentId,
ownerShort,
noindex: unverified,
pageUrl,
embedUrl,
viewerUrl,
ogUrl,
oembedJs,
origin,
manifestURI: agent.tokenURI || '',
}),
);
});
function notFound(res, reason) {
res.statusCode = 404;
res.setHeader('content-type', 'text/html; charset=utf-8');
res.setHeader('cache-control', 'public, max-age=60');
res.end(
`<!doctype html><meta charset="utf-8"><title>Agent not found — three.ws</title>
<style>body{font-family:Inter,system-ui,sans-serif;background:#0a0a0a;color:#e0e0e0;display:grid;place-items:center;min-height:100vh;margin:0}main{text-align:center;padding:2rem;max-width:520px}a{color:#8b5cf6}</style>
<main><h1>Agent not found</h1><p>${escapeHtml(reason)}</p><p><a href="/discover">Browse all on-chain agents</a> · <a href="/">Open viewer</a></p></main>`,
);
}
function renderHtml(p) {
const t = escapeHtml(p.title);
const d = escapeHtml(p.desc);
const chainL = escapeHtml(p.chainLabel);
return `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>${t} · ${chainL} — three.ws</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
<meta name="description" content="${d}">
<meta name="theme-color" content="#0a0a0a">
${p.noindex ? '\t<meta name="robots" content="noindex, nofollow">\n' : ''}
<meta property="og:type" content="profile">
<meta property="og:site_name" content="three.ws">
<meta property="og:title" content="${t}">
<meta property="og:description" content="${d}">
<meta property="og:url" content="${escapeAttr(p.pageUrl)}">
<meta property="og:image" content="${escapeAttr(p.ogUrl)}">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="${t} on ${chainL}">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="${t}">
<meta name="twitter:description" content="${d}">
<meta name="twitter:image" content="${escapeAttr(p.ogUrl)}">
<meta name="twitter:player" content="${escapeAttr(p.embedUrl)}">
<meta name="twitter:player:width" content="480">
<meta name="twitter:player:height" content="600">
<!-- Farcaster Frame (vNext) -->
<meta property="fc:frame" content="vNext">
<meta property="fc:frame:image" content="${escapeAttr(p.ogUrl)}">
<meta property="fc:frame:image:aspect_ratio" content="1.91:1">
<meta property="fc:frame:button:1" content="View 3D">
<meta property="fc:frame:button:1:action" content="link">
<meta property="fc:frame:button:1:target" content="${escapeAttr(p.viewerUrl)}">
<meta property="fc:frame:button:2" content="Discover">
<meta property="fc:frame:button:2:action" content="link">
<meta property="fc:frame:button:2:target" content="${escapeAttr(p.origin)}/discover">
<link rel="canonical" href="${escapeAttr(p.pageUrl)}">
<link rel="alternate" type="application/json+oembed" href="${escapeAttr(p.oembedJs)}" title="${t}">
<link rel="shortcut icon" href="/favicon.ico">
<style>
html,body{margin:0;padding:0;background:#0a0a0a;color:#e0e0e0;font-family:Inter,system-ui,sans-serif;height:100%;overflow:hidden}
.shell{display:grid;place-items:center;height:100vh;text-align:center;padding:2rem;gap:1rem}
.shell a{color:#8b5cf6;text-decoration:none}
.shell a:hover{text-decoration:underline}
.spinner{width:32px;height:32px;border:2px solid rgba(255,255,255,0.1);border-top-color:#8b5cf6;border-radius:50%;animation:spin 1s linear infinite}
@keyframes spin{to{transform:rotate(360deg)}}
@media(prefers-reduced-motion:reduce){.spinner{animation:none}}
</style>
</head>
<body>
<noscript>
<div class="shell">
<h1>${t}</h1>
<p>${d}</p>
<p><a href="${escapeAttr(p.embedUrl)}">Open 3D viewer</a> · <a href="/discover">Browse agents</a></p>
</div>
</noscript>
<div class="shell" id="loading" aria-live="polite">
<div class="spinner" aria-hidden="true"></div>
<p>Loading ${t}…</p>
</div>
<script>
(function () {
var target = ${JSON.stringify(p.viewerUrl)};
try {
var u = new URL(window.location.href);
if (u.searchParams.get('embed') === '0') return;
} catch (e) {}
window.location.replace(target);
})();
</script>
<script type="application/ld+json">
${escapeJsonLd({
'@context': 'https://schema.org',
'@graph': [
{
'@type': ['SoftwareApplication', 'Service'],
'@id': `${p.pageUrl}#agent`,
name: p.title,
description: p.desc,
url: p.pageUrl,
image: p.ogUrl,
identifier: `eip155:${p.chainId}:${p.agentId}`,
sameAs: p.manifestURI ? [p.manifestURI] : undefined,
applicationCategory: 'AIApplication',
applicationSubCategory: 'OnChainAgent',
operatingSystem: 'Web',
browserRequirements: 'Requires WebGL2',
provider: { '@type': 'Organization', name: 'three.ws', url: 'https://three.ws/' },
},
{
'@type': 'BreadcrumbList',
itemListElement: [
{ '@type': 'ListItem', position: 1, name: 'Home', item: 'https://three.ws/' },
{
'@type': 'ListItem',
position: 2,
name: 'Discover',
item: 'https://three.ws/discover',
},
{ '@type': 'ListItem', position: 3, name: p.title, item: p.pageUrl },
],
},
],
})}
</script>
</body>
</html>`;
}
function escapeHtml(s) {
return String(s).replace(
/[&<>"']/g,
(c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c],
);
}
function escapeAttr(s) {
return escapeHtml(s);
}
function escapeJsonLd(obj) {
const clean = JSON.parse(JSON.stringify(obj));
return JSON.stringify(clean, null, 2).replace(/</g, '\\u003c');
}