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
// Datapoint fabric (/api/x402/d/…) — registry, parsing, extractor, and
// payment-boundary guards. All offline: extractors run against real-shaped
// fixture rows; the 402 checks drive the actual dynamic route with a fake res.
import { describe, it, expect } from 'vitest';
Object.assign(process.env, {
APP_ORIGIN: 'https://three.ws',
X402_PAY_TO_BASE: '0x0000000000000000000000000000000000000001',
X402_PAY_TO_SOLANA: 'So11111111111111111111111111111111111111112',
X402_ASSET_ADDRESS_BASE: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
X402_ASSET_MINT_SOLANA: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
X402_ASSET_ADDRESS_ARBITRUM: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
X402_MAX_AMOUNT_REQUIRED: '1000',
X402_FEE_PAYER_SOLANA: 'So11111111111111111111111111111111111111112',
});
const {
DATAPOINT_FAMILIES,
DATAPOINT_DEFAULT_ATOMICS,
datapointDescription,
parseDatapointPath,
datapointEndpointCount,
readDatapoint,
_noteFetchedAtForTest,
} = await import('../api/_lib/market-data/datapoints.js');
function expectThrow(fn, { status, code }) {
let err;
try {
fn();
} catch (e) {
err = e;
}
expect(err, 'expected a throw').toBeTruthy();
expect(err.status).toBe(status);
expect(err.code).toBe(code);
}
// ── Registry invariants ─────────────────────────────────────────────────────
describe('datapoint registry', () => {
it('spans hundreds of thousands of addressable endpoints', () => {
expect(datapointEndpointCount()).toBeGreaterThan(300_000);
});
it('every family and metric carries complete listing metadata', () => {
for (const [family, def] of Object.entries(DATAPOINT_FAMILIES)) {
expect(family).toMatch(/^[a-z-]+$/);
expect(typeof def.row).toBe('function');
expect(def.approxCount).toBeGreaterThan(0);
if (def.describeId != null) expect(typeof def.validateId).toBe('function');
const metrics = Object.entries(def.metrics);
expect(metrics.length, `${family} metrics`).toBeGreaterThanOrEqual(2);
for (const [slug, metricDef] of metrics) {
expect(slug, `${family}/${slug}`).toMatch(/^[a-z0-9-]+$/);
expect(metricDef.label.length).toBeGreaterThan(3);
expect(metricDef.unit.length).toBeGreaterThan(0);
expect(typeof metricDef.extract).toBe('function');
// Discovery-listing quality: descriptions must clear the ≥60-char
// bar every other cataloged service meets.
const description = datapointDescription({
family,
metric: slug,
priceAtomics: DATAPOINT_DEFAULT_ATOMICS,
});
expect(description.length, `${family}/${slug} description`).toBeGreaterThanOrEqual(60);
}
}
});
});
// ── Path parsing / payment boundary ─────────────────────────────────────────
describe('parseDatapointPath', () => {
it('parses id-family and no-id-family paths', () => {
const coin = parseDatapointPath(['coin', 'bitcoin', 'price']);
expect(coin.family).toBe('coin');
expect(coin.id).toBe('bitcoin');
expect(coin.metric).toBe('price');
const global = parseDatapointPath(['global', 'btc-dominance']);
expect(global.id).toBeNull();
expect(global.metric).toBe('btc-dominance');
});
it('url-decodes ids (chain names with spaces)', () => {
const parsed = parseDatapointPath(['chain', 'Arbitrum%20Nova', 'tvl']);
expect(parsed.id).toBe('Arbitrum Nova');
});
it('404s an unknown family, metric, or path shape — never a 402 for a non-resource', () => {
expectThrow(() => parseDatapointPath(['weather', 'nyc', 'temp']), {
status: 404,
code: 'unknown_family',
});
expectThrow(() => parseDatapointPath(['coin', 'bitcoin', 'vibes']), {
status: 404,
code: 'unknown_metric',
});
expectThrow(() => parseDatapointPath(['coin', 'bitcoin']), { status: 404, code: 'bad_path' });
expectThrow(() => parseDatapointPath(['global', 'x', 'btc-dominance']), {
status: 404,
code: 'bad_path',
});
});
it('422s a malformed id per family', () => {
expectThrow(() => parseDatapointPath(['coin', 'NOT A SLUG!', 'price']), {
status: 422,
code: 'invalid_id',
});
expectThrow(() => parseDatapointPath(['pool', 'not-a-uuid', 'apy']), {
status: 422,
code: 'invalid_id',
});
expectThrow(() => parseDatapointPath(['protocol', 'Bad Slug', 'tvl']), {
status: 422,
code: 'invalid_id',
});
});
});
// ── Extractors against real-shaped rows ─────────────────────────────────────
describe('metric extractors', () => {
it('coin metrics read the buildCoinDetail shape', () => {
const coin = {
rank: 1,
market: {
price: 64346, market_cap: 1.2e12, fdv: 1.3e12, volume_24h: 3.8e10,
change_pct: { h24: 1.42, d7: 4.87, d30: 9.1, y1: 55.2 },
ath: 126789, ath_change_pct: -49.2, atl: 67.81,
high_24h: 65000, low_24h: 63000,
circulating: 19_700_000, total: 21_000_000, max: 21_000_000,
mcap_fdv_ratio: 0.94,
},
sentiment: { up_pct: 82.5, watchlist_users: 1_600_000 },
};
const metrics = DATAPOINT_FAMILIES.coin.metrics;
expect(metrics.price.extract(coin)).toBe(64346);
expect(metrics['change-7d'].extract(coin)).toBe(4.87);
expect(metrics['max-supply'].extract(coin)).toBe(21_000_000);
expect(metrics['sentiment-up'].extract(coin)).toBe(82.5);
});
it('stablecoin peg deviation converts price to basis points', () => {
const metrics = DATAPOINT_FAMILIES.stablecoin.metrics;
expect(metrics['peg-deviation-bps'].extract({ price: 0.9992 })).toBe(-8);
expect(metrics['peg-deviation-bps'].extract({ price: 1.0031 })).toBe(31);
expect(metrics['peg-deviation-bps'].extract({ price: null })).toBeNull();
});
it('gas metrics read the buildGasReport tier order', () => {
const gas = {
base_fee_gwei: 0.077,
eth_price_usd: 3251.7,
tiers: [
{ key: 'slow', gas_price_gwei: 0.08 },
{ key: 'standard', gas_price_gwei: 0.1 },
{ key: 'fast', gas_price_gwei: 0.15 },
],
};
const metrics = DATAPOINT_FAMILIES.gas.metrics;
expect(metrics.slow.extract(gas)).toBe(0.08);
expect(metrics.standard.extract(gas)).toBe(0.1);
expect(metrics.fast.extract(gas)).toBe(0.15);
expect(metrics['eth-price'].extract(gas)).toBe(3251.7);
});
it('global dominance metrics read the failover shape', () => {
const g = {
market_cap_usd: 3.9e12, volume_24h_usd: 1.5e11,
market_cap_change_pct_24h: 0.7, active_coins: 17505,
dominance: [{ symbol: 'BTC', pct: 56.2 }, { symbol: 'ETH', pct: 12.1 }],
};
const metrics = DATAPOINT_FAMILIES.global.metrics;
expect(metrics['btc-dominance'].extract(g)).toBe(56.2);
expect(metrics['eth-dominance'].extract(g)).toBe(12.1);
expect(metrics['active-coins'].extract(g)).toBe(17505);
});
});
// ── New families: per-contract token, security, and the list families ───────
describe('token / security / list families', () => {
const THREE = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
it('token accepts Solana mints and EVM 0x addresses, rejects garbage', () => {
expect(parseDatapointPath(['token', THREE, 'price']).family).toBe('token');
expect(parseDatapointPath(['token', '0x' + 'a'.repeat(40), 'price']).id).toBe('0x' + 'a'.repeat(40));
expectThrow(() => parseDatapointPath(['token', 'not an address', 'price']), {
status: 422,
code: 'invalid_id',
});
});
it('token-security is Solana-only', () => {
expect(parseDatapointPath(['token-security', THREE, 'risk-level']).metric).toBe('risk-level');
expectThrow(() => parseDatapointPath(['token-security', '0x' + 'a'.repeat(40), 'risk-level']), {
status: 422,
code: 'invalid_id',
});
});
it('token metrics read the composeTokenSnapshot shape', () => {
const snap = {
priceUsd: 0.0017, change24h: -4.2, marketCapUsd: 1_700_000, fdvUsd: 2_000_000,
liquidityUsd: 212_000, volume24hUsd: 90_000, name: 'Three', symbol: 'THREE',
chain: 'solana', dexId: 'pumpswap',
};
const mx = DATAPOINT_FAMILIES.token.metrics;
expect(mx.price.extract(snap)).toBe(0.0017);
expect(mx.liquidity.extract(snap)).toBe(212_000);
expect(mx.symbol.extract(snap)).toBe('THREE');
expect(mx.dex.extract(snap)).toBe('pumpswap');
});
it('token-security metrics read the composeTokenSecurity shape', () => {
const row = {
riskLevel: 'medium',
checks: {
mintAuthorityRevoked: true, freezeAuthorityRevoked: false, metadataMutable: true,
liquidityUsd: 8_000, topHolderPctFlag: true,
},
};
const mx = DATAPOINT_FAMILIES['token-security'].metrics;
expect(mx['risk-level'].extract(row)).toBe('medium');
expect(mx['mint-authority-revoked'].extract(row)).toBe(true);
expect(mx['freeze-authority-revoked'].extract(row)).toBe(false);
expect(mx['liquidity-usd'].extract(row)).toBe(8_000);
expect(mx['holders-concentrated'].extract(row)).toBe(true);
});
it('list-family extractors read their builder shapes', () => {
expect(DATAPOINT_FAMILIES.category.metrics['market-cap'].extract({ market_cap: 1e12 })).toBe(1e12);
expect(DATAPOINT_FAMILIES.dex.metrics['volume-24h'].extract({ total24h: 5e9 })).toBe(5e9);
expect(DATAPOINT_FAMILIES.fees.metrics['revenue-24h'].extract({ revenue: { total24h: 68_630 } })).toBe(68_630);
expect(DATAPOINT_FAMILIES.fees.metrics['revenue-24h'].extract({ revenue: null })).toBeNull();
expect(
DATAPOINT_FAMILIES['derivative-exchange'].metrics['open-interest-btc'].extract({ open_interest_btc: 369_801 }),
).toBe(369_801);
});
});
// ── Live 402 boundary on the dynamic route ──────────────────────────────────
function fakeRes() {
return {
statusCode: 0,
headers: {},
body: undefined,
writableEnded: false,
setHeader(k, v) {
this.headers[k.toLowerCase()] = v;
},
getHeader(k) {
return this.headers[k.toLowerCase()];
},
end(body) {
this.body = body;
this.writableEnded = true;
},
};
}
const route = (await import('../api/x402/d/[...path].js')).default;
async function drive(url) {
const res = fakeRes();
await route({ method: 'GET', url, headers: { host: 'three.ws' } }, res);
return res;
}
describe('dynamic datapoint route', () => {
it('issues a 402 whose resource URL is the concrete datapoint', async () => {
const res = await drive('/api/x402/d/global/btc-dominance');
expect(res.statusCode).toBe(402);
const body = JSON.parse(res.body);
expect(body.resource.url).toBe('https://three.ws/api/x402/d/global/btc-dominance');
const usdc = body.accepts.filter((a) =>
[process.env.X402_ASSET_MINT_SOLANA, process.env.X402_ASSET_ADDRESS_BASE].includes(a.asset),
);
expect(usdc.length).toBeGreaterThan(0);
expect(usdc.every((a) => (a.amount ?? a.maxAmountRequired) === DATAPOINT_DEFAULT_ATOMICS)).toBe(true);
});
it('two ids of one (family, metric) advertise their own resource URLs', async () => {
const a = JSON.parse((await drive('/api/x402/d/coin/bitcoin/price')).body);
const b = JSON.parse((await drive('/api/x402/d/coin/ethereum/price')).body);
expect(a.resource.url).toContain('/coin/bitcoin/price');
expect(b.resource.url).toContain('/coin/ethereum/price');
});
it('404s garbage paths without issuing a payment challenge', async () => {
const res = await drive('/api/x402/d/weather/nyc/temp');
expect(res.statusCode).toBe(404);
const body = JSON.parse(res.body);
expect(body.error).toBe('unknown_family');
expect(body.catalog).toBe('/api/x402/d');
});
it('422s a malformed id before payment', async () => {
const res = await drive('/api/x402/d/pool/not-a-uuid/apy');
expect(res.statusCode).toBe(422);
expect(JSON.parse(res.body).error).toBe('invalid_id');
});
it('rejects a bad path in the same error envelope every other api handler uses', async () => {
// A caller written against any other three.ws endpoint reads
// error_description; this route used to answer `message` alone.
const res = await drive('/api/x402/d/global/not-a-metric');
expect(res.statusCode).toBe(404);
const body = JSON.parse(res.body);
expect(body.error).toBe('unknown_metric');
expect(body.error_description).toContain('unknown metric');
expect(body.families).toContain('global');
// An error is never cacheable, whatever the paid path advertises.
expect(String(res.headers['cache-control'])).toContain('no-store');
});
});
// A paid datapoint's `as_of` is when the DATA was read upstream, not when the
// response was assembled. Those were the same thing until the last-good tier
// landed under it; stamping the response time over an hour-old payload would
// sell a stale number to a buyer as a live one.
describe('readDatapoint freshness', () => {
it('reports as_of from the upstream read and flags a stale payload', async () => {
const fetchedAt = Date.now() - 45 * 60_000;
const familyDef = {
row: async () => {
_noteFetchedAtForTest(fetchedAt);
return { tvl: 123 };
},
metrics: {},
};
const metricDef = { label: 'TVL', unit: 'usd', extract: (r) => r.tvl };
const out = await readDatapoint({ family: 'protocol', familyDef, id: 'x', metric: 'tvl', metricDef });
expect(out.value).toBe(123);
expect(Date.parse(out.as_of)).toBeCloseTo(fetchedAt, -4);
expect(out.stale).toBe(true);
expect(out.age_seconds).toBeGreaterThan(600);
});
it('does not flag a fresh read, and stamps it now', async () => {
const familyDef = { row: async () => ({ tvl: 7 }), metrics: {} };
const metricDef = { label: 'TVL', unit: 'usd', extract: (r) => r.tvl };
const out = await readDatapoint({ family: 'protocol', familyDef, id: 'x', metric: 'tvl', metricDef });
expect(out.stale).toBeUndefined();
expect(out.age_seconds).toBeUndefined();
expect(Date.now() - Date.parse(out.as_of)).toBeLessThan(5_000);
});
});