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/protocol?slug=<slug>
// ---------------------------------------------------------------------------
// Rich profile for one DeFi protocol. Powers the /protocol/:slug detail page.
// Proxies DeFiLlama's keyless endpoints (no API key) and slims the multi-MB
// upstream payload to exactly what the page renders:
// · /protocol/{slug} (required): TVL history, per-chain TVL, raises,
// hallmarks, mcap, metadata
// · /summary/fees/{slug} (optional): 24h/7d/30d/all-time fees + revenue
// (dailyFees + dailyRevenue passes)
// · /summary/dexs/{slug} (optional): DEX trading volume
// The fees/dexs summaries also carry richer metadata (category, audits,
// methodology, forkedFrom, parentProtocol) than the bare /protocol payload for
// aggregator ("parent") protocols, so missing metadata is enriched from them.
// The full daily TVL history (often 2k+ points) is downsampled server-side to
// ≤400 points so the SVG chart stays light. Cached 5 min in-memory per slug +
// CDN. 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';
import { normalizeLlamaLogo } from '../_lib/llama-icon.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-protocol:${key}`, load, {
maxAgeMs: STALE_MAX_AGE_MS,
onFallback: (err, ageMs) => console.warn(`[upstream] defi-protocol:${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-protocol:${key}: serving in-memory last good after ${err?.message || err}`);
} });
const staleHeaders = (...keys) => (keys.some((k) => _staleKeys.has(k)) ? { 'x-three-stale': '1' } : {});
// DeFiLlama slugs are not strictly [a-z0-9.-]: 14 of the ~6k protocols it tracks
// carry parentheses, a plus or a bang (`dinero-(pxeth)`, `synthetix-v1+v2`,
// `yay!`). Rejecting those characters turned every /yields row for such a
// protocol into a link that 404s, so the charset matches what upstream actually
// mints. It stays a strict allowlist: the value is interpolated into an
// api.llama.fi path.
const SLUG_RE = /^[a-z0-9.!()+-]{1,80}$/i;
const TTL_MS = 300_000;
const MAX_TVL_POINTS = 400;
const UA = 'three.ws/1.0';
// Per-slug cache, LRU-bounded so a crawl over many slugs evicts the coldest
// entry rather than discarding every warm one, with single-flight de-dup so
// concurrent misses on the same slug share one round of the four upstream
// calls below instead of firing four each.
const _cache = createCache({ max: 512, ttlMs: TTL_MS });
// Coerce numbers and DeFiLlama's occasional numeric strings (audits count, some
// summary totals) to a finite number, else null.
const num = (v) => {
if (v == null || v === '') return null;
const n = typeof v === 'number' ? v : Number(v);
return Number.isFinite(n) ? n : null;
};
const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
const httpUrl = (v) => (typeof v === 'string' && /^https?:\/\//.test(v.trim()) ? v.trim() : null);
// Synthetic per-chain suffixes DeFiLlama appends to `currentChainTvls`. These
// are not real TVL a chain holds (they double-count borrowed collateral, staked
// governance tokens, LP-side liquidity, or locked vesting), so a "TVL by chain"
// view must exclude them or every chain appears 2 to 3 times with inflated numbers.
const SYNTH_SUFFIX = /-(borrowed|staking|pool2|vesting)$/i;
// …and the whole-protocol aggregates of those same categories.
const AGGREGATE_KEYS = new Set(['borrowed', 'staking', 'pool2', 'vesting']);
async function fetchJson(url) {
const resp = await fetchUpstream(url, {
headers: { accept: 'application/json', 'user-agent': UA },
}, { timeoutMs: 10_000, attempts: 2 });
return resp.json();
}
// Optional upstream: a 4xx (many protocols have no fees/dexs feed) or any other
// failure collapses to null so the section is simply hidden, never an error.
async function fetchOptional(url) {
try {
return await fetchJson(url);
} catch {
return null;
}
}
// Reduce the full daily TVL history to ≤MAX points by a fixed stride, always
// keeping the first and last sample so the chart's start and current value are
// exact. Input points are [{ date: unix_s, totalLiquidityUSD }].
function downsampleTvl(series) {
const clean = [];
for (const p of Array.isArray(series) ? series : []) {
const t = num(p?.date);
const tvl = num(p?.totalLiquidityUSD);
if (t == null || tvl == null) continue;
clean.push({ t: Math.floor(t), tvl });
}
if (clean.length <= MAX_TVL_POINTS) return clean;
const stride = Math.ceil(clean.length / MAX_TVL_POINTS);
const out = [];
for (let i = 0; i < clean.length; i += stride) out.push(clean[i]);
const last = clean[clean.length - 1];
if (out[out.length - 1]?.t !== last.t) out.push(last);
return out;
}
// Current per-chain TVL sorted desc, excluding the synthetic/aggregate keys.
// Staking + borrowed totals (if the protocol reports them) are surfaced
// separately so the page can note them without polluting the chain breakdown.
function shapeChainTvls(currentChainTvls) {
const chains = [];
let staking = null;
let borrowed = null;
for (const [key, raw] of Object.entries(currentChainTvls || {})) {
const val = num(raw);
if (val == null) continue;
if (key === 'staking') { staking = val; continue; }
if (key === 'borrowed') { borrowed = val; continue; }
if (AGGREGATE_KEYS.has(key)) continue;
if (SYNTH_SUFFIX.test(key)) continue;
if (val <= 0) continue;
chains.push({ chain: key, tvl: val });
}
chains.sort((a, b) => b.tvl - a.tvl);
return { chains, staking, borrowed };
}
// Embedded funding rounds. DeFiLlama reports `amount` in millions of USD, so it
// is scaled to raw dollars here; the page never has to know the unit.
function shapeRaises(raises) {
if (!Array.isArray(raises) || !raises.length) return null;
const strList = (a) => (Array.isArray(a) ? a.map(str).filter(Boolean) : []);
const out = raises
.map((r) => {
const amt = num(r?.amount);
return {
date: num(r?.date) != null ? Math.floor(num(r.date)) : null,
round: str(r?.round),
amount_usd: amt != null ? amt * 1e6 : null,
leadInvestors: strList(r?.leadInvestors),
otherInvestors: strList(r?.otherInvestors),
valuation: num(r?.valuation),
source: httpUrl(r?.source),
};
})
.sort((a, b) => (b.date || 0) - (a.date || 0));
return out.length ? out : null;
}
// Timeline annotations: [unix_s, label]. Deduped (upstream occasionally repeats
// an entry) and sorted ascending so chart markers land in chronological order.
function shapeHallmarks(hallmarks) {
if (!Array.isArray(hallmarks) || !hallmarks.length) return null;
const seen = new Set();
const out = [];
for (const item of hallmarks) {
if (!Array.isArray(item) || item.length < 2) continue;
const t = num(item[0]);
const label = str(item[1]);
if (t == null || !label) continue;
const key = `${Math.floor(t)}|${label}`;
if (seen.has(key)) continue;
seen.add(key);
out.push([Math.floor(t), label]);
}
out.sort((a, b) => a[0] - b[0]);
return out.length ? out : null;
}
function shapeAudits(protoAudits, protoLinks, metaAudits, metaLinks) {
const count = num(protoAudits ?? metaAudits);
const src = (Array.isArray(protoLinks) && protoLinks.length ? protoLinks : metaLinks) || [];
const audit_links = (Array.isArray(src) ? src : []).map(httpUrl).filter(Boolean).slice(0, 6);
if ((count == null || count === 0) && !audit_links.length) return null;
return { count: count ?? 0, audit_links };
}
function shapeFees(fees, revenue) {
if (!fees && !revenue) return null;
const f = fees || {};
const r = revenue || {};
const out = {
total24h: num(f.total24h),
total7d: num(f.total7d),
total30d: num(f.total30d),
totalAllTime: num(f.totalAllTime),
revenue24h: num(r.total24h),
revenue7d: num(r.total7d),
revenue30d: num(r.total30d),
};
return Object.values(out).some((v) => v != null) ? out : null;
}
function shapeDexVolume(dexs) {
if (!dexs) return null;
const out = {
total24h: num(dexs.total24h),
total7d: num(dexs.total7d),
change_7dover7d: num(dexs.change_7dover7d),
};
return out.total24h != null || out.total7d != null ? out : null;
}
function build(slug, proto, fees, revenue, dexs) {
// The fees/dexs summaries carry the richest metadata; prefer the /protocol
// value, fall back to whichever summary is present.
const meta = fees || dexs || {};
const tvlSeries = downsampleTvl(proto.tvl);
const { chains, staking, borrowed } = shapeChainTvls(proto.currentChainTvls);
const forkedFromSrc =
(Array.isArray(proto.forkedFrom) && proto.forkedFrom.length ? proto.forkedFrom : meta.forkedFrom) || [];
return {
slug,
name: str(proto.name) || slug,
symbol: str(proto.symbol) && proto.symbol !== '-' ? proto.symbol : null,
logo: normalizeLlamaLogo(httpUrl(proto.logo) || httpUrl(meta.logo)),
url: httpUrl(proto.url) || httpUrl(meta.url),
twitter: str(proto.twitter) || str(meta.twitter),
category: str(proto.category) || str(meta.category),
chains: Array.isArray(proto.chains) ? proto.chains.filter((c) => typeof c === 'string') : [],
audits: shapeAudits(proto.audits, proto.audit_links, meta.audits, meta.audit_links),
forkedFrom: (Array.isArray(forkedFromSrc) ? forkedFromSrc : []).map(str).filter(Boolean),
parentProtocol: str(proto.parentProtocol) || str(meta.parentProtocol),
listedAt: num(proto.listedAt),
mcap: num(proto.mcap),
description: (str(proto.description) || str(meta.description) || '').slice(0, 2000) || null,
methodology: str(proto.methodology) || str(meta.methodology),
tvl_current: tvlSeries.length ? tvlSeries[tvlSeries.length - 1].tvl : null,
tvl_series: tvlSeries,
chain_tvls: chains,
staking_tvl: staking,
borrowed_tvl: borrowed,
hallmarks: shapeHallmarks(proto.hallmarks),
raises: shapeRaises(proto.raises),
fees: shapeFees(fees, revenue),
dex_volume: shapeDexVolume(dexs),
updated_at: Date.now(),
};
}
async function load(slug) {
return cachedStale(_cache, slug, async () => {
// Main call is required; the rest are best-effort enrichment fetched in
// parallel. The main fetch throwing a 400/404 propagates as not-found.
const [proto, fees, revenue, dexs] = await Promise.all([
fetchJson(`https://api.llama.fi/protocol/${encodeURIComponent(slug)}`),
fetchOptional(`https://api.llama.fi/summary/fees/${encodeURIComponent(slug)}?dataType=dailyFees`),
fetchOptional(`https://api.llama.fi/summary/fees/${encodeURIComponent(slug)}?dataType=dailyRevenue`),
fetchOptional(`https://api.llama.fi/summary/dexs/${encodeURIComponent(slug)}`),
]);
return build(slug, proto, fees, revenue, dexs);
});
}
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 slug = (params.get('slug') || '').trim().toLowerCase();
if (!SLUG_RE.test(slug)) {
return error(res, 400, 'bad_slug', 'slug must be a DeFiLlama protocol slug (1 to 80 chars: letters, digits, . or -)');
}
try {
const payload = await load(slug);
return json(res, 200, payload, {
'cache-control': 'public, max-age=120, s-maxage=300, stale-while-revalidate=600',
...staleHeaders(slug),
});
} catch (err) {
// DeFiLlama answers an unknown slug with 400 "Protocol not found" (and 404
// for some paths), and both mean "no such protocol" to the client.
if (err?.status === 404 || err?.status === 400) {
return error(res, 404, 'not_found', `no DeFi protocol found for "${slug}"`);
}
return error(res, 502, 'upstream_error', 'DeFi protocol data is unavailable right now. Retry shortly');
}
});