Skip to content

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.

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.js
index 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.js
index 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].js
index 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.js
index 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].js
index 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.js
index 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.js
index 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].js
index 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].js
index 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.js
index 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.js
index 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: handle
diff --git a/api/ibm/galaxy.js b/api/ibm/galaxy.js
index 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.js
index 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.md
index 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 agents
diff --git a/public/agents/index.html b/public/agents/index.html
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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 meta
expect(body.agents[0].meta.encrypted_wallet_key).toBeUndefined();
// Owner sees their own wallet_address
diff --git a/tests/api/avatars-from-forge.test.js b/tests/api/avatars-from-forge.test.js
index 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.js
index 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.js
index 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();