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 { wrap, cors, error, json, readJson, method, rateLimited, serverError } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { cacheGet, cacheSet } from '../_lib/cache.js';
import { dasRpcUrl } from '../_lib/nft-gate.js';
import { resolveGateway } from '../_lib/solana-agents-normalize.js';
import { fetchTokenMeta } from '../_lib/solana-token-meta.js';
import { fetchSafePublicUrlPinned } from '../_lib/ssrf-guard.js';
import {
evmFallbackProvider,
evmRpcEndpoints,
alchemyNftBaseUrl,
alchemySupportsChain,
} from '../_lib/evm/rpc.js';
// NFT metadata is effectively immutable, but the Helius `getAsset` (DAS) and
// Alchemy `getNFTMetadata` calls behind this endpoint are billed per request and
// were re-resolved on every call, a bot re-requesting the same mint paid the
// upstream every time. Cache the resolved descriptor by chain:id so a given
// asset is fetched from the provider at most once per TTL.
const RESOLVE_TTL_SECONDS = 6 * 60 * 60; // 6h
// Last-known-good copy kept far longer, read ONLY when the upstream provider is
// unreachable. NFT metadata is effectively immutable, so serving a long-stale
// descriptor during a Helius/Alchemy outage is correct, far better than a 502.
const RESOLVE_STALE_TTL_SECONDS = 30 * 24 * 60 * 60; // 30d
// A provider that answers but never finishes must not hold the request open
// until the platform's own timeout fires; both upstreams are read-only lookups.
const UPSTREAM_TIMEOUT_MS = 15000;
// Read a JSON body without letting a non-JSON 200 (Helius answers quota refusals
// and maintenance pages as plain text) escape as an unhandled parse crash. This
// is a boundary, so it returns null instead of throwing.
async function readJsonBody(resp) {
try {
return await resp.json();
} catch {
return null;
}
}
// Metadata documents are small JSON files; anything larger is not one.
const MAX_METADATA_BYTES = 512 * 1024;
/**
* Read an NFT metadata document from a token `uri`.
*
* Handles the three forms in the wild: an https URL, a decentralized pointer
* (ipfs:// or ar://, normalized to a gateway), and a fully on-chain
* `data:application/json` URI. Returns null on anything unreadable, so callers
* treat a bad document the same as a missing one.
*/
async function fetchMetadataDoc(uri) {
if (!uri) return null;
const raw = String(uri).trim();
if (raw.startsWith('data:application/json')) {
const comma = raw.indexOf(',');
if (comma < 0) return null;
const payload = raw.slice(comma + 1);
const body = /;base64/i.test(raw.slice(0, comma))
? Buffer.from(payload, 'base64').toString('utf8')
: decodeURIComponent(payload);
try {
return JSON.parse(body);
} catch {
return null;
}
}
const url = resolveGateway(raw);
if (!url || !/^https?:\/\//i.test(url)) return null;
let resp;
try {
// tokenURI is whatever the contract (anyone's contract) returns, so the
// document is read through the pinned SSRF guard: private and metadata
// addresses are refused on every redirect hop, bytes capped in-stream.
resp = await fetchSafePublicUrlPinned(
url,
{ headers: { accept: 'application/json' }, signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS) },
{ allowHttp: true, maxBytes: MAX_METADATA_BYTES },
);
} catch {
return null;
}
if (!resp.ok) return null;
if (Number(resp.headers.get('content-length') || 0) > MAX_METADATA_BYTES) return null;
const text = await resp.text().catch(() => '');
if (!text || text.length > MAX_METADATA_BYTES) return null;
try {
return JSON.parse(text);
} catch {
return null;
}
}
/**
* Pick the 3D model out of a metadata document.
*
* `properties.files[]` with a `model/*` type is the Metaplex convention our own
* mints write; `animation_url` pointing at a .glb/.gltf is what most EVM
* collections use. Test the extension against the path only, since a gateway
* URL carries a query string after it.
*/
function pickModel(doc) {
const files = Array.isArray(doc?.properties?.files) ? doc.properties.files : [];
const modelFile = files.find((f) => {
const t = f?.type || f?.mime;
return typeof t === 'string' && t.startsWith('model/') && f?.uri;
});
if (modelFile) return { model: resolveGateway(modelFile.uri), mime: modelFile.type || modelFile.mime };
const animation = typeof doc?.animation_url === 'string' ? doc.animation_url : null;
if (animation && /\.(glb|gltf)(\?|$)/i.test(animation)) {
return {
model: resolveGateway(animation),
mime: /\.gltf(\?|$)/i.test(animation) ? 'model/gltf+json' : 'model/gltf-binary',
};
}
return { model: null, mime: null };
}
/**
* Keyless Solana rung: read the Metaplex metadata account over the platform's
* ordinary RPC failover chain and follow its `uri`.
*
* Helius DAS is metered, and on 2026-08-14 the account was capped ("max usage
* reached" on every getAsset), which took this endpoint to a blanket 502 with
* no way back. An NFT's metadata is public data on a public chain: nothing about
* reading it requires a billed indexer. This rung is slower (an account read
* plus a document fetch instead of one indexed call), so it runs only after DAS
* has failed.
*
* @returns {Promise<object|null>} the resolved descriptor, or null when the
* token exists but names no metadata document.
*/
async function resolveSolanaOnChain(id) {
const meta = await fetchTokenMeta(id, { includeImage: false });
const doc = meta.raw;
if (!doc && !meta.name) return null;
const { model, mime } = pickModel(doc);
return {
name: meta.name || id,
image: resolveGateway(meta.imageUrl) || null,
model: model || null,
mime: mime || null,
source: 'solana-rpc',
};
}
// ERC-721 and ERC-1155 both expose the metadata pointer, under different names.
// Probing tokenURI first matches the far more common standard for 3D collectibles.
const NFT_URI_ABI = [
'function tokenURI(uint256 tokenId) view returns (string)',
'function uri(uint256 id) view returns (string)',
'function name() view returns (string)',
];
/**
* Keyless EVM rung: read the token's own metadata pointer through the chain's
* RPC failover list, for the same reason as the Solana rung above (Alchemy
* answered "Monthly capacity limit exceeded" on every getNFTMetadata call).
*
* @returns {Promise<object|null>} the resolved descriptor, or null when neither
* metadata interface answers.
*/
async function resolveEvmOnChain(chainId, contractAddress, tokenId) {
const { Contract } = await import('ethers');
const provider = await evmFallbackProvider(chainId);
const contract = new Contract(contractAddress, NFT_URI_ABI, provider);
let uri = null;
for (const method of ['tokenURI', 'uri']) {
try {
uri = await contract[method](tokenId);
if (uri) break;
} catch {
uri = null;
}
}
if (!uri) return null;
// ERC-1155 metadata URIs carry a literal {id} placeholder the client must
// substitute with the zero-padded 64-hex token id.
if (uri.includes('{id}')) {
uri = uri.replace('{id}', BigInt(tokenId).toString(16).padStart(64, '0'));
}
const doc = await fetchMetadataDoc(uri);
if (!doc) return null;
const { model, mime } = pickModel(doc);
let collection = null;
try {
collection = await contract.name();
} catch {
collection = null;
}
return {
name: doc.name || collection || `${contractAddress}:${tokenId}`,
image: resolveGateway(doc.image || doc.image_url) || null,
model: model || null,
mime: mime || null,
source: 'evm-rpc',
};
}
export default wrap(async (req, res) => {
if (cors(req, res)) return;
if (!method(req, res, ['POST'])) return;
const rl = await limits.authedReadIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
// A bare `null` JSON body parses to null, and reading `.chain` off it threw a
// TypeError that surfaced as an opaque 500 instead of the 400 every other
// malformed body gets.
const body = (await readJson(req)) || {};
const chain = String(body.chain || '').toLowerCase();
const id = String(body.id || '').trim();
if (!['solana', 'evm'].includes(chain)) {
return error(res, 400, 'bad_request', 'chain must be solana or evm');
}
if (!id) return error(res, 400, 'bad_request', 'id required');
const cacheKey = `nft-resolve:${chain}:${id}`;
const staleKey = `nft-resolve-stale:${chain}:${id}`;
const cached = await cacheGet(cacheKey).catch(() => null);
if (cached) return json(res, 200, cached);
// Only a cache MISS reaches the billed upstream, gate that on the shared DAS
// cost ceiling so a bot resolving thousands of distinct ids can't run up the
// Helius/Alchemy bill past a fixed hourly cap.
const ceiling = await limits.heliusDasGlobal();
if (!ceiling.success) return rateLimited(res, ceiling);
// Persist a resolved descriptor to both the fresh and long-lived stale tiers.
const store = async (result) => {
await cacheSet(cacheKey, result, RESOLVE_TTL_SECONDS).catch(() => {});
await cacheSet(staleKey, result, RESOLVE_STALE_TTL_SECONDS).catch(() => {});
return result;
};
// Indexer unusable (unreachable, capped, or misconfigured) → in order: read the
// chain directly, then serve the last-known-good descriptor, then surface the
// caller's error. The direct read comes first because it is authoritative and
// current; the stale tier is safe only because metadata is effectively
// immutable, so it is the second choice, not the first.
const rescue = async (onChain, onMiss) => {
try {
const direct = await onChain();
if (direct) return json(res, 200, await store(direct));
} catch (err) {
if (err?.code === 'mint_not_found' || err?.code === 'invalid_mint') {
return error(res, err.status === 400 ? 400 : 404, err.status === 400 ? 'bad_request' : 'not_found', err.message);
}
console.error('[nft/resolve] direct chain read failed', err?.message);
}
const lastGood = await cacheGet(staleKey).catch(() => null);
if (lastGood) {
console.warn('[nft/resolve] upstream unreachable, serving last-known-good for %s', cacheKey);
return json(res, 200, { ...lastGood, stale: true });
}
return onMiss();
};
if (chain === 'solana') {
const solanaRescue = (onMiss) => rescue(() => resolveSolanaOnChain(id), onMiss);
// `getAsset` is a DAS method, and Helius is the only provider in our stack
// that serves it. Reading SOLANA_RPC_URL here pointed the call at whatever
// general-purpose RPC was configured (production runs magicblock), which
// answers a JSON-RPC -32601 that the code below then reported to the user as
// "Asset not found": a real, resolvable NFT read as nonexistent. dasRpcUrl()
// is the same resolver api/_lib/nft-gate.js gates on, and prefers the
// dedicated HELIUS_API_KEY.
const rpcUrl = dasRpcUrl();
if (!rpcUrl) {
return solanaRescue(() =>
error(
res,
503,
'not_configured',
'HELIUS_API_KEY not configured and the token names no readable metadata',
),
);
}
let resp;
try {
resp = await fetch(rpcUrl, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getAsset', params: { id } }),
signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
});
} catch (err) {
console.error('[nft/resolve] Helius network error', err?.message);
return solanaRescue(() =>
serverError(res, 502, 'upstream_error', new Error('Helius unreachable')),
);
}
if (!resp.ok) {
const txt = await resp.text().catch(() => '');
console.error('[nft/resolve] Helius error', resp.status, txt);
return solanaRescue(() =>
serverError(res, 502, 'upstream_error', new Error(`Helius error ${resp.status}`)),
);
}
const data = await readJsonBody(resp);
if (!data) {
console.error('[nft/resolve] Helius returned a non-JSON body');
return solanaRescue(() =>
serverError(res, 502, 'upstream_error', new Error('Helius returned a non-JSON body')),
);
}
if (data.error) {
const msg = data.error.message || JSON.stringify(data.error);
// -32601 is "the endpoint does not implement this method", an operator
// misconfiguration. Only a real DAS miss is a 404.
if (data.error.code === -32601) {
console.error('[nft/resolve] configured RPC does not serve DAS getAsset');
return solanaRescue(() =>
serverError(res, 502, 'upstream_error', new Error(`DAS getAsset unsupported: ${msg}`)),
);
}
return error(res, 404, 'not_found', `Asset not found: ${msg}`);
}
const asset = data.result;
if (!asset) return error(res, 404, 'not_found', `Asset not found: ${id}`);
const name = asset?.content?.metadata?.name || asset?.id || id;
const files = asset?.content?.files || [];
const modelFile = files.find((f) => f.mime && f.mime.startsWith('model/'));
const imageUrl =
asset?.content?.links?.image ||
files.find((f) => f.mime && f.mime.startsWith('image/'))?.uri ||
null;
// The chat NFT viewer hands `model` and `image` straight to GLTFLoader and an
// <img>, and a browser cannot fetch an ipfs:// URI. Metadata that stores raw
// ipfs:// pointers rendered as a blank canvas; resolveGateway is the same
// normalizer the Solana agent index uses and leaves https URLs untouched.
const result = await store({
name,
image: resolveGateway(imageUrl),
model: resolveGateway(modelFile?.uri) || null,
mime: modelFile?.mime || null,
source: 'helius',
});
return json(res, 200, result);
}
// EVM: id is "contract:tokenId" (Ethereum mainnet) or "chainId:contract:tokenId"
const parts = id.split(':');
let contractAddress, tokenId, chainId;
if (parts.length === 2) {
[contractAddress, tokenId] = parts;
chainId = 1;
} else if (parts.length === 3) {
[, contractAddress, tokenId] = parts;
chainId = Number(parts[0]);
} else {
return error(res, 400, 'bad_request', 'evm id must be "contract:tokenId" or "chainId:contract:tokenId"');
}
// Gate on whether the platform can reach the chain AT ALL, not on whether the
// indexer covers it. The keyless rung below reads the token's own metadata
// pointer over the chain's public RPC list and needs no Alchemy host, so a
// chain the registry knows is resolvable even when the indexer is not an
// option. A chainId nothing in the stack has an endpoint for still 400s here
// rather than timing out against nothing.
if (evmRpcEndpoints(chainId).length === 0) {
return error(res, 400, 'bad_request', `unsupported evm chainId ${parts[0]}`);
}
// Both the Alchemy call and the on-chain rung take these verbatim, so reject a
// malformed pair here rather than paying an upstream round-trip to be told.
if (!/^0x[0-9a-fA-F]{40}$/.test(contractAddress)) {
return error(res, 400, 'bad_request', 'evm contract must be a 0x-prefixed 20-byte address');
}
if (!/^(0x[0-9a-fA-F]+|\d+)$/.test(tokenId)) {
return error(res, 400, 'bad_request', 'evm tokenId must be decimal or 0x-hex');
}
const evmRescue = (onMiss) =>
rescue(() => resolveEvmOnChain(chainId, contractAddress, tokenId), onMiss);
// `env` exposes no ALCHEMY getter, so the previous `env.ALCHEMY_API_KEY` read
// was undefined in every environment: the whole EVM branch built a URL with a
// literal "undefined" key and answered 502 on a 401 from Alchemy, configured
// or not. alchemyNftBaseUrl resolves the host and the key together, honoring
// the per-chain key overrides (ALCHEMY_BASE_KEY and friends) that the RPC lane
// already respects, and returns null when either half is absent.
const baseUrl = alchemyNftBaseUrl(chainId);
if (!baseUrl) {
// Two different operator problems wear the same null, and telling them
// apart is the difference between "provision a key" and "this chain has no
// indexer, the keyless rung is all there is".
const reason = alchemySupportsChain(chainId)
? `no Alchemy API key configured for chainId ${chainId}`
: `Alchemy does not index chainId ${chainId}`;
return evmRescue(() =>
error(res, 503, 'not_configured', `${reason} and the token names no readable metadata`),
);
}
const url = `${baseUrl}/getNFTMetadata?contractAddress=${encodeURIComponent(contractAddress)}&tokenId=${encodeURIComponent(tokenId)}`;
let resp;
try {
resp = await fetch(url, { signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS) });
} catch (err) {
console.error('[nft/resolve] Alchemy network error', err?.message);
return evmRescue(() =>
serverError(res, 502, 'upstream_error', new Error('Alchemy unreachable')),
);
}
if (!resp.ok) {
const txt = await resp.text().catch(() => '');
if (resp.status === 404) {
return error(res, 404, 'not_found', `Alchemy error ${resp.status}: ${txt}`);
}
console.error('[nft/resolve] Alchemy error', resp.status, txt);
return evmRescue(() =>
serverError(res, 502, 'upstream_error', new Error(`Alchemy error ${resp.status}`)),
);
}
const data = await readJsonBody(resp);
if (!data) {
console.error('[nft/resolve] Alchemy returned a non-JSON body');
return evmRescue(() =>
serverError(res, 502, 'upstream_error', new Error('Alchemy returned a non-JSON body')),
);
}
const name = data.name || data.contract?.name || id;
const animationUrl = resolveGateway(data.raw?.metadata?.animation_url);
const imageUrl = data.image?.cachedUrl || data.media?.[0]?.gateway || null;
// animation_url may be a glTF/GLB. Test the extension on the path only: a
// gateway URL carries a query string, and ".glb?filename=x" ends in neither.
let model = null;
let mime = null;
if (animationUrl && /\.(glb|gltf)(\?|$)/i.test(animationUrl)) {
model = animationUrl;
mime = /\.gltf(\?|$)/i.test(animationUrl) ? 'model/gltf+json' : 'model/gltf-binary';
}
const result = await store({ name, image: imageUrl, model, mime, source: 'alchemy' });
return json(res, 200, result);
});