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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Oracle — source adapter over the data brain.
//
// This is the only place Oracle touches the platform's existing pump.fun tables.
// It reads them defensively (every query is isolated so a missing/younger table
// degrades that one slice to null instead of failing the whole assembly) and
// maps them into the single normalized `CoinIntel` shape the pure conviction
// engine consumes. Keeping the coupling here means a schema change in the brain
// only ever breaks this file, never the scoring logic or the API surface.
//
// Brain tables read:
// pump_coin_intel — coin record + precomputed structural/narrative signals
// coin_smart_money — pedigree: proven-money score + notable wallets
// oracle_narrative — Oracle's own cultural read (virality), if classified
// pump_coin_wallets — per-wallet ledger (funder clusters, proven-wallet flow)
// wallet_reputation — the coin creator's own launch track record
// pump_coin_outcomes — ground-truth outcome (for the conviction backtest)
import { sql } from '../db.js';
import { knownWallet, knownIsProven, loadKnownWallets } from './known-wallets.js';
import { isQuoteMint, QUOTE_MINT_LIST } from '../quote-mints.js';
import { xAccountSignal } from './x-account.js';
const LAMPORTS = 1e9;
const n = (v) => (v == null ? null : Number(v));
const pct01 = (v) => (v == null ? null : Math.max(0, Math.min(100, Number(v) * 100)));
/** Best-effort single-row query; returns null on any error (missing table etc). */
async function tryRow(fn) {
try {
const rows = await fn();
return rows && rows[0] ? rows[0] : null;
} catch {
return null;
}
}
async function tryRows(fn) {
try {
return (await fn()) || [];
} catch {
return [];
}
}
/**
* Assemble the normalized CoinIntel for one mint from the brain. Any slice that
* isn't available yet is simply omitted — the conviction engine tolerates gaps.
*
* @param {string} mint
* @param {string} network
* @returns {Promise<object|null>} CoinIntel, or null if the coin is unknown
*/
export async function assembleIntel(mint, network = 'mainnet') {
// Quote/stablecoin/LST mints are never a tradeable coin — refuse to assemble
// intel for them so they can never be scored or cached. This is the choke point
// every scoring + lazy-score path flows through, so one guard covers them all.
if (isQuoteMint(mint)) return null;
// The primary existence lookup does NOT use tryRow: a swallowed DB error here
// is indistinguishable from "coin not observed", which makes every caller
// return a misleading 404 during a database/connection outage — a transient
// failure clients and the CDN then cache as an authoritative "doesn't exist".
// Let a query failure throw (callers map it to 503); only an empty result set
// is a true "unknown coin" → null. The secondary enrichment queries below stay
// on tryRow, since partial intel is an acceptable degradation.
const coinRows = await sql`
select mint, symbol, name, image_uri, category, narrative, classify_confidence,
creator, bonding_curve, description, twitter, telegram, website, tags,
created_at, first_seen_at,
dev_buy_lamports, dev_sold, dev_sell_lamports,
buy_count, sell_count, buy_volume_lamports, sell_volume_lamports,
unique_buyers, unique_sellers, largest_buy_lamports,
bundle_score, organic_score, snipe_ratio, fresh_wallet_ratio,
concentration_top10, bubblemap_connectivity,
quality_score, risk_flags, signals
from pump_coin_intel where mint = ${mint} and network = ${network} limit 1
`;
const coin = coinRows[0] || null;
if (!coin) return null;
const [smart, narr, topBuyers, funder, provenFlow, creatorRep, xAccount] = await Promise.all([
tryRow(() => sql`
select smart_money_score, smart_wallet_count, proven_buy_lamports, total_buy_lamports, notable
from coin_smart_money where mint = ${mint} and network = ${network} limit 1
`),
tryRow(() => sql`
select category, narrative, virality, confidence
from oracle_narrative where mint = ${mint} and network = ${network} limit 1
`),
tryRows(() => sql`
select wallet, buy_lamports, is_creator
from pump_coin_wallets where mint = ${mint}
order by buy_lamports desc limit 25
`),
// Funder clustering: among real buyers (creator excluded), how concentrated
// is the funding source? A big single-funder cluster is a bundle wearing a
// wide-base costume. Coverage-gated downstream so sparse enrichment never
// fabricates a penalty.
tryRow(() => sql`
with buyers as (
select wallet, funder
from pump_coin_wallets
where mint = ${mint} and buy_lamports > 0 and coalesce(is_creator, false) = false
),
clusters as (
select funder, count(*)::int as sz from buyers where funder is not null group by funder
)
select (select count(*) from buyers)::int as total_buyers,
(select coalesce(sum(sz), 0) from clusters)::int as funded_buyers,
(select coalesce(max(sz), 0) from clusters)::int as largest_cluster
`),
// Proven-wallet flow on THIS coin: are the smart wallets that bought also
// already selling? coin_smart_money gives the buy side; this adds the exit.
tryRow(() => sql`
select coalesce(sum(w.buy_lamports), 0)::numeric as proven_buy,
coalesce(sum(w.sell_lamports), 0)::numeric as proven_sell,
count(*)::int as proven_wallets
from pump_coin_wallets w
join wallet_reputation r on r.wallet = w.wallet and r.network = ${network}
where w.mint = ${mint}
and (r.label in ('smart_money', 'kol') or r.smart_money_score >= 70)
`),
// The creator's own track record — a serial rugger and a proven shipper
// launch identically without this. Null for first-time / unjudged creators.
coin.creator
? tryRow(() => sql`
select label, win_rate, dump_rate, smart_money_score,
creator_count, creator_wins, coins_traded
from wallet_reputation where wallet = ${coin.creator} and network = ${network} limit 1
`)
: Promise.resolve(null),
// The coin's own linked X account (age, followers). Null when the coin
// links none, the link is not a profile, or the keyless reader is down.
xAccountSignal(coin.twitter),
]);
const intel = toCoinIntel({ coin, smart, narr, funder, provenFlow, creatorRep, xAccount });
await loadKnownWallets();
enrichWithKnownWallets(intel, topBuyers);
return intel;
}
/**
* Funder-cluster concentration as a 0..100 share of the buyer book, or null when
* funder enrichment is too sparse to be trustworthy. Pure, exported for testing.
*
* @param {object|null} funder { total_buyers, funded_buyers, largest_cluster }
*/
export function funderClusterPct(funder) {
if (!funder) return null;
const total = n(funder.total_buyers) || 0;
const funded = n(funder.funded_buyers) || 0;
const largest = n(funder.largest_cluster) || 0;
// Need a real book and real funder coverage before a cluster means anything.
if (total < 8 || funded < 5 || funded / total < 0.3) return null;
return Math.max(0, Math.min(100, (largest / total) * 100));
}
/**
* Fold the known-wallet prior into a coin's pedigree. For each top buyer that's
* a known smart-money/KOL/sniper wallet (gmgn seed), ensure it's in `notable`
* with its known label + a synthetic score, and recount proven wallets. This is
* what gives a brand-new launch real pedigree signal before the brain has
* judged its buyers. Mutates `intel.smartMoney` in place.
*
* @param {object} intel normalized CoinIntel
* @param {Array<{wallet:string, buy_lamports:any}>} topBuyers
*/
export function enrichWithKnownWallets(intel, topBuyers = []) {
const sm = intel.smartMoney || (intel.smartMoney = { notable: [] });
const notable = Array.isArray(sm.notable) ? sm.notable : (sm.notable = []);
const byWallet = new Map(notable.map((w) => [w.wallet, w]));
for (const b of topBuyers) {
const known = knownWallet(b.wallet);
if (!known) continue;
const buySol = Number(b.buy_lamports || 0) / LAMPORTS;
const existing = byWallet.get(b.wallet);
if (existing) {
// Only upgrade an unlabeled/weaker brain entry with the known prior.
if (!existing.label || existing.label === 'unproven') {
existing.label = known.label;
existing.score = existing.score || known.score;
existing.source = 'gmgn';
existing.tag = existing.tag || known.tag;
}
} else {
const entry = { wallet: b.wallet, label: known.label, score: known.score, buy_sol: buySol, source: 'gmgn', tag: known.tag };
notable.push(entry);
byWallet.set(b.wallet, entry);
}
}
// Recount proven wallets across brain + prior so the pedigree pillar sees them.
const provenCount = notable.filter((w) => knownIsProven(w.label) || Number(w.score) >= 70).length;
if (provenCount > (Number(sm.smartWalletCount) || 0)) sm.smartWalletCount = provenCount;
}
/**
* Map raw brain rows → normalized CoinIntel. Pure given its inputs (exported so
* it can be unit-tested without a DB).
*/
export function toCoinIntel({ coin, smart, narr, funder, provenFlow, creatorRep, xAccount } = {}) {
const riskFlags = Array.isArray(coin.risk_flags) ? coin.risk_flags : [];
const devBuy = n(coin.dev_buy_lamports);
const buyVol = n(coin.buy_volume_lamports) || 0;
const largest = n(coin.largest_buy_lamports);
// Single-biggest-buyer share of buy volume — a top-holder proxy.
const topHolderPct = largest != null && buyVol > 0 ? (largest / buyVol) * 100 : null;
// Dev footprint as a share of buy volume — a creator-hold proxy.
const creatorHoldPct = devBuy != null && buyVol > 0 ? (devBuy / buyVol) * 100 : null;
const devSoldPct = coin.dev_sold && devBuy
? (n(coin.dev_sell_lamports) || 0) / devBuy * 100
: 0;
const bundleScore = pct01(coin.bundle_score); // 0..100
const organicScore = pct01(coin.organic_score);
const snipeRatio = pct01(coin.snipe_ratio); // 0..100, buy vol in first seconds
const freshWalletRatio = pct01(coin.fresh_wallet_ratio); // 0..100, farmed-wallet share
const top10Pct = pct01(coin.concentration_top10);
const connectivity = pct01(coin.bubblemap_connectivity);
const bundleFlag = riskFlags.includes('bundle_launch') || (bundleScore != null && bundleScore >= 60);
// Narrative: Oracle's own classification (has virality) wins; else fall back
// to the brain's category with a virality proxy derived from quality/organic.
const narrative = narr
? { category: narr.category, virality: n(narr.virality), confidence: n(narr.confidence) }
: {
category: coin.category || 'unknown',
virality: n(coin.quality_score) != null ? Math.round(n(coin.quality_score) * 0.8 + (organicScore || 0) * 0.2) : null,
confidence: n(coin.classify_confidence) ?? 0.5,
};
const notable = Array.isArray(smart?.notable) ? smart.notable
: (typeof smart?.notable === 'string' ? safeJson(smart.notable) : []);
// Proven-wallet flow observed on this coin (smart money's actual buy AND sell
// here). Prefer coin_smart_money's precomputed buy total; the join below adds
// the exit side and backfills the buy total when smart-money hasn't run yet.
const provenBuy = n(smart?.proven_buy_lamports) || n(provenFlow?.proven_buy) || 0;
const provenSell = n(provenFlow?.proven_sell) || 0;
const uniqueSellers = n(coin.unique_sellers) || 0;
return {
mint: coin.mint,
symbol: coin.symbol,
name: coin.name,
image_uri: coin.image_uri,
category: narrative.category,
createdAt: coin.created_at || coin.first_seen_at,
// Raw launch-time signals exactly as the intel watcher recorded them
// (organic_score, timing_entropy, concentration_top1, mc_sol_first_seen,
// buy_sell_ratio, ...). The fitted conviction model reads these directly:
// they are the same values the model was trained on, so no unit drift
// between training and inference. The derived fields below remain for
// display and for callers that predate the model.
launch: coin.signals && typeof coin.signals === 'object' ? coin.signals : {},
// Off-chain signal the classifier weighs (link presence lifts virality) and
// the API surfaces. Previously never threaded through — a dead input.
social: {
description: coin.description || null,
twitter: coin.twitter || null,
telegram: coin.telegram || null,
website: coin.website || null,
tags: Array.isArray(coin.tags) ? coin.tags : [],
// Age and followers of the linked X account, or null when unknown.
xAccount: xAccount || null,
},
// The wallet that launched the coin and its own track record. Null history
// for a first-time or not-yet-judged creator (treated as neutral, not bad).
creator: {
wallet: coin.creator || null,
label: creatorRep?.label || null,
winRate: n(creatorRep?.win_rate),
dumpRate: n(creatorRep?.dump_rate),
smartMoneyScore: n(creatorRep?.smart_money_score),
launches: n(creatorRep?.creator_count) || 0,
launchWins: n(creatorRep?.creator_wins) || 0,
},
smartMoney: {
score: n(smart?.smart_money_score),
smartWalletCount: n(smart?.smart_wallet_count) || (Array.isArray(notable) ? notable.length : 0),
provenBuyLamports: provenBuy,
provenSellLamports: provenSell,
totalBuyLamports: n(smart?.total_buy_lamports) || buyVol,
notable: Array.isArray(notable) ? notable : [],
},
structure: {
uniqueBuyers: n(coin.unique_buyers) || 0,
uniqueSellers,
topHolderPct,
creatorHoldPct,
devSoldPct,
organicScore,
bundleScore,
snipeRatio,
freshWalletRatio,
funderClusterPct: funderClusterPct(funder),
top10Pct,
bubblemapConnectivity: connectivity,
bundleFlag,
},
narrative,
behavior: {
devBuySol: devBuy != null ? devBuy / LAMPORTS : null,
buyCount: n(coin.buy_count) || 0,
sellCount: n(coin.sell_count) || 0,
buyVolSol: buyVol / LAMPORTS,
sellVolSol: (n(coin.sell_volume_lamports) || 0) / LAMPORTS,
earlyBuyerCount: n(coin.unique_buyers) || 0,
uniqueSellers,
},
riskFlags,
qualityScore: n(coin.quality_score),
};
}
function safeJson(s) {
try { return JSON.parse(s); } catch { return []; }
}
/**
* Recent coins worth (re)scoring — newest first from the brain's coin table.
* Used by the ingestion augmentor and as a fallback when oracle_conviction is
* cold.
*
* @param {object} opts { network, limit, sinceSeconds }
* @returns {Promise<string[]>} mints
*/
export async function recentMints({ network = 'mainnet', limit = 100, sinceSeconds = 6 * 3600 } = {}) {
const rows = await tryRows(() => sql`
select mint from pump_coin_intel
where network = ${network}
and first_seen_at > now() - (${sinceSeconds} || ' seconds')::interval
and mint <> all(${QUOTE_MINT_LIST}::text[])
order by first_seen_at desc
limit ${Math.min(500, Math.max(1, limit))}
`);
return rows.map((r) => r.mint);
}
/** How many recent coin appearances the wallet profile loads. */
export const WALLET_PROFILE_COIN_LIMIT = 60;
/**
* A wallet's reputation + recent footprint, for the wallet profile endpoint.
*
* Unlike the conviction-engine readers above, this one does NOT swallow query
* faults into an empty result. A wallet profile IS the query result, so an
* unreachable database has to read as "we could not answer", never as "this
* trader has no record": the caller publishes that answer to a CDN, and a
* 30-second Neon blip would otherwise pin a false "wallet not indexed" over a
* real trader's track record for the life of the cache entry. Let it throw and
* let `wrap()` turn it into a 503 no-store.
*
* @param {string} wallet
* @param {string} network
*/
export async function walletProfile(wallet, network = 'mainnet') {
const repRows = await sql`
select wallet, coins_traded, early_entries, wins, early_wins, duds, dumps,
creator_count, creator_wins, win_rate, early_win_rate, dump_rate,
smart_money_score, label, first_seen_at, last_active_at
from wallet_reputation where wallet = ${wallet} and network = ${network} limit 1
`;
// pump_coin_wallets carries no network column, so a coin's network comes from
// its intel row. Without this filter a devnet query answered with the wallet's
// mainnet trades. The `is null` arm keeps a coin the indexer has observed but
// not yet classified, so the default mainnet read never silently drops history.
const recent = await sql`
select w.mint, w.buy_count, w.sell_count, w.buy_lamports, w.sell_lamports,
w.base_bought, w.base_sold, w.is_creator, w.first_seen_at, w.last_seen_at,
i.symbol, i.name, i.image_uri, i.category, i.quality_score, i.narrative,
o.graduated, o.rugged, o.ath_multiple, o.last_market_cap_usd
from pump_coin_wallets w
left join pump_coin_intel i on i.mint = w.mint
left join pump_coin_outcomes o on o.mint = w.mint
where w.wallet = ${wallet}
and (i.network is null or i.network = ${network})
order by w.last_seen_at desc
limit ${WALLET_PROFILE_COIN_LIMIT}
`;
return { rep: repRows?.[0] || null, recent: recent || [] };
}
/**
* Ground-truth outcome for a mint (for the conviction-tier backtest).
* @param {string} mint
*/
export async function coinOutcome(mint, network = 'mainnet') {
return tryRow(() => sql`
select graduated, rugged, ath_multiple, last_market_cap_usd
from pump_coin_outcomes where mint = ${mint} limit 1
`).catch(() => null);
}