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.

21.0 KB
Raw Blame
// Oracle — live market intel aggregator for one coin.
//
// Oracle's conviction store (store.js/sources.js) answers "should I trust this
// launch" from the platform's own on-chain brain. It deliberately holds NO live
// market data — no price, market cap, liquidity, holder count, bonding-curve
// progress or security posture. This module fills that gap: it fans out to every
// public market source we have a key (or keyless access) for, in parallel, and
// fuses them into one fully-populated `CoinMarket` shape so the Oracle coin page
// can render every field a trader expects.
//
// Sources (all real, no mocks), each isolated so one being down/rate-limited
// degrades that slice to null instead of failing the whole read:
//   · DexScreener  (keyless) — price, 5m/1h/6h/24h changes + txns + volume,
//                              liquidity, FDV, market cap, DEX pairs, image, socials
//   · pump.fun v3  (keyless) — bonding-curve progress, SOL reserves, replies,
//                              live-status, ATH market cap, creator, socials
//   · GeckoTerminal(keyless) — total supply, FDV, graduation %, CoinGecko id
//   · GoPlus       (keyless) — mint/freeze authority, mutable metadata, transfer
//                              fee, holder count + top-10 concentration
//   · RugCheck     (keyless) - overall 0-100 risk score, named risk findings,
//                              LP-lock % (second security opinion next to GoPlus)
//   · Birdeye      (keyed)   — holders + circulating supply + price (redundancy)
//   · CoinGecko    (keyed)   — ATH/ATL, market-cap rank, categories (listed coins)
//
// Merge precedence favors the richest/most-specific source per field; every
// number traces to a live upstream. Cached L1 (per-instance) + L2 (Upstash) so a
// coin page poll almost never fans out to seven upstreams.

import { cacheGet, cacheSet } from '../cache.js';
import { createCache } from '../mem-cache.js';
import { fetchRugcheckSummary } from '../rugcheck.js';
import { bondingProgressPct } from '../pump-bonding.js';
import { gmgnTokenUrl, dextoolsTokenUrl } from '../../../src/shared/trading-terminals.js';
import { dextoolsUrl } from '../../../src/shared/dextools.js';
import { DEXTOOLS_PAIR_URL } from '../../../src/pump/dextools-social-boost.js';
import { THREE_MINT } from '../stage-split.js';

const DEXSCREENER = 'https://api.dexscreener.com/latest/dex/tokens';
const PUMP_V3 = 'https://frontend-api-v3.pump.fun';
const GECKOTERMINAL = 'https://api.geckoterminal.com/api/v2/networks/solana/tokens';
const GOPLUS = 'https://api.gopluslabs.io/api/v1/solana/token_security';
const BIRDEYE = 'https://public-api.birdeye.so';
const COINGECKO = 'https://api.coingecko.com/api/v3';

const FETCH_TIMEOUT_MS = 6000;
const WSOL = 'So11111111111111111111111111111111111111112';

// True LRU bounding: the previous Map was trimmed with
// `delete(keys().next().value)`, evicting the oldest INSERTED key rather than
// the least recently used one.
const L1 = createCache({ max: 256 }); // key -> { value, expires }
const L1_TTL_MS = 20_000;
const L2_TTL_S = 45;

const num = (v) => {
	if (v == null) return null;
	const n = typeof v === 'string' ? parseFloat(v) : Number(v);
	return Number.isFinite(n) ? n : null;
};
const clampPct = (n) => (n == null ? null : Math.max(0, Math.min(100, n)));

async function fetchJson(url, opts = {}) {
	const ctrl = new AbortController();
	const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs || FETCH_TIMEOUT_MS);
	try {
		const r = await fetch(url, { ...opts, signal: ctrl.signal });
		if (!r.ok) throw new Error(String(r.status));
		return await r.json();
	} finally {
		clearTimeout(timer);
	}
}

// ── per-source adapters (each returns a partial CoinMarket or null) ───────────

async function fromDexScreener(mint) {
	const data = await fetchJson(`${DEXSCREENER}/${mint}`);
	const pairs = Array.isArray(data?.pairs) ? data.pairs.filter((p) => p.chainId === 'solana') : [];
	if (!pairs.length) return null;
	// Deepest-liquidity pair is the canonical market for price/volume/change.
	const best = pairs.reduce((a, b) => ((b.liquidity?.usd || 0) > (a.liquidity?.usd || 0) ? b : a));
	const price = num(best.priceUsd);
	const info = best.info || {};
	const socials = Array.isArray(info.socials) ? info.socials : [];
	const websites = Array.isArray(info.websites) ? info.websites : [];
	const twitter = socials.find((s) => /twitter|^x$/i.test(s.type))?.url || null;
	const telegram = socials.find((s) => /telegram/i.test(s.type))?.url || null;
	return {
		sources: ['dexscreener'],
		identity: {
			name: best.baseToken?.name || null,
			symbol: best.baseToken?.symbol || null,
			image: info.imageUrl || null,
		},
		price_usd: price,
		price_native: num(best.priceNative),
		change: {
			m5: num(best.priceChange?.m5),
			h1: num(best.priceChange?.h1),
			h6: num(best.priceChange?.h6),
			h24: num(best.priceChange?.h24),
		},
		volume: {
			m5: num(best.volume?.m5),
			h1: num(best.volume?.h1),
			h6: num(best.volume?.h6),
			h24: num(best.volume?.h24),
		},
		txns: best.txns || null,
		liquidity_usd: num(best.liquidity?.usd),
		market_cap_usd: num(best.marketCap),
		fdv_usd: num(best.fdv),
		pair_created_at: num(best.pairCreatedAt),
		links: { website: websites[0]?.url || null, twitter, telegram },
		pairs: pairs
			.slice()
			.sort((a, b) => (b.liquidity?.usd || 0) - (a.liquidity?.usd || 0))
			.slice(0, 6)
			.map((p) => ({
				dex: p.dexId || null,
				pair_address: p.pairAddress || null,
				url: p.url || null,
				quote_symbol: p.quoteToken?.symbol || null,
				price_usd: num(p.priceUsd),
				liquidity_usd: num(p.liquidity?.usd),
				volume_h24: num(p.volume?.h24),
			})),
	};
}

async function fromPumpFun(mint) {
	const d = await fetchJson(`${PUMP_V3}/coins-v2/${mint}`, { headers: { accept: 'application/json' } });
	if (!d || !d.mint) return null;
	const complete = Boolean(d.complete);
	// Graduation progress: 100 once complete; otherwise the share of the curve's
	// initial token float that's been bought out (shared curve math — pump-bonding.js).
	const bondingPct = complete ? 100 : bondingProgressPct(d.real_token_reserves);
	return {
		sources: ['pumpfun'],
		identity: {
			name: d.name || null,
			symbol: d.symbol || null,
			image: d.image_uri || null,
			description: d.description || null,
		},
		links: {
			website: d.website || null,
			twitter: d.twitter || null,
			telegram: d.telegram || null,
		},
		creator: d.creator || null,
		created_at: d.created_timestamp ? new Date(Number(d.created_timestamp)).toISOString() : null,
		supply_total: num(d.total_supply) != null ? num(d.total_supply) / 1e6 : null,
		pumpfun: {
			is_pump: true,
			complete,
			graduated: complete,
			bonding_curve_pct: bondingPct,
			real_sol_reserves: num(d.real_sol_reserves) != null ? num(d.real_sol_reserves) / 1e9 : null,
			virtual_sol_reserves: num(d.virtual_sol_reserves) != null ? num(d.virtual_sol_reserves) / 1e9 : null,
			reply_count: num(d.reply_count),
			is_live: Boolean(d.is_currently_live),
			nsfw: Boolean(d.nsfw),
			is_banned: Boolean(d.is_banned),
			ath_market_cap_usd: num(d.ath_market_cap),
			ath_market_cap_at: d.ath_market_cap_timestamp ? new Date(Number(d.ath_market_cap_timestamp)).toISOString() : null,
			king_of_the_hill_at: d.king_of_the_hill_timestamp ? new Date(Number(d.king_of_the_hill_timestamp)).toISOString() : null,
			last_trade_at: d.last_trade_timestamp ? new Date(Number(d.last_trade_timestamp)).toISOString() : null,
			pump_swap_pool: d.pump_swap_pool || null,
			quote_mint: d.quote_mint || null,
		},
	};
}

async function fromGeckoTerminal(mint) {
	const data = await fetchJson(`${GECKOTERMINAL}/${mint}`, { headers: { accept: 'application/json' } });
	const a = data?.data?.attributes;
	if (!a) return null;
	const decimals = num(a.decimals) ?? 6;
	const lp = a.launchpad_details || {};
	return {
		sources: ['geckoterminal'],
		identity: { name: a.name || null, symbol: a.symbol || null, image: a.image_url || null, decimals },
		price_usd: num(a.price_usd),
		market_cap_usd: num(a.market_cap_usd) ?? num(a.fdv_usd),
		fdv_usd: num(a.fdv_usd),
		volume: { h24: num(a.volume_usd?.h24) },
		liquidity_usd: num(a.total_reserve_in_usd),
		supply_total: num(a.normalized_total_supply),
		coingecko_id: a.coingecko_coin_id || null,
		pumpfun: lp && Object.keys(lp).length
			? { graduation_pct: clampPct(num(lp.graduation_percentage)), complete: Boolean(lp.completed) }
			: undefined,
	};
}

function goplusAuthorityRevoked(field) {
	// GoPlus encodes an authority-controlled risk as status "1" (present/active).
	// "0" = the authority is renounced/absent, i.e. the safe state.
	if (!field || field.status == null) return null;
	return String(field.status) === '0';
}

async function fromGoPlus(mint) {
	const data = await fetchJson(`${GOPLUS}?contract_addresses=${mint}`, { headers: { accept: 'application/json' } });
	const r = data?.result?.[mint];
	if (!r) return null;
	const holders = Array.isArray(r.holders) ? r.holders : [];
	// Holders are returned already ranked; sum their share for a top-10 read.
	const top10Pct = holders.length
		? clampPct(holders.slice(0, 10).reduce((s, h) => s + (num(h.percent) || 0) * 100, 0))
		: null;
	const fee = r.transfer_fee && typeof r.transfer_fee === 'object' ? num(r.transfer_fee.fee_rate ?? r.transfer_fee.rate) : null;
	return {
		sources: ['goplus'],
		holders: num(r.holder_count),
		supply_total: num(r.total_supply),
		security: {
			mint_authority_revoked: goplusAuthorityRevoked(r.mintable),
			freeze_authority_revoked: goplusAuthorityRevoked(r.freezable),
			metadata_mutable: r.metadata_mutable?.status != null ? String(r.metadata_mutable.status) === '1' : null,
			transfer_fee_pct: fee != null ? fee * 100 : (r.transfer_fee && Object.keys(r.transfer_fee).length ? null : 0),
			transfer_hook: r.transfer_hook?.status != null ? String(r.transfer_hook.status) === '1' : null,
			non_transferable: r.non_transferable != null ? String(r.non_transferable) === '1' : null,
			trusted_token: r.trusted_token != null ? String(r.trusted_token) === '1' : null,
			top10_holder_pct: top10Pct,
			source: 'goplus',
		},
		top_holders: holders.slice(0, 10).map((h) => ({
			account: h.account || null,
			pct: num(h.percent) != null ? num(h.percent) * 100 : null,
			is_locked: Boolean(h.is_locked),
			tag: h.tag || null,
		})),
	};
}

// RugCheck is the second security opinion next to GoPlus: GoPlus states the
// on-chain facts (authorities, fees, concentration); RugCheck grades the mint
// with its own risk engine (normalized 0-100 score where higher is riskier,
// named findings, LP-lock coverage). The two blend in mergeMarketSources with
// either one failing soft, so a GoPlus outage no longer blanks `security`.
async function fromRugCheck(mint) {
	const s = await fetchRugcheckSummary(mint);
	if (!s) return null;
	return {
		sources: ['rugcheck'],
		security: {
			rugcheck_score: s.score_normalised,
			rugcheck_level: s.level,
			rugcheck_risks: s.risks,
			lp_locked_pct: s.lp_locked_pct,
			source: 'rugcheck',
		},
	};
}

async function fromBirdeye(mint) {
	const key = process.env.BIRDEYE_API_KEY;
	if (!key) return null;
	const data = await fetchJson(`${BIRDEYE}/defi/token_overview?address=${mint}`, {
		headers: { 'X-API-KEY': key, 'x-chain': 'solana', accept: 'application/json' },
	});
	const ov = data?.data;
	if (!ov) return null;
	return {
		sources: ['birdeye'],
		price_usd: num(ov.price),
		change: { h24: num(ov.priceChange24hPercent) },
		market_cap_usd: num(ov.mc ?? ov.marketCap),
		fdv_usd: num(ov.fdv),
		volume: { h24: num(ov.v24hUSD ?? ov.volume24h) },
		liquidity_usd: num(ov.liquidity),
		holders: num(ov.holder),
		supply_total: num(ov.supply),
		supply_circulating: num(ov.circulatingSupply),
	};
}

// CoinGecko only knows *listed* tokens — most fresh pump.fun coins 404 here.
// We only call it when GeckoTerminal handed us a coingecko id (proof it's
// listed), so we never burn quota on unlisted mints. Adds the "real market"
// fields nothing else has: ATH/ATL, market-cap rank, categories.
async function fromCoinGecko(coingeckoId) {
	if (!coingeckoId) return null;
	const key = process.env.COINGECKO_API_KEY;
	const headers = { accept: 'application/json' };
	if (key) headers['x-cg-demo-api-key'] = key;
	const d = await fetchJson(
		`${COINGECKO}/coins/${encodeURIComponent(coingeckoId)}?localization=false&tickers=false&community_data=false&developer_data=false&sparkline=false`,
		{ headers },
	);
	const md = d?.market_data;
	if (!md) return null;
	return {
		sources: ['coingecko'],
		listing: {
			coingecko_id: d.id || coingeckoId,
			market_cap_rank: num(d.market_cap_rank),
			categories: Array.isArray(d.categories) ? d.categories.filter(Boolean).slice(0, 6) : [],
			ath_usd: num(md.ath?.usd),
			ath_date: md.ath_date?.usd || null,
			ath_change_pct: num(md.ath_change_percentage?.usd),
			atl_usd: num(md.atl?.usd),
			atl_date: md.atl_date?.usd || null,
			atl_change_pct: num(md.atl_change_percentage?.usd),
			circulating_supply: num(md.circulating_supply),
			total_supply: num(md.total_supply),
			max_supply: num(md.max_supply),
			change_7d: num(md.price_change_percentage_7d),
			change_30d: num(md.price_change_percentage_30d),
		},
	};
}

// ── merge ─────────────────────────────────────────────────────────────────────

// First non-null across the given partials for a dotted path. Sources are passed
// in precedence order so the richest source wins each field.
function pick(partials, path) {
	const keys = path.split('.');
	for (const p of partials) {
		if (!p) continue;
		let v = p;
		for (const k of keys) v = v == null ? undefined : v[k];
		if (v != null) return v;
	}
	return null;
}

/**
 * Fuse the per-source partials into one fully-populated CoinMarket. Pure given
 * its inputs (no network / clock) so it can be unit-tested against fixtures.
 *
 * @param {string} mint
 * @param {string} network
 * @param {{dex?:object,pump?:object,gecko?:object,goplus?:object,rugcheck?:object,birdeye?:object,coingecko?:object}} p
 * @param {string} fetchedAt ISO timestamp (injected so the merge stays pure)
 */
export function mergeMarketSources(mint, network, p, fetchedAt) {
	const { dex, pump, gecko, goplus, rugcheck, birdeye, coingecko } = p;
	// Precedence chains per field family (richest/most-specific first).
	const idOrder = [pump, dex, gecko, birdeye];
	const priceOrder = [dex, birdeye, gecko];
	const mcOrder = [dex, gecko, birdeye];
	const liqOrder = [dex, gecko, birdeye];
	const supplyOrder = [gecko, birdeye, pump, goplus];

	const sources = [...new Set([dex, pump, gecko, goplus, rugcheck, birdeye, coingecko].filter(Boolean).flatMap((s) => s.sources || []))];

	// Security blends the two independent opinions: GoPlus's on-chain facts keep
	// their fields, RugCheck contributes its score/findings/LP-lock alongside
	// (`rugcheck_*` keys, no collisions). Either opinion alone still yields a
	// security block; `source` names exactly who answered.
	const security = goplus?.security || rugcheck?.security
		? {
			...(rugcheck?.security || {}),
			...(goplus?.security || {}),
			source: [goplus?.security ? 'goplus' : null, rugcheck?.security ? 'rugcheck' : null].filter(Boolean).join('+'),
		}
		: null;

	// pump.fun graduation truth: prefer the explicit flag, fall back to Gecko's %.
	const pf = pump?.pumpfun || {};
	const graduationPct = pf.bonding_curve_pct ?? gecko?.pumpfun?.graduation_pct ?? null;
	const pumpfun = pump?.pumpfun
		? { ...pf, bonding_curve_pct: graduationPct }
		: (gecko?.pumpfun ? { is_pump: /pump$/.test(mint), ...gecko.pumpfun, bonding_curve_pct: graduationPct } : (/pump$/.test(mint) ? { is_pump: true, bonding_curve_pct: graduationPct } : null));

	// DexScreener's socials are curated (project handle); pump.fun's `twitter`
	// is often the launch-tweet URL — so prefer Dex for links, pump as fallback.
	const linkOrder = [dex, pump, gecko, birdeye];
	const links = {
		website: pick(linkOrder, 'links.website'),
		twitter: pick(linkOrder, 'links.twitter'),
		telegram: pick(linkOrder, 'links.telegram'),
		dexscreener: dex?.pairs?.[0]?.url || `https://dexscreener.com/solana/${mint}`,
		// $THREE: the pair its Social Boost wins are credited to. Any other coin:
		// the most-liquid pair DexScreener named, else the counted resolver (a raw
		// mint would land a graduated pump.fun coin on its dead bonding-curve page).
		dextools:
			mint === THREE_MINT
				? DEXTOOLS_PAIR_URL
				: dextoolsUrl(dex?.pairs?.[0]?.pair_address) || dextoolsTokenUrl(mint, { from: 'oracle' }),
		gmgn: gmgnTokenUrl(mint),
		geckoterminal: `https://www.geckoterminal.com/solana/pools/${mint}`,
		birdeye: `https://birdeye.so/token/${mint}?chain=solana`,
		solscan: `https://solscan.io/token/${mint}`,
		pumpfun: `https://pump.fun/coin/${mint}`,
	};

	const priceUsd = num(pick(priceOrder, 'price_usd'));
	const holders = num(pick([goplus, birdeye], 'holders'));

	return {
		mint,
		network,
		fetched_at: fetchedAt,
		sources,
		identity: {
			name: pick(idOrder, 'identity.name'),
			symbol: pick(idOrder, 'identity.symbol'),
			image: pick(idOrder, 'identity.image'),
			description: pick([pump, gecko], 'identity.description'),
			decimals: num(pick([gecko, birdeye], 'identity.decimals')) ?? 6,
			creator: pump?.creator || null,
			created_at: pump?.created_at || (dex?.pair_created_at ? new Date(dex.pair_created_at).toISOString() : null),
		},
		price: {
			usd: priceUsd,
			native_sol: num(dex?.price_native),
			change: {
				m5: num(pick([dex], 'change.m5')),
				h1: num(pick([dex], 'change.h1')),
				h6: num(pick([dex], 'change.h6')),
				h24: num(pick([dex, birdeye], 'change.h24')),
				d7: num(coingecko?.listing?.change_7d),
				d30: num(coingecko?.listing?.change_30d),
			},
		},
		market_cap_usd: num(pick(mcOrder, 'market_cap_usd')),
		fdv_usd: num(pick([dex, gecko, birdeye], 'fdv_usd')),
		liquidity_usd: num(pick(liqOrder, 'liquidity_usd')),
		volume: {
			m5: num(dex?.volume?.m5),
			h1: num(dex?.volume?.h1),
			h6: num(dex?.volume?.h6),
			h24: num(pick([dex, gecko, birdeye], 'volume.h24')),
		},
		activity: activityFrom(dex?.txns),
		holders,
		supply: {
			total: num(pick(supplyOrder, 'supply_total')),
			circulating: num(pick([birdeye, coingecko], 'supply_circulating')) ?? num(coingecko?.listing?.circulating_supply),
			decimals: num(pick([gecko, birdeye], 'identity.decimals')) ?? 6,
		},
		pumpfun,
		security,
		top_holders: goplus?.top_holders || [],
		listing: coingecko?.listing || (gecko?.coingecko_id ? { coingecko_id: gecko.coingecko_id } : null),
		pairs: dex?.pairs || [],
		links,
	};
}

// Roll the per-window DexScreener txn counts into 24h buy/sell totals + a ratio.
function activityFrom(txns) {
	if (!txns || typeof txns !== 'object') return null;
	const h24 = txns.h24 || {};
	const buys = num(h24.buys);
	const sells = num(h24.sells);
	const total = (buys || 0) + (sells || 0);
	return {
		windows: txns,
		buys_24h: buys,
		sells_24h: sells,
		txns_24h: total || null,
		buy_ratio: total ? (buys || 0) / total : null,
	};
}

/**
 * Fully-populated live market intel for one mint, fused across every source.
 * L1 (per-instance) + L2 (Upstash) cached; returns null only when every source
 * is simultaneously unavailable and no price could be established.
 *
 * @param {string} mint
 * @param {string} network
 * @param {{ fresh?: boolean }} [opts]
 */
export async function fetchCoinMarket(mint, network = 'mainnet', { fresh = false } = {}) {
	const key = `oracle:mkt:v1:${network}:${mint}`;
	const now = Date.now();
	if (!fresh) {
		const l1 = L1.get(mint);
		if (l1 && l1.expires > now) return l1.value;
		try {
			const l2 = await cacheGet(key);
			if (l2 && l2.price?.usd != null) {
				L1.set(mint, { value: l2, expires: now + L1_TTL_MS });
				return l2;
			}
		} catch { /* fall through to live fetch */ }
	}

	// Stage 1: every keyless/keyed source that resolves from the mint alone.
	const [dex, pump, gecko, goplus, rugcheck, birdeye] = await Promise.all([
		fromDexScreener(mint).catch(() => null),
		network === 'mainnet' ? fromPumpFun(mint).catch(() => null) : Promise.resolve(null),
		fromGeckoTerminal(mint).catch(() => null),
		network === 'mainnet' ? fromGoPlus(mint).catch(() => null) : Promise.resolve(null),
		network === 'mainnet' ? fromRugCheck(mint).catch(() => null) : Promise.resolve(null),
		fromBirdeye(mint).catch(() => null),
	]);

	// Every upstream missed and we have no price — a true "no market" answer.
	if (!dex && !pump && !gecko && !goplus && !rugcheck && !birdeye) return null;

	// Stage 2: CoinGecko, but only for coins Gecko proved are listed (has an id).
	const coingecko = gecko?.coingecko_id
		? await fromCoinGecko(gecko.coingecko_id).catch(() => null)
		: null;

	const merged = mergeMarketSources(mint, network, { dex, pump, gecko, goplus, rugcheck, birdeye, coingecko }, new Date().toISOString());

	// Only cache a read that actually established a live price — never memoize a
	// hollow all-null result that a transient outage produced.
	if (merged.price?.usd != null) {
		L1.set(mint, { value: merged, expires: now + L1_TTL_MS });
		cacheSet(key, merged, L2_TTL_S).catch(() => {});
	}
	return merged;
}

/** Test seam — clear the per-instance cache between cases. */
export function __resetCoinMarketCache() {
	L1.clear();
}

export { WSOL };