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
import { id as keccakId, getAddress } from 'ethers';
import { z } from 'zod';
import { sql } from '../_lib/db.js';
import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';
import { cors, json, method, wrap, error, readJson, rateLimited } from '../_lib/http.js';
import { parse } from '../_lib/validate.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { CHAIN_BY_ID } from '../_lib/erc8004-chains.js';
import { evmRpcEndpoints } from '../_lib/evm/rpc.js';
import { fetchSafePublicUrlPinned, SsrfBlockedError, MaxBytesExceededError } from '../_lib/ssrf-guard.js';
import { resolveURI } from '../../src/ipfs.js';
const REGISTERED_TOPIC = keccakId('Registered(uint256,string,address)');
const TIMEOUT_MS = 10_000;
const bodySchema = z.object({
chainId: z.number().int().positive(),
txHash: z.string().regex(/^0x[0-9a-fA-F]{64}$/),
agentId: z.union([z.string(), z.number()]).transform(String),
// Stored verbatim as erc8004_agents_index.agent_uri and fetched by
// enrichMetadata, so it is bounded here rather than at the DB.
metadataUri: z.string().min(1).max(2048),
ownerAddress: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
// Optional: when binding an EXISTING three.ws agent on-chain, the agent's
// UUID. After the mint is verified below we write the unified meta.onchain
// block onto that row so the agent profile shows the on-chain badge on reload.
agentDbId: z.string().uuid().optional(),
});
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const session = await getSessionUser(req);
const bearer = session ? null : await authenticateBearer(extractBearer(req));
if (!session && !bearer) return error(res, 401, 'unauthorized', 'sign in required');
if (bearer && !hasScope(bearer.scope, 'avatars:write'))
return error(res, 403, 'insufficient_scope', 'avatars:write scope required');
const rl = await limits.registerIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const body = parse(bodySchema, await readJson(req));
const chain = CHAIN_BY_ID[body.chainId];
if (!chain) return error(res, 400, 'bad_request', `unsupported chain ${body.chainId}`);
const receipt = await rpcCall(body.chainId, 'eth_getTransactionReceipt', [body.txHash]);
if (!receipt) return error(res, 422, 'tx_not_mined', 'transaction not yet mined');
if (receipt.status === '0x0') return error(res, 422, 'tx_failed', 'transaction reverted');
const log = (receipt.logs ?? []).find(
(l) => l.address?.toLowerCase() === chain.registry.toLowerCase() && l.topics?.[0] === REGISTERED_TOPIC,
);
if (!log) return error(res, 422, 'event_not_found', 'Registered event not found in receipt');
const onChainId = BigInt(log.topics[1]).toString();
const ownerHex = getAddress('0x' + log.topics[2].slice(-40)).toLowerCase();
if (onChainId !== body.agentId) return error(res, 422, 'mismatch', 'agentId mismatch');
if (ownerHex !== body.ownerAddress.toLowerCase()) return error(res, 422, 'mismatch', 'ownerAddress mismatch');
// The on-chain Registered log is public, so anyone can replay a stranger's
// mint here. Only the user who controls the owner wallet may index or bind it.
const callerId = session?.id || bearer?.userId || null;
const [linked] = callerId
? await sql`
SELECT id FROM user_wallets
WHERE user_id = ${callerId} AND lower(address) = ${ownerHex}
LIMIT 1
`
: [];
if (!linked) return error(res, 403, 'forbidden', 'ownerAddress is not a wallet linked to your account');
const inserted = await sql`
INSERT INTO erc8004_agents_index
(chain_id, agent_id, owner, registry, agent_uri,
registered_block, registered_tx, registered_at, last_seen_at)
VALUES
(${body.chainId}, ${onChainId}, ${ownerHex}, ${chain.registry.toLowerCase()},
${body.metadataUri}, ${Number.parseInt(receipt.blockNumber, 16)}, ${body.txHash}, now(), now())
ON CONFLICT (chain_id, agent_id) DO NOTHING
RETURNING agent_id
`;
// Only a row this call created takes the caller-supplied metadata URI.
if (inserted?.length) await enrichMetadata(body.chainId, onChainId, body.metadataUri).catch(() => {});
// When binding an existing three.ws agent, persist the unified on-chain block
// onto its agent_identities row. Owner-scoped: only the user who owns the row
// (or a bearer with avatars:write for their own row) may write it. The tx was
// just verified above (Registered event, agentId + owner match), so this is a
// trustworthy source for meta.onchain.
let bound = false;
if (body.agentDbId) {
const userId = session?.id || bearer?.userId || null;
if (userId) {
bound = await bindAgentOnchain({
agentDbId: body.agentDbId,
userId,
chainId: body.chainId,
registry: chain.registry,
onChainId,
ownerHex,
metadataUri: body.metadataUri,
txHash: body.txHash,
}).catch(() => false);
}
}
return json(res, 200, { success: true, agentId: onChainId, chainId: body.chainId, bound });
});
/**
* Write the canonical meta.onchain block (per 2026-04-29-onchain-unified.sql)
* onto an owned agent_identities row. Last-write-wins on re-bind; merges into
* any existing meta. Returns true when a row was updated.
*/
async function bindAgentOnchain({
agentDbId,
userId,
chainId,
registry,
onChainId,
ownerHex,
metadataUri,
txHash,
}) {
const [existing] = await sql`
SELECT id, meta FROM agent_identities
WHERE id = ${agentDbId} AND user_id = ${userId} AND deleted_at IS NULL
LIMIT 1
`;
if (!existing) return false;
const onchain = {
chain: `eip155:${chainId}`,
family: 'evm',
tx_hash: txHash,
onchain_id: String(onChainId),
contract_or_mint: registry,
wallet: ownerHex,
metadata_uri: metadataUri,
confirmed_at: new Date().toISOString(),
};
const mergedMeta = { ...(existing.meta || {}), onchain };
await sql`
UPDATE agent_identities
SET meta = ${JSON.stringify(mergedMeta)}::jsonb,
wallet_address = ${ownerHex},
chain_id = ${chainId},
erc8004_agent_id = ${BigInt(onChainId)},
erc8004_registry = ${registry},
registration_cid = ${metadataUri},
updated_at = now()
WHERE id = ${agentDbId} AND user_id = ${userId}
`;
return true;
}
/**
* Read a JSON-RPC method over the chain's canonical failover chain: an operator
* RPC_URL_<chainId> override, then Alchemy, then the curated public endpoints,
* with the known-hard-fail keyless hosts sorted last. This used to read
* `chain.rpcUrls` directly, which is only the KEYLESS TAIL of that chain, so a
* registration was confirmed against the slowest tier and a tx that was already
* mined came back as `tx_not_mined` whenever a public node lagged.
*/
async function rpcCall(chainId, m, params) {
const urlList = evmRpcEndpoints(chainId);
let lastErr;
for (const url of urlList) {
const ac = new AbortController();
const t = setTimeout(() => ac.abort(), TIMEOUT_MS);
try {
const r = await fetch(url, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: m, params }),
signal: ac.signal,
});
if (!r.ok) throw new Error(`HTTP ${r.status} from ${url}`);
const d = await r.json();
if (d.error) throw new Error(`RPC ${d.error.code}: ${d.error.message}`);
return d.result;
} catch (err) {
lastErr = err;
} finally {
clearTimeout(t);
}
}
// Every endpoint failed: an infrastructure outage, not a caller mistake. An
// authored 503 tells the client to retry; letting lastErr bubble produced an
// opaque `internal_error` that read as a bug in the registration itself. The
// upstream detail rides on `cause` (logged) and never in the response body,
// which would otherwise echo a keyed provider URL.
throw Object.assign(new Error('no RPC endpoint answered for this chain; retry shortly'), {
status: 503,
code: 'rpc_unavailable',
expose: true,
cause: lastErr,
});
}
function resolveGateway(uri) {
if (!uri) return '';
const url = resolveURI(uri);
return url.startsWith('http') ? url : '';
}
async function enrichMetadata(chainId, agentId, uri) {
const url = resolveGateway(uri);
if (!url) return;
// uri is the client-supplied metadataUri; the pinned variant closes the
// DNS-rebinding TOCTOU window, and maxBytes bounds a hostile host's stream.
let r;
try {
r = await fetchSafePublicUrlPinned(
url,
{ signal: AbortSignal.timeout(TIMEOUT_MS) },
{ allowHttp: true, maxBytes: 2 * 1024 * 1024 },
);
} catch (err) {
if (err instanceof SsrfBlockedError || err instanceof MaxBytesExceededError) return;
throw err;
}
if (!r.ok) return;
const meta = await r.json();
const services = Array.isArray(meta.services) ? meta.services : [];
const avatarSvc = services.find((s) => String(s?.name || '').toLowerCase() === 'avatar' && s?.endpoint);
const glbUrl = avatarSvc ? resolveGateway(avatarSvc.endpoint) : null;
await sql`
UPDATE erc8004_agents_index
SET name = ${(meta.name || '').slice(0, 200) || null},
description = ${(meta.description || '').slice(0, 1000) || null},
image = ${resolveGateway(meta.image || '') || null},
glb_url = ${glbUrl}, services = ${JSON.stringify(services)}::jsonb,
has_3d = ${!!glbUrl}, active = ${meta.active !== false},
x402_support = ${!!(meta.x402Support || meta.x402)},
metadata_error = null, last_metadata_at = now()
WHERE chain_id = ${chainId} AND agent_id = ${agentId}
`;
}