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.

12.4 KB
Raw Blame
// GET /api/v1/token/security — free, on-chain rug/risk facts for any Solana token.
//
// The one question every trading agent asks before touching a token: "is this a
// rug?" This endpoint answers it with FACTS, not an invented score — mint/freeze
// authority status, holder concentration, liquidity depth, and pair age, composed
// into one report the agent weighs itself.
//
// Sources (all keyless / already-configured, composed — never proxied raw):
//   • Solana RPC (api/_lib/solana/connection.js failover chain):
//       - getAccountInfo(mint, jsonParsed) → mintAuthority, freezeAuthority,
//         supply, decimals (works for both spl-token and spl-token-2022 mints).
//       - getTokenLargestAccounts(mint)    → top-holder concentration.
//   • DexScreener (api/_lib/token-market.js `fetchTokenMarket`) → liquidity USD,
//     the deepest pair's label, and its creation time.
//
// Honest degradation: each section resolves independently. A partial upstream
// failure nulls only that section and names what answered in `sources`; the call
// succeeds if ANY section resolved and returns 503 only when every source failed.
// A well-formed Solana address that no source can resolve (no on-chain mint, no
// market) returns 404. EVM `0x…` input returns 400 — this endpoint is Solana-only.

import { defineEndpoint, fail } from '../../_lib/gateway.js';
import { rateLimited } from '../../_lib/http.js';
import { limits } from '../../_lib/rate-limit.js';
import { isValidSolanaAddress, isValidEvmAddress } from '../../_lib/validate.js';
import { fetchTokenMarket } from '../../_lib/token-market.js';
import { solanaRpcEndpoints, makeRotatingFetch } from '../../_lib/solana/connection.js';

// Budget for ONE JSON-RPC read across the WHOLE failover chain, not per
// endpoint. makeRotatingFetch bounds each attempt itself (10s) and composes the
// caller's signal with AbortSignal.any, so a caller cap below that bound spends
// the entire budget on the first endpoint and every rotation after it aborts
// instantly: at 8s a read that hit one slow lane logged "all 9 endpoints failed
// this request" and answered 503, while a retry seconds later succeeded. Sized
// to cover a couple of real attempts, matching the wallet-activity lane.
const RPC_TIMEOUT_MS = 25_000;
const DAY_MS = 86_400_000;

// One JSON-RPC call across the platform's failover chain. Resolves with the raw
// `{ result }` / `{ error }` envelope (a JSON-RPC error like "not a Token mint" is
// a soft "this section has no data", not a transport failure) and rejects only
// when every endpoint in the chain is down — which is how the caller tells an
// answered-but-empty source (→ degrade / 404) from a genuinely failed one (→ 503).
async function rpcCall(rpcFetch, method, params) {
	const resp = await rpcFetch(null, {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
		signal: AbortSignal.timeout(RPC_TIMEOUT_MS),
	});
	const body = await resp.json();
	// The rotation can answer an idempotent read from the last body a lane
	// returned when every lane is down, marking it with x-solana-rpc-stale. That
	// is the right trade for a balance chip; it is the wrong one here. Mint and
	// freeze authority and holder concentration are the whole point of a security
	// verdict, and a remembered copy of them presented as live would tell a
	// caller a token is clean at the exact moment we cannot see the chain.
	const stale = resp.headers?.get?.('x-solana-rpc-stale') != null;
	// A JSON-RPC envelope is always an object, but never let the marker itself be
	// the thing that throws on a malformed body.
	return body && typeof body === 'object' ? Object.assign(body, { __stale: stale }) : { result: undefined, __stale: stale };
}

// Round a base-unit part/total ratio to a 2-decimal percentage. Number() on the
// raw base-unit strings is exact enough for a percentage (supply tops out around
// 1e15, well under 2^53), and 2-decimal rounding absorbs any low-digit drift.
function pctOf(part, total) {
	if (!total || !Number.isFinite(total) || total <= 0) return null;
	const p = Number(part);
	if (!Number.isFinite(p)) return null;
	return Math.round((p / total) * 10000) / 100;
}

// Parse a getAccountInfo(jsonParsed) result into the authority/supply/decimals
// section. Returns null when the account isn't an initialized SPL/-2022 mint —
// either it doesn't exist (value === null) or it's some other account type. In
// SPL, a null authority means it was revoked (nobody can mint/freeze anymore).
export function parseMintAccount(result) {
	const value = result?.value;
	if (!value) return null;
	const parsed = value.data?.parsed;
	if (!parsed || parsed.type !== 'mint') return null;
	const info = parsed.info || {};
	const mintAuth = info.mintAuthority ?? null;
	const freezeAuth = info.freezeAuthority ?? null;
	return {
		mint_authority: { revoked: mintAuth === null, address: mintAuth },
		freeze_authority: { revoked: freezeAuth === null, address: freezeAuth },
		supply: typeof info.supply === 'string' ? info.supply : (info.supply ?? null),
		decimals: Number.isInteger(info.decimals) ? info.decimals : null,
	};
}

// Parse getTokenLargestAccounts + the mint supply into a concentration section.
// getTokenLargestAccounts returns up to the 20 largest token accounts; we report
// the cumulative share of the top 1 / 5 / 10 against total supply, and how many
// accounts we sampled. Percentages are null when supply is unknown (can't divide)
// but holders_sampled is still reported — an honest partial.
export function parseTopHolders(accounts, supplyRaw) {
	if (!Array.isArray(accounts) || accounts.length === 0) return null;
	const total = supplyRaw != null ? Number(supplyRaw) : null;
	const amt = (n) => accounts.slice(0, n).reduce((s, a) => s + Number(a?.amount || 0), 0);
	return {
		top1_pct: total ? pctOf(accounts[0]?.amount, total) : null,
		top5_pct: total ? pctOf(amt(5), total) : null,
		top10_pct: total ? pctOf(amt(10), total) : null,
		holders_sampled: accounts.length,
	};
}

// Project a fetchTokenMarket() result onto the liquidity section. null when the
// token has no indexed pair (DexScreener returned nothing).
export function parseLiquidity(market) {
	if (!market) return null;
	return {
		usd: market.liquidity_usd ?? null,
		largest_pair: market.pair_label ?? null,
		pair_created_at: market.pair_created_at ?? null,
	};
}

// Derive the factual flags. Every flag is a hard, observable condition — never a
// judgement — and is emitted ONLY when its inputs are present, so a null section
// never fabricates (or silently suppresses a real) signal.
export function buildFlags({ mint, holders, liquidity }, now) {
	const flags = [];
	if (mint) {
		if (mint.mint_authority.revoked === false) flags.push('mint_authority_active');
		if (mint.freeze_authority.revoked === false) flags.push('freeze_authority_active');
	}
	if (holders) {
		if (holders.top1_pct != null && holders.top1_pct > 20) flags.push('top1_holder_over_20pct');
		if (holders.top10_pct != null && holders.top10_pct > 80) flags.push('top10_holders_over_80pct');
	}
	if (liquidity) {
		if (liquidity.usd != null && liquidity.usd < 10_000) flags.push('liquidity_under_10k');
		if (liquidity.pair_created_at != null && now - liquidity.pair_created_at < DAY_MS) {
			flags.push('pair_younger_than_24h');
		}
	}
	return flags;
}

/**
 * Compose the full security report from the (already-resolved) upstream inputs.
 * Pure + exported so every section, flag, and the sources array can be pinned in
 * tests against captured real shapes without touching the network.
 *
 * @param {object} args
 * @param {string} args.address
 * @param {{ answered: boolean, result?: any }} args.account   getAccountInfo outcome
 * @param {{ answered: boolean, result?: any }} args.largest   getTokenLargestAccounts outcome
 * @param {{ answered: boolean, data?: any }} args.market      fetchTokenMarket outcome
 * @param {number} [now]
 * @returns {{ resolved: boolean, allFailed: boolean, body: object }}
 */
export function buildSecurityReport({ address, account, largest, market }, now = Date.now()) {
	const mint = account.answered ? parseMintAccount(account.result) : null;
	const holders = largest.answered
		? parseTopHolders(largest.result?.value, mint?.supply)
		: null;
	const liquidity = market.answered ? parseLiquidity(market.data) : null;

	const sources = [];
	if (mint || holders) sources.push('solana-rpc');
	if (liquidity) sources.push('dexscreener');

	const flags = buildFlags({ mint, holders, liquidity }, now);

	const body = {
		address,
		chain: 'solana',
		mint_authority: mint ? mint.mint_authority : { revoked: null, address: null },
		freeze_authority: mint ? mint.freeze_authority : { revoked: null, address: null },
		supply: mint ? mint.supply : null,
		decimals: mint ? mint.decimals : null,
		top_holders: holders || {
			top1_pct: null,
			top5_pct: null,
			top10_pct: null,
			holders_sampled: null,
		},
		liquidity: liquidity || { usd: null, largest_pair: null, pair_created_at: null },
		flags,
		sources,
		ts: now,
	};

	return {
		resolved: Boolean(mint || holders || liquidity),
		allFailed: !account.answered && !largest.answered && !market.answered,
		body,
	};
}

export default defineEndpoint({
	name: 'v1.token.security',
	method: 'GET',
	auth: 'public',
	handler: async ({ res, query, ip }) => {
		const address = typeof query.address === 'string' ? query.address.trim() : '';
		if (!address) fail(400, 'validation_error', '"address" query parameter is required');

		// EVM is a deliberate, honest 400 rather than a half-built passthrough: the
		// on-chain facts here (SPL mint/freeze authority, getTokenLargestAccounts) are
		// Solana concepts with no EVM equivalent in this reader.
		if (isValidEvmAddress(address)) {
			fail(400, 'unsupported_chain', 'this endpoint checks Solana tokens only (for now). Pass a base58 Solana mint address, not an EVM 0x address');
		}
		if (!isValidSolanaAddress(address)) {
			fail(400, 'validation_error', '"address" must be a base58 Solana mint address');
		}

		// Public, keyless per-IP quota on top of the gateway's shared budget: the RPC
		// + DexScreener reads are cheap and edge-cached, but this caps a scripted
		// enumeration flood against the shared upstreams.
		const rl = await limits.tokenSecurityIp(ip);
		if (!rl.success) {
			return rateLimited(res, rl, 'token security checks are capped at 20/min per IP');
		}

		const rpcFetch = makeRotatingFetch(solanaRpcEndpoints('mainnet'));
		const [acct, largest, mkt] = await Promise.allSettled([
			rpcCall(rpcFetch, 'getAccountInfo', [address, { encoding: 'jsonParsed', commitment: 'confirmed' }]),
			rpcCall(rpcFetch, 'getTokenLargestAccounts', [address, { commitment: 'confirmed' }]),
			fetchTokenMarket(address),
		]);

		// A stale-served read counts as "did not answer": the caller gets the same
		// honest 503 it would get if the lane had simply refused, instead of a
		// security report quietly assembled out of remembered on-chain state.
		const answered = (settled) => settled.status === 'fulfilled' && !settled.value?.__stale;

		const { resolved, allFailed, body } = buildSecurityReport({
			address,
			account: { answered: answered(acct), result: answered(acct) ? acct.value?.result : undefined },
			largest: { answered: answered(largest), result: answered(largest) ? largest.value?.result : undefined },
			// fetchTokenMarket answers null both for "this token has no indexed
			// pair" and for "DexScreener could not be reached at all", so a
			// fulfilled promise is not proof anything answered. Only a real payload
			// counts, which keeps the definitive 404 below ("not a resolvable
			// token") for cases where some source actually spoke: telling a caller
			// their real token does not exist because every upstream was down is a
			// worse answer than admitting we could not check.
			market: { answered: mkt.status === 'fulfilled' && mkt.value != null, data: mkt.value },
		});

		if (resolved) {
			// Public, cacheable read — 60s at the edge. Set before returning so the
			// gateway's secure-by-default no-store doesn't override it.
			res.setHeader('cache-control', 'public, max-age=60, s-maxage=60, stale-while-revalidate=30');
			return body;
		}

		// Nothing resolved: distinguish "every source failed" (transient — retry)
		// from "sources answered but this isn't a resolvable token" (client input).
		if (allFailed) {
			fail(503, 'sources_unavailable', 'token security sources are unavailable right now, retry shortly');
		}
		fail(404, 'not_found', 'no on-chain mint or market could be resolved for this address, check the mint');
	},
});