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
// Connection, key handling, balances, token metadata, and explorer links.
import bs58 from 'bs58';
import { Connection, Keypair, PublicKey, LAMPORTS_PER_SOL } from '@solana/web3.js';
import {
getMint,
getAccount,
getAssociatedTokenAddressSync,
TokenAccountNotFoundError,
TokenInvalidAccountOwnerError,
TokenInvalidAccountSizeError,
TOKEN_PROGRAM_ID,
TOKEN_2022_PROGRAM_ID,
} from '@solana/spl-token';
import { NETWORK, rpcFor } from '../config.js';
export { LAMPORTS_PER_SOL, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID };
// Circle's canonical USDC mints. The default asset for agent spending because
// x402 prices in it and it is the deepest stable on Solana.
export const USDC_MINT = {
mainnet: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
devnet: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
};
// A signature costs 5000 lamports. An agent pays its own fees, so it needs a
// little SOL of its own; this is the floor below which it cannot transact.
export const MIN_AGENT_FEE_LAMPORTS = 5_000 * 20;
const connections = new Map();
/** Cached Connection per network. Confirmed commitment: fast, and final enough to gate a spend. */
export function connectionFor(network = NETWORK) {
const net = network === 'devnet' ? 'devnet' : 'mainnet';
if (!connections.has(net)) {
connections.set(net, new Connection(rpcFor(net), { commitment: 'confirmed' }));
}
return connections.get(net);
}
/** Parse a base58 secret key or a JSON byte array into a Keypair. */
export function keypairFrom(secret, label = 'secret') {
const raw = String(secret || '').trim();
if (!raw) {
throw Object.assign(new Error(`No ${label} available. Pass one, or set OWNER_SECRET_KEY.`), { code: 'no_signer' });
}
let bytes;
if (raw.startsWith('[')) {
try {
bytes = Uint8Array.from(JSON.parse(raw));
} catch {
throw Object.assign(new Error(`${label} looks like a JSON array but does not parse`), { code: 'bad_secret' });
}
} else {
try {
bytes = bs58.decode(raw);
} catch {
throw Object.assign(new Error(`${label} is not valid base58`), { code: 'bad_secret' });
}
}
if (bytes.length !== 64) {
throw Object.assign(new Error(`${label} must be a 64-byte keypair (got ${bytes.length} bytes)`), {
code: 'bad_secret',
});
}
return Keypair.fromSecretKey(bytes);
}
/** Validate and normalize an address, with a field name that survives into the error. */
export function toPublicKey(value, field = 'address') {
try {
return new PublicKey(String(value).trim());
} catch {
throw Object.assign(new Error(`${field} is not a valid Solana address: "${value}"`), { code: 'bad_address' });
}
}
/** SOL balance of an address, in SOL. */
export async function solBalance(connection, address) {
const lamports = await connection.getBalance(toPublicKey(address, 'address'));
return lamports / LAMPORTS_PER_SOL;
}
/**
* Which token program owns this mint: classic SPL Token or Token-2022. Every
* instruction we build is threaded with it, so a Token-2022 mint works without
* a special case anywhere else.
*/
const programCache = new Map();
export async function tokenProgramFor(connection, mint) {
const key = `${connection.rpcEndpoint}:${mint}`;
if (programCache.has(key)) return programCache.get(key);
const info = await connection.getAccountInfo(toPublicKey(mint, 'mint'));
if (!info) {
throw Object.assign(new Error(`mint ${mint} does not exist on this cluster`), { code: 'unknown_mint' });
}
const owner = info.owner;
if (!owner.equals(TOKEN_PROGRAM_ID) && !owner.equals(TOKEN_2022_PROGRAM_ID)) {
throw Object.assign(new Error(`${mint} is not an SPL token mint (owned by ${owner.toBase58()})`), {
code: 'unknown_mint',
});
}
programCache.set(key, owner);
return owner;
}
/** Decimals for a mint, read from the chain. Cached: a mint's decimals never change. */
const decimalsCache = new Map();
export async function mintDecimals(connection, mint, programId) {
const key = `${connection.rpcEndpoint}:${mint}`;
if (decimalsCache.has(key)) return decimalsCache.get(key);
const program = programId || (await tokenProgramFor(connection, mint));
const info = await getMint(connection, toPublicKey(mint, 'mint'), undefined, program);
decimalsCache.set(key, info.decimals);
return info.decimals;
}
/** Human amount to base units, without float drift. */
export function toBaseUnits(amount, decimals) {
const s = String(amount).trim();
if (!/^\d*(\.\d*)?$/.test(s) || s === '' || s === '.') {
throw Object.assign(new Error(`amount must be a positive decimal number (got "${amount}")`), {
code: 'bad_amount',
});
}
const [whole, frac = ''] = s.split('.');
if (frac.length > decimals) {
throw Object.assign(
new Error(`amount has ${frac.length} decimal places but the mint only has ${decimals}`),
{ code: 'bad_amount' },
);
}
return BigInt(whole || '0') * 10n ** BigInt(decimals) + BigInt(frac.padEnd(decimals, '0') || '0');
}
/** Base units back to a human decimal string, exact. */
export function fromBaseUnits(units, decimals) {
const n = BigInt(units);
const d = 10n ** BigInt(decimals);
const whole = n / d;
const frac = (n % d).toString().padStart(decimals, '0').replace(/0+$/, '');
return frac ? `${whole}.${frac}` : String(whole);
}
/**
* Token account state, or null when the account does not exist yet.
*
* spl-token signals a missing account by throwing a typed error whose message
* is empty, so this matches on the error class rather than its text.
*/
export async function tokenAccount(connection, address, programId = TOKEN_PROGRAM_ID) {
try {
return await getAccount(connection, toPublicKey(address, 'token account'), undefined, programId);
} catch (err) {
const missing =
err instanceof TokenAccountNotFoundError ||
err instanceof TokenInvalidAccountOwnerError ||
err instanceof TokenInvalidAccountSizeError ||
/could not find account|TokenAccountNotFound|TokenInvalidAccountOwner/i.test(err?.name || err?.message || '');
if (missing) return null;
throw err;
}
}
/** The owner's associated token account for a mint. allowOwnerOffCurve: PDAs can hold tokens too. */
export function ataFor(mint, owner, programId = TOKEN_PROGRAM_ID) {
return getAssociatedTokenAddressSync(toPublicKey(mint, 'mint'), toPublicKey(owner, 'owner'), true, programId);
}
const cluster = (network) => (network === 'devnet' ? '?cluster=devnet' : '');
export function txLink(signature, network = NETWORK) {
return `https://solscan.io/tx/${signature}${cluster(network)}`;
}
export function accountLink(address, network = NETWORK) {
return `https://solscan.io/account/${address}${cluster(network)}`;
}