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.

20.3 KB
Raw Blame
// x402 Bazaar discovery client.
//
// Talks directly to facilitator `/discovery/resources` endpoints (HTTP GET).
// No SDK dependency: the wire format is stable enough to consume with fetch.
// We normalize items returned by both spec versions:
//   - v1 facilitators (PayAI): flat shape, network strings like "base"/"solana"
//   - v2 facilitators (CDP):   `extensions.bazaar.info`, CAIP-2 networks
//
// Search is implemented client-side as a text query over normalized items
// because none of the public facilitators expose a server-side search route.
// Multi-facilitator merging dedupes HTTP by `resource` and MCP by
// `(resource, toolName)` per spec.

import { fetchSafePublicUrlPinned } from '../ssrf-guard.js';

const DEFAULT_FACILITATORS = (() => {
	const list = [];
	const base = process.env.X402_FACILITATOR_URL_BASE || 'https://facilitator.payai.network';
	const cdp = process.env.X402_CDP_FACILITATOR_URL || 'https://api.cdp.coinbase.com/platform/v2/x402';
	const sol = process.env.X402_FACILITATOR_URL_SOLANA;
	list.push(base);
	if (cdp && cdp !== base) list.push(cdp);
	if (sol && !list.includes(sol)) list.push(sol);
	return list;
})();

const COMMON_ASSETS = {
	// Base USDC
	'0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': { symbol: 'USDC', decimals: 6 },
	// Solana USDC
	epjfwdd5aufqssqem2qn1xzybapc8g4weggkzwytdt1v: { symbol: 'USDC', decimals: 6 },
	// Optimism USDC
	'0x0b2c639c533813f4aa9d7837caf62653d097ff85': { symbol: 'USDC', decimals: 6 },
	// Arbitrum USDC
	'0xaf88d065e77c8cc2239327c5edb3a432268e5831': { symbol: 'USDC', decimals: 6 },
	// Polygon USDC
	'0x3c499c542cef5e3811e1192ce70d8cc03d5c3359': { symbol: 'USDC', decimals: 6 },
};

function normalizeNetwork(net) {
	if (!net) return '';
	const n = String(net).toLowerCase();
	if (n === 'base') return 'eip155:8453';
	if (n === 'base-sepolia') return 'eip155:84532';
	if (n === 'arbitrum') return 'eip155:42161';
	if (n === 'optimism') return 'eip155:10';
	if (n === 'polygon') return 'eip155:137';
	if (n === 'solana') return 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
	if (n === 'solana-devnet') return 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';
	return n;
}

function networkFamily(net) {
	const n = normalizeNetwork(net);
	if (n.startsWith('eip155:')) return 'evm';
	if (n.startsWith('solana')) return 'solana';
	return 'unknown';
}

function assetInfo(asset) {
	if (!asset) return { symbol: '', decimals: 6 };
	const meta = COMMON_ASSETS[String(asset).toLowerCase()];
	return meta || { symbol: '', decimals: 6 };
}

function pickAmount(accept) {
	// v2 spec uses `amount`; v1 PayAI uses `maxAmountRequired`.
	return accept?.amount ?? accept?.maxAmountRequired ?? '0';
}

// Convert atomic units to a human string. We don't trust the decimals when
// unknown, so fall back to USDC 6dp which is the common case in practice.
function formatPrice(atomic, asset) {
	const { symbol, decimals } = assetInfo(asset);
	const n = Number(atomic) / 10 ** decimals;
	let str;
	if (n === 0) str = '0';
	else if (n < 0.01) str = n.toFixed(6).replace(/0+$/, '').replace(/\.$/, '');
	else if (n < 1) str = n.toFixed(4).replace(/0+$/, '').replace(/\.$/, '');
	else str = n.toFixed(2);
	return symbol ? `${str} ${symbol}` : str;
}

// Normalize one raw item into a stable shape. We keep the original under
// `raw` so callers needing facilitator-specific fields still have them.
export function normalizeItem(item, facilitator) {
	if (!item || typeof item !== 'object') return null;
	const accepts = Array.isArray(item.accepts) ? item.accepts : [];
	const primary = accepts[0] || {};

	const bazaarExt = item?.extensions?.bazaar || null;
	const bazaarInfo = bazaarExt?.info || item?.inputSchema || null;
	const input = bazaarInfo?.input || bazaarInfo || null;
	const isMcp = input?.type === 'mcp';
	const toolName = isMcp ? input?.toolName || '' : '';

	const resourceUrl =
		typeof item.resource === 'string'
			? item.resource
			: item.resource?.url || primary?.resource || '';

	const resourceMeta = typeof item.resource === 'object' ? item.resource : {};
	const serviceMeta = bazaarInfo?.service || {};
	// The v1 ListDiscoveryResourcesResponse carries the human-facing fields on
	// `metadata`, which is where our own facilitator publishes them and where
	// the legacy DiscoveredResource schema puts them. Reading only the bazaar
	// extension left every metadata-carrying listing nameless, tagless and
	// iconless in every consumer of this client: /economy rendered seventeen
	// three.ws services as an anonymous row called "Service".
	const listMeta = item.metadata && typeof item.metadata === 'object' ? item.metadata : {};
	const description =
		item.description ||
		resourceMeta.description ||
		listMeta.description ||
		serviceMeta.description ||
		bazaarExt?.description ||
		primary?.description ||
		'';
	const serviceName =
		resourceMeta.serviceName ||
		resourceMeta.name ||
		listMeta.serviceName ||
		listMeta.name ||
		serviceMeta.name ||
		bazaarExt?.name ||
		'';
	const iconUrl =
		resourceMeta.iconUrl ||
		resourceMeta.icon ||
		listMeta.iconUrl ||
		listMeta.icon ||
		serviceMeta.icon ||
		serviceMeta.iconUrl ||
		bazaarExt?.icon ||
		bazaarExt?.iconUrl ||
		'';
	const rawTags =
		(Array.isArray(resourceMeta.tags) && resourceMeta.tags) ||
		(Array.isArray(item.tags) && item.tags) ||
		(Array.isArray(listMeta.tags) && listMeta.tags) ||
		(Array.isArray(serviceMeta.tags) && serviceMeta.tags) ||
		(Array.isArray(bazaarExt?.tags) && bazaarExt.tags) ||
		[];
	const category = bazaarExt?.category || serviceMeta.category || listMeta.category || resourceMeta.category;
	const tags = category && !rawTags.includes(category) ? [category, ...rawTags] : rawTags;

	const normalizedAccepts = accepts.map((a) => {
		const net = normalizeNetwork(a.network);
		const amount = pickAmount(a);
		return {
			...a,
			network: net,
			networkRaw: a.network,
			amount,
			amountAtomic: amount,
			family: networkFamily(a.network),
			assetInfo: assetInfo(a.asset),
			priceLabel: formatPrice(amount, a.asset),
		};
	});

	const minAtomic = normalizedAccepts.reduce((min, a) => {
		const n = Number(a.amountAtomic);
		return Number.isFinite(n) && (min == null || n < min) ? n : min;
	}, null);
	const minAccept = normalizedAccepts.find((a) => Number(a.amountAtomic) === minAtomic) || normalizedAccepts[0];

	const extensionsList = item.extensions ? Object.keys(item.extensions) : [];
	const method =
		item.method ||
		input?.method ||
		listMeta.method ||
		primary?.method ||
		(isMcp ? 'MCP' : '');

	return {
		type: item.type || (isMcp ? 'mcp' : 'http'),
		resource: resourceUrl,
		toolName,
		uniqueKey: isMcp ? `${resourceUrl}#${toolName}` : resourceUrl,
		serviceName,
		description,
		iconUrl,
		tags,
		method,
		accepts: normalizedAccepts,
		minPriceAtomic: minAtomic,
		minPriceLabel: minAccept ? minAccept.priceLabel : '',
		families: [...new Set(normalizedAccepts.map((a) => a.family))],
		networks: [...new Set(normalizedAccepts.map((a) => a.network))],
		extensions: extensionsList,
		input,
		output: bazaarInfo?.output || null,
		lastUpdated: item.lastUpdated || null,
		facilitator,
		raw: item,
	};
}

// Ceiling on one discovery page from a caller-named facilitator.
const UNTRUSTED_PAGE_MAX_BYTES = 8 * 1024 * 1024;

async function fetchJson(url, { timeoutMs = 15000, untrusted = false } = {}) {
	const ctrl = new AbortController();
	const t = setTimeout(() => ctrl.abort(), timeoutMs);
	try {
		const init = {
			method: 'GET',
			headers: { accept: 'application/json' },
			signal: ctrl.signal,
		};
		// A facilitator URL named by the caller (`?facilitators=` on the public
		// bazaar routes) is fetched through the pinned SSRF guard: https only, no
		// private or metadata address on any redirect hop, bytes capped. Without
		// it the route was an unauthenticated proxy into internal hosts that
		// echoed the response back in the error text.
		const r = untrusted
			? await fetchSafePublicUrlPinned(url, init, { maxBytes: UNTRUSTED_PAGE_MAX_BYTES })
			: await fetch(url, init);
		if (!r.ok) {
			const body = await r.text().catch(() => '');
			throw Object.assign(new Error(`facilitator ${r.status} ${r.statusText}: ${body.slice(0, 200)}`), {
				status: r.status,
				facilitator: url,
			});
		}
		return await r.json();
	} finally {
		clearTimeout(t);
	}
}

// Identity of a raw (pre-normalization) discovery item, mirroring the
// `uniqueKey` normalizeItem() derives. Used only to spot a facilitator that
// replays the same page; the authoritative dedupe still happens in list().
function rawItemKey(item) {
	const url = typeof item?.resource === 'string' ? item.resource : item?.resource?.url || '';
	const info = item?.extensions?.bazaar?.info || item?.inputSchema || null;
	const input = info?.input || info || null;
	const tool = input?.type === 'mcp' ? input?.toolName || '' : '';
	return tool ? `${url}#${tool}` : url;
}

// Page through a facilitator's /discovery/resources. We stop at `maxItems`
// (default 500) to keep responses bounded. Operators that need everything can
// raise the cap explicitly.
async function listOneFacilitator(facilitatorUrl, { type, limit, maxItems, untrusted = false }) {
	const items = [];
	const seen = new Set();
	const pageSize = Math.min(200, Math.max(1, limit || 200));
	let offset = 0;
	let total = null;
	while (items.length < maxItems) {
		const u = new URL(facilitatorUrl.replace(/\/$/, '') + '/discovery/resources');
		if (type) u.searchParams.set('type', type);
		u.searchParams.set('limit', String(pageSize));
		u.searchParams.set('offset', String(offset));
		const body = await fetchJson(u.toString(), { untrusted });
		const got = Array.isArray(body?.items) ? body.items : Array.isArray(body) ? body : [];
		if (got.length === 0) break;
		let fresh = 0;
		for (const it of got) {
			const k = rawItemKey(it);
			if (k && !seen.has(k)) {
				seen.add(k);
				fresh++;
			}
			items.push(it);
		}
		if (body?.pagination?.total != null) total = body.pagination.total;
		offset += got.length;
		// A facilitator that ignores `offset` replays page one forever, which
		// turned a small `limit` into hundreds of identical round trips. Stop as
		// soon as a page carries nothing we have not already collected.
		if (fresh === 0) break;
		// Stop if facilitator returned fewer than requested (last page).
		if (got.length < pageSize) break;
		// Or if we've reached the reported total.
		if (total != null && offset >= total) break;
	}
	// One page can exceed the cap when a facilitator ignores `limit`, so enforce
	// the bound on the way out instead of trusting the loop guard.
	return items.length > maxItems ? items.slice(0, maxItems) : items;
}

const CATALOG_TTL_MS = Math.max(0, Number(process.env.BAZAAR_CATALOG_TTL_MS) || 60_000);
const catalogMemo = new Map();

// The memo key carries caller-chosen facilitators, limit and maxItems, and
// /api/bazaar/list is anonymous, so without a bound every distinct query would
// pin its own multi-MB catalog in memory until the process fell over. The
// platform's own views use a handful of keys; anything past this cap evicts the
// oldest entry (Map iteration is insertion order).
const CATALOG_MEMO_MAX = 16;

function rememberCatalog(key, entry, now) {
	for (const [k, v] of catalogMemo) {
		if (now - v.at >= CATALOG_TTL_MS) catalogMemo.delete(k);
	}
	catalogMemo.delete(key);
	while (catalogMemo.size >= CATALOG_MEMO_MAX) {
		catalogMemo.delete(catalogMemo.keys().next().value);
	}
	catalogMemo.set(key, entry);
}

// Callers filter and sort what they get back, so hand out fresh array wrappers
// around the shared item objects rather than the memo's own arrays.
function shallowCopy(result) {
	return {
		items: [...(result.items || [])],
		sources: [...(result.sources || [])],
		errors: [...(result.errors || [])],
	};
}

// Drop every memoized catalog. Used by tests and by the catalog-refresh
// pipeline, which must observe a facilitator change immediately.
export function clearCatalogCache() {
	catalogMemo.clear();
}

// Bazaar client. Stateless aside from the configured facilitator list.
export class Bazaar {
	// `untrusted: true` marks a facilitator list that came from a request rather
	// than from configuration; every fetch to it then goes through the SSRF guard.
	constructor({ facilitators, untrusted = false } = {}) {
		const custom = Array.isArray(facilitators) && facilitators.length;
		const urls = custom ? facilitators : DEFAULT_FACILITATORS;
		this.facilitators = urls.filter(Boolean);
		this.untrusted = Boolean(custom && untrusted);
	}

	async list({ type = 'http', limit = 200, maxItems = 500 } = {}) {
		const settled = await Promise.allSettled(
			this.facilitators.map(async (f) => {
				const items = await listOneFacilitator(f, { type, limit, maxItems, untrusted: this.untrusted });
				const normalized = items.map((it) => normalizeItem(it, f)).filter(Boolean);
				// Some facilitators (PayAI) ignore the `type` query param and return
				// HTTP items regardless. Apply the filter ourselves so callers get a
				// consistent catalog.
				return normalized.filter((it) => it.type === type);
			}),
		);
		const items = [];
		const sources = [];
		const errors = [];
		const seen = new Map(); // uniqueKey → index in items
		for (let i = 0; i < settled.length; i++) {
			const f = this.facilitators[i];
			const r = settled[i];
			if (r.status !== 'fulfilled') {
				errors.push({ facilitator: f, error: String(r.reason?.message || r.reason || 'error') });
				sources.push({ facilitator: f, count: 0, ok: false });
				continue;
			}
			let added = 0;
			for (const it of r.value) {
				if (!it.uniqueKey) continue;
				const existing = seen.get(it.uniqueKey);
				if (existing == null) {
					seen.set(it.uniqueKey, items.length);
					items.push(it);
					added++;
				} else {
					// Prefer the entry with richer bazaar metadata when deduping.
					const prev = items[existing];
					if (!prev.description && it.description) items[existing] = it;
				}
			}
			sources.push({ facilitator: f, count: added, ok: true });
		}
		return { items, sources, errors };
	}

	async search({ query, type = 'http', maxItems = 500 } = {}) {
		const q = String(query || '').trim().toLowerCase();
		// Scoring is local, so search rides the same memoized catalog as the
		// aggregate views; list() stays the uncached primitive for the pipelines
		// that snapshot the catalog.
		const { items, sources, errors } = await this.listCached({ type, maxItems });
		if (!q) return { resources: items, sources, errors };
		const terms = q.split(/\s+/g).filter(Boolean);
		const scored = items
			.map((it) => ({ it, score: scoreItem(it, terms) }))
			.filter((x) => x.score > 0)
			.sort((a, b) => b.score - a.score)
			.map((x) => x.it);
		return { resources: scored, sources, errors };
	}

	// Same catalog as list(), memoized per (facilitators, type, maxItems) for
	// CATALOG_TTL_MS. The aggregate views (/api/bazaar/providers, /arbitrage,
	// /context) each sweep the full http + mcp catalog across every facilitator,
	// which measured ~15s per request against the live facilitators; one shared
	// in-process sweep per minute makes those pages interactive. In-process on
	// purpose: the merged catalog is tens of MB, far past what belongs in Redis.
	// Concurrent callers share the in-flight promise, so a cold instance under
	// load makes one sweep, not one per request.
	async listCached({ type = 'http', limit = 200, maxItems = 500 } = {}) {
		const key = `${this.facilitators.join('|')}::${type}::${limit}::${maxItems}`;
		const hit = catalogMemo.get(key);
		const now = Date.now();
		if (hit && now - hit.at < CATALOG_TTL_MS) return shallowCopy(await hit.promise);
		const promise = this.list({ type, limit, maxItems });
		rememberCatalog(key, { at: now, promise }, now);
		try {
			return shallowCopy(await promise);
		} catch (e) {
			// A failed sweep must not be served for the rest of the TTL.
			if (catalogMemo.get(key)?.promise === promise) catalogMemo.delete(key);
			throw e;
		}
	}

	// Look up a single resource by URL (and optional MCP tool name).
	async get(resourceUrl, { toolName } = {}) {
		const key = toolName ? `${resourceUrl}#${toolName}` : resourceUrl;
		const type = toolName ? 'mcp' : 'http';
		const { items } = await this.list({ type, maxItems: 1000 });
		return items.find((it) => it.uniqueKey === key) || null;
	}
}

function scoreItem(it, terms) {
	const hay = [it.serviceName, it.description, it.resource, it.toolName, ...(it.tags || [])]
		.filter(Boolean)
		.join(' ')
		.toLowerCase();
	let score = 0;
	for (const t of terms) {
		if (!hay.includes(t)) return 0;
		// Title/tag hits are worth more than generic hits.
		if (it.serviceName && it.serviceName.toLowerCase().includes(t)) score += 4;
		if (it.tags?.some((tag) => tag.toLowerCase().includes(t))) score += 3;
		if (it.toolName && it.toolName.toLowerCase().includes(t)) score += 3;
		if (it.description && it.description.toLowerCase().includes(t)) score += 2;
		score += 1;
	}
	return score;
}

// ---- Filtering helpers ----

// Parse an atomic-unit price cap (a non-negative integer in the asset's smallest
// unit, e.g. 10000 = 0.01 USDC). Returns null when the value is not one, so an
// HTTP boundary can answer 400 instead of letting BigInt's raw SyntaxError blow
// up the request: a user-supplied `maxPrice=0.01` used to 500 /api/bazaar/list,
// /api/bazaar/search and /api/agenc/x402-services, and to silently empty the
// whole services lane of /api/agora/board.
export function parseAtomicAmount(value) {
	const s = String(value ?? '').trim();
	if (!/^\d+$/.test(s)) return null;
	return BigInt(s);
}

export function filterByMaxPrice(items, atomicMax, asset = null) {
	const max = parseAtomicAmount(atomicMax);
	if (max === null) {
		throw new TypeError(`maxPrice must be an atomic (integer) amount, got "${atomicMax}"`);
	}
	// `a.asset` is the raw on-chain identifier (a contract address on EVM, a mint
	// on Solana). Every caller's docs tell users to pass a SYMBOL ("USDC"), which
	// would have matched nothing, so accept either form.
	const wantAsset = asset ? String(asset).toLowerCase() : null;
	return items.filter((it) =>
		it.accepts.some((a) => {
			if (wantAsset) {
				const raw = String(a.asset || '').toLowerCase();
				const symbol = assetInfo(a.asset).symbol.toLowerCase();
				if (raw !== wantAsset && symbol !== wantAsset) return false;
			}
			try {
				return BigInt(a.amountAtomic || 0) <= max;
			} catch {
				return false;
			}
		}),
	);
}

export function filterByNetwork(items, pattern) {
	if (!pattern) return items;
	const re = patternToRegex(pattern);
	return items.filter((it) => it.networks.some((n) => re.test(n)));
}

function patternToRegex(pattern) {
	if (pattern instanceof RegExp) return pattern;
	// support wildcards like "eip155:*" or "solana:*"
	// `*` is the ONLY wildcard; every other regex metacharacter is escaped to a
	// literal. `?` used to be left unescaped, so a user-supplied `network=?`
	// compiled to /^?$/ and threw "Nothing to repeat", 500ing /api/bazaar/list,
	// /api/bazaar/search, /api/agora and the bazaar MCP discovery tools. A
	// pattern that matches no network must return no items, not an error.
	const escaped = String(pattern)
		.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
		.replace(/\*/g, '.*');
	return new RegExp(`^${escaped}$`, 'i');
}

export function filterByExtension(items, extensionName) {
	if (!extensionName) return items;
	return items.filter((it) => it.extensions.includes(extensionName));
}

export function filterByTag(items, tag) {
	if (!tag) return items;
	const t = String(tag).toLowerCase();
	return items.filter((it) => (it.tags || []).some((x) => String(x).toLowerCase() === t));
}

export function groupBy(items, key) {
	const out = new Map();
	for (const it of items) {
		const k = typeof key === 'function' ? key(it) : it[key] ?? '';
		if (!out.has(k)) out.set(k, []);
		out.get(k).push(it);
	}
	return out;
}

export function sortByPriceAsc(items) {
	return [...items].sort((a, b) => {
		const av = a.minPriceAtomic ?? Number.MAX_SAFE_INTEGER;
		const bv = b.minPriceAtomic ?? Number.MAX_SAFE_INTEGER;
		return av - bv;
	});
}

// True when every facilitator we asked failed. list() resolves partial
// failures internally (Promise.allSettled), so without this check a total
// outage reaches callers as an empty catalog, and an empty catalog reads as
// "no such service exists" rather than "discovery is down".
export function allSourcesFailed(...results) {
	const sources = results.flatMap((r) => r?.sources || []);
	return sources.length > 0 && sources.every((s) => !s.ok);
}

export function sourceErrorText(...results) {
	const errs = results.flatMap((r) => r?.errors || []);
	return errs.map((e) => `${e.facilitator}: ${e.error}`).join('; ') || 'no facilitator answered';
}

export function defaultFacilitators() {
	return [...DEFAULT_FACILITATORS];
}