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.

17.9 KB
Raw Blame
// Generic, coin-agnostic token market reader + signal builder.
//
// The mint is supplied at runtime by the caller — this is the plumbing the
// CA → x402 resolver (/ca2x402) and the generic /api/x402/token-intel service
// share. It is deliberately symbol-aware (no hardcoded ticker) so it works for
// any token a user pastes, while the platform still only ever *promotes*
// $THREE. Data is live DexScreener (no key, no mock path).
//
// The $THREE-specific oracle (/api/x402/three-intel) keeps its own THREE-branded
// copy on purpose — it is pinned to one mint and unit-tested as such.
//
// EVM addresses additionally get a keyless Honeypot.is sell-simulation
// (api/_lib/honeypot.js) attached as `honeypot`, fetched in parallel with the
// market read and failing soft to null; buildTokenRisk folds it into the risk
// score. Solana mints keep their security read in the Oracle aggregator
// (GoPlus + RugCheck, api/_lib/oracle/market.js) and /api/v1/token/security.

import { isValidSolanaAddress, isValidEvmAddress } from './validate.js';
import { fetchHoneypot, honeypotChainId } from './honeypot.js';
import { fetchUpstreamJson, lastGood } from './upstream-fetch.js';

const DEXSCREENER_TOKENS = 'https://api.dexscreener.com/latest/dex/tokens/';

/**
 * Is this string a plausible token contract address we can resolve?
 * Accepts Solana base58 mints and EVM 0x addresses — DexScreener indexes both.
 * @param {string} ca
 * @returns {boolean}
 */
export function isResolvableAddress(ca) {
	return isValidSolanaAddress(ca) || isValidEvmAddress(ca);
}

/** Chain family of a contract address, or null if unrecognized. */
export function chainOf(ca) {
	if (isValidEvmAddress(ca)) return 'evm';
	if (isValidSolanaAddress(ca)) return 'solana';
	return null;
}

function num(v) {
	const n = typeof v === 'string' ? parseFloat(v) : v;
	return Number.isFinite(n) ? n : null;
}

/**
 * Fetch live market + identity for any token by contract address.
 *
 * Picks the deepest-liquidity pair across all DEXs/chains DexScreener knows
 * about for the address. Returns null when the token is unknown or upstream is
 * unavailable — callers decide how to surface that (the resolver renders a
 * designed "not found" state; the paid endpoint throws 503 before settling so
 * the buyer is never charged for missing data).
 *
 * @param {string} ca contract address (Solana mint or EVM 0x)
 * @param {{ signal?: AbortSignal, chain?: string|null, security?: boolean }} [opts]
 *   `chain` restricts the pair search to one DexScreener chainId (e.g.
 *   'solana', 'base'); an EVM contract deployed on several chains otherwise
 *   resolves to whichever chain holds the deepest pool. `security: false`
 *   skips the Honeypot.is simulation for callers that only want price shape.
 * @returns {Promise<null | {
 *   mint: string, symbol: string|null, name: string|null, image: string|null,
 *   chain: string|null, dex: string|null, pair_url: string|null,
 *   price_usd: number|null, change_24h: number|null, market_cap_usd: number|null,
 *   fdv_usd: number|null,
 *   liquidity_usd: number|null, volume_24h_usd: number|null, pair_created_at: number|null,
 *   honeypot: object|null,
 * }>}
 */
export async function fetchTokenMarket(ca, opts = {}) {
	// EVM addresses also get Honeypot.is's keyless buy/sell simulation, kicked
	// off in parallel with the market read and failing soft to null. When the
	// caller pinned a chain Honeypot.is cannot simulate, skip it entirely
	// rather than let auto-detection describe a sibling deployment elsewhere.
	const pinnedHpChain = opts.chain ? honeypotChainId(opts.chain) : undefined;
	const wantHoneypot = chainOf(ca) === 'evm' && opts.security !== false && pinnedHpChain !== null;
	const honeypotPromise = wantHoneypot
		? fetchHoneypot(ca, { chainId: pinnedHpChain ?? undefined }).catch(() => null)
		: Promise.resolve(null);

	// One keyless DexScreener read used to decide whether a token exists at all,
	// so a throttle there made a live token read as "not found" on /ca2x402 and
	// 503'd the paid token-intel service. The call is now retried behind a
	// breaker and backed by a last-known-good payload: a few minutes of
	// staleness beats telling a caller their real token is unknown.
	let data = null;
	try {
		const out = await lastGood(
			`token-market:${ca.toLowerCase()}`,
			() => fetchUpstreamJson(
				`${DEXSCREENER_TOKENS}${encodeURIComponent(ca)}`,
				{ headers: { Accept: 'application/json' }, signal: opts.signal },
				{ name: 'dexscreener:tokens', timeoutMs: 6_000, attempts: 2 },
			),
			{ maxAgeMs: 15 * 60_000 },
		);
		data = out.value;
	} catch (err) {
		// Null keeps the contract every existing caller was written against, but
		// the distinction is preserved on the error for the ones that must not
		// confuse "no market exists" with "the indexer could not be reached".
		// fetchTokenMarketResult below is how a caller asks for it.
		if (opts.__surfaceUnavailable) throw Object.assign(new Error('market indexer unreachable'), {
			code: 'market_unavailable',
			status: 503,
			cause: err,
		});
		return null;
	}
	let pairs = Array.isArray(data?.pairs) ? data.pairs : [];
	if (opts.chain) pairs = pairs.filter((p) => p.chainId === opts.chain);
	if (!pairs.length) return null;

	pairs.sort((a, b) => (b.liquidity?.usd ?? 0) - (a.liquidity?.usd ?? 0));
	const p = pairs[0];

	// The address can be either side of a pair; pick the token that matches.
	const lc = ca.toLowerCase();
	const base = p.baseToken || {};
	const quote = p.quoteToken || {};
	const tok = (base.address || '').toLowerCase() === lc ? base
		: (quote.address || '').toLowerCase() === lc ? quote
		: base;
	const info = p.info || {};
	const txns = p.txns || {};

	// Human label for the deepest pair (base/quote), plus its on-chain pair
	// address — the security reader (/api/v1/token/security) surfaces both as the
	// "largest_pair" fact; other callers ignore them.
	const pairLabel =
		base.symbol && quote.symbol ? `${base.symbol}/${quote.symbol}` : null;

	// Attribute the honeypot simulation to the SAME deployment DexScreener
	// resolved. If the deepest pool lives on a chain Honeypot.is cannot
	// simulate, drop the report (it would describe a sibling deployment). If
	// the chain is simulatable but the unpinned answer missed or landed on a
	// different chain (auto-detection misses Base-native tokens), re-run once,
	// pinned to the resolved chain.
	let honeypot = await honeypotPromise;
	if (wantHoneypot) {
		const want = honeypotChainId(p.chainId);
		const got = honeypot?.chain?.id != null ? String(honeypot.chain.id) : null;
		if (want == null) {
			honeypot = null;
		} else if (got !== String(want) && (honeypot != null || pinnedHpChain == null)) {
			honeypot = await fetchHoneypot(ca, { chainId: want }).catch(() => null);
		}
	}

	return {
		mint: tok.address || ca,
		symbol: tok.symbol || null,
		name: tok.name || null,
		image: info.imageUrl || null,
		chain: p.chainId || null,
		dex: p.dexId || null,
		pair_url: p.url || null,
		pair_address: p.pairAddress || null,
		pair_label: pairLabel,
		price_usd: num(p.priceUsd),
		change_24h: p.priceChange?.h24 ?? null,
		market_cap_usd: num(p.marketCap) ?? num(p.fdv),
		fdv_usd: num(p.fdv),
		liquidity_usd: num(p.liquidity?.usd),
		volume_24h_usd: num(p.volume?.h24),
		pair_created_at: num(p.pairCreatedAt),
		// Multi-timeframe price change (% per window) — the shape of the move, not
		// just the 24 h endpoint. Lets the signal read acceleration vs. exhaustion.
		momentum: {
			m5: num(p.priceChange?.m5),
			h1: num(p.priceChange?.h1),
			h6: num(p.priceChange?.h6),
			h24: num(p.priceChange?.h24),
		},
		// Buy/sell transaction counts over 24 h — real order flow, the difference
		// between accumulation and distribution behind the same price move.
		txns_24h: { buys: num(txns.h24?.buys), sells: num(txns.h24?.sells) },
		// Honeypot.is buy/sell simulation for EVM deployments; null for Solana
		// mints, unsupported chains, or when the simulator is unavailable.
		honeypot,
	};
}

/** Money formatter for risk-factor copy — compact, human, no library. */
function usd(n) {
	if (n == null || !Number.isFinite(n)) return '$?';
	if (n >= 1000) return `$${Math.round(n).toLocaleString('en-US')}`;
	return `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
}

/** Human pair age from a millisecond span. */
function fmtAge(ms) {
	if (ms == null || !Number.isFinite(ms)) return 'unknown age';
	const h = ms / 3_600_000;
	if (h < 1) return `${Math.max(1, Math.round(h * 60))}m`;
	if (h < 48) return `${Math.round(h)}h`;
	return `${Math.round(h / 24)}d`;
}

/**
 * Score the safety of any token from its live market shape — the due-diligence
 * layer behind the CA → x402 oracle. Higher score = MORE risk (0 safe … 100
 * critical). Every input is real DexScreener data (plus the real Honeypot.is
 * simulation on `m.honeypot` for EVM tokens); nothing is fabricated, and a
 * missing field degrades to an honest "unknown" factor rather than a fake pass.
 *
 * `now` is injectable so the result is deterministic under test.
 *
 * @param {object} m a fetchTokenMarket() result
 * @param {number} [now] epoch ms, defaults to wall clock
 * @returns {{ score:number, level:'low'|'medium'|'high'|'critical',
 *             summary:string, factors:Array<{label:string,status:string,detail:string}> }}
 */
export function buildTokenRisk(m, now = Date.now()) {
	const sym = (m.symbol || 'This token').toUpperCase();
	const factors = [];
	let risk = 0;

	// 1) Liquidity depth — the single biggest exit-risk signal.
	const liq = m.liquidity_usd;
	if (liq == null) {
		factors.push({ label: 'Liquidity', status: 'unknown', detail: 'Pool depth unavailable from upstream.' });
		risk += 18;
	} else if (liq < 5_000) {
		factors.push({ label: 'Liquidity', status: 'critical', detail: `Only ${usd(liq)} pooled — trivially drained, severe exit risk.` });
		risk += 40;
	} else if (liq < 25_000) {
		factors.push({ label: 'Liquidity', status: 'high', detail: `${usd(liq)} is thin — large orders slip hard.` });
		risk += 26;
	} else if (liq < 100_000) {
		factors.push({ label: 'Liquidity', status: 'medium', detail: `${usd(liq)} pooled — moderate depth.` });
		risk += 12;
	} else {
		factors.push({ label: 'Liquidity', status: 'low', detail: `${usd(liq)} pooled — healthy depth.` });
	}

	// 2) Pair age — brand-new pairs are unproven and the most rug-prone.
	const ageMs = m.pair_created_at ? now - m.pair_created_at : null;
	const ageDays = ageMs != null ? ageMs / 86_400_000 : null;
	if (ageDays == null) {
		factors.push({ label: 'Age', status: 'unknown', detail: 'Pair creation time unavailable.' });
	} else if (ageDays < 1) {
		factors.push({ label: 'Age', status: 'high', detail: `Pair is ${fmtAge(ageMs)} old — unproven and volatile.` });
		risk += 22;
	} else if (ageDays < 7) {
		factors.push({ label: 'Age', status: 'medium', detail: `Pair is ${Math.round(ageDays)}d old — still early.` });
		risk += 10;
	} else {
		factors.push({ label: 'Age', status: 'low', detail: `Pair is ${fmtAge(ageMs)} old — established.` });
	}

	// 3) Float vs. depth — a huge cap on thin liquidity is easy to swing/dump.
	const cap = m.market_cap_usd;
	if (cap != null && liq) {
		const ratio = cap / liq;
		if (ratio > 100) {
			factors.push({ label: 'Float', status: 'high', detail: `Cap is ${Math.round(ratio)}× liquidity — thin float, easy to swing.` });
			risk += 16;
		} else if (ratio > 30) {
			factors.push({ label: 'Float', status: 'medium', detail: `Cap is ${Math.round(ratio)}× liquidity.` });
			risk += 7;
		} else {
			factors.push({ label: 'Float', status: 'low', detail: `Cap is ${ratio.toFixed(1)}× liquidity — well backed.` });
		}
	}

	// 4) Honeypot simulation (EVM tokens): Honeypot.is actually buys and sells
	// the token on a fork of its chain. A failed sell is the one scam the
	// market shape above cannot see; heavy taxes and an unverified contract
	// are its milder cousins. Absent for Solana mints and when the simulator
	// is unavailable, so the factor list degrades honestly, never fabricates.
	const hp = m.honeypot;
	if (hp) {
		if (hp.is_honeypot === true) {
			factors.push({ label: 'Honeypot', status: 'critical', detail: `Sell simulation FAILED${hp.honeypot_reason ? ` (${hp.honeypot_reason})` : ''}: holders cannot exit.` });
			risk += 55;
		} else if (hp.simulation_success === false) {
			factors.push({ label: 'Honeypot', status: 'high', detail: 'Buy/sell simulation could not complete; sellability is unproven.' });
			risk += 18;
		} else {
			const tax = Math.max(hp.buy_tax ?? 0, hp.sell_tax ?? 0, hp.transfer_tax ?? 0);
			if (tax >= 20) {
				factors.push({ label: 'Honeypot', status: 'high', detail: `Sell simulation passes but taxes run ${Math.round(tax)}%; exits are heavily skimmed.` });
				risk += 22;
			} else if (tax >= 10) {
				factors.push({ label: 'Honeypot', status: 'medium', detail: `Simulated round-trip tax is ${Math.round(tax)}%.` });
				risk += 10;
			} else {
				factors.push({ label: 'Honeypot', status: 'low', detail: 'Sell simulation passes with negligible taxes.' });
			}
		}
		if (hp.open_source === false) {
			factors.push({ label: 'Contract', status: 'medium', detail: 'Contract source is not verified; behavior cannot be audited.' });
			risk += 8;
		}
	}

	// 5) Order flow: are the trades net buys or net sells over 24 h?
	const buys = m.txns_24h?.buys;
	const sells = m.txns_24h?.sells;
	if (buys != null && sells != null && buys + sells > 0) {
		const sellShare = sells / (buys + sells);
		if (sellShare > 0.62) {
			factors.push({ label: 'Flow', status: 'high', detail: `${Math.round(sellShare * 100)}% of 24 h trades are sells — net distribution.` });
			risk += 12;
		} else if (sellShare < 0.4) {
			factors.push({ label: 'Flow', status: 'low', detail: `${Math.round((1 - sellShare) * 100)}% of 24 h trades are buys — net accumulation.` });
		} else {
			factors.push({ label: 'Flow', status: 'medium', detail: 'Buy/sell flow is roughly balanced.' });
		}
	}

	const score = Math.max(0, Math.min(100, Math.round(risk)));
	const level = score >= 70 ? 'critical' : score >= 45 ? 'high' : score >= 22 ? 'medium' : 'low';
	const summary =
		level === 'critical' ? `${sym} carries critical risk — treat any position as speculative.`
		: level === 'high' ? `${sym} shows elevated risk; size positions with care.`
		: level === 'medium' ? `${sym} carries moderate risk — normal memecoin caution applies.`
		: `${sym} clears the basic depth, age, and flow checks.`;

	return { score, level, summary, factors };
}

/**
 * Build a bullish/bearish/neutral signal from market data, branded to the
 * token's own symbol. Mirrors the $THREE oracle thresholds so the generated
 * service reads consistently with the in-house one.
 *
 * @param {{ symbol?: string|null, price_usd: number|null, change_24h: number,
 *           volume_24h_usd: number|null, liquidity_usd: number|null }} m
 */
export function buildTokenSignal(m) {
	const sym = (m.symbol || 'token').toUpperCase();
	const change = Number(m.change_24h) || 0;
	const fmt = (n) => (n >= 100 ? n.toFixed(2) : n >= 1 ? n.toFixed(3) : n.toFixed(6));
	const pStr = m.price_usd != null ? `$${fmt(m.price_usd)}` : '?';
	const sign = change >= 0 ? '+' : '';
	const cStr = `${sign}${change.toFixed(2)}%`;

	const turnover =
		m.volume_24h_usd != null && m.liquidity_usd ? m.volume_24h_usd / m.liquidity_usd : null;
	const flowLine =
		turnover == null ? 'Flow data is thin; weigh the move accordingly.'
		: turnover > 3 ? 'Volume is running hot against liquidity — high conviction behind the move.'
		: turnover > 1 ? 'Volume is healthy against liquidity; participation is real.'
		: 'Volume is light against liquidity; the move has limited backing so far.';

	// Order-flow clause — buy/sell skew over 24 h, when DexScreener reports txns.
	const buys = m.txns_24h?.buys;
	const sells = m.txns_24h?.sells;
	const pressureLine =
		buys != null && sells != null && buys + sells > 0
			? sells / (buys + sells) > 0.6 ? ' Sellers dominate the tape.'
				: buys / (buys + sells) > 0.6 ? ' Buyers dominate the tape.'
				: ' Tape is two-sided.'
			: '';

	// Acceleration clause — compare the latest hour to the 24 h trend so the
	// rationale flags a move that is fading or reversing, not just its endpoint.
	const h1 = m.momentum?.h1;
	const accelLine =
		h1 == null ? ''
		: change > 1 && h1 < -0.5 ? ' Momentum is cooling in the last hour.'
		: change < -1 && h1 > 0.5 ? ' It is bouncing in the last hour.'
		: change > 1 && h1 > 1 ? ' The last hour confirms the trend.'
		: '';

	let signal, headline;
	if (change > 5) {
		signal = 'bullish';
		headline = `${sym} surges ${cStr} in 24 h — strong momentum`;
	} else if (change > 1) {
		signal = 'bullish';
		headline = `${sym} climbs ${cStr} — moderate upside`;
	} else if (change < -5) {
		signal = 'bearish';
		headline = `${sym} drops ${Math.abs(change).toFixed(2)}% — sellers in control`;
	} else if (change < -1) {
		signal = 'bearish';
		headline = `${sym} slips ${cStr} — mild weakness`;
	} else {
		signal = 'neutral';
		headline = `${sym} flat at ${cStr} — consolidating at ${pStr}`;
	}

	const rationale = `${sym} is ${change >= 0 ? 'up' : 'down'} ${cStr} over 24 h, trading at ${pStr}. ${flowLine}${pressureLine}${accelLine}`;
	const confidence = Math.min(0.93, 0.64 + Math.min(Math.abs(change) / 20, 0.29));
	return { signal, headline, rationale, confidence };
}

/**
 * Like fetchTokenMarket, but tells apart the two ways it can come back empty.
 *
 * `fetchTokenMarket` answers null both for a token with no indexed pair and for
 * an indexer that could not be reached at all, which is fine for a decorative
 * price chip and wrong for anything that states a conclusion about the token.
 * Reporting "no such token" during an outage denies real tokens; two endpoints
 * shipped that bug before this existed.
 *
 * @param {string} ca
 * @param {object} [opts] same options as fetchTokenMarket
 * @returns {Promise<{ market: object | null, unavailable: boolean }>}
 */
export async function fetchTokenMarketResult(ca, opts = {}) {
	try {
		const market = await fetchTokenMarket(ca, { ...opts, __surfaceUnavailable: true });
		return { market, unavailable: false };
	} catch (err) {
		if (err?.code === 'market_unavailable') return { market: null, unavailable: true };
		throw err;
	}
}