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
// Guardrail: every paid /api/x402/* endpoint must appear in the
// /.well-known/x402-discovery catalog, or agents (and the CDP Bazaar /
// agentic.market crawlers) can never find it — an unlisted paid endpoint earns
// zero, no matter how good it is. The discovery doc in api/wk.js is
// hand-maintained, so it silently drifts every time a new paid route ships
// without a matching catalog entry. This test makes that drift a red build.
//
// "Paid" is detected structurally: a route file is paid if it wraps the shared
// paidEndpoint() helper OR emits a 402 challenge directly via send402(). Pure
// utility/infra routes (did, my-receipts, pay-by-name — a tx-builder, not a
// 402-gated resource) match neither and are correctly out of scope.
import { describe, it, expect } from 'vitest';
import { readFileSync, readdirSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
const here = dirname(fileURLToPath(import.meta.url));
const x402Dir = join(here, '..', '..', 'api', 'x402');
// Routes intentionally absent from the catalog, with the reason each is exempt.
// Keep this list short and justified — it is the only sanctioned escape hatch.
const EXCLUSIONS = new Map([
[
'/api/x402/permit2-paid-demo',
'CDP-only: its sole accept is a Permit2 sibling that permit2VariantOf() ' +
'returns null without CDP creds, so the live 402 (and thus the catalog) ' +
'omits the route entirely in non-CDP environments.',
],
[
'/api/x402/service',
'Dynamic dispatcher, not a single fixed-price route: it serves the paywall ' +
'for every agent-published listing at /api/x402/service/<slug>. Each ' +
'concrete listing is cataloged dynamically from agent_paid_services by ' +
"handleX402Discovery's buildAgentServiceItems(), not as a static entry.",
],
[
'/api/x402/agents',
'Dynamic dispatcher, not a single fixed-price route: it serves the paywall ' +
'for every agent its owner sells as an API at /api/x402/agents/<agentId>. ' +
'Each agent on sale is cataloged dynamically from agent meta.api_service by ' +
"handleX402Discovery's buildSellableAgentItems(), not as a static entry.",
],
[
'/api/x402/ring-settle',
'Internal closed-loop settlement primitive (discoverable:false in the ' +
'endpoint itself): platform-controlled ring wallets pay it to cycle the ' +
'agent economy. Deliberately NOT on the public bazaar/agentic.market ' +
'catalog — ring volume is dogfooding, not organic third-party demand, and ' +
'must not masquerade as such.',
],
[
'/api/x402/three-buy',
'Internal buy-pressure machinery (discoverable:false in the endpoint ' +
'itself, same stance as ring-settle): the micro-buy loop pays it to ' +
'fire small $THREE buys. Not an organic third-party service, so it is ' +
'deliberately absent from the public discovery catalog.',
],
// De-listed in the 2026-07 x402 overhaul (prompt 20): these routes stay live
// for their in-product consumers but are internal-use only — not agent
// products — so they no longer appear on x402scan/agentic.market. Each route
// file carries a matching "INTERNAL-USE ONLY" header.
[
'/api/x402/dance-tip',
'Internal: the /club stage and the /play town Saloon Kid NPC buy dancer ' +
'performances through it. Novelty tip-jar, not an agent product.',
],
[
'/api/x402/three-intel',
'Internal: the paid intel kiosk in the /play town buys from it. The ' +
'agent-facing market read is the free /api/crypto bundle.',
],
[
'/api/x402/tutor',
'Internal: the /tutor page and the /play Schoolmarm NPC buy through it. ' +
'Me-too LLM wrapper as an agent product; kept only for the in-product flows.',
],
[
'/api/x402/crypto-intel',
'Internal: the agent-exchange demo and the /play trading-desk NPC buy ' +
'through it. Agent-facing market intel is the free /api/crypto bundle.',
],
[
'/api/x402/pump-agent-audit',
'De-listed per the 2026-07-08 storefront cleanup (prompt 18): the paid ' +
'"oracle" framing over-claims what a payments-history audit is. The free ' +
'/api/crypto/whales surface replaces it as the agent product; the /play ' +
'town NPC still buys through this route.',
],
]);
// fact-check, mint-to-mesh, and mint-to-mesh-batch were re-listed per the
// 2026-07-08 storefront cleanup (prompt 18) — they now carry real
// service-catalog descriptors (api/_lib/service-catalog/services/) and are
// expected to appear in the discovery doc like any other paid product.
function paidRoutesFromFiles() {
const routes = [];
for (const name of readdirSync(x402Dir)) {
if (!name.endsWith('.js')) continue;
const src = readFileSync(join(x402Dir, name), 'utf8');
const isPaid = src.includes('paidEndpoint(') || src.includes('send402(');
if (!isPaid) continue;
routes.push(`/api/x402/${name.replace(/\.js$/, '')}`);
}
return routes.sort();
}
async function renderDiscovery() {
// Set the env the discovery builder reads BEFORE importing it, so both Base
// and Solana accepts are advertised and APP_ORIGIN resolves. No CDP creds →
// Permit2 siblings are omitted, matching production's non-CDP behavior.
Object.assign(process.env, {
APP_ORIGIN: 'https://three.ws',
X402_PAY_TO_BASE: '0x0000000000000000000000000000000000000001',
X402_PAY_TO_SOLANA: 'So11111111111111111111111111111111111111112',
X402_ASSET_ADDRESS_BASE: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
X402_ASSET_MINT_SOLANA: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
X402_ASSET_ADDRESS_ARBITRUM: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
X402_MAX_AMOUNT_REQUIRED: '1000',
X402_FEE_PAYER_SOLANA: 'So11111111111111111111111111111111111111112',
});
const mod = await import('../../api/wk.js');
const res = {
statusCode: 0,
headers: {},
setHeader(k, v) {
this.headers[k.toLowerCase()] = v;
},
end(body) {
this.body = body;
},
};
const req = {
method: 'GET',
url: '/.well-known/x402-discovery?name=x402-discovery',
query: { name: 'x402-discovery' },
headers: {},
};
await mod.default(req, res);
return JSON.parse(res.body);
}
describe('x402 discovery catalog parity', () => {
it('lists every paid /api/x402/* endpoint (no silent drift)', async () => {
const doc = await renderDiscovery();
const cataloged = new Set(doc.resources.map((r) => r.path));
const required = paidRoutesFromFiles().filter((r) => !EXCLUSIONS.has(r));
const missing = required.filter((r) => !cataloged.has(r));
expect(
missing,
`Paid x402 endpoints missing from /.well-known/x402-discovery: ${missing.join(
', ',
)}. Add a matching resources[] entry in api/wk.js handleX402Discovery, ` +
`or document an exemption in EXCLUSIONS with a reason.`,
).toEqual([]);
});
it('only exempts routes that still exist as paid endpoints', async () => {
// Stops EXCLUSIONS from rotting: an exemption for a deleted/renamed route
// would otherwise hide a real gap forever.
const paid = new Set(paidRoutesFromFiles());
const stale = [...EXCLUSIONS.keys()].filter((r) => !paid.has(r));
expect(
stale,
`Stale EXCLUSIONS entries (route no longer paid): ${stale.join(', ')}`,
).toEqual([]);
});
it('catalogs both hosted MCP servers with their own identities', async () => {
// The 3D Studio (text→3D) lived for months as a deployed-but-uncataloged
// endpoint — x402 facilitators could never index it. Keep both MCP
// transports in the discovery doc, each under its own service identity.
const doc = await renderDiscovery();
const mcp = doc.resources.find((r) => r.path === '/api/mcp');
const studio = doc.resources.find((r) => r.path === '/api/mcp-3d');
expect(mcp, '/api/mcp missing from discovery').toBeTruthy();
expect(studio, '/api/mcp-3d missing from discovery').toBeTruthy();
expect(studio.serviceName).toBe('three.ws 3D Studio MCP');
expect(studio.description).toContain('text_to_3d');
expect(studio.extensions.bazaar.info.input.body.params.name).toBe('text_to_3d');
expect(studio.accepts.length).toBeGreaterThan(0);
});
it('every cataloged x402 resource carries a price and at least one accept', async () => {
const doc = await renderDiscovery();
const x402Resources = doc.resources.filter((r) => r.path?.startsWith('/api/x402/'));
expect(x402Resources.length).toBeGreaterThan(0);
for (const r of x402Resources) {
expect(
Array.isArray(r.accepts) && r.accepts.length > 0,
`${r.path} has no accepts`,
).toBe(true);
for (const a of r.accepts) {
expect(
typeof a.amount === 'string' && a.amount.length > 0,
`${r.path} accept amount`,
).toBe(true);
expect(Boolean(a.payTo), `${r.path} accept payTo`).toBe(true);
}
}
});
it('server profile leads with the real positioning (prompt 22)', async () => {
// The x402scan storefront window: the top-level profile must pitch the
// actual product mix, carry filterable categories, and never regress to
// the old "3D model viewer" blurb that undersold the platform.
const doc = await renderDiscovery();
const svc = doc.service;
expect(svc.tagline).toContain('3D generation + crypto data');
expect(svc.description).toContain('Free Crypto Data API');
expect(svc.description).toContain('Forge Pro');
expect(svc.categories).toEqual(['3D', 'AI', 'Crypto', 'Data', 'Utility']);
expect(svc.tags).toContain('text-to-3d');
expect(svc.tags).toContain('crypto-data');
});
it('no resource ships an empty or placeholder description', async () => {
// A blank card on x402scan reads as abandonware. Every cataloged resource
// must carry a substantive description (the profile overhaul bar: leads
// with the use-case and states the price).
const doc = await renderDiscovery();
for (const r of doc.resources) {
const d = String(r.description || '');
expect(d.length, `${r.path} description too short: "${d}"`).toBeGreaterThanOrEqual(60);
expect(d).not.toMatch(/TODO|placeholder|tbd/i);
}
});
it('every cataloged resource is tagged for category filtering', async () => {
const doc = await renderDiscovery();
for (const r of doc.resources) {
expect(
Array.isArray(r.tags) && r.tags.length >= 2,
`${r.path} needs at least two tags for storefront filters`,
).toBe(true);
}
});
});