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.

4.9 KB
Raw Blame
// `vanity_premium` — FREE MCP tool: browse the premium vanity-address INVENTORY
// (long 4–5+ char brandable addresses ground ahead of time on batch CPU) and get
// difficulty-scaled prices + a ready-to-pay purchase link.
//
// This is the discovery half of the sell-from-stock tier. It is intentionally
// FREE and read-only: it lists what's in stock and each item's price, then hands
// back an x402 buy URL (/api/x402/vanity-premium?address=…) that the caller (or a
// pay-capable agent) settles to receive the key ONCE. The existing paid
// `vanity_grinder` tool — which grinds a fresh ≤3-char keypair per call — is
// untouched and remains the live-grind tier.
//
// CUSTODY HONESTY: every response carries the same disclosure the endpoint and UI
// show — these keys are platform-generated; use as a token mint or sweep to
// self-generated custody, not as a treasury.

import { z } from 'zod';

import { free } from '../payments.js';
import { jsonSchemaFromZod } from './_shared.js';

const TOOL_NAME = 'vanity_premium';

const APP_ORIGIN = (process.env.APP_ORIGIN || 'https://three.ws').replace(/\/$/, '');

const CUSTODY_NOTICE =
	'These keys were generated by three.ws, not by you. For high-value use, treat a purchased address ' +
	'as a token MINT or sweep assets to a self-generated wallet — do not use it as a treasury. The key ' +
	'is delivered once and its ciphertext is destroyed on delivery.';

const TOOL_DESCRIPTION =
	'Browse the three.ws PREMIUM vanity-address inventory — long (4–5+ character) brandable Solana ' +
	'addresses ground ahead of time on batch CPU and sold from stock, which the live grinder cannot reach. ' +
	'FREE and read-only: returns the available patterns, each address, its rarity tier, and a difficulty-' +
	'scaled price ($1–$50), plus a ready-to-pay x402 buyUrl. Pay that URL (USDC on Base or Solana) to ' +
	'receive the private key exactly once; the ciphertext is destroyed on delivery (delete-after-reveal). ' +
	'Filter by prefix or rarity tier and sort by rarity/price/newest. Use this to browse long brandable addresses ' +
	'already in stock; for a fresh grind of up to 3 characters, use the vanity_grinder tool instead. CUSTODY: keys are platform-generated, so use them as a token ' +
	'mint or sweep to self-generated custody, not a treasury. Free — no payment required to browse.';

const inputZodShape = {
	prefix: z.string().max(8).describe('Filter to addresses whose prefix starts with these Base58 chars.').optional(),
	tier: z
		.enum(['common', 'uncommon', 'rare', 'epic', 'legendary', 'mythic'])
		.describe('Filter to a rarity tier.')
		.optional(),
	sort: z.enum(['rarity', 'price', 'new']).describe('Order results — rarity (default), price (cheapest first), or new.').optional(),
	limit: z.number().int().min(1).max(100).describe('Max results (default 40).').optional(),
};

const inputJsonSchema = jsonSchemaFromZod(inputZodShape);

async function runVanityPremium({ prefix, tier, sort = 'rarity', limit = 40 } = {}) {
	// Lazy-import the store so tool enumeration never needs a DB connection.
	let store;
	try {
		store = await import('../../../api/_lib/vanity-inventory-store.js');
	} catch (err) {
		return degraded(`inventory store unavailable (${err.message})`);
	}
	try {
		const [items, stats] = await Promise.all([
			store.listAvailable({ prefix, tier, sort, limit }),
			store.inventoryStats(),
		]);
		return {
			custodyNotice: CUSTODY_NOTICE,
			stats,
			priceRange: { minUsd: stats.minPrice, maxUsd: stats.maxPrice },
			count: items.length,
			items: items.map((it) => ({
				address: it.address,
				pattern: it.patternLabel,
				rarityTier: it.rarityTier,
				rarityScore: it.rarityScore,
				priceUsd: it.priceUsd,
				buyUrl: `${APP_ORIGIN}/api/x402/vanity-premium?address=${encodeURIComponent(it.address)}`,
				explorerUrl: `https://solscan.io/account/${it.address}`,
			})),
			browseUrl: `${APP_ORIGIN}/vanity/premium`,
			howToBuy: 'Pay the item buyUrl with x402 (USDC on Base or Solana). The key is delivered once; add &sealTo=<X25519 pubkey> to receive it sealed.',
		};
	} catch (err) {
		return degraded(`could not read inventory (${err.message})`);
	}
}

// Degrade gracefully: still hand back the browse + purchase surface so the caller
// isn't dead-ended when the store read fails.
function degraded(reason) {
	return {
		custodyNotice: CUSTODY_NOTICE,
		count: 0,
		items: [],
		note: `${reason}. Browse and buy directly at the listing endpoint.`,
		browseUrl: `${APP_ORIGIN}/vanity/premium`,
		listingApi: `${APP_ORIGIN}/api/x402/vanity-premium`,
	};
}

export function buildVanityPremiumTool() {
	const handler = free({ toolName: TOOL_NAME, inputSchema: inputJsonSchema }, (args) => runVanityPremium(args));
	return {
		name: TOOL_NAME,
		title: 'Premium vanity inventory (browse)',
		description: TOOL_DESCRIPTION,
		inputSchema: inputZodShape,
		annotations: {
			readOnlyHint: true,
			destructiveHint: false,
			idempotentHint: false,
			openWorldHint: true,
		},
		handler,
	};
}