Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// 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];
}