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
// Cosmetics purchase rail (R22) — turn a "Buy" into a REAL USDC payment.
//
// The shop (R21) handles browsing + live preview; this module handles money.
// purchaseCosmetic() runs the x402 flow against /api/x402/cosmetic-purchase:
// window.X402.pay opens the wallet, settles the USDC on Base or Solana, and the
// endpoint records ownership of the cosmetic to the player's account in the
// durable ledger (api/_lib/cosmetics-ownership.js). It resolves only after the
// server confirms ownership — there is no optimistic unlock — and rejects with a
// wallet-accurate Error (including insufficient funds) on failure. The rail is
// idempotent (single-use on-chain proof + idempotent ownership grant), so a
// retried buy never double-charges.
//
// Ownership is keyed on the player's stable account id: their verified wallet
// when signed in, otherwise the same persisted guest id the /play economy uses
// (`cc-pid`), so a guest purchase survives a refresh on this device.
//
// $THREE is the coin the shop quotes value in; USDC is only the settlement asset
// the rail charges — never surfaced as a coin to hold.
import { loadStoredPass } from './play-auth.js';
import { ensureX402 } from '../shared/x402-loader.js';
const PURCHASE_ENDPOINT = '/api/x402/cosmetic-purchase';
const OWNED_ENDPOINT = '/api/cosmetics/owned';
// Resolve the account a purchase is attached to. Prefers an explicit verified
// wallet (the id the room already carries), then a cached play pass, then the
// persisted guest id. Returns '' only if storage is entirely unavailable.
export function resolveShopAccount(explicitWallet) {
if (explicitWallet) return explicitWallet;
try {
const pass = loadStoredPass();
if (pass?.wallet) return pass.wallet;
} catch { /* fall through to guest id */ }
try {
let id = localStorage.getItem('cc-pid');
if (!id) { id = 'guest-' + Math.random().toString(36).slice(2, 12); localStorage.setItem('cc-pid', id); }
return id;
} catch {
return '';
}
}
// The coin world the player is currently in, from the /play deep link
// (?coin=<mint> survives navigation). '' outside a coin world.
function currentWorldMint() {
try {
return new URLSearchParams(window.location.search).get('coin') || '';
} catch {
return '';
}
}
// Run the x402 USDC payment for one cosmetic. Resolves with the settled ticket
// ({ ok, owned, newlyOwned, payer, network, … }); rejects with an Error on
// failure or { code:'cancelled' } when the buyer dismisses the wallet.
export async function purchaseCosmetic(item, { account, coin } = {}) {
if (!item?.id) throw new Error('Pick a cosmetic to buy.');
const acct = account || resolveShopAccount();
if (!acct) throw new Error('No account to attach this purchase to.');
// First-timers get the wallet/USDC explainer before the payment modal; returning
// buyers pass straight through. Lazy-loaded so the shop only pays for it on the
// first buy. A cancel here aborts the purchase; a load failure is non-fatal.
try {
const { ensureOnchainPrimer } = await import('../shared/onchain-primer.js');
if (!(await ensureOnchainPrimer({ action: 'buy' }))) {
const err = new Error('cancelled'); err.code = 'cancelled'; throw err;
}
} catch (err) {
if (err?.code === 'cancelled') throw err;
// primer unavailable — proceed to the payment modal anyway.
}
// When bought inside a coin's /play world, tie the sale to that coin (R25) so a
// configurable share of the settled USDC pays out to the coin's creator. The
// server resolves the creator + share from the mint — the client only declares
// which world the purchase happened in; it never sets where the money goes.
// Falls back to the world in the URL (the /play deep link keeps ?coin=<mint>),
// so the tie holds even when the caller doesn't pass an explicit mint.
const coinMint = coin || currentWorldMint();
const coinParam = coinMint && /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(coinMint)
? `&coin=${encodeURIComponent(coinMint)}` : '';
const url = `${PURCHASE_ENDPOINT}?id=${encodeURIComponent(item.id)}&account=${encodeURIComponent(acct)}${coinParam}`;
// The /play world page doesn't ship the payment widget in its HTML — load it
// on demand here (cached after the first buy), same as every other in-world
// paid surface (NPC services, intel kiosk).
const X402 = await ensureX402();
const out = await X402.pay({
endpoint: url,
method: 'GET',
merchant: 'three.ws Avatar Shop',
action: `Unlock ${item.name} — $${item.priceUsdc} USDC`,
});
// SIWX re-access (a wallet that already paid) returns the settled body too;
// either way the server is the source of truth for `owned`.
const ticket = out?.result;
if (!ticket?.ok || !ticket?.owned) {
throw new Error(ticket?.error || 'purchase did not settle');
}
return ticket;
}
// The premium cosmetic ids an account owns, from the ledger. Degrades to [] on
// any error so a caller (shop owned-state, R23 inventory) still renders.
export async function fetchOwnedCosmetics(account) {
const acct = account || resolveShopAccount();
if (!acct) return [];
try {
const res = await fetch(`${OWNED_ENDPOINT}?account=${encodeURIComponent(acct)}`, {
headers: { accept: 'application/json' },
});
if (!res.ok) return [];
const body = await res.json();
return Array.isArray(body?.ownedIds) ? body.ownedIds : [];
} catch {
return [];
}
}