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
// GET /api/defi/yields: DeFi yield pools for the /yields explorer.
// ---------------------------------------------------------------------------
// Two modes over DeFiLlama's keyless yields API (yields.llama.fi):
//
// List: GET /api/defi/yields?chain=&project=&stablecoin=&search=&minTvl=
// &sort=tvl|apy&limit=&offset=
// Fetches /pools (a multi-MB payload of ~15k pools), slims each pool
// to the fields the page renders, caches the slimmed set in-memory
// for 10 min, then filters / sorts / pages per request. The response
// also carries filter-agnostic facets (top chains + projects by pool
// TVL) for the page's dropdowns and whole-dataset stats.
//
// Chart: GET /api/defi/yields?pool=<uuid>
// Fetches /chart/{pool} (per-pool APY + TVL history) and downsamples
// it to ≤300 points. Unknown pools 404 rather than 502.
//
// DeFiLlama is the data source. See the page's attribution line.
import { cors, json, method, wrap, error, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { createCache, cached } from '../_lib/mem-cache.js';
import { fetchUpstream, lastGood } from '../_lib/upstream-fetch.js';
// DeFiLlama is this page's only upstream. A TTL cache alone still 502s the
// moment it expires during an outage, so every loader also keeps its last good
// result for hours and serves that (the handler's cache headers keep the
// staleness honest to the CDN) rather than blanking the page.
const STALE_MAX_AGE_MS = 6 * 60 * 60_000;
// Keys currently served from a last-good copy (either tier), so the handler can
// label the response `x-three-stale: 1` instead of passing it off as live. A key
// leaves the set the moment its loader succeeds again.
const _staleKeys = new Set();
const cachedStale = (cache, key, load) => cached(cache, key, async () => {
const r = await lastGood(`defi-yields:${key}`, load, {
maxAgeMs: STALE_MAX_AGE_MS,
onFallback: (err, ageMs) => console.warn(`[upstream] defi-yields:${key}: serving last good value (${Math.round(ageMs / 60_000)}m old) after ${err?.message || err}`),
});
if (r.stale) _staleKeys.add(key);
else _staleKeys.delete(key);
return r.value;
}, { onStale: (err) => {
_staleKeys.add(key);
console.warn(`[upstream] defi-yields:${key}: serving in-memory last good after ${err?.message || err}`);
} });
const staleHeaders = (...keys) => (keys.some((k) => _staleKeys.has(k)) ? { 'x-three-stale': '1' } : {});
const POOLS_UPSTREAM = 'https://yields.llama.fi/pools';
const CHART_UPSTREAM = 'https://yields.llama.fi/chart/';
const POOLS_TTL_MS = 600_000;
const CHART_TTL_MS = 600_000;
const CHART_CACHE_MAX = 100;
const DEFAULT_LIMIT = 100;
const MAX_LIMIT = 200;
const CHART_MAX_POINTS = 300;
// APY sorting and the median-APY stat only consider pools above this TVL floor:
// dust pools routinely report five-digit APYs on three digits of liquidity,
// which would otherwise bury every real pool under spam.
const APY_MIN_TVL = 10_000;
const FACET_CHAINS = 30;
const FACET_PROJECTS = 50;
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const finite = (n) => (Number.isFinite(n) ? n : null);
// ── Pools cache ─────────────────────────────────────────────────────────────
// Single-entry cache with single-flight de-dup, so concurrent misses share one
// fetch of this multi-MB pool dump instead of each pulling their own copy.
const _pools = createCache({ max: 1, ttlMs: POOLS_TTL_MS });
const POOLS_KEY = 'pools';
function slimPool(p) {
const tvl = Number(p?.tvlUsd);
return {
pool: p.pool,
chain: typeof p.chain === 'string' ? p.chain : 'Unknown',
project: typeof p.project === 'string' ? p.project : 'unknown',
// Matches the 'Unknown' fallback the sibling fields use. This value is
// rendered verbatim as the pool's name on /yields, so it has to read as a
// real label rather than a punctuation placeholder.
symbol: typeof p.symbol === 'string' && p.symbol ? p.symbol : 'Unknown',
tvl_usd: tvl,
apy: finite(Number(p.apy)),
apy_base: finite(Number(p.apyBase)),
apy_reward: finite(Number(p.apyReward)),
apy_mean_30d: finite(Number(p.apyMean30d)),
apy_change_1d: finite(Number(p.apyPct1D)),
apy_change_7d: finite(Number(p.apyPct7D)),
il_risk: typeof p.ilRisk === 'string' ? p.ilRisk : null,
exposure: typeof p.exposure === 'string' ? p.exposure : null,
stablecoin: p.stablecoin === true,
outlook: typeof p.predictions?.predictedClass === 'string' ? p.predictions.predictedClass : null,
outlook_confidence: finite(Number(p.predictions?.predictedProbability)),
pool_meta: typeof p.poolMeta === 'string' && p.poolMeta ? p.poolMeta : null,
};
}
function median(sorted) {
if (!sorted.length) return null;
const mid = Math.floor(sorted.length / 2);
return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
}
// Top-N (chain|project) facets by summed pool TVL, with pool counts, over the
// FULL dataset. The dropdowns must offer every major venue regardless of the
// caller's current filters.
function buildFacets(pools, key, topN) {
const agg = new Map(); // name → { tvl, count }
for (const p of pools) {
const name = p[key];
const cur = agg.get(name) || { tvl: 0, count: 0 };
cur.tvl += p.tvl_usd;
cur.count += 1;
agg.set(name, cur);
}
return [...agg.entries()]
.sort((a, b) => b[1].tvl - a[1].tvl)
.slice(0, topN)
.map(([name, { count }]) => ({ name, pool_count: count }));
}
// Exported for the paid datapoint fabric (api/_lib/market-data/datapoints.js),
// per-pool datapoint endpoints resolve a uuid against this cached full set.
export async function loadYieldPools() {
return loadPools();
}
async function loadPools() {
return cachedStale(_pools, POOLS_KEY, async () => {
const resp = await fetchUpstream(POOLS_UPSTREAM, {
headers: { accept: 'application/json', 'user-agent': 'three.ws/1.0' },
}, { timeoutMs: 20_000, attempts: 2 });
const raw = await resp.json();
if (!Array.isArray(raw?.data)) throw new Error('unexpected upstream shape');
const pools = [];
for (const p of raw.data) {
if (typeof p?.pool !== 'string') continue;
const tvl = Number(p.tvlUsd);
if (!Number.isFinite(tvl) || tvl < 0) continue;
pools.push(slimPool(p));
}
// Default presentation order is TVL desc; sorting once at build time makes
// every default-list request a pure slice.
pools.sort((a, b) => b.tvl_usd - a.tvl_usd);
const apys = pools
.filter((p) => p.tvl_usd >= APY_MIN_TVL && p.apy != null)
.map((p) => p.apy)
.sort((a, b) => a - b);
return {
pools,
facets: {
chains: buildFacets(pools, 'chain', FACET_CHAINS),
projects: buildFacets(pools, 'project', FACET_PROJECTS),
},
stats: {
pool_count: pools.length,
total_tvl: pools.reduce((sum, p) => sum + p.tvl_usd, 0),
median_apy: median(apys),
},
updated_at: Date.now(),
};
});
}
// ── List mode ───────────────────────────────────────────────────────────────
function parseBool(v) {
if (v == null) return undefined;
const s = String(v).toLowerCase();
if (s === 'true' || s === '1') return true;
if (s === 'false' || s === '0') return false;
return undefined;
}
function clampInt(v, { def, min, max }) {
const n = parseInt(v ?? '', 10);
if (!Number.isFinite(n)) return def;
return Math.max(min, Math.min(max, n));
}
// Exported for the paid Market Data API (api/_lib/market-data/), the x402
// market-yields endpoint sells the same filtered pool explorer this page renders.
export async function queryYieldPools({
chain = '',
project = '',
stablecoin,
search = '',
minTvl = 0,
sort = 'tvl',
limit = DEFAULT_LIMIT,
offset = 0,
} = {}) {
const { pools, facets, stats, updated_at } = await loadPools();
let rows = pools.filter((p) => {
if (chain && p.chain.toLowerCase() !== chain) return false;
if (project && p.project.toLowerCase() !== project) return false;
if (stablecoin !== undefined && p.stablecoin !== stablecoin) return false;
if (minTvl && p.tvl_usd < minTvl) return false;
if (search && !`${p.symbol} ${p.project} ${p.chain}`.toLowerCase().includes(search)) return false;
return true;
});
if (sort === 'apy') {
// Dust-pool guard: never let a $200 pool advertising 80,000% APY outrank
// real venues. Only pools above the TVL floor are eligible for APY order.
rows = rows
.filter((p) => p.tvl_usd >= APY_MIN_TVL && p.apy != null)
.sort((a, b) => b.apy - a.apy);
}
// sort === 'tvl' needs no work, the cache is already TVL desc.
return {
pools: rows.slice(offset, offset + limit),
total: rows.length,
limit,
offset,
sort,
facets,
stats,
updated_at,
};
}
async function listMode(req, res, params) {
const payload = await queryYieldPools({
chain: (params.get('chain') || '').trim().toLowerCase(),
project: (params.get('project') || '').trim().toLowerCase(),
stablecoin: parseBool(params.get('stablecoin')),
search: (params.get('search') || '').trim().toLowerCase(),
minTvl: Math.max(0, Number(params.get('minTvl')) || 0),
sort: params.get('sort') === 'apy' ? 'apy' : 'tvl',
limit: clampInt(params.get('limit'), { def: DEFAULT_LIMIT, min: 1, max: MAX_LIMIT }),
offset: clampInt(params.get('offset'), { def: 0, min: 0, max: 1_000_000 }),
});
return json(res, 200, payload, {
'cache-control': 'public, max-age=120, s-maxage=300, stale-while-revalidate=600',
...staleHeaders(POOLS_KEY),
});
}
// ── Chart mode ──────────────────────────────────────────────────────────────
// Per-pool chart cache, LRU-bounded so browsing many pools evicts the coldest
// entry, with single-flight de-dup on concurrent misses for the same pool. A
// pool with no history caches its `null` too, so a uuid that upstream does not
// know is answered from memory instead of re-asking on every request.
const _charts = createCache({ max: CHART_CACHE_MAX, ttlMs: CHART_TTL_MS });
// Even stride over the series, always keeping the last point (the chart cares
// most about where the line ends).
function downsample(points, max) {
if (points.length <= max) return points;
const step = (points.length - 1) / (max - 1);
const out = [];
for (let i = 0; i < max; i++) out.push(points[Math.round(i * step)]);
return out;
}
async function loadChart(pool) {
return cachedStale(_charts, pool, async () => {
const now = Date.now();
// DeFiLlama answers an unknown pool id with a non-200 or an empty data set;
// both mean "no history for this pool", not an outage.
let resp;
try {
resp = await fetchUpstream(`${CHART_UPSTREAM}${pool}`, {
headers: { accept: 'application/json', 'user-agent': 'three.ws/1.0' },
}, { timeoutMs: 15_000, attempts: 2 });
} catch (err) {
if (err?.status === 404 || err?.status === 400) return null;
throw err;
}
const raw = await resp.json();
if (!Array.isArray(raw?.data)) throw new Error('unexpected upstream shape');
const points = [];
for (const d of raw.data) {
const t = Date.parse(d?.timestamp);
if (!Number.isFinite(t)) continue;
points.push({ t, apy: finite(Number(d.apy)), tvl_usd: finite(Number(d.tvlUsd)) });
}
if (!points.length) return null;
return { pool, points: downsample(points, CHART_MAX_POINTS), updated_at: now };
});
}
// Exported for the paid Market Data API, validates + loads a single pool's
// APY/TVL history; throws {status, code} instead of writing to a response.
export async function queryYieldChart(pool) {
if (!UUID_RE.test(pool || '')) {
throw Object.assign(new Error('pool must be a DeFiLlama pool uuid'), {
status: 400,
code: 'invalid_pool',
});
}
const value = await loadChart(pool.toLowerCase());
if (!value) {
throw Object.assign(new Error('no APY/TVL history for this pool id'), {
status: 404,
code: 'pool_not_found',
});
}
return value;
}
async function chartMode(req, res, pool) {
let value;
try {
value = await queryYieldChart(pool);
} catch (err) {
if (err?.status && err.status < 500) return error(res, err.status, err.code, err.message);
throw err;
}
return json(res, 200, value, {
'cache-control': 'public, max-age=300, s-maxage=600, stale-while-revalidate=1200',
...staleHeaders(pool.toLowerCase()),
});
}
// ── Handler ─────────────────────────────────────────────────────────────────
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
if (!method(req, res, ['GET'])) return;
const rl = await limits.marketDataIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const params = new URL(req.url, 'http://x').searchParams;
const pool = params.get('pool');
try {
if (pool) return await chartMode(req, res, pool);
return await listMode(req, res, params);
} catch (err) {
// 4xx from the mode handlers (invalid uuid, unknown pool) already returned;
// anything thrown here is upstream trouble.
if (err?.status && err.status < 500) throw err;
return error(
res,
502,
'upstream_error',
'DeFi yield data is unavailable right now. Retry shortly',
);
}
});