Skip to content

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.

12.7 KB
Raw Blame
// GET /api/x402/cosmetic-purchase?id=<cosmeticId>&account=<accountId>
//
// The avatar shop's checkout (R22). Buying a premium cosmetic settles a real
// USDC payment over x402 (Base or Solana) and, on a verified payment, records
// ownership of that cosmetic to the buyer's account in the durable ownership
// ledger (api/_lib/cosmetics-ownership.js). The shop (R21) and the owned
// inventory (R23) read that ledger back.
//
// Pricing is per rarity and SERVER-OWNED — the USDC amount comes from the
// catalog (api/_lib/cosmetics.js), never from the client, so a buyer can't move
// the price. The $THREE figure the shop quotes is the item's coin-facing value;
// USDC is only the settlement asset, exactly as every other /api/x402/* endpoint.
//
// "Buy once, owned forever": each (cosmetic, wallet) pair gets a permanent SIWX
// grant baked to the item id, so a wallet that already paid re-accesses for free
// by signing — and the handler re-grants ownership idempotently each time. The
// on-chain payment itself is single-use (the facilitator won't settle the same
// signed proof twice), and the ownership SET is idempotent, so the flow is safe
// against replay and can never double-grant.
//
// The SIWX grant is keyed on (resource, wallet) and the resource URL carries the
// cosmetic id, NOT the target account. So the free re-access path must re-check
// entitlement itself (siwxReGrantAllowed below): without that, one purchase
// would let the paying wallet sign the item onto an unlimited number of other
// accounts for free. Re-access re-confirms an unlock; it never sells a new one.

import { paidEndpoint } from '../_lib/x402-paid-endpoint.js';
import { buildBazaarSchema, paymentRequirements, send402 } from '../_lib/x402-spec.js';
import { X402Error } from '../_lib/x402-errors.js';
import { priceFor } from '../_lib/x402-prices.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import { error } from '../_lib/http.js';
import { env } from '../_lib/env.js';
import { getCosmetic, priceUsdcAtomicsOf } from '../_lib/cosmetics.js';
import { grantCosmeticOwnership, normalizeAccountId, ownsCosmetic } from '../_lib/cosmetics-ownership.js';
import { recordSaleAndSplit, isMint } from '../_lib/cosmetics-economy.js';
import cosmeticPurchaseListing from '../_lib/service-catalog/services/cosmetic-purchase.js';

const ROUTE = '/api/x402/cosmetic-purchase';

// Single source of truth:
// api/_lib/service-catalog/services/cosmetic-purchase.js is the storefront
// listing copy — importing it here keeps the live 402 challenge from drifting
// from what /.well-known/x402.json and the OKX projection advertise (same
// pattern as forge.js → forge-listing.js).
const DESCRIPTION = cosmeticPurchaseListing.description;

const INPUT_EXAMPLE = { id: 'skin-midnight', account: 'g_5f3c9a21b8' };

const INPUT_SCHEMA = {
	$schema: 'https://json-schema.org/draft/2020-12/schema',
	type: 'object',
	required: ['id', 'account'],
	properties: {
		id: {
			type: 'string',
			description: 'Premium cosmetic id from /api/cosmetics/catalog.',
			minLength: 1,
			maxLength: 64,
		},
		account: {
			type: 'string',
			description:
				'The account the cosmetic is granted to — a Solana wallet address or ' +
				'a guest id (g_…). Ownership is keyed here, not on the paying wallet.',
			minLength: 3,
			maxLength: 64,
		},
	},
};

const OUTPUT_EXAMPLE = {
	ok: true,
	id: 'skin-midnight',
	name: 'Midnight',
	slot: 'skin',
	rarity: 'legendary',
	account: 'g_5f3c9a21b8',
	owned: true,
	newlyOwned: true,
	payer: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
	network: 'solana',
	amountAtomics: '3000000',
	asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
};

const OUTPUT_SCHEMA = {
	$schema: 'https://json-schema.org/draft/2020-12/schema',
	type: 'object',
	required: ['ok', 'id', 'name', 'slot', 'rarity', 'account', 'owned'],
	properties: {
		ok: { type: 'boolean', const: true },
		id: { type: 'string' },
		name: { type: 'string' },
		slot: { type: 'string' },
		rarity: { type: 'string' },
		account: { type: 'string' },
		owned: { type: 'boolean', const: true },
		newlyOwned: { type: 'boolean' },
		payer: { type: ['string', 'null'] },
		network: { type: ['string', 'null'] },
		amountAtomics: { type: ['string', 'null'] },
		asset: { type: ['string', 'null'] },
		// Coin the sale was tied to (R25), and the creator split that paid out.
		coin: { type: ['string', 'null'] },
		split: {
			type: ['object', 'null'],
			properties: {
				creatorWallet: { type: ['string', 'null'] },
				creatorBps: { type: 'number' },
				creatorCutAtomics: { type: 'string' },
				payoutStatus: { type: 'string' },
				payoutTx: { type: ['string', 'null'] },
			},
		},
	},
};

const BAZAAR = {
	discoverable: true,
	info: {
		input: { type: 'http', method: 'GET', queryParams: INPUT_EXAMPLE },
		output: { type: 'json', example: OUTPUT_EXAMPLE },
	},
	schema: buildBazaarSchema({
		method: 'GET',
		queryParamsSchema: INPUT_SCHEMA,
		outputSchema: OUTPUT_SCHEMA,
	}),
};

// Discovery probes (x402scan registration, Bazaar validators) hit the bare
// route with placeholder or missing query params and expect a valid 402
// challenge, not a 400/404 — the x402 discovery spec treats runtime 402 behavior
// as the source of truth, so request validation must not reject the probe before
// the payment middleware runs. This advertises the endpoint at a representative
// default price (env-overridable via X402_PRICE_COSMETIC_PURCHASE) with the full
// bazaar schema. No money can settle against it: a paid retry still needs a real
// ?id= + ?account= (the paymentPresent branches below keep their 400/404), and
// an X-PAYMENT envelope is only an authorization — USDC moves at settle, which
// this path never reaches. Mirrors asset-download.js sendDiscoveryChallenge.
function sendDiscoveryChallenge(res, errText) {
	const resourceUrl = `${env.APP_ORIGIN}${ROUTE}`;
	return send402(res, {
		resourceUrl,
		accepts: paymentRequirements(resourceUrl, {
			amount: priceFor('cosmetic-purchase', '500000'),
		}),
		description: DESCRIPTION,
		bazaar: BAZAAR,
		error: errText,
		serviceName: 'three.ws Avatar Shop',
		tags: ['3d', 'avatar', 'cosmetic', 'shop', 'wearable'],
	});
}

// Who may be re-granted an item on the FREE SIWX re-access path (no payment in
// this request). Two cases are legitimate:
//   • the signing wallet is the target account, the buyer re-confirming their
//     own unlock from a new device or after a cache wipe;
//   • the target account already owns the item, a guest profile re-confirming
//     an unlock that was paid for earlier.
// Anything else is a fresh sale and must be paid for. Pure; exported for tests.
export function siwxReGrantAllowed({ account, payer, alreadyOwned }) {
	if (alreadyOwned) return true;
	return !!payer && normalizeAccountId(payer) === account;
}

// Per-item paidEndpoint built on the fly: the id picks the catalog row, which
// dictates the USDC price; everything else is shared. Mirrors asset-download.js,
// where the slug drives a per-row price + SIWX grant.
export default async function handler(req, res) {
	const paymentPresent = Boolean(req.headers['x-payment'] || req.headers['payment-signature']);

	const id = req.query?.id ? String(req.query.id).trim() : '';
	if (!id) {
		if (paymentPresent) {
			return error(res, 400, 'id_required', 'query parameter "id" is required');
		}
		return sendDiscoveryChallenge(
			res,
			'query parameter "id" is required — retry with ?id=<cosmeticId>&account=<accountId> from /api/cosmetics/catalog for that item’s exact price',
		);
	}

	const account = normalizeAccountId(req.query?.account);
	if (!account) {
		if (paymentPresent) {
			return error(res, 400, 'account_required',
				'query parameter "account" is required (a Solana wallet or guest id)');
		}
		return sendDiscoveryChallenge(
			res,
			'query parameter "account" is required (a Solana wallet or guest id) — retry with ?id=<cosmeticId>&account=<accountId>',
		);
	}

	// Coin-tied sale (R25): when bought inside a coin's /play world, the optional
	// `coin` mint ties the sale to that coin so a configurable share of the settled
	// USDC pays out to the coin's creator. Untied (no/invalid coin) → full platform
	// revenue, exactly as before.
	const coin = isMint(String(req.query?.coin || '').trim()) ? String(req.query.coin).trim() : null;

	const item = getCosmetic(id);
	if (!item) {
		if (paymentPresent) {
			return error(res, 404, 'cosmetic_not_found', `no cosmetic with id "${id}"`);
		}
		return sendDiscoveryChallenge(
			res,
			`no cosmetic with id "${id}" — browse /api/cosmetics/catalog for available premium ids`,
		);
	}
	if (!item.premium) {
		// Base-pack items ship owned with every avatar — there's nothing to sell.
		if (paymentPresent) {
			return error(res, 400, 'not_purchasable',
				`cosmetic "${id}" is part of the free base pack and is already owned`);
		}
		return sendDiscoveryChallenge(
			res,
			`cosmetic "${id}" is part of the free base pack and is already owned — pick a premium id from /api/cosmetics/catalog`,
		);
	}

	const priceAtomics = priceUsdcAtomicsOf(item);

	const inner = paidEndpoint({
		route: ROUTE,
		method: 'GET',
		priceAtomics,
		description: `${DESCRIPTION} — currently unlocking: ${item.name} (${item.rarity}).`,
		bazaar: BAZAAR,
		service: withService({
			serviceName: 'three.ws Avatar Shop',
			tags: ['3d', 'avatar', 'cosmetic', 'shop', 'wearable'],
		}),
		// Bake the item id into the resource URL so the SIWX grant is per-cosmetic:
		// without this, paying for one cosmetic would unlock every cosmetic via a
		// single signature (the SIWX row is keyed on (resource, wallet) only). The
		// 402 challenge advertises the same URL the client signs against.
		resourceUrlBuilder: () =>
			`${env.APP_ORIGIN}${ROUTE}?id=${encodeURIComponent(item.id)}`,
		siwx: {
			statement: `Sign in to confirm you own "${item.name}" without re-paying.`,
			// Permanent per (cosmetic, wallet) — once paid, re-confirm forever by signing.
			ttlSeconds: null,
			expirationSeconds: 300,
		},
		async handler({ requirement, payer, bypass }) {
			// Free SIWX re-access: nothing settled this call (no `requirement`) and
			// no authorized bypass granted it (a subscription or scoped caller keeps
			// its access). Only re-confirm an unlock the account is already entitled
			// to; a signature must never unlock the item for a THIRD account. 402,
			// not 403, so an x402 client falls straight through to paying for it.
			if (!requirement && !bypass) {
				const allowed = siwxReGrantAllowed({
					account,
					payer,
					alreadyOwned: await ownsCosmetic(account, item.id),
				});
				if (!allowed) {
					throw new X402Error(
						'account_not_entitled',
						`account "${account}" does not own "${item.name}". Signing in re-confirms an ` +
						'unlock you already paid for; pay the challenge to unlock it for this account',
						402,
					);
				}
			}

			// Record ownership BEFORE settlement returns to the buyer. grant throws
			// (503) if the durable store is missing — fail closed, so we never settle
			// a charge we can't record. Idempotent: a re-paid/replayed call just
			// re-confirms the existing unlock.
			const newlyOwned = await grantCosmeticOwnership(account, item.id);

			// Coin-tied creator split (R25). Only on a fresh, genuinely-settled
			// purchase: `requirement` is null on the SIWX free-re-access path, and
			// newlyOwned is false on a re-grant — either way we never re-record or
			// re-pay. The split records the sale and pays the creator's USDC cut
			// on-chain; it's best-effort and never throws, so a recording/payout
			// hiccup can't undo the unlock the buyer already paid for.
			let split = null;
			if (requirement && newlyOwned) {
				const result = await recordSaleAndSplit({
					account,
					cosmeticId: item.id,
					item,
					payerWallet: payer ?? null,
					payerNetwork: requirement?.network ?? null,
					asset: requirement?.asset ?? null,
					// The cut is a share of the item's USDC list price. requirement.amount
					// is in the PAID asset's atomics: a 10 $THREE accept is 10,000,000,
					// which the USDC payout read as $10 and paid half of to whoever
					// launched the coin, on every purchase with a fresh account.
					priceAtomics,
					mint: coin,
				});
				if (result?.creatorWallet) {
					split = {
						creatorWallet: result.creatorWallet,
						creatorBps: result.creatorBps,
						creatorCutAtomics: result.creatorCutAtomics,
						payoutStatus: result.payoutStatus,
						payoutTx: result.payoutTx ?? null,
					};
				}
			}

			return {
				ok: true,
				id: item.id,
				name: item.name,
				slot: item.slot,
				rarity: item.rarity,
				account,
				owned: true,
				newlyOwned,
				payer: payer ?? null,
				network: requirement?.network ?? null,
				amountAtomics: requirement?.amount ?? null,
				asset: requirement?.asset ?? null,
				coin: coin ?? null,
				split,
			};
		},
	});

	return inner(req, res);
}

export const BAZAAR_SCHEMA = BAZAAR;