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.2 KB
Raw Blame
// Consolidated KOL endpoints dispatcher: /api/kol/{wallets,import-gmgn,
// leaderboard,tracker}. The trade feed is the one KOL endpoint that lives in its
// own file (api/kol/trades.js) because an exact file outranks this [action].js
// in filesystem routing; see the DISPATCH note at the bottom.

import { cors, json, method, readJson, wrap, error, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { requireAdmin } from '../_lib/admin.js';
import { createCache } from '../_lib/mem-cache.js';
import { loadWallets, saveImportedWallets } from '../../src/kol/wallet-store.js';

import { getBalances, walletUsdTotal } from '../_lib/balances.js';
// ── wallets (Birdeye P&L proxy) ───────────────────────────────────────────────

const BIRDEYE_BASE = 'https://public-api.birdeye.so';
const CACHE_TTL_MS = 60_000;
// Birdeye failures are negative-cached for a much shorter window: long enough to
// stop an outage hammering the upstream every request, short enough that a
// transient blip doesn't hide a wallet (or, worse, render it as a fake zero-P&L
// row) for a full minute.
const NEG_CACHE_TTL_MS = 15_000;
const MAX_ADDRESSES = 20;
// Keys are caller-supplied addresses, so an LRU bound (not a plain Map) is what
// keeps a long-lived container from growing one entry per address ever queried:
// the hand-rolled Map this replaced only ever dropped an entry that was asked
// for again after it expired, so junk keys accumulated forever. Per-entry TTLs
// still differ by outcome, which lru-cache takes on set().
// Value: { data } (hit) | { error: true } (miss).
const _cache = createCache({ max: 2_000 });

function _getCached(addr) {
	return _cache.get(addr) ?? null;
}

function _setCache(addr, data) {
	_cache.set(addr, { data }, { ttl: CACHE_TTL_MS });
}

// Negative-cache a fetch failure instead of storing a normalized-from-null
// portfolio: that shape is all zeros and is indistinguishable from a real
// flat wallet, so callers would render an upstream outage as legitimate KOL
// data. A miss entry is filtered out of the response and refreshed sooner.
function _setCacheError(addr) {
	_cache.set(addr, { error: true }, { ttl: NEG_CACHE_TTL_MS });
}

// Holdings without Birdeye: the shared balances module reads the wallet over
// the rotating Solana RPC chain and prices every position through Jupiter, so a
// missing or rate-limited Birdeye key degrades to our own data, not to a 503.
async function _fetchOwnHoldings(addr) {
	const bal = await getBalances({ chain: 'solana', address: addr });
	const items = [];
	const nativeUsd = Number(bal?.native?.usd) || 0;
	if (nativeUsd > 0) items.push({ symbol: 'SOL', valueUsd: nativeUsd });
	for (const t of bal?.tokens || []) {
		const valueUsd = Number(t?.usd) || 0;
		if (valueUsd > 0) items.push({ symbol: t?.symbol || t?.mint?.slice(0, 4) || '?', valueUsd });
	}
	return { items, totalUsd: walletUsdTotal(bal), stale: !!bal?.stale };
}

async function _fetchPortfolio(addr, apiKey) {
	if (apiKey) {
		try {
			return await _fetchBirdeye(addr, apiKey);
		} catch (err) {
			console.warn(`[kol] birdeye portfolio failed for ${addr.slice(0, 4)}…, falling back to RPC balances: ${err?.message || err}`);
		}
	}
	return _fetchOwnHoldings(addr);
}

async function _fetchBirdeye(addr, apiKey) {
	const url = `${BIRDEYE_BASE}/v1/wallet/portfolio?wallet=${encodeURIComponent(addr)}&chain=solana`;
	const ctrl = new AbortController();
	const t = setTimeout(() => ctrl.abort(), 8000);
	try {
		const res = await fetch(url, { headers: { 'X-API-KEY': apiKey }, signal: ctrl.signal });
		if (!res.ok) throw new Error(`birdeye ${res.status}`);
		const j = await res.json();
		if (!j.success) throw new Error('birdeye responded with success=false');
		return j.data;
	} finally {
		clearTimeout(t);
	}
}

// Birdeye's /v1/wallet/portfolio is a HOLDINGS endpoint: it returns the wallet's
// current token positions and their USD value. It carries no realized P&L, no win
// rate and no trade count, so this proxy reports holdings under holdings names.
// The row it used to emit dressed them up as a P&L card instead: `realizedPnl`,
// `winRate` and `totalTrades` were hardcoded zeros Birdeye never sends,
// `unrealizedPnl` was really the portfolio's total USD value, and `topToken.pnl`
// was the top holding's value. Downstream (`get_wallet_portfolio` in
// packages/kol-mcp) rendered all four to agents as measured P&L. Real per-wallet
// P&L is FIFO-computed from the wallet's own on-chain trades by
// src/kol/wallet-pnl.js and merged in by _walletPnl below.
function _normalizeHoldings(addr, portfolio) {
	const items = Array.isArray(portfolio?.items) ? portfolio.items : [];
	let topToken = null;
	let maxVal = 0;
	let summedUsd = 0;
	for (const item of items) {
		const valueUsd = Number(item?.valueUsd) || 0;
		summedUsd += valueUsd;
		if (valueUsd > maxVal) {
			maxVal = valueUsd;
			topToken = { symbol: item?.symbol ?? '?', valueUsd };
		}
	}
	const totalUsd = Number(portfolio?.totalUsd);
	return {
		address: addr,
		totalUsd: Number.isFinite(totalUsd) ? totalUsd : summedUsd,
		holdings: items.length,
		topToken,
	};
}

// P&L window this proxy reports. The tracker board is window-selectable; this is
// a single-wallet card, so it answers one question ("how has this wallet traded
// lately") with the widest window the FIFO engine keeps cheap.
const PNL_WINDOW = '30d';
const NO_PNL = {
	realizedPnl: null,
	winRate: null,
	totalTrades: null,
	volumeUsd: null,
	pnlSource: null,
	pnlWindow: PNL_WINDOW,
};

// Real FIFO P&L over the wallet's own on-chain trades. No trade history for the
// wallet (no configured trade source, or none inside the window) is NOT a flat
// record: every P&L field stays null so a caller can tell "unknown" from "broke
// even". Same rule for win rate with no closed trades: a wallet that has only
// bought has no win rate yet, which is not a 0% one.
async function _walletPnl(addr) {
	const { getWalletPnl } = await import('../../src/kol/wallet-pnl.js');
	const pnl = await getWalletPnl({ wallet: addr, window: PNL_WINDOW }).catch(() => null);
	if (!pnl || pnl.trades === 0) return NO_PNL;
	return {
		realizedPnl: pnl.realizedUsd,
		winRate: pnl.closedTrades > 0 ? pnl.winRate : null,
		totalTrades: pnl.trades,
		volumeUsd: pnl.volumeUsd,
		pnlSource: 'onchain-fifo',
		pnlWindow: PNL_WINDOW,
	};
}

async function handleWallets(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	// Optional: without it every wallet is read through the RPC balances path.
	const apiKey = process.env.BIRDEYE_API_KEY || null;

	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url = new URL(req.url, `http://${req.headers.host}`);
	const addresses = (url.searchParams.get('addresses') ?? '')
		.split(',')
		.map((s) => s.trim())
		.filter(Boolean)
		.slice(0, MAX_ADDRESSES);
	if (addresses.length === 0)
		return error(res, 400, 'validation_error', 'addresses query param is required');

	const uncached = addresses.filter((a) => _getCached(a) === null);
	const cacheHit = uncached.length === 0;

	if (uncached.length > 0) {
		await Promise.allSettled(
			uncached.map(async (addr) => {
				try {
					// _walletPnl never rejects, so only a holdings failure on BOTH the
					// Birdeye and RPC paths reaches the catch.
					const [portfolio, pnl] = await Promise.all([
						_fetchPortfolio(addr, apiKey),
						_walletPnl(addr),
					]);
					_setCache(addr, { ..._normalizeHoldings(addr, portfolio), ...pnl });
				} catch (err) {
					// The negative cache bounds this log to once per address per
					// NEG_CACHE_TTL window, so an outage can't flood the function logs.
					console.warn(`[kol] birdeye portfolio failed for ${addr.slice(0, 4)}…: ${err?.message || err}`);
					_setCacheError(addr);
				}
			}),
		);
	}

	const data = addresses
		.map((a) => _getCached(a))
		.filter((e) => e && !e.error)
		.map((e) => e.data);
	res.setHeader('x-cache', cacheHit ? 'HIT' : 'MISS');
	return json(res, 200, { data });
}

// ── import-gmgn ───────────────────────────────────────────────────────────────

async function handleImportGmgn(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['POST'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	// Writes the tracked-wallet list that downstream KOL surfaces read — admin only.
	const admin = await requireAdmin(req, res);
	if (!admin) return;
	const body = await readJson(req);
	if (!body || body.rawJson == null)
		return error(res, 400, 'validation_error', 'body.rawJson is required');
	const { parseGmgnSmartWallets } = await import('../../src/kol/gmgn-parser.js');
	let parsed;
	try {
		parsed = parseGmgnSmartWallets(body.rawJson);
	} catch (err) {
		return error(res, 400, 'validation_error', err.message);
	}
	// Optional admin-supplied wallet→X-handle map — the only way an xHandle ever
	// enters the tracked list. Never inferred or scraped: an admin who has verified
	// a real KOL controls a wallet (e.g. a signed message, a public self-disclosure)
	// attaches it here explicitly.
	const HANDLE_RE = /^[A-Za-z0-9_]{1,15}$/;
	const xHandles = body.xHandles && typeof body.xHandles === 'object' ? body.xHandles : {};
	for (const [wallet, handle] of Object.entries(xHandles)) {
		if (typeof handle !== 'string' || !HANDLE_RE.test(handle.replace(/^@/, ''))) continue;
		const entry = parsed.find((e) => e.wallet === wallet);
		if (entry) entry.xHandle = handle.replace(/^@/, '');
	}
	const existing = await loadWallets();
	const byWallet = new Map(existing.map((w) => [w.wallet, w]));
	for (const entry of parsed) {
		const prev = byWallet.get(entry.wallet);
		// Preserve a previously-attached xHandle across a re-import that doesn't repeat it.
		if (prev?.xHandle && !entry.xHandle) entry.xHandle = prev.xHandle;
		byWallet.set(entry.wallet, entry);
	}
	const merged = [...byWallet.values()];
	try {
		await saveImportedWallets(merged);
	} catch (err) {
		console.error('[kol/import-gmgn] R2 write failed:', err?.message || err);
		return error(res, 503, 'storage_unavailable', 'failed to persist imported wallets');
	}
	return json(res, 200, { imported: parsed.length, wallets: merged });
}

// ── leaderboard ───────────────────────────────────────────────────────────────

async function handleLeaderboard(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, `http://${req.headers.host}`);
	const window = url.searchParams.get('window') || '7d';
	const limitRaw = url.searchParams.get('limit');
	const limit = Math.min(Math.max(Number(limitRaw) || 25, 1), 100);
	const { getLeaderboard } = await import('../../src/kol/leaderboard.js');
	let items;
	try {
		items = await getLeaderboard({ window, limit });
	} catch (err) {
		if (err.status === 400) return error(res, 400, err.code || 'validation_error', err.message);
		throw err;
	}
	return json(res, 200, { items });
}

// ── tracker ───────────────────────────────────────────────────────────────────

async function handleTracker(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, `http://${req.headers.host}`);
	const window = url.searchParams.get('window') || '7d';
	if (!['24h', '7d', '30d'].includes(window))
		return error(res, 400, 'validation_error', 'window must be 24h, 7d, or 30d');
	const limitRaw = url.searchParams.get('limit');
	const limit = Math.min(Math.max(Number(limitRaw) || 100, 1), 100);
	const { getKolTracker } = await import('../../src/kol/tracker.js');
	const rows = await getKolTracker({ window, limit });
	return json(res, 200, { window, rows });
}

// ── dispatcher ────────────────────────────────────────────────────────────────

// /api/kol/trades is deliberately absent: api/kol/trades.js is an exact file, so
// filesystem precedence resolves that path to it and any branch here would be
// unreachable code drifting away from the one that actually serves the feed.
// tests/api/kol-route-resolution.test.js pins that split.
const DISPATCH = {
	'import-gmgn': handleImportGmgn,
	leaderboard: handleLeaderboard,
	tracker: handleTracker,
	wallets: handleWallets,
};

export default wrap(async (req, res) => {
	const action = req.query?.action ?? new URL(req.url, 'http://x').pathname.split('/').pop();
	const fn = DISPATCH[action];
	if (!fn) return error(res, 404, 'not_found', `unknown kol action: ${action}`);
	return fn(req, res);
});