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.

79.0 KB
Raw Blame
// Consolidated /.well-known/* handler.
// Dispatches on ?name= query param set by vercel.json rewrites.

import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { cors, json, method, wrap, error } from './_lib/http.js';
import { env } from './_lib/env.js';
import { REGISTERABLE_SCOPES, SUPPORTED_SCOPES } from './_lib/oauth-scopes.js';
import { hostedMcpPath, mcpResourceFor } from './_lib/mcp-resources.js';
import {
	paymentRequirements,
	bazaarExtension,
	build402Body,
	declareEip2612GasSponsoringExtension,
	declareErc20ApprovalGasSponsoringExtension,
	permit2VariantOf,
	baseSettleable,
	solanaSettleable,
	NETWORK_BASE_MAINNET,
	NETWORK_SOLANA_MAINNET,
} from './_lib/x402-spec.js';
import {
	declareHttpDiscovery,
	declareMcpDiscovery,
	withService,
} from './_lib/x402/bazaar-helpers.js';
import { TOOL_CATALOG } from './_mcp/catalog.js';
import { STUDIO_CHALLENGE } from './_mcp3d/discovery.js';
import { TOOL_CATALOG as STUDIO_TOOL_CATALOG } from './_mcp3d/catalog.js';
import { priceFor as studioPriceFor } from './_mcp3d/pricing.js';
import { priceFor } from './_lib/pump-pricing.js';
import { priceFor as datapointPriceFor } from './_lib/x402-prices.js';
import {
	DATAPOINT_FAMILIES,
	DATAPOINT_DEFAULT_ATOMICS,
	datapointDescription,
	allChains,
	allStablecoins,
	allCategories,
	allDexes,
	allFees,
	allDerivativeExchanges,
} from './_lib/market-data/datapoints.js';
import { fetchMarketsTable } from './_lib/market-fallbacks.js';
import { buildProtocols } from './defi/protocols.js';
import { loadYieldPools } from './defi/yields.js';
import { buildExchanges } from './coin/exchanges.js';
import { FORGE_OUTPUT_EXAMPLE } from './_lib/forge-listing.js';
import { listBazaarServices, serviceResourceUrl } from './_lib/agent-paid-services.js';
import { listActiveAgentServices, CALL_INPUT_EXAMPLE, CALL_INPUT_SCHEMA, CALL_OUTPUT_EXAMPLE, serviceNameFor } from './_lib/agent-api-service.js';
import { buildRequirements } from './_lib/x402-paid-endpoint.js';
import { toBazaarDiscovery } from './_lib/service-catalog/index.js';

// ── agent-attestation-schemas ─────────────────────────────────────────────────

const COMMON = {
	v: { type: 'integer', const: 1 },
	kind: { type: 'string' },
	agent: { type: 'string', description: 'Metaplex Core asset pubkey (base58)' },
	ts: { type: 'integer', description: 'Unix seconds when attestation was created' },
};

const SCHEMAS = {
	'threews.feedback.v1': {
		description: 'Client → agent feedback.',
		required: ['v', 'kind', 'agent', 'score'],
		properties: {
			...COMMON,
			score: { type: 'integer', minimum: 1, maximum: 5 },
			task_id: { type: 'string' },
			uri: { type: 'string', format: 'uri' },
		},
	},
	'threews.validation.v1': {
		description:
			'Validator attestation. Two forms: a task validation (task_hash) or a ' +
			'glTF/GLB schema validation of the agent model (subkind "glb-schema", ' +
			'carrying proof_hash + proof_uri) — the Solana analog of the EVM ' +
			'ValidationRegistry validationResponse.',
		required: ['v', 'kind', 'agent', 'passed'],
		properties: {
			...COMMON,
			passed: { type: 'boolean' },
			subkind: { type: 'string', enum: ['glb-schema'], description: 'Present for model (glTF/GLB schema) validations.' },
			task_hash: { type: 'string', description: 'Task validation form: sha256 of the validated task.' },
			proof_hash: { type: 'string', description: 'Model form: sha256 of the canonical validation report JSON.' },
			proof_uri: { type: 'string', description: 'Model form: URL to the full pinned validation report.' },
			model_sha256: { type: 'string', description: 'Model form: sha256 of the GLB bytes.' },
			source: { type: 'string' },
			uri: { type: 'string', format: 'uri' },
		},
	},
	'threews.task.v1': {
		description: 'Client posts a task offer to an agent.',
		required: ['v', 'kind', 'agent', 'task_id', 'scope_hash'],
		properties: {
			...COMMON,
			task_id: { type: 'string' },
			scope_hash: { type: 'string' },
			uri: { type: 'string', format: 'uri' },
		},
	},
	'threews.accept.v1': {
		description: 'Agent accepts a task.',
		required: ['v', 'kind', 'agent', 'task_id'],
		properties: { ...COMMON, task_id: { type: 'string' } },
	},
	'threews.revoke.v1': {
		description: 'Revoke a previous attestation.',
		required: ['v', 'kind', 'agent', 'target_signature'],
		properties: { ...COMMON, target_signature: { type: 'string' }, reason: { type: 'string' } },
	},
	'threews.dispute.v1': {
		description: 'Agent owner disputes a feedback or validation.',
		required: ['v', 'kind', 'agent', 'target_signature'],
		properties: {
			...COMMON,
			target_signature: { type: 'string' },
			reason: { type: 'string' },
			uri: { type: 'string', format: 'uri' },
		},
	},
};

function handleAttestationSchemas(req, res) {
	return json(
		res,
		200,
		{
			version: 1,
			transport: {
				type: 'spl-memo',
				program: 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr',
				note: 'Each attestation is a signed memo tx with the agent asset pubkey as a non-signer key.',
			},
			schemas: SCHEMAS,
			discovery: {
				list_endpoint: '/api/agents/solana-attestations?asset=<pubkey>&kind=...',
				reputation_endpoint: '/api/agents/solana-reputation?asset=<pubkey>',
				validation_endpoint: '/api/agents/solana-validation?asset=<pubkey>',
			},
		},
		{ 'cache-control': 'public, max-age=300' },
	);
}

// ── oauth-authorization-server ────────────────────────────────────────────────

function handleOauthAuthServer(req, res) {
	const base = env.APP_ORIGIN;
	return json(
		res,
		200,
		{
			issuer: base,
			authorization_endpoint: `${base}/oauth/authorize`,
			token_endpoint: `${base}/api/oauth/token`,
			registration_endpoint: `${base}/api/oauth/register`,
			revocation_endpoint: `${base}/api/oauth/revoke`,
			introspection_endpoint: `${base}/api/oauth/introspect`,
			response_types_supported: ['code'],
			grant_types_supported: ['authorization_code', 'refresh_token'],
			code_challenge_methods_supported: ['S256'],
			token_endpoint_auth_methods_supported: [
				'none',
				'client_secret_basic',
				'client_secret_post',
			],
			// Everything this AS can issue: the self-registerable scopes plus the
			// USE-21 auth-hints scopes paid endpoints accept for Bearer bypass.
			scopes_supported: [...SUPPORTED_SCOPES],
			service_documentation: `${base}/docs/mcp`,
			ui_locales_supported: ['en'],
		},
		{ 'cache-control': 'public, max-age=300' },
	);
}

// ── oauth-protected-resource ──────────────────────────────────────────────────

// The root document describes the platform resource (/api/mcp). RFC 9728 §3.1
// path insertion (/.well-known/oauth-protected-resource/api/mcp-3d, routed here
// with ?path=) describes one hosted MCP server, whose `resource` must be that
// server's own URL: an MCP client refuses to sign in when the metadata names a
// resource that does not cover the URL it connected to.
function handleOauthProtectedResource(req, res) {
	const requestedPath = req.query?.path ?? new URL(req.url, 'http://x').searchParams.get('path');
	if (requestedPath && !hostedMcpPath(requestedPath)) {
		return error(res, 404, 'not_found', `no protected resource at ${String(requestedPath).slice(0, 64)}`);
	}
	const resource = requestedPath ? mcpResourceFor(requestedPath) : env.MCP_RESOURCE;
	return json(
		res,
		200,
		{
			resource,
			authorization_servers: [env.APP_ORIGIN],
			bearer_methods_supported: ['header'],
			resource_documentation: `${env.APP_ORIGIN}/docs/mcp`,
			// Exactly what /api/oauth/register will keep for a self-registering
			// client. A discovery-driven MCP client reads its scope list from
			// here, so a scope missing from this array is a scope it never asks
			// for: publishing fewer than the endpoint grants left the whole
			// agent-wallet server (wallet:read / wallet:write / services:write)
			// unreachable through the documented flow.
			scopes_supported: [...REGISTERABLE_SCOPES],
		},
		{ 'cache-control': 'public, max-age=300' },
	);
}

// ── x402 ─────────────────────────────────────────────────────────────────────

function handleX402(req, res) {
	const mcpResource = `${env.APP_ORIGIN}/api/mcp`;
	const mcpService = withService({
		serviceName: 'three.ws MCP',
		tags: ['mcp', '3d', 'gltf', 'solana', 'agent'],
	});
	const body = build402Body({
		resourceUrl: mcpResource,
		accepts: paymentRequirements(mcpResource),
		serviceName: mcpService.serviceName,
		tags: mcpService.tags,
		iconUrl: mcpService.iconUrl,
	});
	return json(
		res,
		200,
		{
			...body,
			schemes: ['pump-agent-payments', 'x402', 'x402-v2'],
			pump_agent_payments: {
				prep: '/api/pump/accept-payment-prep',
				confirm: '/api/pump/accept-payment-confirm',
				balances: '/api/pump/balances',
			},
		},
		{ 'cache-control': 'public, max-age=300' },
	);
}

// ── x402 Bazaar discovery (/.well-known/x402.json) ───────────────────────────
// Crawled by agentic.market / Bazaar to index our paid endpoints.
// Schema: https://x402.org/schemas/discovery.json

const RAW_AMOUNT_TO_USDC = (raw) => {
	const n = Number(raw || 0) / 1_000_000;
	const decimals = n < 0.01 ? 4 : 2;
	const s = n.toFixed(decimals);
	const trimmed = s.includes('.') ? s.replace(/0+$/, '').replace(/\.$/, '') : s;
	return `$${trimmed}`;
};

// Build the per-endpoint `accepts` block for a given USDC atomics price.
// Each new /api/x402/* endpoint has its own price set in its handler via
// paidEndpoint(priceAtomics); the discovery doc has to mirror that or
// agentic.market shows the wrong price to potential buyers.
// Push an EVM accept entry followed by its Permit2 sibling so the Bazaar
// discovery doc mirrors the live 402 response exactly (EIP-3009 first,
// Permit2 second). Non-EVM entries get no sibling.
function pushAcceptWithPermit2Sibling(out, accept) {
	out.push(accept);
	const sibling = permit2VariantOf(accept);
	if (sibling) out.push(sibling);
}

// Per-resource extensions for the discovery catalog. The bazaar entry is
// always present; the two gasless-Permit2-onboarding extensions are added
// whenever any accept in the list opts into the Permit2 transfer method.
// EIP-2612 covers tokens that implement `permit()` (USDC, DAI, ...); the
// ERC-20 approval variant covers tokens that don't. Both let the facilitator
// sponsor the approve() so the payer never broadcasts the approval tx.
// Normalize the second arg into a spec-shaped v2 bazaar extension
// ({discoverable, info, schema}). Catalog entries historically passed a raw
// {method, discoverable, input, inputSchema} descriptor straight through,
// which facilitator validators reject as a malformed discovery extension —
// every REST row was silently uncatalogable while the MCP rows (already
// spec-shaped) validated fine. Already-proper extensions (bazaarExtension(),
// declareMcpDiscovery(), STUDIO_CHALLENGE.bazaar) pass through untouched.
function extensionsForAccepts(accepts, bazaar) {
	const normalized =
		bazaar && bazaar.info && bazaar.schema
			? bazaar
			: declareHttpDiscovery({
					method: bazaar?.method || 'GET',
					input: bazaar?.input,
					inputSchema: bazaar?.inputSchema,
					// Catalog descriptors that carry their own output example declare it
					// here; older entries get theirs backfilled by addOutputExample.
					output: bazaar?.output,
				});
	const exts = { bazaar: normalized };
	if (accepts.some((a) => a?.extra?.assetTransferMethod === 'permit2')) {
		Object.assign(
			exts,
			declareEip2612GasSponsoringExtension(),
			declareErc20ApprovalGasSponsoringExtension(),
		);
	}
	return exts;
}

// Build the accepts[] block for a discovery-catalog entry. `resourceUrl` is
// echoed on every accept so reviewers + wallet/facilitator spend logs can
// reconcile each accept entry against the resource it gates, without having
// to walk back to the parent resource[] entry.
function acceptsForPrice(amountAtomics, resourceUrl) {
	const out = [];
	const price = RAW_AMOUNT_TO_USDC(amountAtomics);
	// Solana-first platform default — the Solana accept leads so first-accept
	// clients and marketplaces treat it as the primary rail; Base follows.
	// Solana only when settlement is fulfillable — solanaSettleable() confirms the
	// self-facilitator can co-sign (its X402_FEE_PAYER_SECRET_BASE58 is loaded), so
	// the catalog never lists a Solana rail the live 402 now drops. See
	// solanaSettleable() / baseSettleable() in x402-spec.js.
	if (env.X402_PAY_TO_SOLANA && solanaSettleable()) {
		out.push({
			scheme: 'exact',
			network: NETWORK_SOLANA_MAINNET,
			network_label: 'solana-mainnet',
			amount: String(amountAtomics),
			price,
			payTo: env.X402_PAY_TO_SOLANA,
			asset: env.X402_ASSET_MINT_SOLANA,
			asset_symbol: 'USDC',
			maxTimeoutSeconds: 60,
			resource: resourceUrl,
			extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },
		});
	}
	// Base only when a WORKING facilitator will settle it (CDP creds or the
	// X402_ADVERTISE_BASE opt-in). A bare facilitator URL is not enough — the prod
	// host was decommissioned and 404s /verify, so an unsettleable Base accept would
	// drift from the live 402 (which now drops Base) and hand buyers a catalog rail
	// that 502s at verify. See baseSettleable().
	if (env.X402_PAY_TO_BASE && baseSettleable()) {
		pushAcceptWithPermit2Sibling(out, {
			scheme: 'exact',
			network: NETWORK_BASE_MAINNET,
			network_label: 'base-mainnet',
			amount: String(amountAtomics),
			price,
			payTo: env.X402_PAY_TO_BASE,
			asset: env.X402_ASSET_ADDRESS_BASE,
			asset_symbol: 'USDC',
			maxTimeoutSeconds: 60,
			resource: resourceUrl,
			extra: { name: 'USD Coin', version: '2', decimals: 6 },
		});
	}
	return out;
}

// USE-13: one Bazaar catalog row per priced MCP tool. Facilitators key MCP
// rows on (resource, toolName) so each priced tool needs its own row; the
// shared `/api/mcp` resource alone would collapse them into one entry. We
// only emit rows for priced tools (otherwise the row would advertise a paid
// catalog entry for a free tool and confuse buyers about what's actually
// gated). Falls back to the canonical `mcp://tool/<name>` identifier when
// the spec wants a logical resource that distinguishes tools at the URL
// level, while the actual call still goes to the server's own path.
// Generic over the server: pass the endpoint path/url, its accepts, its
// service metadata, its tool catalog, and its per-tool pricing lookup —
// /api/mcp and /api/mcp-3d both feed through here.
function buildMcpToolItems({ path, mcpUrl, mcpAccepts, mcpService, catalog, priceForTool }) {
	const items = [];
	for (const tool of catalog) {
		const pricing = priceForTool(tool.name);
		if (!pricing) continue;
		const exampleArgs = exampleArgsForTool(tool);
		const discovery = declareMcpDiscovery({
			toolName: tool.name,
			description: tool.description,
			// MCP 2025-06-18 transport: Streamable HTTP is the default for
			// these servers; SSE clients still work through the same path.
			transport: 'streamable-http',
			inputSchema: tool.inputSchema,
			example: exampleArgs,
		});
		items.push({
			type: 'mcp',
			path,
			url: mcpUrl,
			toolName: tool.name,
			method: 'POST',
			description: tool.description,
			mimeType: 'application/json',
			serviceName: mcpService.serviceName,
			tags: mcpService.tags,
			iconUrl: mcpService.iconUrl,
			pricing: {
				amount_usdc: pricing.amount_usdc,
				currency: 'USDC',
				description: pricing.description,
			},
			accepts: mcpAccepts,
			extensions: extensionsForAccepts(mcpAccepts, discovery),
		});
	}
	return items;
}

// Synthesize a minimal example arguments object that satisfies the tool's
// inputSchema.required fields. We use type-appropriate placeholders rather
// than the full schema so the example stays short — facilitators index it
// for search relevance, not exact matching.
function exampleArgsForTool(tool) {
	const props = tool.inputSchema?.properties || {};
	const required = tool.inputSchema?.required || [];
	const out = {};
	for (const key of required) {
		const def = props[key] || {};
		if (def.type === 'integer' || def.type === 'number') out[key] = def.default ?? 1;
		else if (def.type === 'boolean') out[key] = def.default ?? true;
		else if (def.type === 'array') out[key] = [];
		else out[key] = def.default ?? `example-${key}`;
	}
	return out;
}

// Agent-published paid services (the `monetize_endpoint` tool). Each active,
// bazaar-listed row in agent_paid_services becomes a discovery catalog entry so
// facilitators — and therefore find_services / the bazaar — index the agent's
// endpoint the moment it's published. The advertised payTo is the agent's OWN
// payout wallet, mirroring the live 402 that api/x402/service.js serves.
//
// Never throws: a DB hiccup (or no DB, as in unit tests) yields an empty list so
// the static catalog still renders. Capped by listBazaarServices().
async function buildAgentServiceItems(origin) {
	let rows;
	try {
		rows = await listBazaarServices({ limit: 200 });
	} catch (err) {
		console.error('[wk/x402-discovery] agent services unavailable', err?.message || err);
		return [];
	}

	const items = [];
	for (const row of rows) {
		const url = serviceResourceUrl(row.slug);
		const price = RAW_AMOUNT_TO_USDC(row.price_atomics);
		const accepts = [];
		if (row.network === 'base' && row.payout_address && env.X402_ASSET_ADDRESS_BASE && baseSettleable()) {
			pushAcceptWithPermit2Sibling(accepts, {
				scheme: 'exact',
				network: NETWORK_BASE_MAINNET,
				network_label: 'base-mainnet',
				amount: String(row.price_atomics),
				price,
				payTo: row.payout_address,
				asset: env.X402_ASSET_ADDRESS_BASE,
				asset_symbol: 'USDC',
				maxTimeoutSeconds: 60,
				resource: url,
				extra: { name: 'USD Coin', version: '2', decimals: 6 },
			});
		} else if (
			row.network === 'solana' &&
			row.payout_address &&
			env.X402_ASSET_MINT_SOLANA &&
			env.X402_FEE_PAYER_SOLANA &&
			solanaSettleable()
		) {
			accepts.push({
				scheme: 'exact',
				network: NETWORK_SOLANA_MAINNET,
				network_label: 'solana-mainnet',
				amount: String(row.price_atomics),
				price,
				payTo: row.payout_address,
				asset: env.X402_ASSET_MINT_SOLANA,
				asset_symbol: 'USDC',
				maxTimeoutSeconds: 60,
				resource: url,
				extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },
			});
		}
		// No advertisable accept (missing payout / env for this network) → skip,
		// matching the live 402 which would also refuse to advertise it.
		if (!accepts.length) continue;

		const inputSchema = row.input_schema || { type: 'object', additionalProperties: true };
		items.push({
			path: `/api/x402/service/${row.slug}`,
			url,
			method: row.target_method,
			description: row.description,
			mimeType: 'application/json',
			serviceName: row.name,
			tags: ['agent', 'monetized', row.network],
			accepts,
			extensions: extensionsForAccepts(accepts, {
				method: row.target_method,
				discoverable: true,
				input: {},
				inputSchema,
			}),
		});
	}
	return items;
}

// Whole agents sold as paid APIs (POST /api/x402/agents/:id, switched on from
// the agent wallet's Earn tab). One entry per agent on sale, built with the SAME
// buildRequirements() call the live route makes, so the advertised accepts
// (Solana USDC to the agent's own payout wallet, the owner's price) are exactly
// what the 402 will ask for. Never throws: a DB hiccup yields no rows and the
// rest of the catalog still renders.
async function buildSellableAgentItems() {
	let services;
	try {
		services = await listActiveAgentServices({ limit: 200 });
	} catch (err) {
		console.error('[wk/x402-discovery] agent API services unavailable', err?.message || err);
		return [];
	}
	const items = [];
	for (const svc of services) {
		let accepts;
		try {
			accepts = buildRequirements({
				priceAtomics: svc.price_atomics,
				networks: ['solana'],
				resourceUrl: svc.url,
				payToOverride: { solana: svc.pay_to },
				acceptThree: false,
			}).map((a) => ({
				...a,
				network_label: 'solana-mainnet',
				price: RAW_AMOUNT_TO_USDC(a.amount),
				asset_symbol: 'USDC',
			}));
		} catch (err) {
			// Solana settlement is not configured on this deploy, so the live route
			// would refuse too. Skip rather than advertise an unpayable entry.
			console.error('[wk/x402-discovery] agent API accepts unavailable', err?.message || err);
			return [];
		}
		items.push({
			path: svc.path,
			url: svc.url,
			method: 'POST',
			description: `${svc.description} (one turn with ${svc.name} on three.ws)`,
			mimeType: 'application/json',
			serviceName: serviceNameFor({ name: svc.name }),
			tags: ['agent', 'chat', 'pay-per-call', 'solana'],
			accepts,
			extensions: extensionsForAccepts(accepts, {
				method: 'POST',
				discoverable: true,
				input: CALL_INPUT_EXAMPLE,
				inputSchema: CALL_INPUT_SCHEMA,
				output: { type: 'json', example: CALL_OUTPUT_EXAMPLE },
			}),
		});
	}
	return items;
}

// Datapoint fabric (/api/x402/d/<family>/<id>/<metric>) — 400k+ addressable
// single-datapoint endpoints served by one dynamic route. Every one already
// exists and settles; the discovery doc advertises a WIDE enumerated slice so
// indexers (x402scan, the Bazaar, 402index's well-known reader) surface
// thousands of concrete datapoint URLs — top coins × every metric, every chain,
// top protocols / stablecoins / pools / exchanges × their metrics, plus every
// no-id metric. Ids come from the SAME live cached feeds the paid route resolves
// against (nothing hardcodes a third-party asset); each family retains its last
// good rows when its feed fails, so a hiccup refreshes the catalog in place
// instead of shrinking it under a paging crawler, and the whole result is
// memoized so a discovery request never triggers a rebuild storm. Set
// X402_DISCOVERY_DATAPOINTS_WIDE=false to fall back to the small headline slice,
// or tune any per-family cap via X402_DISCOVERY_<FAMILY>_IDS. The fabric serves
// every id regardless of what's enumerated here; /api/x402/d walks the full space.

const DP_WIDE = env.X402_DISCOVERY_DATAPOINTS_WIDE !== 'false';
const dpIntEnv = (key, dflt) => {
	const n = Number.parseInt(process.env[key] ?? '', 10);
	return Number.isFinite(n) && n >= 0 ? n : dflt;
};
// Per-family enumeration caps (id count). Defaults advertise ~4,800 concrete
// datapoint endpoints; every id resolves against a cached feed so render stays
// bounded, and the built array is memoized for DP_TTL_MS.
const DP_CAPS = {
	coin: dpIntEnv('X402_DISCOVERY_COIN_IDS', 100),
	protocol: dpIntEnv('X402_DISCOVERY_PROTOCOL_IDS', 100),
	chain: dpIntEnv('X402_DISCOVERY_CHAIN_IDS', 150),
	stablecoin: dpIntEnv('X402_DISCOVERY_STABLECOIN_IDS', 100),
	pool: dpIntEnv('X402_DISCOVERY_POOL_IDS', 60),
	exchange: dpIntEnv('X402_DISCOVERY_EXCHANGE_IDS', 60),
	category: dpIntEnv('X402_DISCOVERY_CATEGORY_IDS', 80),
	dex: dpIntEnv('X402_DISCOVERY_DEX_IDS', 60),
	fees: dpIntEnv('X402_DISCOVERY_FEES_IDS', 80),
	'derivative-exchange': dpIntEnv('X402_DISCOVERY_DERIVATIVE_EXCHANGE_IDS', 40),
};

// The token / token-security families resolve ANY contract at runtime, so there
// is no finite id list to enumerate. Advertise the capability with $THREE — the
// platform's own coin — as the worked example id (it resolves to a live 402),
// and let the free /api/x402/d catalog document the unbounded address space.
const DP_TOKEN_EXAMPLE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
const DP_TTL_MS = dpIntEnv('X402_DISCOVERY_DATAPOINTS_TTL_MS', 900_000); // 15 min

// Coin has 20 metrics; enumerating all × 100 coins alone is 2,000 rows and
// bloats the doc past what some crawlers ingest. Advertise the high-value
// headline metrics for coins (breadth of assets matters more than niche metrics
// like watchlist-users); the fabric still serves every metric for every coin.
// Every other family enumerates all its metrics (each has ≤7).
const DP_COIN_METRICS = [
	'price', 'market-cap', 'fdv', 'volume-24h', 'change-24h',
	'change-7d', 'rank', 'ath', 'atl', 'circulating-supply',
];

let _dpDiscoveryCache = null; // { origin, items, at }

// Per-family retention, keyed by origin. A crawler reads this catalog by
// offset over ~50 sequential requests, so a family that silently disappears
// mid-sweep does not just hide its own rows: every row after it shifts up an
// offset, and the crawler never reads the tail it already paged past. One
// upstream feed timing out used to drop its whole family (the coin family
// alone is 1,000 rows), shrinking `total` mid-crawl. Each family now keeps its
// last good rows and re-serves them when its feed fails or returns empty, so
// the advertised catalog only ever grows or refreshes in place.
const _dpSliceCache = new Map(); // origin -> Map(family -> rows)

// A synthetic, schema-shaped example value for a metric, derived from its unit.
// The datapoint output.example carries the real label/unit; the value is
// illustrative (all datapoint examples are synthetic by design).
function datapointExampleValue(metricDef) {
	const unit = String(metricDef?.unit || '').toLowerCase();
	if (unit.includes('usd') || unit.includes('$')) return 1234567.89;
	if (unit.includes('bps')) return -3;
	if (unit.includes('%') || unit.includes('pct') || unit.includes('percent')) return 2.5;
	if (
		unit === '' || unit.includes('text') || unit.includes('label') ||
		unit.includes('name') || unit.includes('symbol') || unit.includes('class')
	)
		return metricDef?.label || 'value';
	return 42.5;
}

async function buildDatapointItemsUncached(origin) {
	const items = [];
	const svc = withService({
		serviceName: 'three.ws Datapoints',
		tags: ['crypto', 'market-data', 'datapoint', 'x402'],
	});

	// `push` writes into whichever collector is active: `items` directly for the
	// always-present families, or a family-scoped buffer while `slice` runs.
	let target = items;

	const sliceCache = _dpSliceCache.get(origin) ?? new Map();
	_dpSliceCache.set(origin, sliceCache);

	// Run one family's enumeration into its own buffer. Rows land in the catalog
	// when the feed produced any; otherwise the family's last good rows do, so a
	// transient upstream failure cannot shrink the catalog under a crawler.
	const slice = async (family, fn) => {
		const rows = [];
		target = rows;
		try {
			await fn();
		} catch (err) {
			console.error(`[wk/x402-discovery] ${family} slice`, err?.message || err);
		} finally {
			target = items;
		}
		if (rows.length > 0) {
			sliceCache.set(family, rows);
			items.push(...rows);
			return;
		}
		const retained = sliceCache.get(family);
		if (retained?.length) {
			console.error(`[wk/x402-discovery] ${family} slice empty, serving retained rows`);
			items.push(...retained);
		}
	};

	const push = (family, id, metric) => {
		const familyDef = DATAPOINT_FAMILIES[family];
		const metricDef = familyDef.metrics[metric];
		const priceAtomics = datapointPriceFor(`datapoint-${family}`, DATAPOINT_DEFAULT_ATOMICS);
		const path =
			id != null
				? `/api/x402/d/${family}/${encodeURIComponent(id)}/${metric}`
				: `/api/x402/d/${family}/${metric}`;
		const url = `${origin}${path}`;
		const accepts = acceptsForPrice(priceAtomics, url);
		target.push({
			path,
			url,
			method: 'GET',
			description: datapointDescription({ family, metric, priceAtomics }),
			mimeType: 'application/json',
			serviceName: svc.serviceName,
			tags: [...svc.tags.slice(0, 4), family].slice(0, 5),
			iconUrl: svc.iconUrl,
			accepts,
			extensions: extensionsForAccepts(accepts, {
				method: 'GET',
				discoverable: true,
				input: {},
				inputSchema: { type: 'object', properties: {} },
				output: {
					example: {
						family,
						...(id != null ? { id } : {}),
						metric,
						label: metricDef.label,
						unit: metricDef.unit,
						value: datapointExampleValue(metricDef),
						as_of: '2026-07-11T00:00:00.000Z',
						source: 'three.ws market-data',
					},
				},
			}),
		});
	};

	const metricsOf = (family) => Object.keys(DATAPOINT_FAMILIES[family].metrics);

	// Every metric of the no-id families — static, always present.
	for (const family of ['global', 'fear-greed', 'gas']) {
		for (const metric of metricsOf(family)) push(family, null, metric);
	}

	// Small headline slice when wide enumeration is disabled — reproduces the
	// original catalog (top 20 coins × 3 metrics, top 10 protocols × tvl).
	if (!DP_WIDE) {
		await slice('coin', async () => {
			const { rows } = await fetchMarketsTable({ page: 1, perPage: 20, category: '' });
			for (const row of rows) for (const metric of ['price', 'market-cap', 'change-24h']) if (row.id) push('coin', row.id, metric);
		});
		await slice('protocol', async () => {
			const { protocols } = await buildProtocols();
			for (const p of protocols.slice(0, 10)) if (p.slug) push('protocol', p.slug, 'tvl');
		});
		return items;
	}

	// ── Wide enumeration: real ids from the cached feeds × every family metric ──

	// Top coins by market cap (CoinGecko markets table, one cached page ≤100).
	await slice('coin', async () => {
		const { rows } = await fetchMarketsTable({ page: 1, perPage: Math.min(DP_CAPS.coin, 100), category: '' });
		const all = new Set(metricsOf('coin'));
		const metrics = DP_COIN_METRICS.filter((m) => all.has(m));
		for (const row of rows.slice(0, DP_CAPS.coin)) {
			if (!row.id) continue;
			for (const metric of metrics) push('coin', row.id, metric);
		}
	});

	// Top protocols by TVL (DeFiLlama).
	await slice('protocol', async () => {
		const { protocols } = await buildProtocols();
		const metrics = metricsOf('protocol');
		for (const p of protocols.slice(0, DP_CAPS.protocol)) {
			if (!p.slug) continue;
			for (const metric of metrics) push('protocol', p.slug, metric);
		}
	});

	// Every chain (DeFiLlama /v2/chains — ~350, fully enumerable).
	await slice('chain', async () => {
		const chains = [...(await allChains()).values()].map((c) => c?.name).filter(Boolean);
		const metrics = metricsOf('chain');
		for (const name of chains.slice(0, DP_CAPS.chain)) {
			for (const metric of metrics) push('chain', name, metric);
		}
	});

	// Top stablecoins by supply (DeFiLlama). The map keys id AND symbol to the
	// same row — enumerate each once by its canonical id (matches d/index.js).
	await slice('stablecoin', async () => {
		const seen = new Set();
		const ids = [];
		for (const [key, row] of (await allStablecoins()).entries()) {
			if (seen.has(row)) continue;
			seen.add(row);
			ids.push(/^\d+$/.test(key) ? key : row.symbol || key);
			if (ids.length >= DP_CAPS.stablecoin) break;
		}
		const metrics = metricsOf('stablecoin');
		for (const id of ids) for (const metric of metrics) push('stablecoin', id, metric);
	});

	// Top yield pools by TVL (DeFiLlama yields — pre-sorted TVL desc).
	await slice('pool', async () => {
		const { pools } = await loadYieldPools();
		const metrics = metricsOf('pool');
		for (const p of pools.slice(0, DP_CAPS.pool)) {
			if (!p.pool) continue;
			for (const metric of metrics) push('pool', p.pool, metric);
		}
	});

	// Top exchanges by trust rank (CoinGecko /exchanges).
	await slice('exchange', async () => {
		const { exchanges } = await buildExchanges();
		const metrics = metricsOf('exchange');
		for (const e of exchanges.slice(0, DP_CAPS.exchange)) {
			if (!e.id) continue;
			for (const metric of metrics) push('exchange', e.id, metric);
		}
	});

	// Sector categories (CoinGecko categories, market-cap desc).
	await slice('category', async () => {
		const metrics = metricsOf('category');
		let n = 0;
		for (const id of (await allCategories()).keys()) {
			if (n++ >= DP_CAPS.category) break;
			for (const metric of metrics) push('category', id, metric);
		}
	});

	// Top DEXs by 24h volume (DeFiLlama).
	await slice('dex', async () => {
		const metrics = metricsOf('dex');
		let n = 0;
		for (const slug of (await allDexes()).keys()) {
			if (n++ >= DP_CAPS.dex) break;
			for (const metric of metrics) push('dex', slug, metric);
		}
	});

	// Top protocols by fees/revenue (DeFiLlama).
	await slice('fees', async () => {
		const metrics = metricsOf('fees');
		let n = 0;
		for (const slug of (await allFees()).keys()) {
			if (n++ >= DP_CAPS.fees) break;
			for (const metric of metrics) push('fees', slug, metric);
		}
	});

	// Derivative (perp) venues by open interest (CoinGecko).
	await slice('derivative-exchange', async () => {
		const metrics = metricsOf('derivative-exchange');
		let n = 0;
		for (const id of (await allDerivativeExchanges()).keys()) {
			if (n++ >= DP_CAPS['derivative-exchange']) break;
			for (const metric of metrics) push('derivative-exchange', id, metric);
		}
	});

	// Per-contract token market + security — advertised via the $THREE worked
	// example (the families resolve any address at runtime; no id list to walk).
	for (const metric of metricsOf('token')) push('token', DP_TOKEN_EXAMPLE_MINT, metric);
	for (const metric of metricsOf('token-security')) push('token-security', DP_TOKEN_EXAMPLE_MINT, metric);

	return items;
}

// Memoized wrapper: the slice rebuilds at most once per DP_TTL_MS per origin. A
// total-failure rebuild serves the last good cache (or an empty block) rather
// than dropping — or hammering upstreams on — every discovery request.
async function buildDatapointItems(origin) {
	const now = Date.now();
	if (_dpDiscoveryCache && _dpDiscoveryCache.origin === origin && now - _dpDiscoveryCache.at < DP_TTL_MS) {
		return _dpDiscoveryCache.items;
	}
	try {
		const items = await buildDatapointItemsUncached(origin);
		_dpDiscoveryCache = { origin, items, at: now };
		return items;
	} catch (err) {
		console.error('[wk/x402-discovery] datapoint build failed', err?.message || err);
		if (_dpDiscoveryCache?.items) return _dpDiscoveryCache.items;
		return [];
	}
}

// ── output.example backfill ──────────────────────────────────────────────────
// Indexers (agentic.market / x402scan) render and rank a resource by its
// response example. A resource with no `bazaar.info.output.example` still
// catalogs, but ranks poorly and shows an empty result card — the verifier
// (`scripts/verify-x402-discovery.mjs`) flags every one as a warning. These maps
// are the single source of a realistic, schema-shaped success example for each
// paid endpoint so the catalog renders fully everywhere it's indexed.
//
// Every value here is SYNTHETIC: $THREE (the only coin) or an obviously-fake
// placeholder address — never a real third-party mint/creator/holder. Examples
// mirror the actual 200-response keys each handler emits (post-settlement).
const REST_OUTPUT_EXAMPLES = Object.freeze({
	'/api/x402/model-check': {
		url: 'https://three.ws/avatars/mannequin.glb',
		fetchedBytes: 1572864,
		model: {
			container: 'glb',
			generator: 'three.ws CharacterStudio v1.5',
			version: '2.0',
			extensionsUsed: ['KHR_materials_unlit'],
			extensionsRequired: [],
			counts: {
				scenes: 1,
				nodes: 18,
				meshes: 6,
				materials: 4,
				textures: 3,
				animations: 1,
				skins: 1,
				totalVertices: 12480,
				totalTriangles: 24812,
			},
		},
		suggestions: [
			{
				id: 'texture_size',
				severity: 'info',
				message: 'All textures are within 1024x1024 — good for mobile.',
			},
		],
	},
	'/api/x402/token-intel': {
		mint: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',
		symbol: 'THREE',
		name: 'three.ws',
		chain: 'solana',
		price_usd: 0.003685,
		change_24h: 12.4,
		market_cap_usd: 3685000,
		liquidity_usd: 412000,
		volume_24h_usd: 1268079,
		momentum: { m5: 0.3, h1: 1.8, h6: 6.1, h24: 12.4 },
		signal: 'bullish',
		headline: 'THREE climbs +12.40% — moderate upside',
		rationale:
			'THREE is up +12.40% over 24 h, trading at $0.003685. Volume is healthy against liquidity; participation is real. Buyers dominate the tape. The last hour confirms the trend.',
		confidence: 0.86,
		risk: {
			score: 8,
			level: 'low',
			summary: 'THREE clears the basic depth, age, and flow checks.',
			factors: [
				{ label: 'Liquidity', status: 'low', detail: '$412,000 pooled — healthy depth.' },
				{ label: 'Age', status: 'low', detail: 'Pair is 240d old — established.' },
				{ label: 'Float', status: 'low', detail: 'Cap is 8.9× liquidity — well backed.' },
				{ label: 'Flow', status: 'low', detail: '63% of 24 h trades are buys — net accumulation.' },
			],
		},
		ts: '2026-06-12T10:00:00Z',
	},
	'/api/x402/analytics': {
		ok: true,
		report: 'clubs',
		period: '24h',
		generated_at: '2026-06-27T18:42:09.000Z',
		metrics: {
			active_clubs: 3,
			total_clubs: 4,
			members: 27,
			tips: { count: 41, volume_atomics: '410000', volume_usdc: 0.41 },
			cover_charges: { count: 12, atomics: '120000', usdc: 0.12 },
		},
		top_clubs: [
			{ dancer: '1', display_name: 'Nyx', volume_atomics: '190000', volume_usdc: 0.19, tips: 19 },
		],
	},
	'/api/x402/api-key-health': {
		valid: true,
		scopes: ['internal', 'autonomous_loop', 'bypass_x402'],
		expires_at: null,
		key_type: 'internal',
		source: 'env',
		key_prefix: null,
		rate_limit_per_minute: null,
		checked_at: '2026-06-28T12:00:00Z',
	},
	'/api/x402/auth-health': {
		all_pass: true,
		failed_step: null,
		latency_ms: 38,
		steps: {
			create: { pass: true, latency_ms: 8 },
			validate: { pass: true, latency_ms: 3 },
			refresh: { pass: true, latency_ms: 11 },
			expire: { pass: true, latency_ms: 2 },
		},
		ts: '2026-06-28T00:00:00Z',
	},
	'/api/x402/avatar-optimize-batch': {
		analyzed: 50,
		critical_count: 12,
		warn_count: 38,
		info_count: 91,
		total_size_bytes: 82000000,
		avatars: [
			{
				id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55',
				name: 'My Avatar',
				size_bytes: 2100000,
				critical_count: 1,
				warn_count: 3,
				info_count: 5,
				top_suggestion: 'Apply Draco compression to reduce geometry size by ~60%',
			},
		],
	},
	'/api/x402/pipeline-rig': {
		stage: 'rig',
		input_url: 'https://three.ws/avatars/mannequin.glb',
		output_url: 'https://three.ws/cdn/x402-pipeline/rig/abc123.glb',
		bytes: 1940112,
		persisted: true,
		rig_type: 'biped',
	},
	'/api/x402/pipeline-remesh': {
		stage: 'remesh',
		input_url: 'https://three.ws/avatars/mannequin.glb',
		output_url: 'https://three.ws/cdn/x402-pipeline/remesh/abc123.glb',
		bytes: 812044,
		persisted: true,
		remesh_mode: 'quad',
		operation: 'full',
		face_count: 20000,
		quad_ratio: 0.98,
		textured: true,
	},
	'/api/x402/pipeline-gameready': {
		stage: 'gameready',
		input_url: 'https://three.ws/avatars/mannequin.glb',
		output_url: 'https://three.ws/cdn/x402-pipeline/gameready/abc123.glb',
		bytes: 640220,
		persisted: true,
		topology: 'quad',
		poly_budget: 12000,
		face_count: 12000,
		quad_ratio: 0.97,
		textured: true,
	},
	'/api/x402/pipeline-stylize': {
		stage: 'stylize',
		input_url: 'https://three.ws/avatars/mannequin.glb',
		output_url: 'https://three.ws/cdn/x402-pipeline/stylize/abc123.glb',
		bytes: 512880,
		persisted: true,
		style: 'voxel',
		resolution: 48,
		face_count: 18240,
	},
	'/api/x402/pipeline-rembg': {
		stage: 'rembg',
		input_url: 'https://three.ws/avatars/thumbs/default.png',
		output_url: 'https://three.ws/cdn/x402-pipeline/rembg/abc123.png',
		bytes: 284112,
		persisted: true,
		model: 'rmbg2',
	},
	'/api/x402/bazaar-feed': {
		filter: 'new',
		limit: 10,
		count: 3,
		listings: [
			{
				id: 'http:https://svc.example/x402',
				name: 'Example Feed',
				price: '0.001 USDC',
				first_seen: '2026-06-28T00:00:00Z',
			},
		],
		activity: {
			new_24h: 3,
			new_7d: 9,
			daily_avg_7d: 1.29,
			signal: 'active',
			headline: '3 new bazaar listings in 24 h',
			confidence: 0.65,
		},
		generated_at: '2026-06-28T10:00:00Z',
	},
	'/api/x402/billboard': {
		ok: true,
		coin: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',
		image: 'https://three.ws/og-image.png',
		caption: 'gm from the gallery',
		slotHours: 6,
		startsAt: '2026-06-28T18:42:09.000Z',
		endsAt: '2026-06-29T00:42:09.000Z',
		payer: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
		network: 'solana',
		amountAtomics: '50000',
		asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
	},
	'/api/x402/cross-chain': {
		mode: 'bridge_status',
		bridges: [
			{ chain: 'wormhole', status: 'operational', latency_ms: 210, provider: 'wormholescan' },
			{ chain: 'lifi', status: 'operational', latency_ms: 334, provider: 'li.fi' },
			{ chain: 'debridge', status: 'degraded', latency_ms: 1870, provider: 'dln.trade' },
		],
		down_count: 0,
		signal: 'neutral',
		headline: 'All Solana bridges operational',
		confidence: 0.82,
		ts: '2026-06-28T12:00:00Z',
	},
	'/api/x402/did': {
		verified: true,
		latency_ms: 142,
		did: 'did:three:canary',
		mode: 'verify',
		resolved_did: 'did:web:three.ws',
		http_status: 200,
		within_latency: true,
		malformed: false,
		configured: true,
		checks: {
			is_object: true,
			has_did_context: true,
			has_did_id: true,
			has_verification_method: true,
			assertion_resolves: true,
			has_x402_service: true,
			valid: true,
		},
		ts: '2026-06-27T10:00:00Z',
	},
	'/api/x402/feed-health': {
		feed: 'changelog_rss',
		valid: true,
		item_count: 1241,
		latest_title: 'x402 Volume Analytics — the platform measures its own payment economy',
		title_match: true,
		fetch_ms: 312,
		checked_at: '2026-06-28T12:00:00.000Z',
	},
	'/api/x402/llm-proxy': {
		content: '1, 2, 3.',
		model: 'llama-3.3-70b-versatile',
		provider: 'groq',
		latency_ms: 312,
		tokens_used: 11,
		input_tokens: 5,
		output_tokens: 6,
	},
	'/api/x402/mcp-tool-catalog': {
		ok: true,
		mode: 'discover',
		total_tools: 24,
		priced_tools: 11,
		free_tools: 13,
		new_tools: [
			{ name: 'segment_model', description: 'Split a mesh into named parts', priced: true, price_usdc: 0.04, input_fields: 2 },
		],
		changed_tools: [
			{ name: 'render_avatar', change: 'price', price_usdc: 0.005, prev_price_usdc: 0.003 },
		],
		removed_tools: [],
		ts: '2026-06-27T10:00:00.000Z',
	},
	'/api/x402/model-validation-sweep': {
		ok: true,
		avatar_id: 'a3f3d6c2-1f1b-4f10-9b6c-1b1f5e0c9c34',
		avatar_name: 'Realistic Male',
		score: 82,
		has_errors: false,
		missing_bones: false,
		counts: {
			scenes: 1,
			nodes: 22,
			meshes: 4,
			materials: 3,
			textures: 5,
			animations: 12,
			skins: 1,
			totalVertices: 8432,
			totalTriangles: 14200,
			indexedPrimitives: 4,
			nonIndexedPrimitives: 0,
		},
		extensions_used: ['KHR_draco_mesh_compression'],
		file_size_bytes: 1572864,
		inspected_at: '2026-06-27T10:00:00.000Z',
	},
	'/api/x402/notify': {
		delivered: true,
		channel: 'canary',
		latency_ms: 18,
		notification_id: 'a3f3d6c2-1f1b-4f10-9b6c-1b1f5e0c9c34',
		message: 'x402 loop heartbeat',
		priority: 'low',
		payer: null,
		ts: '2026-06-28T10:00:00Z',
	},
	'/api/x402/pay-by-name': {
		data: {
			name: 'nich.threews.sol',
			address: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
			verified: true,
			source: 'sns',
		},
	},
	'/api/x402/rate-limit-probe': {
		endpoint: '/api/x402/forge',
		remaining_calls: 42,
		reset_at: '2026-06-29T00:00:00.000Z',
		limit: 500,
		daily_cap_atomic: 5000000,
		daily_spent_atomic: 4580000,
		remaining_capacity_atomic: 420000,
		price_atomic: 10000,
		cooldown_active: false,
		cooldown_ttl_seconds: null,
	},
	'/api/x402/schema-check': {
		ok: true,
		api: 'changelog_json',
		valid: true,
		version: '2026-06-28',
		entry_count: 42,
		schema_errors: [],
		fetched_at: '2026-06-28T12:00:00.000Z',
	},
	'/api/x402/solana-register-health': {
		tool: 'solana_register',
		healthy: true,
		network: 'mainnet',
		canary_agent_id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55',
		asset: 'THREEsynthetic1111111111111111111111111111',
		identity_pda: 'AgentRegyPDA11111111111111111111111111111111',
		registration_uri: 'https://three.ws/api/agents/7b9a4f30/registration.json',
		checks: {
			indexed: true,
			registry_enrolled: true,
			asset_onchain: true,
			identity_pda_onchain: true,
		},
		rpc_latency_ms: 184,
		checked_at: '2026-06-27T18:00:00Z',
	},
	'/api/x402/spend-session': {
		ok: true,
		mode: 'canary',
		created: true,
		consumed: true,
		latency_ms: 12,
		session_id: 'a3f3d6c2-1f1b-4f10-9b6c-1b1f5e0c9c34',
		budget: 0.01,
		payer: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
		network: 'solana',
		amountAtomics: '10000',
		asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
	},
	'/api/x402/telegram-health': {
		bot: 'changelog',
		reachable: true,
		bot_id: 7234567890,
		bot_username: 'three_ws_bot',
		latency_ms: 142,
		reason: null,
		checked_at: '2026-06-28T12:00:00.000Z',
	},
	'/api/x402/wallet-connect': {
		mode: 'health',
		session_created: true,
		latency_ms: 83,
		slow: false,
		nonce_valid: true,
		domain: 'three.ws',
		reason: null,
		checked_at: '2026-06-28T00:00:00Z',
	},
	'/api/x402/agent-reputation': {
		subject: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',
		subjectType: 'solana_mint',
		score: 71,
		tier: 'high',
		signals: {
			dimensions: {
				activity: { available: true, weight: 25, norm: 0.62, points: 16, value: 124 },
				age: { available: true, weight: 15, norm: 0.48, points: 7, days: 176 },
				counterparties: { available: true, weight: 15, norm: 0.72, points: 11, value: 18 },
				holdings: { available: true, weight: 10, norm: 1, points: 10, usd: 412000 },
				reliability: { available: true, weight: 15, norm: 0.98, points: 15, failure_rate: 0.02 },
				attestations: { available: true, weight: 20, norm: 0.6, points: 12, count: 6, avg_feedback: null },
			},
			weight_considered: 100,
		},
		evidence: [
			{ kind: 'solana_token', ref: 'https://solscan.io/token/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump' },
			{ kind: 'threews_agent', ref: '/agents/7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55' },
		],
		caveats: [],
		ts: '2026-07-07T00:00:00Z',
	},
	'/api/x402/agent-bouncer': {
		ok: true,
		admitted: true,
		banned: false,
		tier: 'trusted',
		reason: null,
		reasons: [],
		newcomer: false,
		agent_id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55',
		name: 'Helios',
		visits: 4,
		reputation: {
			deployed_mints: 2,
			payments: { confirmed_count: 142, distinct_payers: 87, failure_rate: 0.021 },
			distributions: { confirmed: 12, failed: 1, success_rate: 0.923 },
		},
		policy: {
			minPayments: 10,
			minDistinctPayers: 3,
			maxFailureRate: 0.2,
			allowNewcomers: true,
		},
		fetchedAt: '2026-06-22T17:00:00.000Z',
	},
	'/api/x402/onchain-identity-verify': {
		claim: {
			identity: 'vitalik.eth',
			address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
			chain: 'eip155:1',
		},
		identity_type: 'ens',
		verified: true,
		method: 'ens-resolution',
		evidence: [
			{
				kind: 'ens_forward_resolution',
				ref: 'vitalik.eth',
				detail: 'resolves to 0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
			},
		],
		caveats: [],
		ts: '2026-07-07T00:00:00.000Z',
	},
	'/api/x402/pump-launch': {
		mint: 'HEL1oXyzABCDEFGHJKLMNopqrstuvwxyZ12345abcdef',
		signature: '5xYExampleTxSignatureDoNotUse...',
		creator: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
		name: 'Helios',
		symbol: 'HELIO',
		metadataUri: 'https://ipfs.io/ipfs/QmExampleMetadataCid',
		network: 'mainnet',
		pumpfun_url: 'https://pump.fun/coin/HEL1oXyzABCDEFGHJKLMNopqrstuvwxyZ12345abcdef',
		vanity_prefix: 'HEL',
		vanity_iterations: 4821,
	},
	// Sourced from the shared forge listing so the discovery output example
	// matches the live 402's exactly (backend field included).
	'/api/x402/forge': FORGE_OUTPUT_EXAMPLE,
	'/api/x402/skill-marketplace': {
		skill_filter: 'inspect_model',
		count: 1,
		cheapest: {
			agent_name: 'Helios',
			skill: 'inspect_model',
			amount_atomics: '10000',
			chain: 'solana',
		},
		listings: [
			{
				agent_id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55',
				agent_name: 'Helios',
				skill: 'inspect_model',
				amount_atomics: '10000',
				mint_decimals: 6,
				chain: 'solana',
				trial_uses: 1,
				time_pass_hours: 24,
			},
		],
		indexed_at: '2026-05-14T17:00:00Z',
	},
	'/api/x402/symbol-availability': {
		ticker: 'HELIO',
		network: 'mainnet',
		exact_collision: false,
		exact_matches: [],
		similar: [
			{
				ticker: 'HELIOS',
				mint: 'C3vQABCDEFGHJKLMNopqrstuvwxyZ12345abcdefghi',
				name: 'Helios',
				similarity: 0.71,
			},
		],
		recommendation: 'available — one near-match exists at similarity 0.71',
		indexed_at: '2026-05-14T17:00:00Z',
	},
	'/api/x402/vanity': {
		address: 'SoEXAMPLEdoNotUse1111111111111111111111111111',
		prefix: 'So',
		suffix: null,
		ignoreCase: false,
		format: 'keypair',
		secretKeyBase58: '<example only — the live endpoint returns the ground secret key here>',
		mnemonic: null,
		wordCount: null,
		derivationPath: null,
		attempts: 160,
		durationMs: 6,
		expectedAttempts: 58,
		network: 'solana',
		explorerUrl: 'https://solscan.io/account/SoEXAMPLEdoNotUse1111111111111111111111111111',
		verifyUrl: 'https://three.ws/vanity/verify',
		serviceKeyUrl: 'https://three.ws/.well-known/three-vanity.json',
	},
	'/api/x402/vanity-verifiable': {
		protocol: 'three-vanity/v1',
		receiptType: 'grind-receipt',
		address: 'SoEXAMPLEdoNotUse1111111111111111111111111111',
		pattern: { prefix: 'So', suffix: null, ignoreCase: false },
		commitment: 'sha256:0000000000000000000000000000000000000000000000000000000000000000',
		winningIndex: 3041,
		attempts: 3042,
		sealed: false,
		servicePublicKey: '3WzwpVSmSExamplePublicKeyDoNotUse',
		signature: 'ed25519:abcdef1234567890...',
		network: 'solana',
		verifyUrl: 'https://three.ws/vanity/verify',
		serviceKeyUrl: 'https://three.ws/.well-known/three-vanity.json',
	},
	'/api/x402/vanity-premium': {
		address: 'PUMPEXAMPLEdoNotUse1111111111111111111111111',
		prefix: 'PUMP',
		suffix: null,
		patternLabel: 'PUMP…',
		rarityTier: 'rare',
		format: 'keypair',
		priceUsd: 12,
		secretKeyBase58: '<delivered once — ciphertext destroyed on delivery>',
		delivery: 'once',
		network: 'solana',
		explorerUrl: 'https://solscan.io/account/PUMPEXAMPLEdoNotUse1111111111111111111111111',
		custodyNotice:
			'Platform-generated key delivered once — use as a token mint or sweep to self-generated custody, not as a treasury.',
	},
	'/api/x402/asset-download': {
		ok: true,
		slug: 'pole-dancer-rumba',
		title: 'Pole Dancer (Rumba)',
		mimeType: 'model/gltf-binary',
		sizeBytes: 6492840,
		expiresAt: '2026-05-21T18:48:09.000Z',
		downloadUrl: 'https://three-ws-public.r2.dev/assets/pole-dancer-rumba.glb?X-Amz-Algorithm=...',
	},
	'/api/x402/skill-call': {
		ok: true,
		skill: { slug: 'wallet-balance', name: 'Wallet Balance', category: 'crypto' },
		tools: [{ type: 'function', function: { name: 'get_balance', description: 'Fetch balances.' } }],
		content: '# Wallet Balance\n\nUse get_balance to fetch token balances...',
		calledAt: '2026-05-31T18:48:09.000Z',
	},
	'/api/x402/cosmetic-purchase': {
		ok: true,
		id: 'skin-midnight',
		name: 'Midnight',
		slot: 'skin',
		rarity: 'legendary',
		account: 'g_5f3c9a21b8',
		owned: true,
		newlyOwned: true,
		network: 'solana',
		amountAtomics: '3000000',
	},
	'/api/x402/animation-download': {
		ok: true,
		id: '00000000-0000-0000-0000-000000000000',
		slug: 'spin-kick-combo',
		name: 'Spin Kick Combo',
		mimeType: 'model/gltf-binary',
		sizeBytes: 248400,
		expiresAt: '2026-06-15T18:48:09.000Z',
		downloadUrl: 'https://three.ws/cdn/u/spin-kick-combo.glb?X-Amz-Algorithm=...',
	},
	'/api/x402/club-cover': {
		ok: true,
		admitted: true,
		banned: false,
		tier: 'regular',
		visits: 4,
		passId: 'a3f3d6c2-1f1b-4f10-9b6c-1b1f5e0c9c34',
		issuedAt: '2026-06-15T18:42:09.000Z',
		expiresAt: '2026-06-16T00:42:09.000Z',
		network: 'solana',
		amountAtomics: '10000',
	},
	// Only advertised when CDP creds are present (its sole accept is a Permit2
	// sibling), so it never appears in the public non-CDP catalog — but include
	// its example so the catalog stays green in CDP-credentialed environments.
	'/api/x402/permit2-paid-demo': {
		ok: true,
		demo: 'permit2-eip2612-gas-sponsoring',
		method: 'permit2',
		supportsEip2612: true,
		payer: '0x1111111111111111111111111111111111111111',
		network: 'eip155:8453',
		asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
		amountAtomics: '1000',
		transaction: '0x9c0a7e5ad5c9c0bb6f04f6ad9c52f4f44bb6c5d9c0a7e5ad5c9c0bb6f04f6ad9',
		explorer:
			'https://basescan.org/tx/0x9c0a7e5ad5c9c0bb6f04f6ad9c52f4f44bb6c5d9c0a7e5ad5c9c0bb6f04f6ad9',
		settledAt: '2026-06-15T18:42:09.000Z',
	},
});

// MCP tool result examples, keyed by toolName. Wrapped in the same JSON-RPC 2.0
// CallToolResult envelope the live /api/mcp + /api/mcp-3d transports return, so
// the example mirrors exactly what a buyer's MCP client receives.
const MCP_TOOL_OUTPUT_SUMMARIES = Object.freeze({
	render_avatar: { ok: true, scene: 'avatar', format: 'glb', url: 'https://three.ws/cdn/avatar-preview.glb' },
	validate_model: { ok: true, warnings: [], errors: [], meta: { vertices: 12480, triangles: 24812 } },
	inspect_model: { container: 'glb', meshes: 6, materials: 4, animations: 1, vertices: 12480 },
	optimize_model: { ok: true, before: { bytes: 1572864 }, after: { bytes: 640000 }, savedPct: 59 },
	apply_animation: { ok: true, clip: 'walk', format: 'glb', url: 'https://three.ws/cdn/animated.glb' },
	text_to_3d: { job_id: 'f1.eyJwIjoiZXhhbXBsZSJ9.sig', status: 'queued', poll_url: '/api/forge?job=f1.eyJwIjoiZXhhbXBsZSJ9.sig' },
	image_to_3d: { job_id: 'f1.eyJpIjoiZXhhbXBsZSJ9.sig', status: 'queued', poll_url: '/api/forge?job=f1.eyJpIjoiZXhhbXBsZSJ9.sig' },
	remove_background: { ok: true, image_url: 'https://three.ws/cdn/cutout.png' },
	remesh_model: { ok: true, glb_url: 'https://three.ws/cdn/remeshed.glb', triangles: 20000 },
	stylize_model: { ok: true, glb_url: 'https://three.ws/cdn/stylized.glb', style: 'voxel' },
	segment_model: { ok: true, parts: ['head', 'torso', 'legs'], glb_url: 'https://three.ws/cdn/segmented.glb' },
	retexture_model: { ok: true, glb_url: 'https://three.ws/cdn/retextured.glb' },
	retexture_region: { ok: true, glb_url: 'https://three.ws/cdn/retextured-region.glb', region: 'face' },
	auto_rig_model: { ok: true, glb_url: 'https://three.ws/cdn/rigged.glb', bones: 52 },
	pose_model: { ok: true, glb_url: 'https://three.ws/cdn/posed.glb', pose: 't-pose' },
	direct_prompt: { job_id: 'f1.eyJkIjoiZXhhbXBsZSJ9.sig', status: 'queued', poll_url: '/api/forge?job=f1.eyJkIjoiZXhhbXBsZSJ9.sig' },
	generate_material: { ok: true, material_url: 'https://three.ws/cdn/material.glb' },
	cad_generate: {
		id: '0b4b6e61-42aa-424d-8aef-2bddbd9b7abb',
		title: 'Raspberry Pi 4 Case Base',
		url: 'https://three.ws/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb',
		files: { step: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/part.step', stl: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/part.stl', glb: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/part.glb' },
		metrics: { size_mm: [100, 75, 12], volume_mm3: 21623.8631, solids: 1, valid: true },
		params: [{ name: 'WIDTH', label: 'Overall width', value: 100, min: 80, max: 120, step: 1, unit: 'mm' }],
	},
	cad_rebuild: {
		id: '0b4b6e61-42aa-424d-8aef-2bddbd9b7abb',
		key: '1mf1luf',
		url: 'https://three.ws/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb?v=1mf1luf',
		values: { WIDTH: 112 },
		files: { step: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/v/1mf1luf/part.step', stl: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/v/1mf1luf/part.stl', glb: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/v/1mf1luf/part.glb' },
		cached: false,
	},
	search_public_avatars: {
		count: 2,
		avatars: [
			{ id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55', slug: 'midnight-robot', name: 'Midnight Robot', tags: ['robot', 'sci-fi'], thumbnail_url: 'https://three.ws/cdn/avatars/midnight-robot.png' },
			{ id: 'c1e8a902-5b44-4f0a-8e21-7d3f0c2b1a90', slug: 'anime-dancer', name: 'Anime Dancer', tags: ['anime', 'dancer'], thumbnail_url: 'https://three.ws/cdn/avatars/anime-dancer.png' },
		],
	},
	solana_agent_reputation: {
		asset: 'AgEntWa11etExamp1eDoNotUse111111111111111111',
		network: 'mainnet',
		feedback: { total: 142, verified: 118 },
		score: { average: 4.6, verified_average: 4.8 },
		validation: { passed: 8, failed: 1 },
		tasks: { accepted: 96, disputed: 2 },
		indexed_at: '2026-05-14T17:00:00Z',
	},
	capture_scene: {
		job_id: 'v2s.eyJ2IjoiZXhhbXBsZSJ9.sig',
		status: 'queued',
		source_video_url: 'https://three.ws/cdn/sample-room-walkthrough.mp4',
		mode: 'streaming',
		eta_seconds: 180,
	},
	// Mirrors mintTokenized3dAsset()'s structuredContent in api/_mcp/tools/tokenize.js.
	mint_3d_asset: {
		status: 'minted',
		idempotent: false,
		name: 'Midnight Robot',
		network: 'devnet',
		mint: 'M1ntExamp1eDoNotUse1111111111111111111111111',
		explorer_asset_url: 'https://core.metaplex.com/explorer/M1ntExamp1eDoNotUse1111111111111111111111111?env=devnet',
		explorer_tx_url: 'https://explorer.solana.com/tx/5synthetictransactionsignature111111111111111111111111111111111111111111111111111111?cluster=devnet',
		viewer_url: 'https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2Fcdn%2Favatars%2Fmidnight-robot.glb',
		royalty: { percent: 5, requested_basis_points: 500, cap_basis_points: 1000, capped: false },
	},
	// Mirrors handleAnchor()'s structuredContent in api/_mcp3d/tools/provenance.js.
	anchor_provenance: {
		status: 'anchored',
		glbSha256: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
		credentialHash: '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
		issuer: 'AtteStIssuerExamp1eDoNotUse11111111111111111',
		anchor: {
			tx: '5synthetictransactionsignature111111111111111111111111111111111111111111111111111111',
			cluster: 'devnet',
			explorerUrl: 'https://explorer.solana.com/tx/5synthetictransactionsignature111111111111111111111111111111111111111111111111111111?cluster=devnet',
		},
	},
});

// Wrap a tool result summary in the JSON-RPC CallToolResult envelope.
function mcpResultExample(summary) {
	return {
		jsonrpc: '2.0',
		id: 1,
		result: { content: [{ type: 'text', text: JSON.stringify(summary) }] },
	};
}

// Backfill bazaar.info.output.example on one resource that lacks it, from the
// maps above. Mutates the already-built bazaar extension in place (the root info
// schema permits the extra `output` field — verified against both the REST and
// MCP meta-schemas) and returns the resource so it composes as an array .map().
// Resources that already carry an output example (the /api/mcp + /api/mcp-3d
// transport rows) are left untouched. Agent-published dynamic listings get a
// generic settled-result example so they catalog fully too.
function addOutputExample(r) {
	const info = r?.extensions?.bazaar?.info;
	if (!info || info.output?.example !== undefined) return r;
	let example;
	if (r.toolName && MCP_TOOL_OUTPUT_SUMMARIES[r.toolName]) {
		example = mcpResultExample(MCP_TOOL_OUTPUT_SUMMARIES[r.toolName]);
	} else if (REST_OUTPUT_EXAMPLES[r.path]) {
		example = REST_OUTPUT_EXAMPLES[r.path];
	} else if (typeof r.path === 'string' && r.path.startsWith('/api/x402/service/')) {
		// Agent-published listing: the response shape is the agent's own, so
		// advertise a generic settled envelope rather than a fabricated body.
		example = { ok: true, paid: true, result: {} };
	}
	if (example !== undefined) info.output = { type: 'json', example };
	return r;
}

// Builds the full x402 discovery document served at /.well-known/x402.json.
// Exported so the self-facilitator's GET /discovery/resources action
// (api/x402-facilitator/[action].js) can project the same catalog into the
// facilitator-standard ListDiscoveryResourcesResponse consumed by x402scan's
// crawler — one catalog, two wire formats, no drift.
export async function buildX402DiscoveryDoc() {
	const origin = env.APP_ORIGIN;
	const mcpUrl = `${origin}/api/mcp`;
	const mcp3dUrl = `${origin}/api/mcp-3d`;
	const price = RAW_AMOUNT_TO_USDC(env.X402_MAX_AMOUNT_REQUIRED);

	// Build the MCP accept list (Base + Solana). `resource` is echoed on every
	// accept so reviewers + spend logs can reconcile the entry against the
	// resource it gates without walking back to the parent resource[] entry.
	function buildMcpAccepts(resourceUrl) {
		const out = [];
		// Solana-first platform default — Solana leads, Base follows. Gated on
		// solanaSettleable() so the catalog never advertises a Solana rail the live
		// 402 drops when the self-facilitator's co-signing secret is missing.
		if (env.X402_PAY_TO_SOLANA && solanaSettleable()) {
			out.push({
				scheme: 'exact',
				network: NETWORK_SOLANA_MAINNET,
				network_label: 'solana-mainnet',
				amount: env.X402_MAX_AMOUNT_REQUIRED,
				price,
				payTo: env.X402_PAY_TO_SOLANA,
				asset: env.X402_ASSET_MINT_SOLANA,
				asset_symbol: 'USDC',
				maxTimeoutSeconds: 60,
				resource: resourceUrl,
				extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },
			});
		}
		// Base only when settleable (CDP creds or the X402_ADVERTISE_BASE opt-in) —
		// else the catalog would advertise a rail the live 402 now drops. See baseSettleable().
		if (env.X402_PAY_TO_BASE && baseSettleable()) {
			pushAcceptWithPermit2Sibling(out, {
				scheme: 'exact',
				network: NETWORK_BASE_MAINNET,
				network_label: 'base-mainnet',
				amount: env.X402_MAX_AMOUNT_REQUIRED,
				price,
				payTo: env.X402_PAY_TO_BASE,
				asset: env.X402_ASSET_ADDRESS_BASE,
				asset_symbol: 'USDC',
				maxTimeoutSeconds: 60,
				resource: resourceUrl,
				extra: { name: 'USDC', version: '2', decimals: 6 },
			});
		}
		return out;
	}

	// model-check is CDP-Bazaar-cataloged.
	// CDP supports Base mainnet + Arbitrum One; advertise both here so
	// agentic.market shows the same network options buyers will see in the
	// live 402 challenge. Each EVM entry gets a Permit2 sibling so
	// EIP-2612-aware clients can pick the gasless Permit2-via-EIP-2612 path.
	const ARB_USDC = env.X402_ASSET_ADDRESS_ARBITRUM;
	function buildBazaarAccepts(resourceUrl) {
		const out = [];
		// Solana-first platform default — Solana leads the catalog entry. The
		// Base + Arbitrum accepts still follow so CDP keeps processing an EVM
		// verify+settle for agentic.market cataloging.
		if (env.X402_PAY_TO_SOLANA) {
			out.push({
				scheme: 'exact',
				network: NETWORK_SOLANA_MAINNET,
				network_label: 'solana-mainnet',
				amount: env.X402_MAX_AMOUNT_REQUIRED,
				price,
				payTo: env.X402_PAY_TO_SOLANA,
				asset: env.X402_ASSET_MINT_SOLANA,
				asset_symbol: 'USDC',
				maxTimeoutSeconds: 60,
				resource: resourceUrl,
				extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },
			});
		}
		// Base + Arbitrum are CDP-settled EVM rails; advertise them only when a
		// working facilitator is configured (CDP creds or the X402_ADVERTISE_BASE
		// opt-in). Without one the live 402 drops Base, so an ungated catalog entry
		// would drift and 502.
		if (env.X402_PAY_TO_BASE && baseSettleable()) {
			pushAcceptWithPermit2Sibling(out, {
				scheme: 'exact',
				network: NETWORK_BASE_MAINNET,
				network_label: 'base-mainnet',
				amount: env.X402_MAX_AMOUNT_REQUIRED,
				price,
				payTo: env.X402_PAY_TO_BASE,
				asset: env.X402_ASSET_ADDRESS_BASE,
				asset_symbol: 'USDC',
				maxTimeoutSeconds: 60,
				resource: resourceUrl,
				extra: { name: 'USDC', version: '2', decimals: 6 },
			});
		}
		if (env.X402_PAY_TO_BASE && ARB_USDC && baseSettleable()) {
			pushAcceptWithPermit2Sibling(out, {
				scheme: 'exact',
				network: 'eip155:42161',
				network_label: 'arbitrum-one',
				amount: env.X402_MAX_AMOUNT_REQUIRED,
				price,
				payTo: env.X402_PAY_TO_BASE,
				asset: ARB_USDC,
				asset_symbol: 'USDC',
				maxTimeoutSeconds: 60,
				resource: resourceUrl,
				extra: { name: 'USDC', version: '2', decimals: 6 },
			});
		}
		return out;
	}

	const mcpAccepts = buildMcpAccepts(mcpUrl);
	const mcp3dAccepts = buildMcpAccepts(mcp3dUrl);
	// Service metadata for the two MCP transport entries. Every static
	// /api/x402/* resource entry now derives from the unified service catalog
	// (api/_lib/service-catalog/) — its per-service descriptors carry each
	// route's serviceName/tags, which used to be mapped inline here.
	const mcpService = withService({
		serviceName: 'three.ws MCP',
		tags: ['mcp', '3d', 'gltf', 'solana', 'agent'],
	});

	// USE-13: per-tool MCP catalog entries. Each priced tool is its own
	// catalog row keyed on (resource, toolName) so search can find them
	// individually instead of all hiding behind the parent /api/mcp resource.
	// Built from the live TOOL_CATALOG so adding a new priced tool only
	// requires a pricing entry; the discovery shape follows automatically.
	const mcpToolItems = buildMcpToolItems({
		path: '/api/mcp',
		mcpUrl,
		mcpAccepts,
		mcpService,
		catalog: TOOL_CATALOG,
		priceForTool: priceFor,
	});

	// 3D Studio paid tools — one row per priced tool so "text to 3d" searches
	// on facilitators land on the tool, not just the transport. Service
	// identity comes from STUDIO_CHALLENGE (same source as the live 402).
	const studioService = {
		serviceName: STUDIO_CHALLENGE.serviceName,
		tags: STUDIO_CHALLENGE.tags,
		iconUrl: STUDIO_CHALLENGE.iconUrl,
	};
	const studioToolItems = buildMcpToolItems({
		path: '/api/mcp-3d',
		mcpUrl: mcp3dUrl,
		mcpAccepts: mcp3dAccepts,
		mcpService: studioService,
		catalog: STUDIO_TOOL_CATALOG,
		priceForTool: studioPriceFor,
	});

	// Every static /api/x402/* resource entry, derived from the unified
	// service catalog (one descriptor per service — the single source of truth
	// both storefronts read; see specs/service-catalog.md). The env-aware
	// accepts builders stay here so the advertised rails keep matching the
	// live 402 exactly.
	const x402CatalogItems = toBazaarDiscovery({
		origin,
		extensionsForAccepts,
		acceptsFor(service, url) {
			// model-check is CDP-Bazaar-cataloged: Base + Arbitrum + Solana.
			if (service.acceptsBuilder === 'cdp-bazaar') return buildBazaarAccepts(url);
			if (service.acceptsBuilder === 'permit2-only') {
				// Permit2-only demo: skip the EIP-3009 entry that acceptsForPrice
				// would push first, so SDK clients are forced through the gasless
				// EIP-2612 → settleWithPermit path the endpoint is meant to prove.
				// permit2VariantOf returns null without CDP creds, in which case we
				// omit the resource from discovery (matches the runtime 402 behavior).
				const baseAccept = env.X402_PAY_TO_BASE
					? {
							scheme: 'exact',
							network: NETWORK_BASE_MAINNET,
							network_label: 'base-mainnet',
							amount: service.priceAtomics,
							price: RAW_AMOUNT_TO_USDC(service.priceAtomics),
							payTo: env.X402_PAY_TO_BASE,
							asset: env.X402_ASSET_ADDRESS_BASE,
							asset_symbol: 'USDC',
							maxTimeoutSeconds: 60,
							resource: url,
							extra: { name: 'USD Coin', version: '2', decimals: 6 },
						}
					: null;
				const permit2 = baseAccept ? permit2VariantOf(baseAccept) : null;
				return permit2 ? [permit2] : null;
			}
			return acceptsForPrice(service.priceAtomics, url);
		},
	});

	// Agent-published paid services — dynamic, one entry per active listing.
	const agentServiceItems = await buildAgentServiceItems(origin);
	const sellableAgentItems = await buildSellableAgentItems();
	const datapointItems = await buildDatapointItems(origin);

	return {
		$schema: 'https://x402.org/schemas/discovery.json',
		service: {
			name: 'three.ws',
			legal_name: 'three.ws',
			tagline: '3D generation + crypto data + launch/trust tools for AI agents.',
			description:
				'three.ws — 3D generation + crypto data + launch/trust tools for AI agents. ' +
				'Free Crypto Data API (token snapshots, security checks, holders, whales, trending, wallets — keyless) and free text→3D generation; ' +
				'pay-per-call for Forge Pro, rigged avatars, vanity addresses, pump.fun token launches, and cross-chain trust checks (agent reputation, on-chain identity verify). ' +
				'Reachable as paid REST endpoints (x402 v2) and MCP tool calls. USDC on Solana, Base, and Arbitrum mainnet.',
			operator: 'three.ws',
			mission:
				'Give autonomous agents the tools they reach for mid-task — 3D assets, crypto data, launches, and trust — machine-native over HTTP 402.',
			website: origin,
			docs: `${origin}/docs/start-here`,
			skill_md: `${origin}/.well-known/skill.md`,
			repository: 'https://github.com/nirholas/three.ws',
			contact: `${origin}/`,
			tags: [
				'x402',
				'x402-v2',
				'mcp',
				'agent-first',
				'3d',
				'text-to-3d',
				'crypto-data',
				'trust',
				'token-launch',
				'solana',
				'base',
				'arbitrum',
				'usdc',
			],
			categories: ['3D', 'AI', 'Crypto', 'Data', 'Utility'],
			environment: 'apex',
			origin,
		},
		// `.filter(Boolean)` drops any resource whose IIFE returned null —
		// e.g. permit2-paid-demo is omitted when CDP creds are missing,
		// matching the runtime 402 behavior so we don't catalog a route that
		// would fail at first paid call. The trailing .map(addOutputExample)
		// backfills a realistic response example onto every entry so indexers
		// render and rank each one (no empty result cards, no verifier warnings).
		resources: [
			{
				path: '/api/mcp',
				url: mcpUrl,
				method: 'POST',
				description:
					'MCP 2025-06-18 Streamable HTTP transport — 3D avatar viewer, glTF model validation/inspection/optimization, and Solana agent data exposed as MCP tools. JSON-RPC 2.0 batch-aware. Currency: USDC.',
				mimeType: 'application/json',
				serviceName: mcpService.serviceName,
				tags: mcpService.tags,
				iconUrl: mcpService.iconUrl,
				accepts: mcpAccepts,
				extensions: extensionsForAccepts(mcpAccepts, bazaarExtension()),
				links: {
					openapi: `${origin}/openapi.json`,
					docs: `${origin}/docs/mcp`,
					agent_card: `${origin}/.well-known/agent-card.json`,
					payment_config: `${origin}/.well-known/x402`,
				},
			},
			{
				path: '/api/mcp-3d',
				url: mcp3dUrl,
				method: 'POST',
				description: STUDIO_CHALLENGE.description,
				mimeType: 'application/json',
				serviceName: STUDIO_CHALLENGE.serviceName,
				tags: STUDIO_CHALLENGE.tags,
				iconUrl: STUDIO_CHALLENGE.iconUrl,
				accepts: mcp3dAccepts,
				extensions: extensionsForAccepts(mcp3dAccepts, STUDIO_CHALLENGE.bazaar),
				links: {
					docs: `${origin}/docs/mcp-3d-studio`,
					payment_config: `${origin}/.well-known/x402`,
				},
			},
			// Every static /api/x402/* entry (model-check through wallet-connect),
			// generated from the unified service catalog in catalog order. Editing
			// a listing = editing api/_lib/service-catalog/services/<slug>.js.
			...x402CatalogItems,
			// USE-13: one Bazaar catalog row per priced MCP tool. The shared
			// `/api/mcp` and `/api/mcp-3d` resources above are the transport
			// entries; these are the individual paid tools facilitators
			// index by toolName.
			...mcpToolItems,
			...studioToolItems,
			// Agent-published paid endpoints (monetize_endpoint). Dynamic —
			// one entry per active agent_paid_services listing.
			...agentServiceItems,
			// Whole agents sold as paid APIs (Earn tab switch). Dynamic, one
			// entry per public agent whose owner turned the service on.
			...sellableAgentItems,
			// Datapoint fabric (/api/x402/d/…): a curated, runtime-derived
			// slice of the 400k+ addressable single-datapoint endpoints, so
			// indexers surface the fabric; the full id space is enumerated
			// free at /api/x402/d.
			...datapointItems,
		]
			.filter(Boolean)
			.map(addOutputExample),
	};
}

async function handleX402Discovery(req, res) {
	return json(res, 200, await buildX402DiscoveryDoc(), {
		'cache-control': 'public, max-age=300',
	});
}

// ── dispatcher ────────────────────────────────────────────────────────────────

// LobeChat manifest. Single source of truth is the static file at
// public/lobehub/plugin.json (also served by /api/lobehub/manifest); this
// alias serves it at the /.well-known/chat-plugin.json URL the chat-plugin
// README documents for the LobeChat plugin-store install flow. It previously
// served a hardcoded pre-launch manifest with no `api` tools and no `ui.url`,
// which installed as a plugin that could do nothing.
let lobeChatManifest;
try {
	lobeChatManifest = JSON.parse(
		readFileSync(join(process.cwd(), 'public/lobehub/plugin.json'), 'utf8'),
	);
} catch (err) {
	console.error('[wk/chat-plugin] failed to load manifest', err);
}

function handleChatPlugin(req, res) {
	if (!lobeChatManifest) return error(res, 500, 'internal_error', 'manifest unavailable');
	return json(res, 200, lobeChatManifest, { 'cache-control': 'public, max-age=3600' });
}

// SperaxOS / plugin.delivery manifest. Single source of truth is the static
// file at public/sperax/manifest.json (also served verbatim at /sperax/manifest.json);
// this alias adds cross-origin headers so the marketplace + browser validators
// can fetch it from /.well-known/sperax-plugin.json.
let speraxManifest;
try {
	speraxManifest = JSON.parse(
		readFileSync(join(process.cwd(), 'public/sperax/manifest.json'), 'utf8'),
	);
} catch (err) {
	console.error('[wk/sperax-plugin] failed to load manifest', err);
}

function handleSperaxPlugin(req, res) {
	if (!speraxManifest) return error(res, 500, 'internal_error', 'manifest unavailable');
	return json(res, 200, speraxManifest, { 'cache-control': 'public, max-age=3600' });
}

// ── three-vanity (/.well-known/three-vanity.json) ────────────────────────────
// Publishes the provably-fair vanity grinder's service identity: the long-lived
// Ed25519 public key that signs every verifiable-grind receipt, the protocol
// version, and the scheme ids. The SDK + CLI + /vanity/verify page pin this key
// so a buyer can prove a receipt really came from three.ws. The SECRET seed
// never leaves the server — only the public key is published here.
async function handleThreeVanity(req, res) {
	let identity;
	try {
		const mod = await import('./_lib/vanity-service-key.js');
		identity = await mod.getServiceIdentity();
	} catch (err) {
		console.error('[wk/three-vanity] service key unavailable', err?.message || err);
		return error(res, 500, 'service_key_unavailable', 'vanity service key not configured');
	}
	const origin = env.APP_ORIGIN;
	return json(
		res,
		200,
		{
			protocol: 'three-vanity/v1',
			protocols: ['three-vanity/v1', 'three-pog/v1'],
			description:
				'Provably-fair Solana vanity grinding. Keys are ground under a commit-reveal ' +
				'seed-mixing protocol (three-vanity/v1) and/or attested with a proof-of-grind ' +
				'certificate (three-pog/v1). Both are signed by the attestation key below and ' +
				'verified entirely client-side — nothing here is trusted, everything is recomputed.',
			serviceKey: {
				curve: 'ed25519',
				keyId: identity.keyId,
				publicKeyBase58: identity.publicKeyBase58,
				publicKeyHex: identity.publicKeyHex,
				use: 'receipt-signing, proof-of-grind-attestation',
			},
			// Rotation-aware verifier keyring: the set of attestation keys a verifier
			// should accept. On rotation, the retiring key stays here (with a
			// `retired` flag/date) until all in-flight certs age out, so historical
			// proofs keep verifying. Today there is one active key.
			keyring: [
				{
					keyId: identity.keyId,
					curve: 'ed25519',
					publicKeyBase58: identity.publicKeyBase58,
					status: 'active',
				},
			],
			schemes: {
				commitment: 'sha256(domain‖serverSeed)',
				seedMix: 'hkdf-sha256(serverSeed‖clientSeed‖requestNonce)',
				candidate: 'hmac-sha256(masterSeed, domain‖uint64_be(index)) → ed25519 seed',
				signature: 'ed25519',
				sealedEnvelope: 'x25519-hkdf-sha256-aes256gcm/v1',
				proofOfGrind: 'ed25519 over canonical(three-pog/cert/v1 ‖ sorted-json(core))',
				splitKeyNonCustody: 'P1 + a2·B == address (recomputed from public points)',
			},
			endpoints: {
				grind: `${origin}/api/x402/vanity`,
				verifiableGrind: `${origin}/api/x402/vanity-verifiable`,
				certRegistry: `${origin}/api/vanity/cert`,
				verifyPage: `${origin}/vanity/verify`,
			},
			documentation: `${origin}/vanity/verify`,
			protocolSpec: 'https://github.com/nirholas/three.ws/blob/main/docs/PROTOCOL-vanity.md',
		},
		{ 'cache-control': 'public, max-age=300' },
	);
}

// ── apple-app-site-association (/.well-known/apple-app-site-association) ──────
//
// The file iOS fetches to decide whether a https://three.ws link opens the app
// instead of Safari (universal links) and whether the login form in the app's
// WebView may offer a saved three.ws password (webcredentials). Apple's CDN
// requires it over TLS at exactly this path, with no redirect, no .json
// extension, and a JSON content type; every one of those is why it is served
// from here rather than dropped in public/.well-known/ next to assetlinks.json,
// which the static route would hand back with the wrong headers.
//
// The app identifier is "<TeamID>.<bundle id>" and the Team ID is only knowable
// once the Apple Developer account exists, so it comes from APPLE_TEAM_ID on the
// Cloud Run service. Until that is set the endpoint answers 503 rather than
// publishing an association for a team that cannot sign anything: a wrong
// appIDs entry fails silently on device (links just keep opening in Safari),
// and an honest 503 is the only version of this that is debuggable.
const IOS_BUNDLE_ID = 'ws.three.app';

function handleAppleAppSiteAssociation(req, res) {
	const teamId = env.APPLE_TEAM_ID;
	if (!teamId) {
		return error(
			res,
			503,
			'not_configured',
			'APPLE_TEAM_ID is not set on this deployment, so no app association can be published',
		);
	}
	const appId = `${teamId}.${IOS_BUNDLE_ID}`;
	return json(
		res,
		200,
		{
			applinks: {
				details: [
					{
						appIDs: [appId],
						components: [
							// The API is data, not a screen. Handing /api/* to the app
							// would swallow OAuth redirects and x402 callbacks that have
							// to complete in the browser that started them.
							{ '/': '/api/*', exclude: true, comment: 'API surface stays in the browser' },
							// Embeds are meant to render inside someone else's page.
							{ '/': '/embed*', exclude: true, comment: 'third-party embeds stay on the web' },
							{ '/': '/widget*', exclude: true, comment: 'third-party embeds stay on the web' },
							{ '/': '/*' },
						],
					},
				],
			},
			webcredentials: { apps: [appId] },
		},
		{
			// Apple caches this aggressively at the CDN either way; a short TTL keeps
			// a Team ID correction from taking a day to reach devices.
			'cache-control': 'public, max-age=300',
		},
	);
}

const DISPATCH = {
	'agent-attestation-schemas': handleAttestationSchemas,
	'three-vanity': handleThreeVanity,
	'chat-plugin': handleChatPlugin,
	'sperax-plugin': handleSperaxPlugin,
	'oauth-authorization-server': handleOauthAuthServer,
	'oauth-protected-resource': handleOauthProtectedResource,
	x402: handleX402,
	'x402-discovery': handleX402Discovery,
	'apple-app-site-association': handleAppleAppSiteAssociation,
};

// Public discovery docs (x402, x402-discovery, chat-plugin, agent-attestation-schemas)
// must be readable cross-origin so browser-based validators (agentic.market,
// x402scan, bazaar) can fetch them. OAuth metadata stays restricted.
const PUBLIC_DISCOVERY = new Set([
	'x402',
	'x402-discovery',
	'chat-plugin',
	'sperax-plugin',
	'agent-attestation-schemas',
	'three-vanity',
]);

export default wrap(async (req, res) => {
	const name = req.query?.name ?? new URL(req.url, 'http://x').searchParams.get('name');
	const corsOpts = PUBLIC_DISCOVERY.has(name)
		? { methods: 'GET,OPTIONS', origins: '*' }
		: { methods: 'GET,OPTIONS' };
	if (cors(req, res, corsOpts)) return;
	if (!method(req, res, ['GET'])) return;
	const fn = Object.hasOwn(DISPATCH, name) ? DISPATCH[name] : null;
	// Echo at most a label's worth of the caller's input. Unbounded reflection let
	// a 5 KB ?name= come straight back in the 404 body (and into the access log),
	// which is free amplification for anyone pointing a scraper at /.well-known.
	if (!fn) return error(res, 404, 'not_found', `unknown well-known resource: ${String(name ?? 'null').slice(0, 64)}`);
	return fn(req, res);
});