Skip to content

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.

13.3 KB
Raw Blame
// 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',
		);
	}
});