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.

18.0 KB
Raw Blame
// /api/agents/:id/alpha — the In-Character Alpha Co-pilot.
//
// The intelligence + voice layer ON TOP of the wallet program's trade rails.
// The agent's LLM persona reads a REAL live pump.fun launch, decides what it
// would do, and explains it in character for its 3D avatar to speak aloud. The
// owner can then act on the read — but only ever through the same guarded path
// the conversational copilot uses (executeAgentTrade → POST /solana/trade),
// which enforces the spend policy, the rug/honeypot firewall, and the custody
// audit. This endpoint NEVER signs and NEVER moves funds.
//
//   GET  /api/agents/:id/alpha/candidates?network=  → real live launches to read
//   POST /api/agents/:id/alpha/read  { mint, network } → grounded in-character read
//
// Anti-hallucination: the model only ever sees real numbers we fetched, and its
// output is clamped + scrubbed against those inputs (api/_lib/alpha-read.js)
// before it is shown or spoken — a fabricated figure is rejected, never voiced.
//
// $THREE (FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump) is the only coin three.ws
// promotes. This reads whatever runtime mint the live feed surfaces — coin-
// agnostic analytics — and never names or recommends any other token.

import { PublicKey } from '@solana/web3.js';
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { sql } from '../_lib/db.js';
import { cors, json, method, error, readJson, rateLimited, wrap } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { solanaPublicConnection } from '../_lib/agent-pumpfun.js';
import { getSmartMoneyForMint } from '../_lib/smart-money.js';
import { getTradeLimits, getSpendLimits, getDailySpendLamports } from '../_lib/agent-trade-guards.js';
import { getBondingCurveState, getBuyQuote, getGraduationProgress } from '../_lib/solana/sdk-bridge.js';
import { connectPumpFunFeed, recentBuffered, recentGraduations } from '../_lib/pumpfun-ws-feed.js';
import { llmComplete, LlmUnavailableError } from '../_lib/llm.js';
import { buildReadPrompt, parseReadJson, validateRead } from '../_lib/alpha-read.js';
import { pumpFetchJson } from '../_lib/pump-feed-fetch.js';
import { fetchUpstreamJson } from '../_lib/upstream-fetch.js';

const NETWORKS = new Set(['mainnet', 'devnet']);
const netOf = (v) => (NETWORKS.has(v) ? v : 'mainnet');
const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const LAMPORTS_PER_SOL = 1_000_000_000;
// Per-coin lookups use the v2 route: pump.fun retired `/coins/:mint` on this host
// around 2026-09-17 (404 "Cannot GET"); `/coins-v2/:mint` returns the same fields.
const PUMPFUN_COIN_API = 'https://frontend-api-v3.pump.fun/coins-v2';
const REFERENCE_BUY_SOL = 0.1; // probe size for a real, non-binding price-impact read

const num = (v) => (v == null || !Number.isFinite(Number(v)) ? null : Number(v));

// ── auth (optional — public commentary works logged-out) ───────────────────────
async function resolveAuth(req) {
	const session = await getSessionUser(req).catch(() => null);
	if (session) return { userId: session.id };
	const bearer = await authenticateBearer(extractBearer(req)).catch(() => null);
	if (bearer) return { userId: bearer.userId };
	return null;
}

// Load the agent for an alpha read. Public commentary is allowed for published
// agents; the owner additionally unlocks wallet-aware sizing + the action gate.
async function loadAgent(id, userId) {
	const [row] = await sql`
		SELECT id, user_id, name, persona_prompt, voice_provider, voice_id, avatar_id,
		       is_published, meta
		FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
	if (!row) return { error: { status: 404, code: 'not_found', msg: 'agent not found' } };
	const owner = !!userId && row.user_id === userId;
	if (!owner && !row.is_published) return { error: { status: 404, code: 'not_found', msg: 'agent not found' } };
	return { row, owner };
}

// ── live launch candidates ──────────────────────────────────────────────────────

// The read only consumes `created_timestamp` (launch age). pump.fun is the
// source of truth; when it does not answer, DexScreener's pair listing carries
// the pair creation time for the same mint, so the age still comes from a real
// record rather than going missing on a pump.fun blip.
async function fetchPumpCoin(mint) {
	const { ok, body } = await pumpFetchJson(`${PUMPFUN_COIN_API}/${encodeURIComponent(mint)}`, { timeoutMs: 2500, retries: 1 });
	if (ok && body && typeof body === 'object') return body;
	try {
		const data = await fetchUpstreamJson(`https://api.dexscreener.com/latest/dex/tokens/${encodeURIComponent(mint)}`, {}, {
			timeoutMs: 2500, attempts: 1, name: 'dexscreener',
		});
		const pairs = (Array.isArray(data?.pairs) ? data.pairs : []).filter((p) => p?.chainId === 'solana');
		if (!pairs.length) return null;
		pairs.sort((a, b) => (a.pairCreatedAt ?? Infinity) - (b.pairCreatedAt ?? Infinity));
		const createdMs = Number(pairs[0].pairCreatedAt);
		return Number.isFinite(createdMs) ? { mint, created_timestamp: createdMs } : null;
	} catch { return null; }
}

// Briefly tap the live PumpPortal mint feed to gather fresh launches. Bounded so
// a serverless request never hangs; resolves with whatever real mints arrived.
function collectLiveMints({ ms = 3200, want = 12 } = {}) {
	return new Promise((resolve) => {
		const out = [];
		const seen = new Set();
		const abort = new AbortController();
		let done = false;
		const finish = () => { if (done) return; done = true; try { abort.abort(); } catch {} resolve(out); };
		try {
			connectPumpFunFeed({
				kind: 'mint',
				signal: abort.signal,
				onEvent: ({ kind, data }) => {
					if (done || kind !== 'mint' || !data?.mint || seen.has(data.mint)) return;
					seen.add(data.mint);
					out.push(data);
					if (out.length >= want) finish();
				},
			});
		} catch { finish(); }
		setTimeout(finish, ms);
	});
}

async function enrichCandidate(c, network) {
	const [sm, intel] = await Promise.all([
		getSmartMoneyForMint(c.mint, network).catch(() => null),
		loadIntel(c.mint, network).catch(() => null),
	]);
	const createdSec = num(c.created_at) || num(c.timestamp);
	const ageSeconds = createdSec ? Math.max(0, Math.floor(Date.now() / 1000 - createdSec)) : null;
	return {
		mint: c.mint,
		symbol: c.symbol || intel?.symbol || null,
		name: c.name || intel?.name || null,
		image_uri: c.image_uri || null,
		age_seconds: ageSeconds,
		market_cap_usd: num(c.market_cap_usd) ?? num(c.usd_market_cap),
		initial_buy_sol: num(c.initial_buy_sol),
		creator: c.creator || null,
		creator_launches: num(c.creator_launches),
		creator_graduated: num(c.creator_graduated),
		twitter: c.twitter || null,
		telegram: c.telegram || null,
		website: c.website || null,
		smart_money_score: sm?.smart_money_score ?? null,
		smart_money_count: sm?.count ?? null,
		sybil_flag: sm?.sybil_flag ?? false,
		quality_score: intel?.quality_score ?? null,
		risk_flags: intel?.risk_flags ?? [],
	};
}

async function handleCandidates(req, res, id) {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['GET'])) return;

	const auth = await resolveAuth(req);
	const rl = await limits.publicIp(clientIp(req)).catch(() => ({ success: true }));
	if (rl && rl.success === false) return rateLimited(res, rl);

	const loaded = await loadAgent(id, auth?.userId);
	if (loaded.error) return error(res, loaded.error.status, loaded.error.code, loaded.error.msg);

	const url = new URL(req.url, 'http://x');
	const network = netOf(url.searchParams.get('network'));

	// Merge three real sources, newest-first, deduped by mint: the warm in-process
	// buffer (instant), a brief live tap of the feed (fresh mints), and persisted
	// graduations from Postgres (always available, even on a cold instance).
	const byMint = new Map();
	const add = (d) => { if (d?.mint && !byMint.has(d.mint)) byMint.set(d.mint, d); };

	if (network === 'mainnet') {
		recentBuffered({ kind: 'mint', limit: 12 }).forEach((e) => add(e.data));
		if (byMint.size < 8) {
			const live = await collectLiveMints({ want: 12 - byMint.size }).catch(() => []);
			live.forEach(add);
		}
		recentBuffered({ kind: 'graduation', limit: 6 }).forEach((e) => add(e.data));
		if (byMint.size < 4) {
			const grads = await recentGraduations({ limit: 8 }).catch(() => []);
			grads.forEach(add);
		}
	}

	const raw = [...byMint.values()].slice(0, 10);
	const items = await Promise.all(raw.map((c) => enrichCandidate(c, network).catch(() => null)));
	return json(res, 200, { network, items: items.filter(Boolean) }, { 'cache-control': 'no-store' });
}

// ── intel read (same shape the copilot uses) ────────────────────────────────────
async function loadIntel(mint, network) {
	const [row] = await sql`
		SELECT i.mint, i.symbol, i.name, i.quality_score, i.bundle_score, i.organic_score,
		       i.snipe_ratio, i.concentration_top10, i.fresh_wallet_ratio, i.risk_flags,
		       i.category, i.narrative, i.dev_sold, i.unique_buyers,
		       o.outcome, o.ath_multiple
		FROM pump_coin_intel i
		LEFT JOIN pump_coin_outcomes o ON o.mint = i.mint AND o.network = i.network
		WHERE i.mint = ${mint} AND i.network = ${network}
		LIMIT 1`.catch(() => []);
	if (!row) return null;
	return {
		symbol: row.symbol, name: row.name,
		quality_score: num(row.quality_score),
		bundle_score: num(row.bundle_score), organic_score: num(row.organic_score),
		snipe_ratio: num(row.snipe_ratio), concentration_top10: num(row.concentration_top10),
		fresh_wallet_ratio: num(row.fresh_wallet_ratio), risk_flags: row.risk_flags || [],
		category: row.category, narrative: row.narrative, dev_sold: row.dev_sold,
		unique_buyers: num(row.unique_buyers),
		outcome: row.outcome || null, ath_multiple: num(row.ath_multiple),
	};
}

// Gather every REAL signal for one mint. Each source degrades to null on its own
// — a thin coin yields a thin (but honest) signal bundle, never a fabricated one.
async function gatherSignals(mint, network, { agentId, meta, owner }) {
	const conn = solanaPublicConnection(network);
	const mintPk = new PublicKey(mint);
	const refLamports = Math.floor(REFERENCE_BUY_SOL * LAMPORTS_PER_SOL);
	const walletPk = owner && meta.solana_address ? new PublicKey(meta.solana_address) : null;

	const [coin, intel, sm, curve, grad, buyQuote, walletLamports, dailySpentLamports] = await Promise.all([
		network === 'mainnet' ? fetchPumpCoin(mint).catch(() => null) : Promise.resolve(null),
		loadIntel(mint, network).catch(() => null),
		getSmartMoneyForMint(mint, network).catch(() => null),
		getBondingCurveState(conn, mintPk).catch(() => null),
		getGraduationProgress(conn, mintPk).catch(() => null),
		getBuyQuote(conn, mintPk, refLamports).catch(() => null),
		walletPk ? conn.getBalance(walletPk).catch(() => null) : Promise.resolve(null),
		owner ? getDailySpendLamports(agentId, network).catch(() => 0n) : Promise.resolve(0n),
	]);

	const createdSec = num(coin?.created_timestamp) ? Math.floor(coin.created_timestamp / 1000) : null;
	const liquiditySol = curve ? round3(Number(BigInt(curve.realSolReserves)) / 1e9) : null;
	const gradPct = num(grad?.progress) != null ? Math.round(num(grad.progress) * 100) : (curve?.complete ? 100 : null);

	const tradeLimits = getTradeLimits(meta);
	const spendLimits = getSpendLimits(meta);
	const balanceSol = walletLamports != null ? round3(Number(walletLamports) / 1e9) : null;
	const dailySpentSol = round3(Number(dailySpentLamports || 0n) / 1e9);

	const signals = {
		symbol: coin?.symbol || intel?.symbol || null,
		name: coin?.name || intel?.name || null,
		network,
		age_minutes: createdSec ? Math.max(0, Math.round((Date.now() / 1000 - createdSec) / 60)) : null,
		market_cap_usd: num(coin?.usd_market_cap),
		liquidity_sol: liquiditySol,
		bonding_curve_progress_pct: gradPct,
		graduated: curve ? !!curve.complete : (coin?.complete ?? null),
		reference_buy_sol: buyQuote ? REFERENCE_BUY_SOL : null,
		reference_buy_price_impact_pct: buyQuote ? round2(buyQuote.priceImpact) : null,
		// Intelligence engine fingerprint (null when the engine hasn't observed it).
		quality_score: intel?.quality_score ?? null,
		organic_score: intel?.organic_score ?? null,
		bundle_score: intel?.bundle_score ?? null,
		concentration_top10_pct: intel?.concentration_top10 ?? null,
		fresh_wallet_ratio: intel?.fresh_wallet_ratio ?? null,
		unique_buyers: intel?.unique_buyers ?? null,
		dev_sold: intel?.dev_sold ?? null,
		narrative: intel?.narrative || null,
		risk_flags: intel?.risk_flags ?? [],
		outcome: intel?.outcome ?? null,
		// Smart money (reputation graph).
		smart_money_score: sm?.smart_money_score ?? null,
		smart_money_wallets: sm?.count ?? null,
		sybil_dominated: sm?.sybil_flag ?? null,
	};

	// Owner-only wallet context (also feeds the size clamp + action gate).
	const context = owner
		? {
				balanceSol,
				perTradeSol: tradeLimits.per_trade_sol,
				dailyBudgetSol: tradeLimits.daily_budget_sol,
				dailySpentSol,
				killSwitch: tradeLimits.kill_switch,
				frozen: spendLimits.frozen,
			}
		: {};
	if (owner) {
		signals.wallet_balance_sol = balanceSol;
		signals.per_trade_limit_sol = tradeLimits.per_trade_sol;
		signals.daily_budget_sol = tradeLimits.daily_budget_sol;
		signals.daily_spent_sol = dailySpentSol;
		signals.trading_paused = tradeLimits.kill_switch || spendLimits.frozen;
	}

	// True when literally nothing real is known — used to skip the LLM and answer
	// honestly rather than ask the model to opine on a void.
	const hasData = [signals.market_cap_usd, signals.liquidity_sol, signals.quality_score,
		signals.smart_money_score, signals.symbol, signals.reference_buy_price_impact_pct]
		.some((v) => v != null);

	return { signals, context, hasData };
}

const round3 = (n) => Math.round(n * 1e3) / 1e3;
const round2 = (n) => Math.round(n * 1e2) / 1e2;

async function handleRead(req, res, id) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const auth = await resolveAuth(req);
	const rl = auth?.userId
		? await limits.tradePerUser(auth.userId).catch(() => ({ success: true }))
		: await limits.publicIp(clientIp(req)).catch(() => ({ success: true }));
	if (rl && rl.success === false) return rateLimited(res, rl);

	const loaded = await loadAgent(id, auth?.userId);
	if (loaded.error) return error(res, loaded.error.status, loaded.error.code, loaded.error.msg);
	const { row, owner } = loaded;
	const meta = row.meta || {};

	const body = await readJson(req).catch(() => null);
	const network = netOf(body?.network);
	const mint = typeof body?.mint === 'string' ? body.mint.trim() : '';
	if (!BASE58_RE.test(mint)) return error(res, 422, 'invalid_mint', 'a valid token mint is required');
	if (owner && !meta.solana_address) return error(res, 409, 'no_wallet', 'this agent has no wallet yet');

	const agentName = row.name || 'Agent';
	const agentMeta = {
		id: row.id,
		name: agentName,
		voice_provider: row.voice_provider || 'browser',
		voice_id: row.voice_id || null,
		avatar_id: row.avatar_id || null,
	};

	let signals, context, hasData;
	try {
		({ signals, context, hasData } = await gatherSignals(mint, network, { agentId: id, meta, owner }));
	} catch (e) {
		console.error('[agents/alpha] signal gather failed', mint, e?.message || e);
		return error(res, 502, 'signal_error', 'could not read live signals for this launch — try again');
	}

	// Nothing real to go on: answer honestly, no LLM, no invented confidence.
	if (!hasData) {
		const read = {
			verdict: 'pass',
			conviction: 0,
			suggested_size_sol: null,
			risks: ['No live data is available for this mint yet.'],
			cited_signals: [],
			spoken_line: `I can't read ${signals.symbol ? '$' + signals.symbol : 'this one'} yet — there's no live data in front of me, so I'm not going to pretend I have a call.`,
			hallucination_guard: { ok: true, suspicious_numbers: [], line_replaced: false },
		};
		return json(res, 200, {
			mint, network, agent: agentMeta, owner, signals, read,
			gate: { can_act: false, reason: owner ? 'no_data' : 'not_owner', message: 'No data to act on.' },
			grounded: true, source: 'no_data',
		}, { 'cache-control': 'no-store' });
	}

	const { system, user } = buildReadPrompt({ agentName, persona: row.persona_prompt, network, signals, owner });

	let completion;
	try {
		completion = await llmComplete({
			// Sonnet 5 thinks by default and max_tokens caps thinking + answer
			// together, so the budget carries headroom beyond the ~700-token read.
			system, user, maxTokens: 2000, anthropicModel: 'claude-sonnet-5', timeoutMs: 30_000,
			track: { userId: auth?.userId ?? null, agentId: id, tool: 'alpha_read' },
		});
	} catch (e) {
		if (e instanceof LlmUnavailableError || e?.code === 'llm_unavailable') {
			return error(res, 503, 'narrator_offline', 'The co-pilot narrator is offline right now. Your wallet and trading still work — try the read again shortly.');
		}
		if (e?.code === 'daily_spend_cap_exceeded') return error(res, 429, e.code, e.message);
		console.error('[agents/alpha] read failed', mint, e?.message || e);
		return error(res, 502, 'read_failed', 'The co-pilot could not complete this read. Try again.');
	}

	const raw = parseReadJson(completion.text);
	const { read, gate } = validateRead({ raw, signals, agentName, owner, context });

	return json(res, 200, {
		mint, network, agent: agentMeta, owner, signals, read, gate,
		grounded: read.hallucination_guard.ok,
		model: completion.model, provider: completion.provider,
		source: 'llm',
	}, { 'cache-control': 'no-store' });
}

// ── dispatch ────────────────────────────────────────────────────────────────────
export default wrap(async function handler(req, res, id, action) {
	if (action === 'candidates') return handleCandidates(req, res, id);
	if (action === 'read') return handleRead(req, res, id);
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	return error(res, 404, 'not_found', 'unknown alpha sub-resource');
});