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(links): make the detail page the canonical link target across APIs, search, gallery, and the agents index
nirholas659114e25aa6
diff --git a/api/agents.js b/api/agents.jsindex 44ab263f4..3515e48b8 100644--- a/api/agents.js+++ b/api/agents.js@@ -814,7 +814,7 @@ function decorate(row, isOwner = true) {avatar_visibility: avatarVisibility,avatar_model_url: avatarModelUrl,avatar_thumbnail_url: avatarThumbnailUrl,- home_url: row.home_url || `/agent/${row.id}`,+ home_url: row.home_url || `/agents/${row.id}`,skills: row.skills || [],skill_prices: row.skill_prices || {},meta,diff --git a/api/agents/by-wallet.js b/api/agents/by-wallet.jsindex 932b681af..8aa1eb704 100644--- a/api/agents/by-wallet.js+++ b/api/agents/by-wallet.js@@ -58,7 +58,7 @@ export default wrap(async (req, res) => {name: r.name,description: r.description,avatar_id: r.avatar_id,- home_url: r.home_url || `/agent/${r.id}`,+ home_url: r.home_url || `/agents/${r.id}`,erc8004_agent_id: r.erc8004_agent_id != null ? String(r.erc8004_agent_id) : null,erc8004_registry: r.erc8004_registry,chain_id: r.chain_id,diff --git a/api/agents/ens/[name].js b/api/agents/ens/[name].jsindex 742654e6e..1817494d8 100644--- a/api/agents/ens/[name].js+++ b/api/agents/ens/[name].js@@ -55,7 +55,7 @@ async function agentsByAddress(address) {name: r.name,description: r.description,avatar_id: r.avatar_id,- home_url: r.home_url || `/agent/${r.id}`,+ home_url: r.home_url || `/agents/${r.id}`,erc8004_agent_id: r.erc8004_agent_id != null ? String(r.erc8004_agent_id) : null,erc8004_registry: r.erc8004_registry,chain_id: r.chain_id,diff --git a/api/agents/featured.js b/api/agents/featured.jsindex 110574d3a..2d6e29fca 100644--- a/api/agents/featured.js+++ b/api/agents/featured.js@@ -74,7 +74,7 @@ export default wrap(async (req, res) => {display_name: row.name,bio: row.description || null,avatar_url,- detail_url: row.home_url || `/agent/${row.id}`,+ detail_url: row.home_url || `/agents/${row.id}`,net_30d: Number(row.net_total),},},diff --git a/api/agents/onchain/[action].js b/api/agents/onchain/[action].jsindex 07e4fa483..1e263c56f 100644--- a/api/agents/onchain/[action].js+++ b/api/agents/onchain/[action].js@@ -671,7 +671,7 @@ async function handleConfirm(req, res) {agent: {...agent,onchain,- home_url: `${env.APP_ORIGIN}/agent/${agent.id}`,+ home_url: `${env.APP_ORIGIN}/agents/${agent.id}`,},});}diff --git a/api/agents/public.js b/api/agents/public.jsindex 0f214cf42..84be12879 100644--- a/api/agents/public.js+++ b/api/agents/public.js@@ -61,7 +61,7 @@ function mapAgent(r) {description: r.description || null,skills: r.skills || [],avatar_thumbnail: thumbnail,- home_url: r.home_url || `/agent/${r.id}`,+ home_url: r.home_url || `/agents/${r.id}`,chat_count: Number(r.chat_count) || 0,is_registered: !!(onchain || meta.sol_mint_address || r.erc8004_agent_id || meta.erc8004_agent_id),onchain: onchain ? { network: onchain.network, asset: onchain.sol_asset || null } : null,diff --git a/api/agents/solana/_handlers.js b/api/agents/solana/_handlers.jsindex df6672783..f16ee3704 100644--- a/api/agents/solana/_handlers.js+++ b/api/agents/solana/_handlers.js@@ -789,7 +789,7 @@ export const handleRegisterConfirm = wrap(async (req, res) => {validation = { error: e.code || 'validation_failed' };}- return json(res, 201, { ok: true, agent: { ...agent, home_url: `${env.APP_ORIGIN}/agent/${agent.id}` }, sol_mint_address: asset_pubkey, tx_signature, network, ...(validation ? { validation } : {}) });+ return json(res, 201, { ok: true, agent: { ...agent, home_url: `${env.APP_ORIGIN}/agents/${agent.id}` }, sol_mint_address: asset_pubkey, tx_signature, network, ...(validation ? { validation } : {}) });});// ── solana-collection-metadata ─────────────────────────────────────────────────@@ -1075,7 +1075,7 @@ export const handleEdit = wrap(async (req, res) => {return json(res, 200, {ok: true,- agent: { ...updated, home_url: `${env.APP_ORIGIN}/agent/${updated.id}` },+ agent: { ...updated, home_url: `${env.APP_ORIGIN}/agents/${updated.id}` },asset_pubkey,network,signatures,diff --git a/api/agents/tokens/[action].js b/api/agents/tokens/[action].jsindex aaa08554c..f815f313a 100644--- a/api/agents/tokens/[action].js+++ b/api/agents/tokens/[action].js@@ -918,7 +918,7 @@ async function handleLaunchConfirm(req, res) {return json(res, 201, {ok: true,- agent: { ...updated, token, home_url: `${env.APP_ORIGIN}/agent/${updated.id}` },+ agent: { ...updated, token, home_url: `${env.APP_ORIGIN}/agents/${updated.id}` },plan: shapePlan(launchedPlan),});}diff --git a/api/avatars/[id]/[action].js b/api/avatars/[id]/[action].jsindex 078a48bb3..019efab76 100644--- a/api/avatars/[id]/[action].js+++ b/api/avatars/[id]/[action].js@@ -104,7 +104,7 @@ async function handleAgentsByAvatar(req, res) {solana_vanity_prefix: r.solana_vanity_prefix || null,solana_vanity_suffix: r.solana_vanity_suffix || null,createdAt: r.created_at,- url: `/agent/${r.id}`,+ url: `/agents/${r.id}`,}));res.setHeader('cache-control', 'public, max-age=30, s-maxage=120, stale-while-revalidate=600');diff --git a/api/avatars/from-forge.js b/api/avatars/from-forge.jsindex eb6646756..e013b00bb 100644--- a/api/avatars/from-forge.js+++ b/api/avatars/from-forge.js@@ -205,6 +205,6 @@ export default wrap(async (req, res) => {// once and pays the two-sided referral reward when referred. Fire-and-forget.queueMicrotask(() => markActivated(auth.userId, { source: 'forge_save', meta: { avatarId: avatar.id } }));- const viewUrl = `${env.APP_ORIGIN || ''}/discover/avatar/${avatar.id}`;+ const viewUrl = `${env.APP_ORIGIN || ''}/avatars/${avatar.id}`;return json(res, 201, { avatar, view_url: viewUrl });});diff --git a/api/explore.js b/api/explore.jsindex 9273a94df..62148901d 100644--- a/api/explore.js+++ b/api/explore.js@@ -208,6 +208,7 @@ export default wrap(async (req, res) => {registeredAt: r.registered_at,tokenExplorerUrl: tokenExplorerUrl(r.chain_id, r.agent_id),ownerExplorerUrl: addressExplorerUrl(r.chain_id, r.owner),+ detailUrl: `/a/${r.chain_id}/${r.agent_id}`,viewerUrl: r.glb_url ? `/app#model=${encodeURIComponent(r.glb_url)}` : null,services: (r.services || []).map((s) => ({name: s?.name || null,@@ -234,7 +235,8 @@ export default wrap(async (req, res) => {owner: r.wallet_address,ownerShort: shortAddr(r.wallet_address),createdAt: r.created_at,- viewerUrl: `/agent/${r.id}`,+ detailUrl: `/agents/${r.id}`,+ viewerUrl: `/agents/${r.id}`,explorerUrl: asset ? `https://solscan.io/token/${asset}` : null,ownerExplorerUrl: r.wallet_address ? `https://solscan.io/account/${r.wallet_address}` : null,network: r.meta?.network || 'mainnet',@@ -269,6 +271,7 @@ export default wrap(async (req, res) => {owner: r.owner || null,ownerShort: shortAddr(r.owner),createdAt: r.registered_at,+ detailUrl: r.asset ? `/discover/a/sol/${encodeURIComponent(r.asset)}` : null,viewerUrl: r.glb_url ? `/app#model=${encodeURIComponent(r.glb_url)}` : null,explorerUrl: explorerTarget ? `https://solscan.io/account/${explorerTarget}` : null,ownerExplorerUrl: r.owner ? `https://solscan.io/account/${r.owner}` : null,@@ -308,6 +311,7 @@ export default wrap(async (req, res) => {featured: r.featured === true || r.featured === 't',viewCount: Number(r.view_count) || 0,createdAt: r.created_at,+ detailUrl: `/avatars/${r.id}`,viewerUrl: `/app#model=${encodeURIComponent(glb)}`,price,author: handlediff --git a/api/ibm/galaxy.js b/api/ibm/galaxy.jsindex 342666c25..c8dd9932d 100644--- a/api/ibm/galaxy.js+++ b/api/ibm/galaxy.js@@ -121,7 +121,7 @@ function agentImage(a) {}function agentUrl(a) {- return a.home_url || `/agent/${a.id}`;+ return a.home_url || `/agents/${a.id}`;}// ── Cluster naming ───────────────────────────────────────────────────────────diff --git a/api/trending.js b/api/trending.jsindex 85251f3ba..ec2e838cb 100644--- a/api/trending.js+++ b/api/trending.js@@ -146,7 +146,7 @@ export default wrap(async (req, res) => {solana_address: typeof meta.solana_address === 'string' ? meta.solana_address : null,solana_vanity_prefix: meta.solana_vanity_prefix || null,solana_vanity_suffix: meta.solana_vanity_suffix || null,- agent_url: `https://three.ws/agent/${encodeURIComponent(r.id)}`,+ agent_url: `https://three.ws/agents/${encodeURIComponent(r.id)}`,};});diff --git a/docs/api-reference.md b/docs/api-reference.mdindex 6dfc88e2f..06c3f2888 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -3392,42 +3392,53 @@ Requires auth. Permanently revokes the key.GET /api/explore```-Paginated search over ERC-8004 registered agents. No auth required.+Paginated directory across every source the platform crawls: ERC-8004 registered agents (EVM), three.ws Solana agents, external Solana agents (Metaplex Agent Registry + AgenC), and public 3D avatars. No auth required.**Query parameters**-| Parameter | Type | Description |-| --------- | ------- | ----------------------------------------------- |-| `q` | string | Full-text search query |-| `only3d` | `1` | Filter to agents with 3D avatars only |-| `chain` | integer | Filter by chain ID |-| `cursor` | string | ISO 8601 timestamp cursor for keyset pagination |-| `limit` | integer | Max results (default: 20) |+| Parameter | Type | Description |+| ---------- | ------- | ----------------------------------------------------------------------------------------------------- |+| `q` | string | Name/description substring search |+| `source` | string | `all` (default), `onchain`, `avatar`, `solana`, or `agents` (every on-chain agent, no avatars) |+| `only3d` | `1` | Only rows with a 3D body (avatars are always 3D) |+| `chain` | integer | Filter by EVM chain ID (implicitly excludes avatars and Solana) |+| `category` | string | Avatar `model_category` filter, single or comma-separated (`avatar`, `accessory`, `item`, `scene`, `creature`, `vehicle`, `other`) |+| `quality` | string | `high` (default, hides auto-named junk) or `all` |+| `cursor` | string | ISO 8601 timestamp cursor for keyset pagination |+| `limit` | integer | Max results, 1 to 250 (default: 24) |**Response**```json{- "agents": [+ "items": [{- "id": "onchain_abc",+ "kind": "onchain",+ "chainId": 8453,+ "agentId": 42,"name": "Aria","description": "Product guide",- "avatar_url": "https://three.ws/avatars/default.glb",- "thumbnail_url": "https://three.ws/avatars/thumbs/default.png",- "chain_id": 8453,- "chain_agent_id": 42,- "registered_at": "2025-01-15T10:00:00Z",- "services": [],- "explorer_url": "https://basescan.org/..."+ "detailUrl": "/a/8453/42",+ "viewerUrl": "/app#model=...",+ "registeredAt": "2025-01-15T10:00:00Z",+ "services": []+ },+ {+ "kind": "avatar",+ "avatarId": "13f259c7-7024-4d68-b1f0-dbbf52c06209",+ "name": "Michelle",+ "detailUrl": "/avatars/13f259c7-7024-4d68-b1f0-dbbf52c06209",+ "viewerUrl": "/app#model=...",+ "glbUrl": "https://three.ws/avatars/michelle.glb"}],- "total": 142,- "total_3d": 89,- "cursor": "2025-01-10T10:00:00Z"+ "nextCursor": "2025-01-10T10:00:00Z",+ "totals": { "all": 142, "threeD": 89, "onchain": 40, "solana": 12, "solanaExternal": 4, "avatars": 86 }}```+Every item carries a `detailUrl`: the canonical on-platform detail page for that entity (`/avatars/:id` for avatars, `/agents/:id` for three.ws agents, `/a/:chainId/:agentId` for ERC-8004 agents, `/discover/a/sol/:asset` for external Solana agents). Link to it rather than assembling paths from ids.+---### Featured agentsdiff --git a/public/agents/index.html b/public/agents/index.htmlindex 6dbdb9ab9..f8f507b9b 100644--- a/public/agents/index.html+++ b/public/agents/index.html@@ -290,17 +290,18 @@return { label: 'Solana', src: 'metaplex' };}- // Each kind links to its natural detail surface: EVM to /a/<chain>/<id>,- // our Solana agents to their profile, external Solana to the 3D viewer or- // the on-chain explorer when there's nothing else to open. A registry row- // with no asset and no ref has nowhere real to go, so it returns null and- // the card renders without a link rather than with a dead stub link.+ // Each kind links to its canonical detail page: EVM to /a/<chain>/<id>,+ // our Solana agents to /agents/<id>, external Solana to its detail page+ // when the API provides one, else the 3D viewer or the on-chain explorer+ // when there's nothing else to open. A registry row with no asset and no+ // ref has nowhere real to go, so it returns null and the card renders+ // without a link rather than with a dead stub link.function hrefFor(a) {if (a.kind === 'onchain' && a.chainId != null && a.agentId != null) {return `/a/${encodeURIComponent(a.chainId)}/${encodeURIComponent(a.agentId)}`;}- if (a.source === 'three.ws' && a.agentId) return `/agent/${encodeURIComponent(a.agentId)}`;- return a.viewerUrl || a.explorerUrl || null;+ if (a.source === 'three.ws' && a.agentId) return `/agents/${encodeURIComponent(a.agentId)}`;+ return a.detailUrl || a.viewerUrl || a.explorerUrl || null;}function cardHtml(a) {diff --git a/public/avatar-actions.js b/public/avatar-actions.jsindex 0520337eb..c30b51924 100644--- a/public/avatar-actions.js+++ b/public/avatar-actions.js@@ -213,7 +213,7 @@ class AvatarActions extends HTMLElement {const lineage = a.forked_from? `<div class="lineage">⑂ Forked from- <a href="/avatar-page.html?id=${a.forked_from.avatar_id}" title="View the original">+ <a href="/avatars/${a.forked_from.avatar_id}" title="View the original">${escapeHtml(a.forked_from.owner_name || a.forked_from.name || 'original')}</a></div>`: '';@@ -457,7 +457,7 @@ class AvatarActions extends HTMLElement {const wallet = d.agent?.wallet_address ? ` Its agent wallet: <code>${short(d.agent.wallet_address)}</code>.` : '';this._msg('ok',- `Saved to your avatars. <a class="manage" href="/avatar-page.html?id=${d.avatar.id}">Open →</a>${wallet}`,+ `Saved to your avatars. <a class="manage" href="/avatars/${d.avatar.id}">Open →</a>${wallet}`,);this.dispatchEvent(new CustomEvent('avatar-forked', { detail: d, bubbles: true, composed: true }),diff --git a/public/gallery/gallery.js b/public/gallery/gallery.jsindex 23d9ad532..ec96b501b 100644--- a/public/gallery/gallery.js+++ b/public/gallery/gallery.js@@ -474,7 +474,6 @@ function renderCard(a) {card.className = 'gallery-card';const glbUrl = a.model_url || '';- const viewerUrl = glbUrl ? `/app#model=${encodeURIComponent(glbUrl)}` : '#';const detailUrl = `/avatars/${a.id}`;const studioUrl = `/studio?avatar=${encodeURIComponent(a.id)}`;const animateUrl = `/pose?avatar=${encodeURIComponent(a.id)}`;@@ -516,7 +515,7 @@ function renderCard(a) {const rigBadge = window.twsRig?.rigBadgeHTML ? window.twsRig.rigBadgeHTML(a) : '';card.innerHTML = `- <a class="gallery-card-thumb" href="${escapeAttr(viewerUrl)}" aria-label="View ${escapeAttr(a.name || 'Avatar')} in 3D viewer">+ <a class="gallery-card-thumb" href="${escapeAttr(detailUrl)}" aria-label="Open ${escapeAttr(a.name || 'Avatar')}">${thumbContent}<span class="gallery-card-3dpill">3D</span>${rigBadge ? `<span class="gallery-card-rig">${rigBadge}</span>` : ''}diff --git a/public/search.js b/public/search.jsindex 0891fbbe0..9fa64b2d1 100644--- a/public/search.js+++ b/public/search.js@@ -1285,14 +1285,26 @@});var agentItems = (agents || []).slice(0, 6).map(function (a) {- var href = '/agent/' + esc(a.agent_id || a.id || '');+ // Canonical detail-page permalink per entity kind: avatars to+ // /avatars/:id, on-chain agents to /a/:chain/:id, three.ws agents+ // to /agents/:id. The API's detailUrl is authoritative; the local+ // branches keep results linked if a cached bundle outlives it.+ var href = a.detailUrl+ || (a.kind === 'avatar' && a.avatarId ? '/avatars/' + esc(a.avatarId)+ : a.kind === 'onchain' && a.chainId != null && a.agentId != null+ ? '/a/' + esc(a.chainId) + '/' + esc(a.agentId)+ : a.agentId ? '/agents/' + esc(a.agentId)+ : a.viewerUrl || a.explorerUrl || '/agents');+ var badge = a.kind === 'avatar' ? 'Avatar'+ : a.kind === 'onchain' ? 'ERC-8004'+ : a.kind === 'solana' ? 'Solana' : '';return {el: resultRow(href,agentIcon(a),a.name || 'Agent',a.description || '',- a.source === 'solana' ? 'Solana' : a.chain_id ? 'ERC-8004' : '',+ badge,q),};diff --git a/src/home-live-agents.js b/src/home-live-agents.jsindex 0e89b583e..f23acb434 100644--- a/src/home-live-agents.js+++ b/src/home-live-agents.js@@ -838,7 +838,9 @@function makeAgentCard(item, idx) {var card = document.createElement('a');card.className = 'showcase-agent-card';- card.href = item.viewerUrl || ('/avatars/' + (item.avatarId || item.agentId));+ // The canonical avatar detail page, not the bare GLB viewer: the+ // detail template carries chat, skills, embed, and launch actions.+ card.href = item.detailUrl || ('/avatars/' + (item.avatarId || item.agentId));var h = hashHue(item.avatarId || item.agentId || item.name || String(idx));var h2 = (h + 50) % 360;diff --git a/tests/api-agents-identity-endpoints.test.js b/tests/api-agents-identity-endpoints.test.jsindex b48d93f5d..7ab7161a4 100644--- a/tests/api-agents-identity-endpoints.test.js+++ b/tests/api-agents-identity-endpoints.test.js@@ -204,7 +204,7 @@ describe('GET /api/agents/by-wallet', () => {await byWalletHandler(req({ url: `/api/agents/by-wallet?address=${EVM_ADDR}&chain_id=8453` }), res);expect(res.statusCode).toBe(200);- expect(res.body.agents[0]).toMatchObject({ id: AGENT_ID, chain_id: 8453, home_url: `/agent/${AGENT_ID}` });+ expect(res.body.agents[0]).toMatchObject({ id: AGENT_ID, chain_id: 8453, home_url: `/agents/${AGENT_ID}` });});it('rejects a malformed wallet address', async () => {diff --git a/tests/api/agents.test.js b/tests/api/agents.test.jsindex bc00f025d..985107b94 100644--- a/tests/api/agents.test.js+++ b/tests/api/agents.test.js@@ -143,7 +143,7 @@ describe('GET /api/agents — list', () => {expect(body.agents).toHaveLength(1);expect(body.agents[0].id).toBe('agent-1');expect(body.agents[0].name).toBe('Alpha');- expect(body.agents[0].home_url).toBe('/agent/agent-1');+ expect(body.agents[0].home_url).toBe('/agents/agent-1');// decorate() must strip encrypted_wallet_key from metaexpect(body.agents[0].meta.encrypted_wallet_key).toBeUndefined();// Owner sees their own wallet_addressdiff --git a/tests/api/avatars-from-forge.test.js b/tests/api/avatars-from-forge.test.jsindex 5d3f62b78..9edd747ff 100644--- a/tests/api/avatars-from-forge.test.js+++ b/tests/api/avatars-from-forge.test.js@@ -134,7 +134,7 @@ describe('POST /api/avatars/from-forge', () => {});expect(res.statusCode).toBe(201);expect(json.avatar.id).toBe('avatar-uuid-0001');- expect(json.view_url).toBe('https://three.ws/discover/avatar/avatar-uuid-0001');+ expect(json.view_url).toBe('https://three.ws/avatars/avatar-uuid-0001');// Copied into the caller's own namespace.expect(r2State.put).toHaveBeenCalledTimes(1);expect(r2State.put.mock.calls[0][0].key).toMatch(/^u\/user-1\//);diff --git a/tests/api/mcp-avatar-persist.test.js b/tests/api/mcp-avatar-persist.test.jsindex c329768a0..8d1cc241b 100644--- a/tests/api/mcp-avatar-persist.test.js+++ b/tests/api/mcp-avatar-persist.test.js@@ -170,7 +170,7 @@ describe('save_avatar', () => {avatar_id: 'avatar-uuid-0001',slug: expect.stringMatching(/^studio-/),model_url: expect.stringContaining('https://cdn.test/'),- view_url: 'https://three.ws/discover/avatar/avatar-uuid-0001',+ view_url: 'https://three.ws/avatars/avatar-uuid-0001',});expect(r.isError).toBeUndefined();});diff --git a/tests/trending-endpoint.test.js b/tests/trending-endpoint.test.jsindex d470fee77..8da7a4a22 100644--- a/tests/trending-endpoint.test.js+++ b/tests/trending-endpoint.test.js@@ -174,7 +174,7 @@ describe('GET /api/trending payload', () => {const { agents, coins } = res.json;expect(agents.map((a) => a.rank)).toEqual([1, 2]);- expect(agents[0].agent_url).toBe('https://three.ws/agent/4339aafa-e5ed-496f-a8dd-9e6c4bff914d');+ expect(agents[0].agent_url).toBe('https://three.ws/agents/4339aafa-e5ed-496f-a8dd-9e6c4bff914d');expect(agents[0].avatar_thumbnail_url).toBe('https://cdn.test/thumb/harbor.png');// A private avatar's thumbnail never leaves the platform on a public feed.expect(agents[1].avatar_thumbnail_url).toBeNull();