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 — the registry behind /api/x402/d/<family>/<id>/<metric>.
//
// The Market Data API's category endpoints sell whole payloads; this fabric
// sells SINGLE datapoints. Every (family, id, metric) triple is its own
// individually addressable, individually priced x402 endpoint:
//
// /api/x402/d/coin/bitcoin/price → { value: 64346, unit: 'usd', … }
// /api/x402/d/protocol/lido/tvl
// /api/x402/d/pool/747c1d2a-…-296708a3dd90/apy
// /api/x402/d/global/btc-dominance
//
// Families × live catalog sizes × metrics ≈ 1,000,000+ standalone endpoints
// (~17.5k coins × 20 metrics, ~15k pools × 7, ~6k protocols × 6, per-contract
// token market + security for any Solana mint / EVM address, plus chains,
// stablecoins, exchanges, categories, DEXs, fees/revenue, derivative venues, and
// the no-id global/gas/fear-greed families) — all served by ONE dynamic route
// (api/x402/d/[...path].js) reading this registry.
// Ids are supplied at runtime by the caller; nothing here hardcodes a specific
// third-party asset.
//
// Sources reuse the same cached builders the category endpoints and /markets
// pages run on. Where a category builder slices for page rendering (top-100
// protocols/chains/stablecoins), the fabric keeps its own slim FULL-set cache
// of the identical upstream feed so every id is addressable, not just the
// leaderboard.
//
// Error contract (same as ../fetch.js — enforced pre-settle, buyer never
// charged): unknown family/metric → 404 at the route (no 402 issued for a
// resource that cannot exist); malformed id → 422; unknown id → 404; upstream
// outage → 503.
import { fetchGlobalMarket } from '../market-fallbacks.js';
import { fetchUpstreamJson, lastGood } from '../upstream-fetch.js';
import { isPlausibleCoinId } from '../coingecko.js';
import { buildCoinDetail, MINT_RE } from '../../coin/detail.js';
import { buildExchanges } from '../../coin/exchanges.js';
import { fetchFearGreed } from '../../coin/global.js';
import { buildGasReport } from '../../coin/gas.js';
import { loadYieldPools } from '../../defi/yields.js';
import { buildCategories } from '../../coin/categories.js';
import { buildDexVolumes } from '../../defi/dex-volumes.js';
import { buildFees } from '../../defi/fees.js';
import { buildDerivativeExchanges } from '../../coin/derivatives.js';
import { composeTokenSnapshot } from '../crypto-token-snapshot.js';
import { composeTokenSecurity } from '../crypto-token-security.js';
import { isResolvableAddress, chainOf } from '../token-market.js';
import { isValidSolanaAddress } from '../validate.js';
const fail = (status, code, message) => {
throw Object.assign(new Error(message), { status, code });
};
const finite = (n) => (Number.isFinite(n) ? n : null);
// ── Full-set caches (feeds the category builders slice for page rendering) ──
const TTL_MS = 600_000;
const _full = new Map(); // key → { value, expiresAt }
// The positive-only TTL map above has no answer for a failed load, so a
// DeFiLlama blip threw straight through every paid Market Data datapoint and the
// free /api/x402/d enumerator with it. The retry absorbs the transient and the
// last-known-good tier absorbs the rest: these feeds move slowly enough that an
// hour-old protocol list is a good answer, and infinitely better than a 503 on
// an endpoint a buyer has paid to call.
async function fullSet(key, url, slim) {
const now = Date.now();
const hit = _full.get(key);
if (hit && hit.expiresAt > now) {
noteFetchedAt(hit.fetchedAt);
return hit.value;
}
const { value, stale, ageMs } = await lastGood(
`market-datapoints:${key}`,
async () => {
const raw = await fetchUpstreamJson(
url,
{ headers: { accept: 'application/json', 'user-agent': 'three.ws/1.0' } },
{ name: `market-datapoints:${key}`, timeoutMs: 15_000, attempts: 2 },
);
return slim(raw);
},
{ maxAgeMs: 60 * 60_000 },
);
// When the last-good tier answered, the payload is as old as `ageMs`, and a
// buyer paying for this datapoint has to be told that rather than handed a
// timestamp claiming it was fetched just now.
const fetchedAt = stale ? Date.now() - ageMs : Date.now();
_full.set(key, { value, expiresAt: Date.now() + TTL_MS, fetchedAt });
noteFetchedAt(fetchedAt);
return value;
}
// The freshness of the upstream payload the CURRENT request read. A datapoint
// is assembled from one family read, so recording it per request (rather than
// threading a timestamp through every extractor) keeps `as_of` honest without
// reshaping the family API. Reset by readDatapoint before the read it describes.
let _readFetchedAt = null;
/** Test seam: stand in for a family read that came from the last-good tier. */
export function _noteFetchedAtForTest(at) {
noteFetchedAt(at);
}
function noteFetchedAt(at) {
if (at == null) return;
_readFetchedAt = _readFetchedAt == null ? at : Math.min(_readFetchedAt, at);
}
// slug → slim protocol row, over the FULL ~6k-protocol DeFiLlama feed.
// Exported (with the other full-set accessors) for the free enumerator at
// /api/x402/d, which pages through the same cached id space.
export function allProtocols() {
return fullSet('protocols', 'https://api.llama.fi/protocols', (raw) => {
if (!Array.isArray(raw)) throw new Error('unexpected upstream shape');
const bySlug = new Map();
for (const p of raw) {
if (typeof p?.slug !== 'string' || !p.slug) continue;
bySlug.set(p.slug, {
name: typeof p.name === 'string' ? p.name : p.slug,
category: typeof p.category === 'string' ? p.category : null,
tvl: finite(Number(p.tvl)),
change_1d: finite(Number(p.change_1d)),
change_7d: finite(Number(p.change_7d)),
mcap: finite(Number(p.mcap)),
chain_count: Array.isArray(p.chains) ? p.chains.length : 0,
});
}
return bySlug;
});
}
// lowercase chain name → slim row + whole-market total for share-pct.
export function allChains() {
return fullSet('chains', 'https://api.llama.fi/v2/chains', (raw) => {
if (!Array.isArray(raw)) throw new Error('unexpected upstream shape');
const byName = new Map();
let totalTvl = 0;
for (const c of raw) {
const tvl = Number(c?.tvl);
if (typeof c?.name !== 'string' || !Number.isFinite(tvl)) continue;
totalTvl += Math.max(0, tvl);
byName.set(c.name.toLowerCase(), {
name: c.name,
tvl,
token_symbol: typeof c.tokenSymbol === 'string' && c.tokenSymbol ? c.tokenSymbol : null,
});
}
for (const row of byName.values()) {
row.share_pct = totalTvl > 0 ? (Math.max(0, row.tvl) / totalTvl) * 100 : 0;
}
return byName;
});
}
// id AND lowercase symbol → slim stablecoin row, over the full pegged set.
export function allStablecoins() {
return fullSet(
'stablecoins',
'https://stablecoins.llama.fi/stablecoins?includePrices=true',
(body) => {
const assets = Array.isArray(body?.peggedAssets) ? body.peggedAssets : null;
if (!assets) throw new Error('unexpected upstream shape');
const byKey = new Map();
for (const a of assets) {
const pegType = typeof a?.pegType === 'string' ? a.pegType : null;
const circulating = pegType && a.circulating ? Number(a.circulating[pegType]) : NaN;
if (!Number.isFinite(circulating)) continue;
const price = Number(a.price);
const row = {
name: typeof a.name === 'string' ? a.name : 'Unknown',
symbol: typeof a.symbol === 'string' ? a.symbol : '',
price: Number.isFinite(price) ? price : null,
peg_type: pegType,
peg_mechanism: typeof a.pegMechanism === 'string' ? a.pegMechanism : null,
circulating: circulating,
chain_count: Array.isArray(a.chains) ? a.chains.length : 0,
};
if (a.id != null) byKey.set(String(a.id), row);
if (row.symbol) byKey.set(row.symbol.toLowerCase(), row);
}
return byKey;
},
);
}
// slug/id → row, over any of our own list-returning builders (categories, DEX
// volumes, fees/revenue, derivative venues). These builders already cache their
// own upstream fetch; we memoize the id→row map on top so a per-id lookup is a
// Map.get, not a linear scan of the whole list on every datapoint call.
const _listMaps = new Map(); // key → { value: Map, expiresAt }
async function listMap(key, builder, toEntries) {
const now = Date.now();
const hit = _listMaps.get(key);
if (hit && hit.expiresAt > now) return hit.value;
const built = await builder();
const map = new Map();
for (const [k, row] of toEntries(built)) {
if (typeof k === 'string' && k) map.set(k, row);
}
_listMaps.set(key, { value: map, expiresAt: now + TTL_MS });
return map;
}
// The full DeFiLlama category list keyed by CoinGecko category id.
export function allCategories() {
return listMap('categories', buildCategories, ({ categories }) =>
(Array.isArray(categories) ? categories : []).map((c) => [c.id, c]),
);
}
// Top-100 DEXs keyed by DeFiLlama protocol slug.
export function allDexes() {
return listMap('dexes', buildDexVolumes, ({ protocols }) =>
(Array.isArray(protocols) ? protocols : [])
.filter((p) => p.slug)
.map((p) => [p.slug, p]),
);
}
// Top protocols keyed by slug, merging the fees and revenue series into one row
// so a single id exposes both fees-* and revenue-* metrics.
export function allFees() {
return listMap(
'fees',
async () => {
const [fees, revenue] = await Promise.all([buildFees('fees'), buildFees('revenue')]);
const bySlug = new Map();
for (const p of fees.protocols || []) {
if (p.slug) bySlug.set(p.slug, { name: p.name, category: p.category, fees: p, revenue: null });
}
for (const p of revenue.protocols || []) {
if (!p.slug) continue;
const row = bySlug.get(p.slug);
if (row) row.revenue = p;
else bySlug.set(p.slug, { name: p.name, category: p.category, fees: null, revenue: p });
}
return bySlug;
},
(bySlug) => bySlug.entries(),
);
}
// Derivative (perp) venues keyed by CoinGecko exchange id.
export function allDerivativeExchanges() {
return listMap('derivative-exchanges', buildDerivativeExchanges, ({ exchanges }) =>
(Array.isArray(exchanges) ? exchanges : []).map((e) => [e.id, e]),
);
}
// ── Per-address compose memo (token / token-security families) ───────────────
//
// composeTokenSnapshot / composeTokenSecurity each fan out to several upstreams
// per call. An agent that walks all metrics of one mint would otherwise repeat
// that fan-out per metric; a short per-address memo collapses it to one.
const COMPOSE_TTL_MS = 60_000;
const COMPOSE_CACHE_MAX = 500;
const _composeMemo = new Map(); // `${kind}:${address}` → { value, expiresAt }
async function composeMemo(kind, address, compose) {
const key = `${kind}:${address}`;
const now = Date.now();
const hit = _composeMemo.get(key);
if (hit && hit.expiresAt > now) return hit.value;
const result = await compose();
if (_composeMemo.size >= COMPOSE_CACHE_MAX) {
// Evict the oldest ~10% to bound memory without a full LRU.
let drop = Math.ceil(COMPOSE_CACHE_MAX / 10);
for (const k of _composeMemo.keys()) {
_composeMemo.delete(k);
if (--drop <= 0) break;
}
}
_composeMemo.set(key, { value: result, expiresAt: now + COMPOSE_TTL_MS });
return result;
}
// Map a compose-style result ({status:'ok'|'not_found'|'upstream_down'}) onto
// the resolver contract: ok → the row, not_found → null (404), down → 503.
function fromCompose(label, id, result, pick) {
if (result.status === 'upstream_down') {
fail(503, 'data_unavailable', `live ${label} data is temporarily unavailable — retry shortly`);
}
if (result.status !== 'ok') return null;
return pick(result);
}
// ── Row resolvers (throw 404 for an unknown id, 503 for an outage) ──────────
async function resolve(label, id, lookup) {
let row;
try {
row = await lookup();
} catch (err) {
if (err?.status && err.status < 500) throw err;
fail(503, 'data_unavailable', `live ${label} data is temporarily unavailable — retry shortly`);
}
if (row == null) fail(404, 'not_found', `no ${label} found for "${id}"`);
return row;
}
// ── The registry ────────────────────────────────────────────────────────────
//
// Each family: { idKind, describeId, validateId(id) → 422 on garbage,
// row(id) → the object metrics extract from, metrics: { slug → {label, unit,
// extract} }, count() → approximate live id count for the enumerator }.
const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
const m = (label, unit, extract) => ({ label, unit, extract });
export const DATAPOINT_FAMILIES = {
coin: {
describeId: 'CoinGecko coin id (e.g. a lowercase slug) or a base58 Solana mint',
validateId(id) {
if (!isPlausibleCoinId(id) && !MINT_RE.test(id)) {
fail(422, 'invalid_id', 'id must be a CoinGecko coin id (lowercase slug) or a base58 Solana mint');
}
},
async row(id) {
const contract = MINT_RE.test(id) && !isPlausibleCoinId(id) ? id : '';
return resolve('coin', id, async () => {
try {
const { coin } = await buildCoinDetail(contract ? { contract } : { id });
return coin;
} catch (err) {
if (err?.status === 404) return null;
throw err;
}
});
},
approxCount: 17_000,
metrics: {
price: m('Spot price', 'usd', (c) => num(c.market?.price)),
'market-cap': m('Market capitalization', 'usd', (c) => num(c.market?.market_cap)),
fdv: m('Fully diluted valuation', 'usd', (c) => num(c.market?.fdv)),
'volume-24h': m('24h trading volume', 'usd', (c) => num(c.market?.volume_24h)),
'change-24h': m('24h price change', 'pct', (c) => num(c.market?.change_pct?.h24)),
'change-7d': m('7-day price change', 'pct', (c) => num(c.market?.change_pct?.d7)),
'change-30d': m('30-day price change', 'pct', (c) => num(c.market?.change_pct?.d30)),
'change-1y': m('1-year price change', 'pct', (c) => num(c.market?.change_pct?.y1)),
rank: m('Market-cap rank', 'rank', (c) => num(c.rank)),
ath: m('All-time-high price', 'usd', (c) => num(c.market?.ath)),
'ath-change': m('Drawdown from all-time high', 'pct', (c) => num(c.market?.ath_change_pct)),
atl: m('All-time-low price', 'usd', (c) => num(c.market?.atl)),
'high-24h': m('24h high', 'usd', (c) => num(c.market?.high_24h)),
'low-24h': m('24h low', 'usd', (c) => num(c.market?.low_24h)),
'circulating-supply': m('Circulating supply', 'tokens', (c) => num(c.market?.circulating)),
'total-supply': m('Total supply', 'tokens', (c) => num(c.market?.total)),
'max-supply': m('Max supply', 'tokens', (c) => num(c.market?.max)),
'mcap-fdv-ratio': m('Market-cap / FDV ratio', 'ratio', (c) => num(c.market?.mcap_fdv_ratio)),
'sentiment-up': m('Bullish sentiment votes', 'pct', (c) => num(c.sentiment?.up_pct)),
'watchlist-users': m('Watchlist portfolio users', 'count', (c) => num(c.sentiment?.watchlist_users)),
},
},
protocol: {
describeId: 'DeFiLlama protocol slug (e.g. a lowercase-hyphen name)',
validateId(id) {
if (!/^[a-z0-9-]{1,100}$/.test(id)) {
fail(422, 'invalid_id', 'id must be a DeFiLlama protocol slug (lowercase, hyphens)');
}
},
row: (id) => resolve('protocol', id, async () => (await allProtocols()).get(id) ?? null),
approxCount: 6_000,
metrics: {
tvl: m('Total value locked', 'usd', (p) => p.tvl),
'change-1d': m('1-day TVL change', 'pct', (p) => p.change_1d),
'change-7d': m('7-day TVL change', 'pct', (p) => p.change_7d),
mcap: m('Token market cap', 'usd', (p) => p.mcap),
category: m('Protocol category', 'text', (p) => p.category),
'chain-count': m('Deployed chain count', 'count', (p) => p.chain_count),
},
},
chain: {
describeId: 'chain name as DeFiLlama spells it (case-insensitive)',
validateId(id) {
if (!/^[a-z0-9 ._-]{1,60}$/i.test(id)) {
fail(422, 'invalid_id', 'id must be a chain name (letters, digits, spaces, dots, hyphens)');
}
},
row: (id) => resolve('chain', id, async () => (await allChains()).get(id.toLowerCase()) ?? null),
approxCount: 350,
metrics: {
tvl: m('DeFi total value locked', 'usd', (c) => finite(c.tvl)),
'share-pct': m('Share of all-chain TVL', 'pct', (c) => finite(c.share_pct)),
'token-symbol': m('Native token symbol', 'text', (c) => c.token_symbol),
},
},
pool: {
describeId: 'DeFiLlama yield-pool uuid',
validateId(id) {
if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {
fail(422, 'invalid_id', 'id must be a DeFiLlama pool uuid');
}
},
row: (id) =>
resolve('yield pool', id, async () => {
const { pools } = await loadYieldPools();
const key = id.toLowerCase();
return pools.find((p) => p.pool.toLowerCase() === key) ?? null;
}),
approxCount: 15_000,
metrics: {
apy: m('Current APY', 'pct', (p) => p.apy),
'apy-base': m('Base APY (fee-derived)', 'pct', (p) => p.apy_base),
'apy-reward': m('Reward APY (incentives)', 'pct', (p) => p.apy_reward),
'apy-mean-30d': m('30-day mean APY', 'pct', (p) => p.apy_mean_30d),
tvl: m('Pool TVL', 'usd', (p) => finite(p.tvl_usd)),
'il-risk': m('Impermanent-loss risk', 'text', (p) => p.il_risk),
outlook: m('Predicted APY outlook', 'text', (p) => p.outlook),
},
},
stablecoin: {
describeId: 'DeFiLlama stablecoin id (numeric) or its symbol',
validateId(id) {
if (!/^[a-z0-9$+._-]{1,30}$/i.test(id)) {
fail(422, 'invalid_id', 'id must be a DeFiLlama stablecoin id or symbol');
}
},
row: (id) =>
resolve('stablecoin', id, async () => {
const set = await allStablecoins();
return set.get(id) ?? set.get(id.toLowerCase()) ?? null;
}),
approxCount: 400,
metrics: {
supply: m('Circulating supply (peg units)', 'peg-units', (s) => finite(s.circulating)),
price: m('Current price', 'usd', (s) => s.price),
'peg-deviation-bps': m('Deviation from $1 peg', 'bps', (s) =>
s.price == null ? null : Math.round((s.price - 1) * 10_000),
),
'peg-mechanism': m('Peg mechanism', 'text', (s) => s.peg_mechanism),
'chain-count': m('Deployed chain count', 'count', (s) => s.chain_count),
},
},
exchange: {
describeId: 'CoinGecko exchange id (e.g. a lowercase slug)',
validateId(id) {
if (!/^[a-z0-9_-]{1,60}$/.test(id)) {
fail(422, 'invalid_id', 'id must be a CoinGecko exchange id (lowercase slug)');
}
},
row: (id) =>
resolve('exchange', id, async () => {
const { exchanges } = await buildExchanges();
return exchanges.find((e) => e.id === id) ?? null;
}),
approxCount: 100,
metrics: {
'volume-24h': m('24h volume', 'usd', (e) => e.volume_24h_usd),
'volume-24h-btc': m('24h volume', 'btc', (e) => e.volume_24h_btc),
'trust-score': m('Trust score (0–10)', 'score', (e) => e.trust_score),
'trust-rank': m('Trust-score rank', 'rank', (e) => e.trust_score_rank),
country: m('Registered country', 'text', (e) => e.country),
},
},
token: {
// The coin family resolves CoinGecko-listed assets; this one resolves ANY
// on-chain token by contract address — DexScreener + pump.fun + Helius, keyless
// where possible — so freshly launched mints with no CoinGecko id are addressable.
describeId: 'token contract address — a base58 Solana mint or an EVM 0x address',
validateId(id) {
if (!isResolvableAddress(id)) {
fail(422, 'invalid_id', 'id must be a Solana mint or EVM 0x contract address');
}
},
row: (id) =>
resolve('token', id, async () => {
const chain = chainOf(id) === 'evm' ? null : 'solana';
const result = await composeMemo('snapshot', id, () =>
composeTokenSnapshot({ address: id, chain: chain === 'solana' ? null : chain }),
);
return fromCompose('token', id, result, (r) => r.snapshot);
}),
approxCount: 40_000, // unbounded in practice — any indexed contract resolves
metrics: {
price: m('Spot price', 'usd', (s) => num(s.priceUsd)),
'change-24h': m('24h price change', 'pct', (s) => num(s.change24h)),
'market-cap': m('Market capitalization', 'usd', (s) => num(s.marketCapUsd)),
fdv: m('Fully diluted valuation', 'usd', (s) => num(s.fdvUsd)),
liquidity: m('Pooled DEX liquidity', 'usd', (s) => num(s.liquidityUsd)),
'volume-24h': m('24h trading volume', 'usd', (s) => num(s.volume24hUsd)),
name: m('Token name', 'text', (s) => s.name ?? null),
symbol: m('Token symbol', 'text', (s) => s.symbol ?? null),
chain: m('Host chain', 'text', (s) => s.chain ?? null),
dex: m('Deepest-liquidity DEX', 'text', (s) => s.dexId ?? null),
},
},
'token-security': {
// Rug-lever safety checks for one Solana mint — mint/freeze authority,
// metadata mutability, holder concentration, liquidity depth, risk verdict.
describeId: 'base58 Solana mint address',
validateId(id) {
if (!isValidSolanaAddress(id)) {
fail(422, 'invalid_id', 'id must be a base58 Solana mint address');
}
},
row: (id) =>
resolve('token security', id, async () => {
const result = await composeMemo('security', id, () => composeTokenSecurity({ address: id }));
return fromCompose('token security', id, result, (r) => r);
}),
approxCount: 40_000, // unbounded — any Solana mint
metrics: {
'risk-level': m('Overall risk verdict', 'text', (r) => r.riskLevel),
'mint-authority-revoked': m('Mint authority revoked', 'bool', (r) => r.checks.mintAuthorityRevoked),
'freeze-authority-revoked': m('Freeze authority revoked', 'bool', (r) => r.checks.freezeAuthorityRevoked),
'metadata-mutable': m('Metadata still mutable', 'bool', (r) => r.checks.metadataMutable),
'liquidity-usd': m('Pooled liquidity', 'usd', (r) => num(r.checks.liquidityUsd)),
'holders-concentrated': m('Top-holder concentration flag', 'bool', (r) => r.checks.topHolderPctFlag),
},
},
category: {
describeId: 'CoinGecko category id (e.g. a lowercase-hyphen sector slug)',
validateId(id) {
if (!/^[a-z0-9-]{1,80}$/.test(id)) {
fail(422, 'invalid_id', 'id must be a CoinGecko category id (lowercase, hyphens)');
}
},
row: (id) => resolve('category', id, async () => (await allCategories()).get(id) ?? null),
approxCount: 300,
metrics: {
'market-cap': m('Sector market cap', 'usd', (c) => num(c.market_cap)),
'market-cap-change-24h': m('24h sector market-cap change', 'pct', (c) => num(c.market_cap_change_24h)),
'volume-24h': m('24h sector volume', 'usd', (c) => num(c.volume_24h)),
},
},
dex: {
describeId: 'DeFiLlama DEX slug (e.g. a lowercase-hyphen protocol key)',
validateId(id) {
if (!/^[a-z0-9.-]{1,100}$/.test(id)) {
fail(422, 'invalid_id', 'id must be a DeFiLlama DEX slug (lowercase, hyphens)');
}
},
row: (id) => resolve('DEX', id, async () => (await allDexes()).get(id) ?? null),
approxCount: 100,
metrics: {
'volume-24h': m('24h trading volume', 'usd', (d) => finite(d.total24h)),
'volume-7d': m('7-day trading volume', 'usd', (d) => finite(d.total7d)),
'change-7d': m('7d-over-prior-7d volume change', 'pct', (d) => finite(d.change_7d)),
'share-pct': m('Share of all-DEX volume', 'pct', (d) => finite(d.share_pct)),
},
},
fees: {
describeId: 'DeFiLlama protocol slug (e.g. a lowercase-hyphen name)',
validateId(id) {
if (!/^[a-z0-9-]{1,100}$/.test(id)) {
fail(422, 'invalid_id', 'id must be a DeFiLlama protocol slug (lowercase, hyphens)');
}
},
row: (id) => resolve('fees', id, async () => (await allFees()).get(id) ?? null),
approxCount: 150,
metrics: {
'fees-24h': m('24h fees paid by users', 'usd', (r) => finite(r.fees?.total24h)),
'fees-7d': m('7-day fees', 'usd', (r) => finite(r.fees?.total7d)),
'fees-30d': m('30-day fees', 'usd', (r) => finite(r.fees?.total30d)),
'revenue-24h': m('24h protocol revenue', 'usd', (r) => finite(r.revenue?.total24h)),
'revenue-7d': m('7-day protocol revenue', 'usd', (r) => finite(r.revenue?.total7d)),
'revenue-30d': m('30-day protocol revenue', 'usd', (r) => finite(r.revenue?.total30d)),
},
},
'derivative-exchange': {
describeId: 'CoinGecko derivatives exchange id (e.g. a lowercase slug)',
validateId(id) {
if (!/^[a-z0-9_-]{1,60}$/.test(id)) {
fail(422, 'invalid_id', 'id must be a CoinGecko derivatives exchange id');
}
},
row: (id) => resolve('derivatives exchange', id, async () => (await allDerivativeExchanges()).get(id) ?? null),
approxCount: 50,
metrics: {
'open-interest-btc': m('Open interest', 'btc', (e) => num(e.open_interest_btc)),
'volume-24h-btc': m('24h trade volume', 'btc', (e) => num(e.trade_volume_24h_btc)),
'perpetual-pairs': m('Listed perpetual pairs', 'count', (e) => num(e.perpetual_pairs)),
'futures-pairs': m('Listed futures pairs', 'count', (e) => num(e.futures_pairs)),
},
},
global: {
describeId: null, // no id segment — /api/x402/d/global/<metric>
row: () => resolve('global market', 'global', () => fetchGlobalMarket()),
approxCount: 1,
metrics: {
'market-cap': m('Total crypto market cap', 'usd', (g) => num(g.market_cap_usd)),
'volume-24h': m('Total 24h volume', 'usd', (g) => num(g.volume_24h_usd)),
'market-cap-change-24h': m('24h market-cap change', 'pct', (g) => num(g.market_cap_change_pct_24h)),
'active-coins': m('Active tracked coins', 'count', (g) => num(g.active_coins)),
'btc-dominance': m('BTC dominance', 'pct', (g) => num(g.dominance?.[0]?.pct)),
'eth-dominance': m('ETH dominance', 'pct', (g) => num(g.dominance?.[1]?.pct)),
},
},
'fear-greed': {
describeId: null,
row: () => resolve('fear & greed', 'fear-greed', () => fetchFearGreed()),
approxCount: 1,
metrics: {
index: m('Fear & Greed index (0–100)', 'index', (f) => num(f.value)),
label: m('Fear & Greed classification', 'text', (f) => f.label),
},
},
gas: {
describeId: null,
row: () => resolve('gas', 'gas', () => buildGasReport()),
approxCount: 1,
metrics: {
slow: m('Slow tier gas price', 'gwei', (g) => finite(g.tiers?.[0]?.gas_price_gwei)),
standard: m('Standard tier gas price', 'gwei', (g) => finite(g.tiers?.[1]?.gas_price_gwei)),
fast: m('Fast tier gas price', 'gwei', (g) => finite(g.tiers?.[2]?.gas_price_gwei)),
'base-fee': m('Current base fee', 'gwei', (g) => finite(g.base_fee_gwei)),
'eth-price': m('ETH spot price', 'usd', (g) => g.eth_price_usd),
},
},
};
// $0.0005 USDC per datapoint by default — half the category-call price, since
// a datapoint is one scalar. Ops override per family: X402_PRICE_DATAPOINT_<FAMILY>.
export const DATAPOINT_DEFAULT_ATOMICS = '500';
// ── Path parsing ─────────────────────────────────────────────────────────────
//
// /api/x402/d/<family>/<id>/<metric> for id families,
// /api/x402/d/<family>/<metric> for the no-id families.
// Returns { family, familyDef, id, metric, metricDef } or throws
// { status: 404 } for a shape that cannot exist / { status: 422 } for a
// malformed id — both BEFORE any 402 is issued, so nobody is asked to pay for
// a resource that does not exist.
export function parseDatapointPath(segments) {
const [familySlug, ...rest] = segments;
const familyDef = DATAPOINT_FAMILIES[familySlug];
if (!familyDef) {
fail(404, 'unknown_family', `unknown datapoint family "${familySlug}" — GET /api/x402/d for the catalog`);
}
const needsId = familyDef.describeId != null;
const expected = needsId ? 2 : 1;
if (rest.length !== expected) {
fail(
404,
'bad_path',
needsId
? `expected /api/x402/d/${familySlug}/<id>/<metric>`
: `expected /api/x402/d/${familySlug}/<metric>`,
);
}
const id = needsId ? decodeURIComponent(rest[0]) : null;
const metric = rest[needsId ? 1 : 0];
const metricDef = familyDef.metrics[metric];
if (!metricDef) {
fail(
404,
'unknown_metric',
`unknown metric "${metric}" for ${familySlug} — valid: ${Object.keys(familyDef.metrics).join(', ')}`,
);
}
if (needsId) familyDef.validateId(id);
return { family: familySlug, familyDef, id, metric, metricDef };
}
// Fetch + extract one datapoint. The paid handler's whole job.
export async function readDatapoint({ family, familyDef, id, metric, metricDef }) {
_readFetchedAt = null;
const row = await familyDef.row(id);
const value = metricDef.extract(row);
// `as_of` is when the DATA was read from upstream, not when this response was
// assembled. Those were the same thing before the last-good tier existed;
// now they are not, and stamping the response time over an hour-old payload
// would sell a stale number as a live one.
const fetchedAt = _readFetchedAt ?? Date.now();
const staleMs = Date.now() - fetchedAt;
return {
family,
...(id != null ? { id } : {}),
metric,
label: metricDef.label,
unit: metricDef.unit,
value: value === undefined ? null : value,
as_of: new Date(fetchedAt).toISOString(),
...(staleMs > TTL_MS ? { stale: true, age_seconds: Math.round(staleMs / 1000) } : {}),
source: 'three.ws market-data',
};
}
// Storefront description for one (family, metric) datapoint listing — shared
// by the live 402 (api/x402/d/[...path].js) and the discovery-doc entries
// (api/wk.js) so the two surfaces can never drift.
export function datapointDescription({ family, metric, priceAtomics }) {
const familyDef = DATAPOINT_FAMILIES[family];
const metricDef = familyDef.metrics[metric];
const price = (Number(priceAtomics) / 1_000_000)
.toFixed(4)
.replace(/0+$/, '')
.replace(/\.$/, '');
const idPart = familyDef.describeId
? ` Pass the ${familyDef.describeId} as the path id — supplied at runtime by the caller.`
: '';
return (
`Single datapoint: ${metricDef.label.toLowerCase()} for one ${family} — ` +
`pay $${price} USDC per call and get back one machine-readable value ` +
`(unit: ${metricDef.unit}) with a timestamp.${idPart} ` +
`Part of the three.ws datapoint fabric — 1,000,000+ addressable endpoints, cataloged free at /api/x402/d.`
);
}
// Approximate count of addressable datapoint endpoints, for the enumerator.
export function datapointEndpointCount() {
let total = 0;
for (const def of Object.values(DATAPOINT_FAMILIES)) {
total += def.approxCount * Object.keys(def.metrics).length;
}
return total;
}