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
// GET /api/registry/resolve?q=<input>
// ---------------------------------------------------------------------------
// Public agent-registry lookup. Detects the input type and normalises any of
// • a Solana Core asset mint (base58, 32–44 chars)
// • an agent identity UUID / avatar UUID
// • an avatar slug
// into one JSON record describing the agent's 3D body + on-chain identity.
//
// Never leaks a private GLB: modelUrl is only resolved for public/unlisted
// avatars (resolveAvatarUrl would otherwise mint a presigned URL for a private
// object). Unknown input resolves to { state: 'not_found' } with a 200 — the
// page renders a clean not-found, never a 500.
import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
import { mplCore, fetchAssetV1, findAssetSignerPda } from '@metaplex-foundation/mpl-core';
import { publicKey as umiPublicKey } from '@metaplex-foundation/umi';
import { sql } from '../_lib/db.js';
import { cors, json, method, wrap, error, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { isUuid } from '../_lib/validate.js';
import { resolveAvatarUrl } from '../_lib/avatars.js';
import { thumbnailUrl } from '../_lib/r2.js';
import { solanaConnection } from '../_lib/solana/connection.js';
// Solana base58 pubkey — excludes 0/O/I/l, length 32–44. A UUID contains
// hyphens so it can never match; we still check isUuid() first for clarity.
const PUBKEY_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
// A read-only Umi per network. fetchAssetV1 hits the RPC; findAssetSignerPda is
// pure program-derived address math (no network), so it works for either.
const _umi = {};
function readUmi(network) {
// A multi-endpoint failover Connection (not a bare URL): fetchAssetV1's RPC read
// rotates across the endpoint chain, so a single node returning a malformed/empty
// 200 body fails over instead of throwing the `StructError: … but received:` crash.
if (!_umi[network]) _umi[network] = createUmi(solanaConnection({ network })).use(mplCore());
return _umi[network];
}
function explorerLinks(mint, network) {
const devnet = network === 'devnet';
return {
metaplex: `https://core.metaplex.com/explorer/${mint}${devnet ? '?env=devnet' : ''}`,
solscan: `https://solscan.io/token/${mint}${devnet ? '?cluster=devnet' : ''}`,
magiceden: `https://magiceden.io/item-details/${mint}`,
};
}
// Derive the asset signer PDA (the agent's on-chain wallet) for a Core asset.
// Pure derivation — returns null only if the mint is not a valid pubkey.
function assetSignerWalletFor(mint) {
try {
const [pda] = findAssetSignerPda(readUmi('mainnet'), { asset: umiPublicKey(mint) });
return pda.toString();
} catch {
return null;
}
}
// Genesis rank: an agent's 1-based position among every on-chain-deployed
// agent, ordered by the moment it was minted. cz, the first agent deployed,
// is Genesis #1. Null for agents that aren't minted yet.
async function genesisRankFor(agentId) {
if (!agentId) return null;
const [row] = await sql`
WITH ranked AS (
SELECT id,
row_number() OVER (
ORDER BY COALESCE((meta->'onchain'->>'confirmed_at')::timestamptz, created_at) ASC,
created_at ASC, id ASC
) AS rank
FROM agent_identities
WHERE deleted_at IS NULL
AND (meta->>'sol_mint_address' IS NOT NULL
OR meta->'devnet'->>'sol_mint_address' IS NOT NULL)
)
SELECT rank FROM ranked WHERE id = ${agentId}
`;
return row ? Number(row.rank) : null;
}
// Pull the on-chain coordinates out of an agent's meta blob, picking the
// network the agent was actually deployed on (mainnet preferred).
function onchainCoords(meta) {
if (!meta || typeof meta !== 'object') return null;
const mainMint = meta.sol_mint_address || null;
const devMint = meta.devnet?.sol_mint_address || null;
const mint = mainMint || devMint || meta.onchain?.sol_asset || null;
if (!mint) return null;
const network = mainMint ? 'mainnet' : devMint ? 'devnet' : meta.network || 'mainnet';
const net = mainMint ? meta : devMint ? meta.devnet : meta;
return {
mint,
network,
collection: net?.collection || meta.collection || null,
owner: net?.onchain?.owner || meta.onchain?.owner || null,
};
}
// Build the unified response from a normalised record. `avatar` carries the
// raw storage row (storage_key + visibility) so we can gate the GLB; `meta` is
// the agent's meta blob (null for avatars with no linked agent).
async function build({ name, description, agentId, meta, avatar, ownerFallback }) {
const coords = onchainCoords(meta);
let modelUrl = null;
const isPublicAvatar =
avatar && (avatar.visibility === 'public' || avatar.visibility === 'unlisted');
if (isPublicAvatar) {
try {
const resolved = await resolveAvatarUrl({
storage_key: avatar.storage_key,
visibility: avatar.visibility,
});
modelUrl = resolved?.url || null;
} catch {
modelUrl = null;
}
}
// The thumbnail is a render of the avatar itself, so it is gated on exactly the
// visibility that gates the GLB above: a private avatar yields identity
// metadata and no imagery, the same gate api/characters.js, api/trending.js and
// api/og/agent.js apply. thumbnailUrl() (never a bare publicUrl) is the one
// resolver every read path uses, so a legacy origin-pointing `*_og.png` key is
// dropped instead of published as a doomed <img> src; it reads S3_PUBLIC_DOMAIN,
// which throws when unset, and an unconfigured var must degrade to no image
// rather than 503 the whole identity lookup.
let imageUrl = null;
if (isPublicAvatar && avatar.thumbnail_key) {
try {
imageUrl = thumbnailUrl(avatar.thumbnail_key);
} catch {
imageUrl = null;
}
}
let onchain = null;
if (coords) {
const owner = coords.owner || ownerFallback || null;
onchain = {
mint: coords.mint,
collection: coords.collection,
owner,
assetSignerWallet: assetSignerWalletFor(coords.mint),
active: true,
x402Support: true,
links: explorerLinks(coords.mint, coords.network),
};
}
// State: a private avatar yields metadata + identity but no model.
const state = avatar && avatar.visibility === 'private' ? 'private' : 'public';
return {
name: name || null,
description: description || '',
// On-platform identity: the canonical agent profile lives at
// /agents/:id. Null for bare on-chain assets that aren't three.ws agents.
agentId: agentId || null,
genesisRank: await genesisRankFor(agentId),
modelUrl,
imageUrl,
onchain,
state,
};
}
// ── resolvers ─────────────────────────────────────────────────────────────────
//
// Queries are written out in full per resolver. The Neon HTTP driver does not
// renumber placeholders across embedded `sql`…`` fragments, so composing a
// shared SELECT fragment with a parameterised WHERE produces invalid SQL.
function agentRowToRecord(r) {
return {
name: r.name,
description: r.description,
agentId: r.id,
meta: r.meta,
ownerFallback: r.wallet_address,
avatar: r.storage_key
? {
storage_key: r.storage_key,
visibility: r.visibility,
content_type: r.content_type,
thumbnail_key: r.thumbnail_key,
}
: null,
};
}
async function resolveAgentById(id) {
const [r] = await sql`
SELECT ai.id, ai.name, ai.description, ai.wallet_address, ai.meta,
av.storage_key, av.visibility, av.content_type, av.thumbnail_key
FROM agent_identities ai
LEFT JOIN avatars av ON av.id = ai.avatar_id AND av.deleted_at IS NULL
WHERE ai.id = ${id} AND ai.deleted_at IS NULL
LIMIT 1
`;
return r ? agentRowToRecord(r) : null;
}
async function resolveByMint(mint) {
const [r] = await sql`
SELECT ai.id, ai.name, ai.description, ai.wallet_address, ai.meta,
av.storage_key, av.visibility, av.content_type, av.thumbnail_key
FROM agent_identities ai
LEFT JOIN avatars av ON av.id = ai.avatar_id AND av.deleted_at IS NULL
WHERE ai.deleted_at IS NULL
AND (ai.meta->>'sol_mint_address' = ${mint}
OR ai.meta->'onchain'->>'sol_asset' = ${mint}
OR ai.meta->'devnet'->>'sol_mint_address' = ${mint})
LIMIT 1
`;
if (r) return agentRowToRecord(r);
// Not in our DB — read the asset on-chain and back-resolve via its URI,
// which for three.ws agents points at /api/agents/<uuid>/registration.
for (const network of ['mainnet', 'devnet']) {
let asset;
try {
asset = await fetchAssetV1(readUmi(network), umiPublicKey(mint));
} catch {
continue;
}
const uri = asset?.uri || '';
const m = uri.match(/\/api\/agents\/([0-9a-f-]{36})\b/i);
if (m) {
const rec = await resolveAgentById(m[1]);
if (rec) return rec;
}
// Real on-chain asset that isn't a three.ws agent: surface its identity
// without a model rather than a false not-found.
return {
name: asset?.name || null,
description: '',
agentId: null,
meta: {
sol_mint_address: mint,
network,
onchain: { owner: asset?.owner?.toString?.() || null },
},
ownerFallback: asset?.owner?.toString?.() || null,
avatar: null,
};
}
return null;
}
// Avatar resolution (by UUID or slug) prefers a deployed agent linked to the
// avatar so an avatar id / slug resolves to the same on-chain view as the mint.
function avatarRowToRecord(r) {
return {
name: r.agent_name || r.name,
description: r.agent_description || r.description,
agentId: r.agent_id || null,
meta: r.agent_meta || null,
ownerFallback: r.agent_wallet || null,
avatar: {
storage_key: r.storage_key,
visibility: r.visibility,
content_type: r.content_type,
thumbnail_key: r.thumbnail_key,
},
};
}
async function resolveAvatarById(id) {
const [r] = await sql`
SELECT av.id, av.name, av.description, av.slug, av.storage_key, av.visibility,
av.content_type, av.thumbnail_key,
ai.id AS agent_id, ai.name AS agent_name, ai.description AS agent_description,
ai.wallet_address AS agent_wallet, ai.meta AS agent_meta
FROM avatars av
LEFT JOIN LATERAL (
SELECT id, name, description, wallet_address, meta
FROM agent_identities
WHERE avatar_id = av.id AND deleted_at IS NULL
ORDER BY (meta->>'sol_mint_address') IS NOT NULL DESC, created_at ASC
LIMIT 1
) ai ON true
WHERE av.id = ${id} AND av.deleted_at IS NULL
LIMIT 1
`;
return r ? avatarRowToRecord(r) : null;
}
async function resolveBySlug(slug) {
// Slug is unique per owner, so a bare slug can match several avatars; prefer
// a public one, then the earliest. Never matches a private avatar (a public
// lookup must not leak that a private slug exists).
const [r] = await sql`
SELECT av.id, av.name, av.description, av.slug, av.storage_key, av.visibility,
av.content_type, av.thumbnail_key,
ai.id AS agent_id, ai.name AS agent_name, ai.description AS agent_description,
ai.wallet_address AS agent_wallet, ai.meta AS agent_meta
FROM avatars av
LEFT JOIN LATERAL (
SELECT id, name, description, wallet_address, meta
FROM agent_identities
WHERE avatar_id = av.id AND deleted_at IS NULL
ORDER BY (meta->>'sol_mint_address') IS NOT NULL DESC, created_at ASC
LIMIT 1
) ai ON true
WHERE av.slug = ${slug}
AND av.deleted_at IS NULL
AND av.visibility IN ('public', 'unlisted')
ORDER BY av.created_at ASC
LIMIT 1
`;
return r ? avatarRowToRecord(r) : null;
}
// ── handler ─────────────────────────────────────────────────────────────────
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
if (!method(req, res, ['GET'])) return;
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const q = (req.query?.q || new URL(req.url, 'http://x').searchParams.get('q') || '').trim();
if (!q) return error(res, 400, 'validation_error', 'q is required');
if (q.length > 64) return error(res, 400, 'validation_error', 'q is too long');
let record = null;
if (isUuid(q)) {
record = (await resolveAgentById(q)) || (await resolveAvatarById(q));
} else if (PUBKEY_RE.test(q)) {
record = await resolveByMint(q);
} else {
record = await resolveBySlug(q);
}
if (!record) {
return json(res, 200, {
name: null,
description: '',
agentId: null,
genesisRank: null,
modelUrl: null,
imageUrl: null,
onchain: null,
state: 'not_found',
});
}
const result = await build(record);
return json(res, 200, result, {
'cache-control': 'public, max-age=30, s-maxage=120, stale-while-revalidate=600',
});
});