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
// Read-only Solana token metadata fetcher.
//
// On-chain: Metaplex Token Metadata v1 (PDA = ["metadata", program, mint]).
// Off-chain: the JSON document referenced by the on-chain `uri` field —
// typically Pinata/Arweave/pump.fun-cdn — providing `image` (and friends).
//
// Used by /api/x402/mint-to-mesh to derive a 3D representation of any fungible
// token. Distinct from api/pump-fun-mcp.js's inline reader, which only exposes
// the on-chain decode (no off-chain JSON or image bytes resolution).
import { PublicKey } from '@solana/web3.js';
import {
TOKEN_2022_PROGRAM_ID,
TOKEN_PROGRAM_ID,
getTokenMetadata,
} from '@solana/spl-token';
import { getConnection, solanaPubkey } from './pump.js';
import { isRpcOutageError, rpcUnavailableError } from './rpc-degrade.js';
import { fetchSafePublicUrlPinned } from './ssrf-guard.js';
import { IPFS_GATEWAYS, ipfsPath } from './ipfs-gateways.js';
const METADATA_PROGRAM = new PublicKey('metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s');
const NAME_MAX = 32;
const SYMBOL_MAX = 10;
const URI_MAX = 200;
const METADATA_FETCH_TIMEOUT_MS = 8_000;
const IMAGE_FETCH_TIMEOUT_MS = 8_000;
const MAX_OFFCHAIN_JSON_BYTES = 256 * 1024; // 256 KB
const MAX_IMAGE_BYTES = 4 * 1024 * 1024; // 4 MB
const ALLOWED_IMAGE_MIME = new Set(['image/png', 'image/jpeg', 'image/webp']);
/**
* Decode the Metaplex Token Metadata account for `mint`.
* Returns null when the metadata PDA does not exist on-chain.
*/
async function fetchOnchainMetadata(connection, mintPk) {
const [metadataPda] = PublicKey.findProgramAddressSync(
[Buffer.from('metadata'), METADATA_PROGRAM.toBuffer(), mintPk.toBuffer()],
METADATA_PROGRAM,
);
// Metadata is decoration on top of the mint: an RPC blip here degrades the
// name/symbol/uri to null rather than failing the whole read.
let info;
try {
info = await connection.getAccountInfo(metadataPda);
} catch (err) {
console.warn(`[solana-token-meta] metadata PDA read failed for ${mintPk.toBase58()}: ${err?.message || err}`);
return null;
}
if (!info) return null;
// Layout: 1 key + 32 updateAuthority + 32 mint + name + symbol + uri.
// Each string is length-prefixed (u32 LE) but space-padded to a fixed max.
const buf = info.data;
let cursor = 1 + 32 + 32;
const readPaddedStr = (max) => {
if (cursor + 4 > buf.length) return '';
const len = buf.readUInt32LE(cursor);
cursor += 4;
const slice = buf.slice(cursor, cursor + len);
cursor += max;
return slice.toString('utf8').replace(/\u0000+$/g, '').trim();
};
return {
name: readPaddedStr(NAME_MAX),
symbol: readPaddedStr(SYMBOL_MAX),
uri: readPaddedStr(URI_MAX),
};
}
/**
* Read the metadata a Token-2022 mint carries inside its own account, in the
* `TokenMetadata` extension, instead of in a separate Metaplex PDA. Every
* pump.fun launch since the Token-2022 cutover stores it this way (the platform
* coin $THREE included), and those mints have NO Metaplex account at all, so a
* PDA-only reader reports them as nameless and image-less.
*
* Returns the same { name, symbol, uri } shape as the Metaplex path, or null
* when the mint is classic SPL or carries no metadata extension.
*/
async function fetchToken2022Metadata(connection, mintPk, ownerProgram) {
if (ownerProgram !== TOKEN_2022_PROGRAM_ID.toBase58()) return null;
let md;
try {
md = await getTokenMetadata(connection, mintPk, undefined, TOKEN_2022_PROGRAM_ID);
} catch (err) {
// Same soft-null contract as the Metaplex reader: the caller still gets
// a token profile, just without the embedded name/symbol/uri.
console.warn(`[solana-token-meta] token-2022 metadata read failed for ${mintPk.toBase58()}: ${err?.message || err}`);
return null;
}
if (!md) return null;
return {
name: (md.name || '').trim(),
symbol: (md.symbol || '').trim(),
uri: (md.uri || '').trim(),
};
}
// Resolve common gateway-less URIs to a fetchable HTTPS URL. Pinata/IPFS hashes
// (`ipfs://...`) get rewritten to a public gateway; everything else is returned
// as-is (must already be http(s):).
function resolveOffchainUrl(uri) {
if (!uri) return null;
const trimmed = uri.trim();
if (!trimmed) return null;
// ipfs:// and URLs pinned to a gateway that stopped serving (pump.fun still
// hands out ipfs.io) both re-point at the first live shared gateway.
const cidPath = ipfsPath(trimmed);
if (cidPath) return IPFS_GATEWAYS[0] + cidPath;
if (trimmed.startsWith('ar://')) {
return `https://arweave.net/${trimmed.slice('ar://'.length)}`;
}
if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) return trimmed;
return null;
}
async function fetchOffchainJson(uri) {
const url = resolveOffchainUrl(uri);
if (!url) return null;
let res;
try {
// The metadata URI is whatever the mint's creator wrote on-chain, so it is
// fetched through the pinned SSRF guard: private and metadata addresses
// are refused on every redirect hop, and the byte cap holds while
// streaming.
res = await fetchSafePublicUrlPinned(
url,
{
signal: AbortSignal.timeout(METADATA_FETCH_TIMEOUT_MS),
headers: { accept: 'application/json' },
},
{ allowHttp: true, maxBytes: MAX_OFFCHAIN_JSON_BYTES },
);
} catch {
return null;
}
if (!res.ok) return null;
const len = Number(res.headers.get('content-length') || 0);
if (len && len > MAX_OFFCHAIN_JSON_BYTES) return null;
let text;
try {
text = await res.text();
} catch {
return null;
}
if (text.length > MAX_OFFCHAIN_JSON_BYTES) return null;
try {
return JSON.parse(text);
} catch {
return null;
}
}
/**
* Fetch the binary bytes of an off-chain image, validating size and MIME type.
* Returns { bytes, mimeType } on success or null on any failure (timeout,
* 4xx/5xx, oversize, unsupported MIME).
*/
export async function fetchTokenImage(imageUrl) {
const url = resolveOffchainUrl(imageUrl);
if (!url) return null;
let res;
try {
res = await fetchSafePublicUrlPinned(
url,
{
signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS),
headers: { accept: 'image/png, image/jpeg, image/webp, image/*' },
},
{ allowHttp: true, maxBytes: MAX_IMAGE_BYTES },
);
} catch {
return null;
}
if (!res.ok) return null;
const headerMime = (res.headers.get('content-type') || '').split(';')[0].trim().toLowerCase();
const len = Number(res.headers.get('content-length') || 0);
if (len && len > MAX_IMAGE_BYTES) return null;
const ab = await res.arrayBuffer();
if (ab.byteLength > MAX_IMAGE_BYTES) return null;
const bytes = new Uint8Array(ab);
// Sniff the first bytes — many CDNs return content-type: application/octet-stream
// for legitimate PNG/JPEG, and the embedding-into-glTF requires we declare a
// real MIME. PNG: 89 50 4E 47. JPEG: FF D8 FF. WebP: "RIFF" + "WEBP".
let sniffed = null;
if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
sniffed = 'image/png';
} else if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
sniffed = 'image/jpeg';
} else if (
bytes.length >= 12 &&
bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 &&
bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50
) {
sniffed = 'image/webp';
}
const mimeType = sniffed || (ALLOWED_IMAGE_MIME.has(headerMime) ? headerMime : null);
if (!mimeType) return null;
// glTF 2.0 only mandates PNG/JPEG support; WebP requires KHR_texture_webp.
// Skip WebP for now — keeps the GLB compatible with every viewer.
if (mimeType === 'image/webp') return null;
return { bytes, mimeType };
}
/**
* Read a Solana fungible token's full metadata profile.
*
* @param {string} mint Base58 SPL mint address.
* @param {object} [opts]
* @param {'mainnet'|'devnet'} [opts.network='mainnet']
* @param {boolean} [opts.includeImage=true] Fetch and return image bytes/mime.
*
* @returns {Promise<{
* mint: string,
* name: string|null,
* symbol: string|null,
* uri: string|null,
* description: string|null,
* imageUrl: string|null,
* image: { bytes: Uint8Array, mimeType: string } | null,
* externalUrl: string|null,
* raw: object|null,
* }>}
*
* `raw` is the parsed off-chain JSON document verbatim (null when the token has
* no `uri` or it could not be read). The named fields above cover what a token
* profile needs; a caller after anything else in the document (`animation_url`,
* `properties.files`, attributes) would otherwise have to fetch and parse the
* same document a second time.
*/
export async function fetchTokenMeta(mint, { network = 'mainnet', includeImage = true } = {}) {
const pk = solanaPubkey(mint);
if (!pk) {
const err = new Error('invalid mint address');
err.code = 'invalid_mint';
err.status = 400;
throw err;
}
const connection = getConnection({ network });
// The mint read is the one hard dependency: without it "not found" cannot be
// told apart from "RPC down", so an outage answers a typed retryable 503.
let accountInfo;
try {
accountInfo = await connection.getAccountInfo(pk);
} catch (err) {
if (isRpcOutageError(err)) throw rpcUnavailableError(`could not read the mint on ${network}: Solana RPC is temporarily unavailable`, err);
throw err;
}
if (!accountInfo) {
const err = new Error(`mint account not found on ${network}`);
err.code = 'mint_not_found';
err.status = 404;
throw err;
}
// An address can exist on-chain without being a token mint at all (a program,
// a PDA, a wallet). Reading metadata off one of those yields an untitled
// husk, so reject it here rather than charging a caller for a nameless
// result: only the two SPL token programs own real mints.
const owner = accountInfo.owner?.toBase58?.() || '';
if (owner !== TOKEN_PROGRAM_ID.toBase58() && owner !== TOKEN_2022_PROGRAM_ID.toBase58()) {
const err = new Error(`address is not an SPL token mint on ${network}`);
err.code = 'mint_not_found';
err.status = 404;
throw err;
}
const onchain = (await fetchToken2022Metadata(connection, pk, owner))
|| (await fetchOnchainMetadata(connection, pk));
const off = onchain?.uri ? await fetchOffchainJson(onchain.uri) : null;
const name = (off?.name || onchain?.name || '').toString().trim() || null;
const symbol = (off?.symbol || onchain?.symbol || '').toString().trim() || null;
const description = (off?.description || '').toString().trim() || null;
const imageUrl = (off?.image || '').toString().trim() || null;
const externalUrl =
(off?.external_url || off?.website || '').toString().trim() || null;
const image = imageUrl && includeImage ? await fetchTokenImage(imageUrl) : null;
return {
mint,
name,
symbol,
uri: onchain?.uri || null,
description,
imageUrl,
image,
externalUrl,
raw: off || null,
};
}