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
// Contract tests for the five /api/bazaar/* handlers and the discovery client
// they share (api/_lib/x402/bazaar-client.js).
//
// The facilitators are stubbed at `fetch`, so every layer under it runs for
// real: pagination, cross-facilitator dedupe, normalization, filtering, the
// per-endpoint caps, and the failure paths. These cover the defects the
// 2026-08-10 audit found against the live catalog:
// - `limit` on /api/bazaar/list reached only the facilitator page size, so a
// caller asking for 20 endpoints got the entire catalog.
// - `maxItems` bounded nothing when a facilitator ignored `limit`.
// - A facilitator that ignores `offset` replayed page one until `maxItems`,
// turning one small query into hundreds of identical round trips.
// - /api/bazaar/providers?host= returned every listing (10 MB for the
// largest provider in the live catalog).
// - An explicit `minProviders` was ignored whenever two facilitators listed
// the same single-host capability.
// - A total facilitator outage surfaced as an empty 200 catalog, which reads
// as "no such service exists".
import { describe, it, expect, beforeEach, afterAll } from 'vitest';
const FAC_A = 'https://fac-a.test';
const FAC_B = 'https://fac-b.test';
process.env.X402_FACILITATOR_URL_BASE = FAC_A;
process.env.X402_CDP_FACILITATOR_URL = FAC_B;
delete process.env.X402_FACILITATOR_URL_SOLANA;
const USDC_BASE = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
function httpItem({ resource, name, amount, category = 'data', description = 'A paid endpoint.' }) {
return {
type: 'http',
resource,
description,
accepts: [
{
scheme: 'exact',
network: 'base',
maxAmountRequired: String(amount),
asset: USDC_BASE,
payTo: '0x00000000000000000000000000000000000000a1',
},
],
extensions: { bazaar: { name, category } },
};
}
function mcpItem({ resource, toolName, amount }) {
return {
type: 'mcp',
resource,
description: `MCP tool ${toolName}.`,
accepts: [
{
scheme: 'exact',
network: 'base',
maxAmountRequired: String(amount),
asset: USDC_BASE,
payTo: '0x00000000000000000000000000000000000000a2',
},
],
extensions: { bazaar: { name: toolName, info: { input: { type: 'mcp', toolName } } } },
};
}
// alpha.example sells five endpoints; beta.example sells the same weather
// capability at 10x the price (the arbitrage case) plus one of its own.
const ALPHA_WEATHER = httpItem({
resource: 'https://alpha.example/api/weather-forecast',
name: 'Weather Forecast',
amount: 5_000,
category: 'weather',
});
const CATALOG = {
[FAC_A]: [
ALPHA_WEATHER,
httpItem({ resource: 'https://alpha.example/api/notes', name: 'Notes Store', amount: 1_000 }),
httpItem({ resource: 'https://alpha.example/api/geocode', name: 'Geocoder', amount: 2_000 }),
httpItem({ resource: 'https://alpha.example/api/ocr', name: 'OCR Reader', amount: 3_000 }),
httpItem({ resource: 'https://alpha.example/api/translate', name: 'Translator', amount: 4_000 }),
httpItem({
resource: 'https://beta.example/api/weather-forecast',
name: 'Weather Forecast',
amount: 50_000,
category: 'weather',
}),
mcpItem({ resource: 'https://alpha.example/mcp', toolName: 'summarize', amount: 900 }),
],
// Same weather listing as fac-a (dedupe), plus one fac-b exclusive.
[FAC_B]: [
ALPHA_WEATHER,
httpItem({ resource: 'https://gamma.example/api/quotes', name: 'Quote Feed', amount: 7_000 }),
],
};
let fetchCalls = [];
let failAll = false;
let replayOffsets = false;
const realFetch = globalThis.fetch;
globalThis.fetch = async (input) => {
const raw = typeof input === 'string' ? input : input?.url || String(input);
const u = new URL(raw);
const origin = `${u.protocol}//${u.host}`;
fetchCalls.push(raw);
if (!(origin in CATALOG)) {
// Anything else (the LLM chain in /api/bazaar/context) must not reach the
// network from a test: refusing it exercises the deterministic fallback.
throw new Error(`blocked network call to ${origin}`);
}
if (failAll) return new Response('facilitator down', { status: 503 });
const type = u.searchParams.get('type') || 'http';
const limit = Number(u.searchParams.get('limit') || 200);
const offset = replayOffsets ? 0 : Number(u.searchParams.get('offset') || 0);
const all = CATALOG[origin].filter((i) => i.type === type);
return new Response(
JSON.stringify({ items: all.slice(offset, offset + limit), pagination: { total: all.length } }),
{ status: 200, headers: { 'content-type': 'application/json' } },
);
};
afterAll(() => {
globalThis.fetch = realFetch;
});
const { default: listHandler } = await import('../../api/bazaar/list.js');
const { default: searchHandler } = await import('../../api/bazaar/search.js');
const { default: providersHandler } = await import('../../api/bazaar/providers.js');
const { default: arbitrageHandler } = await import('../../api/bazaar/arbitrage.js');
const { default: contextHandler } = await import('../../api/bazaar/context.js');
const { Bazaar, clearCatalogCache, normalizeItem } = await import('../../api/_lib/x402/bazaar-client.js');
let ipCounter = 0;
function makeReq({ url, method = 'GET' } = {}) {
ipCounter++;
return {
method,
url,
headers: { 'x-forwarded-for': `198.51.100.${ipCounter % 250}` },
socket: { remoteAddress: `198.51.100.${ipCounter % 250}` },
};
}
function makeRes() {
return {
statusCode: 200,
headers: {},
body: '',
writableEnded: false,
headersSent: false,
setHeader(k, v) {
this.headers[k.toLowerCase()] = v;
},
getHeader(k) {
return this.headers[k.toLowerCase()];
},
end(chunk) {
if (chunk !== undefined) this.body += chunk;
this.writableEnded = true;
this.headersSent = true;
},
};
}
async function invoke(handler, url, method = 'GET') {
const res = makeRes();
await handler(makeReq({ url, method }), res);
let payload = null;
if (res.body) {
try {
payload = JSON.parse(res.body);
} catch {
payload = res.body;
}
}
return { status: res.statusCode, payload, headers: res.headers };
}
beforeEach(() => {
fetchCalls = [];
failAll = false;
replayOffsets = false;
// The handlers share an in-process catalog memo; each case configures its
// own facilitator behaviour, so start every one from a cold catalog.
clearCatalogCache();
});
describe('GET /api/bazaar/list', () => {
it('merges facilitators, dedupes by resource, and reports both sources', async () => {
const { status, payload } = await invoke(listHandler, '/api/bazaar/list');
expect(status).toBe(200);
// 6 HTTP listings on fac-a + 1 exclusive on fac-b; the shared weather
// listing must appear exactly once.
expect(payload.count).toBe(7);
const weather = payload.items.filter(
(i) => i.resource === 'https://alpha.example/api/weather-forecast',
);
expect(weather).toHaveLength(1);
expect(payload.sources.map((s) => s.ok)).toEqual([true, true]);
expect(payload.errors).toEqual([]);
});
it('caps the response at `limit` and reports the pre-cut total', async () => {
const { status, payload } = await invoke(listHandler, '/api/bazaar/list?limit=2');
expect(status).toBe(200);
expect(payload.items).toHaveLength(2);
expect(payload.count).toBe(2);
expect(payload.total).toBe(7);
});
it('pages past `limit` with `offset` and never repeats a row', async () => {
const first = await invoke(listHandler, '/api/bazaar/list?limit=3');
const second = await invoke(listHandler, '/api/bazaar/list?limit=3&offset=3');
const third = await invoke(listHandler, '/api/bazaar/list?limit=3&offset=6');
expect(first.payload.offset).toBe(0);
expect(second.payload.offset).toBe(3);
expect(second.payload.total).toBe(7);
expect(third.payload.count).toBe(1);
const walked = [...first.payload.items, ...second.payload.items, ...third.payload.items]
.map((i) => i.uniqueKey);
expect(walked).toHaveLength(7);
expect(new Set(walked).size).toBe(7);
// Past the end is an empty page, not the first page over again.
const past = await invoke(listHandler, '/api/bazaar/list?limit=3&offset=99');
expect(past.status).toBe(200);
expect(past.payload.count).toBe(0);
expect(past.payload.total).toBe(7);
});
it('filters by network, tag, and atomic max price', async () => {
const byTag = await invoke(listHandler, '/api/bazaar/list?tag=weather');
expect(byTag.payload.count).toBe(2);
const byNetwork = await invoke(listHandler, '/api/bazaar/list?network=eip155:*');
expect(byNetwork.payload.count).toBe(7);
const noMatch = await invoke(listHandler, '/api/bazaar/list?network=solana:*');
expect(noMatch.payload.count).toBe(0);
const cheap = await invoke(listHandler, '/api/bazaar/list?maxPrice=3000&sort=price');
expect(cheap.payload.items.map((i) => i.minPriceAtomic)).toEqual([1000, 2000, 3000]);
});
it('rejects a decimal maxPrice and an unknown type with a 400 JSON error', async () => {
const decimal = await invoke(listHandler, '/api/bazaar/list?maxPrice=0.01');
expect(decimal.status).toBe(400);
expect(decimal.payload.error).toBe('bad_request');
const type = await invoke(listHandler, '/api/bazaar/list?type=grpc');
expect(type.status).toBe(400);
});
it('treats an empty maxPrice as no cap instead of a 400', async () => {
const { status, payload } = await invoke(listHandler, '/api/bazaar/list?maxPrice=');
expect(status).toBe(200);
expect(payload.count).toBe(7);
});
it('answers 405 on a non-GET and sets wildcard CORS', async () => {
const { status, payload, headers } = await invoke(listHandler, '/api/bazaar/list', 'POST');
expect(status).toBe(405);
expect(payload.error).toBe('method_not_allowed');
expect(headers['access-control-allow-origin']).toBe('*');
});
it('answers 502 when every facilitator fails instead of an empty catalog', async () => {
failAll = true;
const { status, payload } = await invoke(listHandler, '/api/bazaar/list');
expect(status).toBe(502);
expect(payload.error).toBe('facilitator_error');
expect(payload.error_description).toContain('fac-a.test');
});
});
describe('GET /api/bazaar/search', () => {
it('ranks matches for the query and reports the pre-cut total', async () => {
const { status, payload } = await invoke(listHandler, '/api/bazaar/search?query=weather');
expect(status).toBe(200);
expect(payload.count).toBe(7);
const search = await invoke(searchHandler, '/api/bazaar/search?query=weather');
expect(search.status).toBe(200);
expect(search.payload.count).toBe(2);
expect(search.payload.resources.every((r) => /weather/i.test(JSON.stringify(r)))).toBe(true);
const capped = await invoke(searchHandler, '/api/bazaar/search?query=weather&limit=1');
expect(capped.payload.count).toBe(1);
expect(capped.payload.total).toBe(2);
// The second ranked match is only reachable through `offset`.
const next = await invoke(searchHandler, '/api/bazaar/search?query=weather&limit=1&offset=1');
expect(next.payload.offset).toBe(1);
expect(next.payload.count).toBe(1);
expect(next.payload.total).toBe(2);
expect(next.payload.resources[0].uniqueKey).not.toBe(capped.payload.resources[0].uniqueKey);
});
it('returns the whole catalog for an empty query and 400s a decimal price cap', async () => {
const all = await invoke(searchHandler, '/api/bazaar/search');
expect(all.payload.count).toBe(7);
const bad = await invoke(searchHandler, '/api/bazaar/search?maxPrice=1.5');
expect(bad.status).toBe(400);
});
it('answers 502 when every facilitator fails', async () => {
failAll = true;
const { status, payload } = await invoke(searchHandler, '/api/bazaar/search?query=weather');
expect(status).toBe(502);
expect(payload.error).toBe('facilitator_error');
});
});
describe('GET /api/bazaar/providers', () => {
it('aggregates hosts into profiles ordered by service count', async () => {
const { status, payload } = await invoke(providersHandler, '/api/bazaar/providers');
expect(status).toBe(200);
expect(payload.providers[0].host).toBe('alpha.example');
expect(payload.providers[0].serviceCount).toBe(6); // 5 HTTP + 1 MCP tool
expect(payload.providers[0].mcpCount).toBe(1);
expect(payload.providers[0].minPriceAtomic).toBe(900);
expect(payload.totalProviders).toBe(3);
});
it('caps a host profile listing array and reports the true total', async () => {
const { status, payload } = await invoke(
providersHandler,
'/api/bazaar/providers?host=alpha.example&limit=2',
);
expect(status).toBe(200);
expect(payload.listings).toHaveLength(2);
expect(payload.listingTotal).toBe(6);
expect(payload.serviceCount).toBe(6);
// Cheapest first, so the cap keeps the head of the price ladder.
expect(payload.listings.map((l) => l.priceAtomic)).toEqual([900, 1000]);
});
it('404s an unknown host and 405s a non-GET', async () => {
const missing = await invoke(providersHandler, '/api/bazaar/providers?host=nope.invalid');
expect(missing.status).toBe(404);
expect(missing.payload.error).toBe('not_found');
const post = await invoke(providersHandler, '/api/bazaar/providers', 'POST');
expect(post.status).toBe(405);
});
it('answers 502 when every facilitator fails', async () => {
failAll = true;
const { status } = await invoke(providersHandler, '/api/bazaar/providers');
expect(status).toBe(502);
});
});
describe('GET /api/bazaar/arbitrage', () => {
it('surfaces the same capability priced differently across two hosts', async () => {
const { status, payload } = await invoke(arbitrageHandler, '/api/bazaar/arbitrage');
expect(status).toBe(200);
const weather = payload.opportunities.find((o) => o.key === 'http:weather-forecast');
expect(weather).toBeTruthy();
expect(weather.providerCount).toBe(2);
expect(weather.minPriceAtomic).toBe(5_000);
expect(weather.maxPriceAtomic).toBe(50_000);
expect(weather.spreadAtomic).toBe(45_000);
expect(weather.spreadPct).toBe(900);
expect(weather.cheapest.host).toBe('alpha.example');
expect(weather.mostExpensive.host).toBe('beta.example');
expect(weather.minPriceLabel).toBe('0.005 USDC');
});
it('honors an explicitly raised minProviders floor', async () => {
const two = await invoke(arbitrageHandler, '/api/bazaar/arbitrage?minProviders=2');
expect(two.payload.opportunities.some((o) => o.key === 'http:weather-forecast')).toBe(true);
const three = await invoke(arbitrageHandler, '/api/bazaar/arbitrage?minProviders=3');
expect(three.payload.opportunities.some((o) => o.key === 'http:weather-forecast')).toBe(false);
});
it('drops groups below minSpreadPct and caps at limit', async () => {
const wide = await invoke(arbitrageHandler, '/api/bazaar/arbitrage?minSpreadPct=1000');
expect(wide.payload.count).toBe(0);
const capped = await invoke(arbitrageHandler, '/api/bazaar/arbitrage?limit=1');
expect(capped.payload.opportunities).toHaveLength(1);
});
it('answers 405 on a non-GET and 502 on a total facilitator outage', async () => {
const post = await invoke(arbitrageHandler, '/api/bazaar/arbitrage', 'POST');
expect(post.status).toBe(405);
failAll = true;
const down = await invoke(arbitrageHandler, '/api/bazaar/arbitrage');
expect(down.status).toBe(502);
});
});
describe('GET /api/bazaar/context', () => {
const target = encodeURIComponent('https://alpha.example/api/weather-forecast');
it('requires a resource and 404s one outside the catalog', async () => {
const missing = await invoke(contextHandler, '/api/bazaar/context');
expect(missing.status).toBe(400);
expect(missing.payload.error).toBe('bad_request');
const unknown = await invoke(
contextHandler,
'/api/bazaar/context?resource=https%3A%2F%2Fnope.invalid%2Fx',
);
expect(unknown.status).toBe(404);
});
it('falls back to a grounded deterministic summary when no LLM answers', async () => {
const { status, payload } = await invoke(
contextHandler,
`/api/bazaar/context?resource=${target}`,
);
expect(status).toBe(200);
expect(payload.source).toBe('deterministic');
expect(payload.summary.length).toBeGreaterThan(0);
expect(['up', 'down', 'neutral']).toContain(payload.sentiment);
expect(payload.stats.peerCount).toBe(1);
expect(payload.stats.targetPriceAtomic).toBe(5_000);
expect(payload.stats.providerSiblingsCount).toBe(5);
// Every [n] the summary cites must map to a real citation anchor.
const cited = [...payload.summary.matchAll(/\[(\d+)\]/g)].map((m) => Number(m[1]));
for (const n of cited) expect(payload.citations[n - 1]).toBeTruthy();
// No citation may link at an empty search query.
for (const c of payload.citations) expect(c.url).not.toMatch(/\?q=$/);
});
it('answers 405 on a non-GET and 502 on a total facilitator outage', async () => {
const post = await invoke(contextHandler, `/api/bazaar/context?resource=${target}`, 'POST');
expect(post.status).toBe(405);
failAll = true;
const down = await invoke(contextHandler, `/api/bazaar/context?resource=${target}`);
expect(down.status).toBe(502);
});
});
describe('bazaar-client catalog memo', () => {
it('serves a second read from memory instead of re-sweeping facilitators', async () => {
const baz = new Bazaar({ facilitators: [FAC_A] });
const first = await baz.listCached({ type: 'http', maxItems: 500 });
const afterFirst = fetchCalls.length;
expect(afterFirst).toBeGreaterThan(0);
const second = await baz.listCached({ type: 'http', maxItems: 500 });
expect(fetchCalls).toHaveLength(afterFirst);
expect(second.items).toHaveLength(first.items.length);
// Callers filter and sort in place, so each read gets its own array.
expect(second.items).not.toBe(first.items);
});
it('does not memoize a failed sweep', async () => {
failAll = true;
const baz = new Bazaar({ facilitators: [FAC_A] });
const down = await baz.listCached({ type: 'http', maxItems: 500 });
expect(down.sources.every((s) => !s.ok)).toBe(true);
failAll = false;
clearCatalogCache();
const up = await baz.listCached({ type: 'http', maxItems: 500 });
expect(up.items.length).toBeGreaterThan(0);
});
});
describe('bazaar-client paging bounds', () => {
it('never returns more than maxItems from one facilitator', async () => {
const baz = new Bazaar({ facilitators: [FAC_A] });
const { items } = await baz.list({ type: 'http', limit: 200, maxItems: 2 });
expect(items).toHaveLength(2);
});
it('stops after one duplicate page when a facilitator ignores offset', async () => {
replayOffsets = true;
const baz = new Bazaar({ facilitators: [FAC_A] });
const { items } = await baz.list({ type: 'http', limit: 2, maxItems: 500 });
// Page one (2 fresh) then page two (all duplicates) ends the walk, rather
// than the 250 round trips the unbounded loop used to make.
expect(fetchCalls).toHaveLength(2);
expect(items).toHaveLength(2);
});
});
// The v1 ListDiscoveryResourcesResponse puts the human-facing fields on
// `metadata`, which is exactly where our own facilitator publishes them
// (api/_lib/x402/discovery-resources.js toV1Item). normalizeItem only read the
// v2 bazaar extension, so every listing that carried metadata normalized to an
// empty name, no tags and no icon: /economy rendered seventeen three.ws
// services as an anonymous row called "Service".
describe('bazaar-client v1 metadata', () => {
const v1Item = {
resource: 'https://three.ws/api/x402/analytics',
type: 'http',
x402Version: 1,
accepts: [
{
scheme: 'exact',
network: 'solana',
maxAmountRequired: '5000',
payTo: 'wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU',
asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
},
],
metadata: {
serviceName: 'three.ws Economy Analytics',
tags: ['analytics', 'economy'],
iconUrl: 'https://three.ws/favicon.ico',
method: 'POST',
path: '/api/x402/analytics',
},
};
it('reads serviceName, tags, iconUrl and method off metadata', () => {
const n = normalizeItem(v1Item, FAC_A);
expect(n.serviceName).toBe('three.ws Economy Analytics');
expect(n.tags).toEqual(['analytics', 'economy']);
expect(n.iconUrl).toBe('https://three.ws/favicon.ico');
expect(n.method).toBe('POST');
expect(n.minPriceLabel).toBe('0.005 USDC');
});
it('keeps a v2 bazaar extension authoritative over metadata', () => {
const n = normalizeItem(
{
...v1Item,
extensions: { bazaar: { name: 'Extension name', info: { service: { name: 'Service block name' } } } },
},
FAC_A,
);
// resource/serviceMeta names still win, so the fix adds a fallback rung
// rather than reordering the existing ones.
expect(n.serviceName).toBe('three.ws Economy Analytics');
});
it('leaves a listing with no metadata untouched', () => {
const { metadata, ...bare } = v1Item;
expect(metadata).toBeTruthy();
const n = normalizeItem(bare, FAC_A);
expect(n.serviceName).toBe('');
expect(n.tags).toEqual([]);
expect(n.method).toBe('');
});
});