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
// Sentiment Scout: surfaces pump.fun momentum candidates with EVIDENCE a
// trading agent (or a human) can cite to followers. It never trades.
//
// Contract (roadmap 917, prompt 14.2):
// { mint, ticker, momentum_score: 0-100,
// evidence: [{ type, detail, source, at, checked_against? }], caution }
//
// "Cite only real, retrievable evidence; never fabricate" is enforced by
// construction rather than by asking a model nicely: every evidence line is
// rendered from a row or an upstream read this module just made, carries a
// source a reader can open to check it, and the time the fact was true. A
// social claim (an X post, a pump.fun callout, a paid market read) also names
// the on-chain facts it was checked against at scout time, so a reader can see
// a loud post next to a chart that did or did not back it up. A signal we
// could not read is left out (and listed under `unavailable`), never estimated.
//
// Pipeline (cheap on everything, expensive on candidates):
// 1. Window: every coin the Coin Intelligence Engine observed in the last
// N minutes (pump_coin_intel, ~1k rows/hour on mainnet).
// 2. Rank: percentile of early buy volume and distinct buyers against that
// same window. Percentiles, not lift over the median: the median launch
// has one buyer, so "40x the median" would be noise dressed as signal.
// 3. Screen: coordinated launches and dumped devs never qualify; a coin has
// to sit in the top quartile of its window on buy volume.
// 4. Enrich the survivors only: live bonding-curve state, X posts quoting
// the exact contract address (api/_lib/x-search.js), pump.fun callouts
// (served only to signed-in sessions now, so they usually land under
// `unavailable`), and the fleet's paid Crypto Intel sentiment reads, each
// backed by the x402 payment transaction that bought it.
// 5. Score + one caution line, both deterministic and explainable.
// 6. Record every board candidate (sentiment_scout_reads) so a trade receipt
// can show what the Scout had flagged before an entry, and so the Scout's
// own calls are graded against labeled outcomes (scoutTrackRecord).
import { sql } from './db.js';
import { cacheGet, cacheSet, cacheWrap } from './cache.js';
import { getBondingStatus } from './pump-bonding.js';
import { fetchPumpFunCallouts } from './pump-callouts.js';
import { receiptTxUrl } from './trade-receipt.js';
import { searchMintPostsDetailed, summarizePosts, anyXSearchConfigured } from './x-search.js';
export const EVIDENCE_TYPES = Object.freeze([
'volume_spike',
'fresh_buyers',
'social_mention',
'graduation_approach',
'smart_money',
'news_match',
'paid_signal',
]);
// A coordinated launch or a dev who already sold is not "momentum", whatever
// the volume says. These never reach the candidate list.
const DISQUALIFYING_FLAGS = new Set(['bundle_launch', 'dev_dumped']);
const MIN_WINDOW_MIN = 15;
const MAX_WINDOW_MIN = 240;
const DEFAULT_WINDOW_MIN = 60;
const MAX_LIMIT = 10;
const MIN_VOLUME_PCTL = 0.75;
const MIN_BUYERS = 3;
const ENRICH_TIMEOUT_MS = 6000;
const CACHE_TTL_MS = 30_000;
const PAID_SIGNAL_MAX_AGE_H = 6;
// X posts about a coin move slowly next to its chart, and search is metered:
// one read per coin per ten minutes is plenty.
const X_CACHE_TTL_S = 600;
const X_FAIL_TTL_S = 60;
// Posts from before a coin existed cannot be about it; allow a little slack
// for creators who tease an address minutes before the first trade.
const X_LOOKBACK_BEFORE_LAUNCH_MS = 10 * 60 * 1000;
const MAX_POST_RECEIPTS = 3;
// A curve back at the start after real early buying means the buyers left.
const CURVE_RESET_PCT = 2;
const CURVE_RESET_MIN_SOL = 5;
const JUDGE_STATS_TTL_MS = 60_000;
const cache = new Map();
const lamportsToSol = (v) => (v == null ? null : Number(v) / 1e9);
const clamp01 = (n) => Math.max(0, Math.min(1, n));
const round = (n, d = 2) => (n == null || !Number.isFinite(n) ? null : Math.round(n * 10 ** d) / 10 ** d);
const pct = (x) => `${Math.round(x * 100)}%`;
const fmtSol = (x) => (x >= 10 ? x.toFixed(1) : x.toFixed(2));
const iso = (t) => {
if (t == null) return null;
const ms = t instanceof Date ? t.getTime() : Date.parse(t);
return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
};
/** 1234 -> "1.2k", 2500000 -> "2.5M". Follower counts read at a glance. */
export function fmtCount(n) {
const v = Number(n);
if (!Number.isFinite(v)) return null;
if (v >= 1e6) return `${(v / 1e6).toFixed(v >= 1e7 ? 0 : 1)}M`;
if (v >= 1e3) return `${(v / 1e3).toFixed(v >= 1e4 ? 0 : 1)}k`;
return String(Math.round(v));
}
export function appOrigin() {
return (process.env.PUBLIC_APP_ORIGIN || 'https://three.ws').replace(/\/+$/, '');
}
export function clampWindow(minutes) {
const n = Number(minutes);
if (minutes == null || minutes === '' || !Number.isFinite(n)) return DEFAULT_WINDOW_MIN;
return Math.max(MIN_WINDOW_MIN, Math.min(MAX_WINDOW_MIN, Math.round(n)));
}
export function clampLimit(limit) {
const n = Number(limit);
if (limit == null || limit === '' || !Number.isFinite(n)) return 5;
return Math.max(1, Math.min(MAX_LIMIT, Math.round(n)));
}
/**
* Fraction of `sorted` (ascending) strictly below `value`. 0.97 means the value
* beat 97% of the window.
*/
export function percentileRank(sorted, value) {
if (!sorted.length || value == null) return 0;
let lo = 0;
let hi = sorted.length;
while (lo < hi) {
const mid = (lo + hi) >> 1;
if (sorted[mid] < value) lo = mid + 1;
else hi = mid;
}
return lo / sorted.length;
}
/** "top 3%" phrasing for a percentile rank, floored at 1 so it never reads "top 0%". */
export function topPct(rank) {
return Math.max(1, Math.ceil((1 - rank) * 100));
}
function median(sorted) {
if (!sorted.length) return 0;
const m = sorted.length >> 1;
return sorted.length % 2 ? sorted[m] : (sorted[m - 1] + sorted[m]) / 2;
}
function symbolKey(sym) {
return String(sym || '').trim().toLowerCase();
}
/**
* Per-window statistics every candidate is measured against. Pure.
* @param {Array<object>} rows pump_coin_intel rows (the window)
*/
export function windowStats(rows) {
const vols = [];
const buyers = [];
const concs = [];
const symbols = new Map();
for (const r of rows) {
vols.push(lamportsToSol(r.buy_volume_lamports) ?? 0);
buyers.push(Number(r.unique_buyers) || 0);
// Concentration is only comparable between coins that actually traded:
// a one-buyer launch is 100% concentrated by definition.
if ((Number(r.unique_buyers) || 0) >= MIN_BUYERS && r.concentration_top10 != null) concs.push(Number(r.concentration_top10));
const k = symbolKey(r.symbol);
if (k) symbols.set(k, (symbols.get(k) || 0) + 1);
}
vols.sort((a, b) => a - b);
buyers.sort((a, b) => a - b);
concs.sort((a, b) => a - b);
return { size: rows.length, vols, buyers, concs, symbols, medianVol: median(vols), medianBuyers: median(buyers) };
}
function buySellRatio(r) {
const fromSignals = r.signals?.buy_sell_ratio;
if (fromSignals != null && Number.isFinite(Number(fromSignals))) return Number(fromSignals);
const buys = Number(r.buy_count) || 0;
const sells = Number(r.sell_count) || 0;
if (!buys) return null;
return sells ? buys / sells : buys;
}
/** Window-relative measurements for one row, with no qualification screen. Pure. */
export function measure(r, stats) {
const vol = lamportsToSol(r.buy_volume_lamports) ?? 0;
const nBuyers = Number(r.unique_buyers) || 0;
const volPct = percentileRank(stats.vols, vol);
const buyerPct = percentileRank(stats.buyers, nBuyers);
const bsr = buySellRatio(r);
const bsrScore = bsr == null ? 0 : clamp01((bsr - 1) / 2);
const smScore = clamp01((Number(r.smart_money_count) || 0) / 3);
// Early top-10 share is 90%+ for most launches in their first 90 seconds, so
// an absolute threshold flags everything. Rank it against comparable coins.
const top10 = r.concentration_top10 != null ? Number(r.concentration_top10) : null;
const concPct = top10 == null || !stats.concs?.length ? null : percentileRank(stats.concs, top10);
return {
vol,
top10,
concPct,
nBuyers,
volPct,
buyerPct,
bsr,
bsrScore,
smScore,
base: 30 * volPct + 25 * buyerPct + 10 * bsrScore + 10 * smScore,
};
}
/**
* Rank one intel row against its window before any network enrichment. Pure.
* Returns null when the row does not qualify as a board candidate.
*/
export function preScore(r, stats) {
const flags = Array.isArray(r.risk_flags) ? r.risk_flags : [];
if (flags.some((f) => DISQUALIFYING_FLAGS.has(f))) return null;
const m = measure(r, stats);
if (m.nBuyers < MIN_BUYERS || m.volPct < MIN_VOLUME_PCTL) return null;
return m;
}
/**
* True when the X chatter about a coin is one account talking to itself: at
* least three posts and one poster wrote 70%+ of them. Pure.
*/
export function isSingleVoice(x) {
if (!x || !x.posts) return false;
return x.posts >= 3 && (x.authors === 1 || x.top_poster_share >= 0.7);
}
/**
* How much independent X attention a coin has, 0..1. Distinct accounts count,
* reach counts a little, and one account posting on repeat counts for almost
* nothing, because that is promotion rather than interest. Pure.
*/
export function xAttention(x) {
if (!x || !x.posts) return 0;
const breadth = clamp01((x.authors - 1) / 4);
const reach = clamp01(Math.log10(1 + (x.reach_followers || 0)) / 5);
const raw = 0.7 * breadth + 0.3 * reach;
return isSingleVoice(x) ? raw * 0.25 : raw;
}
/**
* Final 0-100 momentum score with its parts, so a reader can see why. Pure.
*/
export function momentumScore(pre, { curve, calloutCount, newsMatch, paidSignal, flags, copycats, xSummary = null }) {
let curveScore = 0;
if (curve?.graduated) curveScore = 0.6;
else if (curve?.bondingProgressPct != null) curveScore = clamp01(curve.bondingProgressPct / 100);
const paidBoost = paidSignal?.signal === 'bullish' ? 0.4 * clamp01(Number(paidSignal.confidence) || 0) : 0;
const socialScore = clamp01((calloutCount || 0) / 5 + (newsMatch ? 0.5 : 0) + paidBoost + 0.6 * xAttention(xSummary));
let penalty = 8 * (flags || []).length;
if (copycats > 0) penalty += 10;
if (pre.concPct != null && pre.concPct >= 0.9) penalty += 10;
if (isSingleVoice(xSummary)) penalty += 5;
const parts = {
volume: round(30 * pre.volPct, 1),
buyers: round(25 * pre.buyerPct, 1),
buy_pressure: round(10 * pre.bsrScore, 1),
smart_money: round(10 * pre.smScore, 1),
curve: round(15 * curveScore, 1),
social: round(10 * socialScore, 1),
risk_penalty: -penalty,
};
const total = Object.values(parts).reduce((s, v) => s + (v || 0), 0);
return { score: Math.max(0, Math.min(100, Math.round(total))), parts };
}
/** When the launch-window facts were true: the end of the observation window. */
function observedAt(r) {
const first = Date.parse(r.first_seen_at instanceof Date ? r.first_seen_at.toISOString() : r.first_seen_at);
if (!Number.isFinite(first)) return null;
const obs = Number(r.observation_seconds) || 0;
return new Date(first + obs * 1000).toISOString();
}
/**
* The on-chain facts a social claim is checked against, in one line. Built
* only from reads this run made: the launch window (always) and the live
* bonding curve (when it answered). Pure.
*/
export function marketCheckLine(pre, r, curve, checkedAt) {
const obs = Number(r.observation_seconds) || null;
const parts = [`${fmtSol(pre.vol)} SOL bought by ${pre.nBuyers} wallets in the first ${obs ? `${obs}s` : 'minutes'}`];
if (curve?.graduated) parts.push(`graduated${curve.migratedTo ? ` to ${curve.migratedTo}` : ''}`);
else if (curve?.bondingProgressPct != null) parts.push(`bonding curve at ${Math.round(curve.bondingProgressPct)}%`);
const when = iso(checkedAt);
return `On-chain${when ? ` at ${when.slice(11, 16)} UTC` : ''}: ${parts.join('; ')}`;
}
/**
* Build the evidence list. Every line comes from a value read in this run,
* carries the time the fact was true, and points at a source that returns it.
* Social and paid lines also carry the on-chain facts they were checked
* against. Pure.
*/
export function buildEvidence(r, pre, stats, { curve, callouts, paidSignal, origin, xSummary = null, xPosts = null, checkedAt = null }) {
const mint = r.mint;
const intelApi = `${origin}/api/pump/coin-intel?mint=${encodeURIComponent(mint)}`;
const pumpPage = `https://pump.fun/coin/${encodeURIComponent(mint)}`;
const obs = Number(r.observation_seconds) || null;
const inWindow = obs ? `in its first ${obs}s` : 'in its observation window';
const launchAt = observedAt(r);
const readAt = iso(checkedAt) || new Date().toISOString();
const check = marketCheckLine(pre, r, curve, readAt);
const evidence = [];
evidence.push({
type: 'volume_spike',
detail: `${fmtSol(pre.vol)} SOL bought ${inWindow}, top ${topPct(pre.volPct)}% of ${stats.size} launches in the window (median ${fmtSol(stats.medianVol)} SOL)`,
source: intelApi,
at: launchAt,
});
const fresh = r.fresh_wallet_ratio != null ? Number(r.fresh_wallet_ratio) : null;
evidence.push({
type: 'fresh_buyers',
detail: `${pre.nBuyers} distinct buyers ${inWindow}, top ${topPct(pre.buyerPct)}% of the window`
+ (fresh != null ? `; ${pct(fresh)} of them brand-new wallets` : '')
+ (pre.bsr != null ? `; ${round(pre.bsr, 2)} buys per sell` : ''),
source: intelApi,
at: launchAt,
});
const sm = Number(r.smart_money_count) || 0;
if (sm > 0) {
const notable = Array.isArray(r.smart_money_notable) ? r.smart_money_notable : [];
const best = notable
.map((n) => Number(n?.win_rate))
.filter((w) => Number.isFinite(w))
.sort((a, b) => b - a)[0];
evidence.push({
type: 'smart_money',
detail: `${sm} wallet${sm === 1 ? '' : 's'} with a profitable pump.fun record bought early`
+ (best != null ? ` (best win rate ${pct(best > 1 ? best / 100 : best)})` : ''),
source: intelApi,
at: launchAt,
});
}
if (curve?.graduated) {
evidence.push({
type: 'graduation_approach',
detail: `already graduated off the bonding curve${curve.migratedTo ? ` to ${curve.migratedTo}` : ''}`,
source: pumpPage,
at: readAt,
});
} else if (curve?.bondingProgressPct != null) {
evidence.push({
type: 'graduation_approach',
detail: `bonding curve ${Math.round(curve.bondingProgressPct)}% of the way to graduation`
+ (curve.solInCurve != null ? `, ${fmtSol(curve.solInCurve)} SOL in the curve` : ''),
source: pumpPage,
at: readAt,
});
}
if (xSummary?.posts && Array.isArray(xPosts) && xPosts.length) {
// Quote the most-followed account's post: the one with the most reach is
// the one a follower is most likely to have seen.
const lead = xPosts.slice().sort((a, b) => (b.author?.followers || 0) - (a.author?.followers || 0))[0];
const flat = String(lead.text || '').replace(/https?:\/\/\S+/g, '').replace(/\s+/g, ' ').trim();
const quote = flat.length > 140 ? `${flat.slice(0, 140)}...` : flat;
const who = lead.author?.username ? `@${lead.author.username}` : 'an account';
const followers = fmtCount(lead.author?.followers);
evidence.push({
type: 'social_mention',
platform: 'x',
detail: `${xSummary.posts} X post${xSummary.posts === 1 ? '' : 's'} quoted this exact contract address, from ${xSummary.authors} account${xSummary.authors === 1 ? '' : 's'}`
+ `; most-followed ${who}${followers ? ` (${followers} followers)` : ''}`
+ (quote ? `: "${quote}"` : ''),
source: lead.url,
at: iso(lead.created_at),
checked_against: check,
});
}
if (callouts?.length) {
const latest = callouts[0];
const flat = latest.text.replace(/\s+/g, ' ');
const quote = flat.length > 140 ? `${flat.slice(0, 140)}...` : flat;
evidence.push({
type: 'social_mention',
platform: 'pump.fun',
detail: `${callouts.length} pump.fun callout${callouts.length === 1 ? '' : 's'}; latest`
+ (latest.author ? ` from @${latest.author}` : '')
+ `: "${quote}"`,
source: pumpPage,
at: iso(latest.ts),
checked_against: check,
});
}
if (paidSignal?.signal) {
const conf = Number(paidSignal.confidence);
evidence.push({
type: 'paid_signal',
detail: `paid ${paidSignal.source || 'sentiment'} read (x402${Number.isFinite(conf) ? `, confidence ${pct(conf)}` : ''}): ${paidSignal.signal}`
+ (paidSignal.headline ? `, "${String(paidSignal.headline).slice(0, 120)}"` : ''),
source: receiptTxUrl(paidSignal.tx_signature) || intelApi,
at: iso(paidSignal.checked_at),
checked_against: check,
});
}
const headline = r.signals?.news_headline;
if (r.is_news_meme && headline) {
evidence.push({
type: 'news_match',
detail: `name matches a live news story: "${String(headline).slice(0, 140)}"`,
source: r.signals?.news_url || intelApi,
at: launchAt,
checked_against: check,
});
}
return evidence;
}
/**
* The single most important risk, in one line. Deterministic priority order,
* worst first. Pure.
*/
export function cautionFor(r, { copycats = 0, calloutCount = 0, calloutsRead = true, paidSignal = null, concPct = null, curve = null, earlyVolSol = null, xSummary = null } = {}) {
const flags = new Set(Array.isArray(r.risk_flags) ? r.risk_flags : []);
const fresh = r.fresh_wallet_ratio != null ? Number(r.fresh_wallet_ratio) : null;
const top10 = r.concentration_top10 != null ? Number(r.concentration_top10) : null;
const snipe = r.snipe_ratio != null ? Number(r.snipe_ratio) : null;
const sym = r.symbol ? `$${r.symbol}` : 'this name';
if (flags.has('dev_dumped')) return 'The creator already sold; momentum from here is exit liquidity.';
if (flags.has('bundle_launch')) return 'Launch was bundled: a coordinated group bought the early supply.';
if (curve && !curve.graduated && curve.bondingProgressPct != null && curve.bondingProgressPct < CURVE_RESET_PCT
&& earlyVolSol != null && earlyVolSol >= CURVE_RESET_MIN_SOL) {
return `The bonding curve is back at ${Math.round(curve.bondingProgressPct)}% after ${fmtSol(earlyVolSol)} SOL of early buying: the early buyers have already sold.`;
}
if (flags.has('single_whale')) return 'One wallet holds most of the early supply; a single sell can erase the move.';
if (flags.has('fresh_wallet_swarm') || (fresh != null && fresh >= 0.5)) {
return `${fresh != null ? pct(fresh) : 'Most'} of early buyers are brand-new wallets, a common sign of manufactured volume.`;
}
if (isSingleVoice(xSummary)) {
const who = xSummary.top_poster?.username ? `@${xSummary.top_poster.username}` : 'one account';
return xSummary.authors === 1
? `All ${xSummary.posts} X posts quoting this contract came from ${who}: that is promotion, not independent interest.`
: `${who} wrote ${xSummary.top_poster?.posts} of the ${xSummary.posts} X posts quoting this contract: the chatter is mostly one voice.`;
}
if (top10 != null && concPct != null && concPct >= 0.8) {
return `The top 10 wallets hold ${pct(top10)} of what was bought early, more concentrated than ${Math.floor(concPct * 100)}% of comparable launches; exits can be sudden.`;
}
if (copycats > 0) {
return `${copycats} other coin${copycats === 1 ? '' : 's'} named ${sym} launched in the same window; check you have the right mint.`;
}
if (paidSignal?.signal === 'bearish') {
return `A paid sentiment read on this coin came back bearish${paidSignal.headline ? `: "${String(paidSignal.headline).slice(0, 100)}"` : '.'}`;
}
if (flags.has('sell_pressure')) return 'Sells are already heavy against buys; the early pump may be distributing.';
// The engine's own `sniped` flag, not the raw ratio: most launches are
// majority-sniped in their first block, so a bare threshold flags nearly all.
if (flags.has('sniped')) {
return `${snipe != null ? pct(snipe) : 'Much'} of early volume came from first-block snipers, who usually sell into the first pump.`;
}
if (!r.twitter && !r.telegram && !r.website && !calloutCount && !xSummary?.posts) {
return calloutsRead
? 'No X, Telegram, website or callouts: nothing outside the chart is holding attention.'
: 'No X, Telegram or website linked: nothing outside the chart is holding attention.';
}
const obs = Number(r.observation_seconds) || null;
return `These signals cover only the first ${obs ? `${obs}s` : 'minutes'} of trading; most early momentum on pump.fun fades.`;
}
const intelColumns = () => sql`
mint, network, symbol, name, image_uri, twitter, telegram, website,
first_seen_at, observation_seconds, buy_count, sell_count,
buy_volume_lamports, sell_volume_lamports, unique_buyers, signals,
snipe_ratio, concentration_top10, fresh_wallet_ratio, quality_score,
risk_flags, smart_money_count, smart_money_notable, is_news_meme
`;
async function loadWindow({ network, windowMinutes }) {
return sql`
select ${intelColumns()}
from pump_coin_intel
where network = ${network}
and first_seen_at > now() - make_interval(mins => ${windowMinutes})
order by first_seen_at desc
limit 5000
`;
}
// Peers for a single-coin scout: every coin first seen within half the window
// either side of it, so an older coin is still measured against its own hour.
async function loadPeers({ network, mint, windowMinutes }) {
const [row] = await sql`
select ${intelColumns()} from pump_coin_intel
where mint = ${mint} and network = ${network} limit 1
`;
if (!row) return { row: null, peers: [] };
const half = Math.max(1, Math.round(windowMinutes / 2));
const peers = await sql`
select ${intelColumns()} from pump_coin_intel
where network = ${network}
and first_seen_at between ${row.first_seen_at}::timestamptz - make_interval(mins => ${half})
and ${row.first_seen_at}::timestamptz + make_interval(mins => ${half})
limit 5000
`;
return { row, peers };
}
function withTimeout(promise, ms) {
let tid;
return Promise.race([
promise,
new Promise((resolve) => { tid = setTimeout(() => resolve({ timedOut: true }), ms); }),
]).finally(() => clearTimeout(tid));
}
// Latest paid Crypto Intel read per mint (sniper_coin_sentiment), one query for
// the whole shortlist. A read older than a few hours says nothing about now.
async function loadPaidSignals(network, mints) {
if (!mints.length) return new Map();
const rows = await sql`
select distinct on (mint) mint, signal, headline, confidence, source, tx_signature, checked_at
from sniper_coin_sentiment
where network = ${network}
and mint = any(${mints}::text[])
and checked_at > now() - make_interval(hours => ${PAID_SIGNAL_MAX_AGE_H})
order by mint, checked_at desc
`.catch(() => null);
return rows ? new Map(rows.map((r) => [r.mint, r])) : null;
}
/** The post receipts a candidate ships with: the most-followed few, trimmed. Pure. */
export function postReceipts(posts, n = MAX_POST_RECEIPTS) {
return (posts || [])
.slice()
.sort((a, b) => (b.author?.followers || 0) - (a.author?.followers || 0) || Date.parse(b.created_at) - Date.parse(a.created_at))
.slice(0, n)
.map((p) => ({
url: p.url,
author: p.author?.username || null,
followers: p.author?.followers ?? null,
verified: p.author?.verified === true,
at: iso(p.created_at),
text: String(p.text || '').replace(/\s+/g, ' ').slice(0, 280),
likes: p.likes,
reposts: p.reposts,
}));
}
// X posts quoting one mint, cached per mint. A failed read is cached briefly
// as a failure, so an X outage does not turn every board refresh into a wait.
async function readXPosts(mint, firstSeenAt) {
if (!anyXSearchConfigured()) return { unavailable: 'not_configured' };
const key = `scout:x:v1:${mint}`;
const hit = await cacheGet(key).catch(() => null);
if (hit) return hit;
let value;
try {
const first = Date.parse(firstSeenAt instanceof Date ? firstSeenAt.toISOString() : firstSeenAt);
const sinceIso = Number.isFinite(first) ? new Date(first - X_LOOKBACK_BEFORE_LAUNCH_MS).toISOString() : null;
const { posts, rung } = await searchMintPostsDetailed(mint, { sinceIso, maxResults: 25 });
value = { posts, summary: summarizePosts(posts), rung, read_at: new Date().toISOString() };
cacheSet(key, value, X_CACHE_TTL_S).catch(() => {});
} catch (err) {
value = { unavailable: err?.reason || 'upstream_error' };
cacheSet(key, value, X_FAIL_TTL_S).catch(() => {});
}
return value;
}
async function enrich(mint, firstSeenAt) {
const [curveRes, calloutRes, xRes] = await Promise.all([
withTimeout(getBondingStatus(mint).catch(() => ({ kind: 'upstream_down' })), ENRICH_TIMEOUT_MS),
withTimeout(
fetchPumpFunCallouts(mint, 20, { timeoutMs: ENRICH_TIMEOUT_MS - 500 }).catch(() => ({ error: 'unreachable' })),
ENRICH_TIMEOUT_MS,
),
withTimeout(readXPosts(mint, firstSeenAt), ENRICH_TIMEOUT_MS),
]);
const unavailable = [];
let curve = null;
let socials = null;
if (curveRes?.kind === 'ok') {
curve = curveRes.status;
// Creators often add links after the intel window closes; the live coin
// object is the fresher read.
const c = curveRes.coin || {};
socials = { twitter: c.twitter || null, telegram: c.telegram || null, website: c.website || null };
}
else if (curveRes?.kind !== 'not_found') unavailable.push('bonding_curve');
let callouts = [];
if (Array.isArray(calloutRes?.posts)) callouts = calloutRes.posts;
else unavailable.push('callouts');
let xPosts = null;
let xSummary = null;
if (Array.isArray(xRes?.posts)) {
xPosts = xRes.posts;
xSummary = xRes.summary;
} else {
unavailable.push('x_posts');
}
return {
curve, callouts, socials, xPosts, xSummary,
calloutsRead: !unavailable.includes('callouts'),
checkedAt: new Date().toISOString(),
unavailable,
};
}
export function shapeCandidate(row, pre, stats, extra, origin) {
const live = extra.socials || {};
const r = {
...row,
twitter: row.twitter || live.twitter || null,
telegram: row.telegram || live.telegram || null,
website: row.website || live.website || null,
};
const copycats = Math.max(0, (stats.symbols.get(symbolKey(r.symbol)) || 1) - 1);
const flags = Array.isArray(r.risk_flags) ? r.risk_flags : [];
const callouts = extra.callouts || [];
const { score, parts } = momentumScore(pre, {
curve: extra.curve,
calloutCount: callouts.length,
paidSignal: extra.paidSignal,
newsMatch: !!(r.is_news_meme && r.signals?.news_headline),
flags,
copycats,
xSummary: extra.xSummary,
});
const disqualified = flags.some((f) => DISQUALIFYING_FLAGS.has(f));
const mint = r.mint;
const checkedAt = extra.checkedAt || new Date().toISOString();
return {
mint,
ticker: r.symbol ? `$${r.symbol}` : null,
name: r.name || null,
image_uri: r.image_uri || null,
momentum_score: disqualified ? 0 : score,
score_parts: parts,
evidence: buildEvidence(r, pre, stats, { ...extra, callouts, origin, checkedAt }),
caution: cautionFor(r, {
copycats,
calloutCount: callouts.length,
calloutsRead: extra.calloutsRead !== false,
paidSignal: extra.paidSignal,
concPct: pre.concPct,
curve: extra.curve,
earlyVolSol: pre.vol,
xSummary: extra.xSummary,
}),
market_check: {
checked_at: checkedAt,
early_buy_volume_sol: round(pre.vol, 3),
early_buyers: pre.nBuyers,
observation_seconds: Number(r.observation_seconds) || null,
graduated: extra.curve ? extra.curve.graduated === true : null,
bonding_progress_pct: extra.curve?.bondingProgressPct != null ? round(extra.curve.bondingProgressPct, 1) : null,
sol_in_curve: extra.curve?.solInCurve != null ? round(extra.curve.solInCurve, 3) : null,
},
x: extra.xSummary || null,
posts: postReceipts(extra.xPosts),
socials: { twitter: r.twitter, telegram: r.telegram, website: r.website },
risk_flags: flags,
quality_score: r.quality_score ?? null,
first_seen_at: r.first_seen_at,
unavailable: extra.unavailable || [],
links: {
intel: `${origin}/coin-intel?mint=${encodeURIComponent(mint)}`,
oracle: `${origin}/oracle/coin/${encodeURIComponent(mint)}`,
pump: `https://pump.fun/coin/${encodeURIComponent(mint)}`,
fork: `${origin}/trades?fork=${encodeURIComponent(mint)}`,
},
};
}
// ── persistence: what the Scout flagged, and when ──────────────────────────
/**
* Record board candidates. The first sighting is kept forever (it is what a
* trade receipt compares an entry against, and what the track record grades);
* the latest read overwrites the rest. Best-effort: a write failure never
* fails the board.
*/
export async function recordScoutReads(network, candidates) {
const rows = (candidates || []).filter((c) => c?.mint);
await Promise.all(rows.map((c) => sql`
insert into sentiment_scout_reads (
mint, network, symbol,
first_scouted_at, first_score, first_evidence, first_caution,
last_scouted_at, last_score, peak_score, evidence, caution, x_summary, posts
) values (
${c.mint}, ${network}, ${c.ticker ? c.ticker.replace(/^\$/, '') : null},
now(), ${c.momentum_score}, ${JSON.stringify(c.evidence)}::jsonb, ${c.caution},
now(), ${c.momentum_score}, ${c.momentum_score}, ${JSON.stringify(c.evidence)}::jsonb, ${c.caution},
${c.x ? JSON.stringify(c.x) : null}::jsonb, ${c.posts?.length ? JSON.stringify(c.posts) : null}::jsonb
)
on conflict (mint, network) do update set
last_scouted_at = now(),
last_score = excluded.last_score,
peak_score = greatest(sentiment_scout_reads.peak_score, excluded.last_score),
evidence = excluded.evidence,
caution = excluded.caution,
x_summary = coalesce(excluded.x_summary, sentiment_scout_reads.x_summary),
posts = coalesce(excluded.posts, sentiment_scout_reads.posts)
`.catch(() => null)));
}
/** The recorded Scout read for one coin, or null. Best-effort. */
export async function loadScoutRead(mint, network = 'mainnet') {
const [row] = await sql`
select mint, network, symbol, first_scouted_at, first_score, first_evidence, first_caution,
last_scouted_at, last_score, peak_score, evidence, caution, x_summary, posts
from sentiment_scout_reads
where mint = ${mint} and network = ${network}
limit 1
`.catch(() => []);
return row || null;
}
/**
* Grade the Scout's own calls. Of the coins it flagged in the last `days`,
* how many went on to graduate or pump, next to the same rate for every
* labeled coin the engine observed over the same days. A scout that cannot
* beat the base rate is noise, and this is where a reader finds that out.
* Pure shaping of the two aggregate rows.
*/
export function shapeTrackRecord(scout, base, days) {
const rate = (good, n) => (n > 0 ? round(good / n, 4) : null);
const bands = ['70_plus', '50_69', 'under_50'].map((band) => {
const n = Number(scout?.[`labeled_${band}`]) || 0;
const good = Number(scout?.[`good_${band}`]) || 0;
return { band, labeled: n, good, good_rate: rate(good, n) };
});
const labeled = Number(scout?.labeled) || 0;
const good = Number(scout?.good) || 0;
const baseLabeled = Number(base?.labeled) || 0;
const baseGood = Number(base?.good) || 0;
const scoutRate = rate(good, labeled);
const baseRate = rate(baseGood, baseLabeled);
return {
days,
scouted: Number(scout?.scouted) || 0,
labeled,
graduated: Number(scout?.graduated) || 0,
pumped: Number(scout?.pumped) || 0,
rugged: Number(scout?.rugged) || 0,
good_rate: scoutRate,
base_rate: baseRate,
base_labeled: baseLabeled,
lift: scoutRate != null && baseRate ? round(scoutRate / baseRate, 2) : null,
bands,
definition: 'good = the coin graduated off the bonding curve or pumped (the Coin Intelligence Engine\'s own outcome labels); unknown outcomes are excluded',
};
}
export async function scoutTrackRecord(network = 'mainnet', { days = 14 } = {}) {
const d = Math.max(1, Math.min(60, Math.round(Number(days) || 14)));
return cacheWrap(`scout:track:v1:${network}:${d}`, 600, async () => {
const [[scout], [base]] = await Promise.all([
sql`
select count(*) as scouted,
count(o.mint) as labeled,
count(*) filter (where o.outcome = 'graduated') as graduated,
count(*) filter (where o.outcome = 'pumped') as pumped,
count(*) filter (where o.outcome = 'rugged') as rugged,
count(*) filter (where o.outcome in ('graduated', 'pumped')) as good,
count(o.mint) filter (where s.first_score >= 70) as labeled_70_plus,
count(*) filter (where s.first_score >= 70 and o.outcome in ('graduated', 'pumped')) as good_70_plus,
count(o.mint) filter (where s.first_score between 50 and 69) as labeled_50_69,
count(*) filter (where s.first_score between 50 and 69 and o.outcome in ('graduated', 'pumped')) as good_50_69,
count(o.mint) filter (where s.first_score < 50) as labeled_under_50,
count(*) filter (where s.first_score < 50 and o.outcome in ('graduated', 'pumped')) as good_under_50
from sentiment_scout_reads s
left join pump_coin_outcomes o on o.mint = s.mint and o.outcome is not null and o.outcome <> 'unknown'
where s.network = ${network}
and s.first_scouted_at > now() - make_interval(days => ${d})
`,
sql`
select count(*) as labeled,
count(*) filter (where o.outcome in ('graduated', 'pumped')) as good
from pump_coin_intel i
join pump_coin_outcomes o on o.mint = i.mint and o.outcome is not null and o.outcome <> 'unknown'
where i.network = ${network}
and i.first_seen_at > now() - make_interval(days => ${d})
`,
]);
return shapeTrackRecord(scout, base, d);
});
}
// ── the judge's view ────────────────────────────────────────────────────────
let _judgeStats = null;
async function judgeWindowStats(network) {
if (_judgeStats && _judgeStats.network === network && Date.now() - _judgeStats.at < JUDGE_STATS_TTL_MS) {
return _judgeStats.stats;
}
const rows = await loadWindow({ network, windowMinutes: DEFAULT_WINDOW_MIN });
const stats = windowStats(rows);
_judgeStats = { network, at: Date.now(), stats };
return stats;
}
/**
* Render a Scout read as the plain-text block an LLM judge is handed. Every
* line is an evidence line the Scout built, so the judge sees the same
* receipts a human does. Pure.
*/
export function formatJudgeBlock(candidate) {
if (!candidate) return '';
const lines = [
'',
'Sentiment Scout read (every line below is sourced, timestamped, and was checked against on-chain data at read time):',
`momentum_score: ${candidate.momentum_score}/100`,
...candidate.evidence.map((e) => `- ${e.type}${e.platform ? ` (${e.platform})` : ''}: ${e.detail}`),
`caution: ${candidate.caution}`,
'Weigh this as evidence, not as a verdict. Thin or one-voice evidence should lower your confidence, not raise it.',
];
return lines.join('\n');
}
/**
* The Scout's read of one observed coin, for the sniper's LLM judge, built
* without any network call on the hot path: the launch window row, a cached
* window to rank it against, the latest paid read, and any X posts the board
* already recorded for it. Returns '' when the coin has not been observed.
*/
export async function scoutJudgeBlock(mint, network = 'mainnet') {
const net = network === 'devnet' ? 'devnet' : 'mainnet';
const [[row], stats, paid, recorded] = await Promise.all([
sql`select ${intelColumns()} from pump_coin_intel where mint = ${mint} and network = ${net} limit 1`,
judgeWindowStats(net),
loadPaidSignals(net, [mint]),
loadScoutRead(mint, net),
]);
if (!row) return '';
const pre = measure(row, stats.size ? stats : windowStats([row]));
const posts = Array.isArray(recorded?.posts) ? recorded.posts.map((p) => ({
url: p.url, text: p.text, created_at: p.at, author: { username: p.author, followers: p.followers },
})) : null;
const candidate = shapeCandidate(row, pre, stats.size ? stats : windowStats([row]), {
curve: null,
callouts: [],
calloutsRead: false,
paidSignal: paid?.get(mint) || null,
xSummary: recorded?.x_summary || null,
xPosts: posts,
unavailable: ['bonding_curve'],
}, appOrigin());
return formatJudgeBlock(candidate);
}
// ── the run ─────────────────────────────────────────────────────────────────
/**
* Run the scout.
* @param {{ network?: 'mainnet'|'devnet', windowMinutes?: number, limit?: number, mint?: string|null, record?: boolean }} opts
*/
export async function runSentimentScout({ network = 'mainnet', windowMinutes, limit, mint = null, record = true } = {}) {
const net = network === 'devnet' ? 'devnet' : 'mainnet';
const win = clampWindow(windowMinutes);
const lim = clampLimit(limit);
const key = `${net}:${win}:${lim}:${mint || ''}`;
const hit = cache.get(key);
if (hit && Date.now() - hit.at < CACHE_TTL_MS) return hit.value;
const origin = appOrigin();
const generated_at = new Date().toISOString();
let value;
if (mint) {
// A single-coin read always answers, even for a coin that would not
// qualify on the board: the caller asked about THIS coin.
const { row, peers } = await loadPeers({ network: net, mint, windowMinutes: win });
if (!row) {
value = {
network: net, window_minutes: win, observed: 0, generated_at, found: false, candidates: [],
reason: 'This coin has not been observed by the Coin Intelligence Engine (launched before it was watching, or still in its first seconds).',
};
} else {
const stats = windowStats(peers.length ? peers : [row]);
const [extra, paid, recorded] = await Promise.all([
enrich(row.mint, row.first_seen_at),
loadPaidSignals(net, [row.mint]),
loadScoutRead(row.mint, net),
]);
extra.paidSignal = paid?.get(row.mint) || null;
if (!paid) extra.unavailable.push('paid_signals');
const candidate = shapeCandidate(row, measure(row, stats), stats, extra, origin);
candidate.qualifies = preScore(row, stats) != null;
candidate.scouted = recorded
? { first_at: iso(recorded.first_scouted_at), first_score: recorded.first_score, peak_score: recorded.peak_score }
: null;
value = {
network: net, window_minutes: win, observed: stats.size, generated_at, found: true,
candidates: [candidate],
};
}
} else {
const rows = await loadWindow({ network: net, windowMinutes: win });
const stats = windowStats(rows);
const ranked = [];
for (const r of rows) {
const pre = preScore(r, stats);
if (pre) ranked.push({ r, pre });
}
ranked.sort((a, b) => b.pre.base - a.pre.base);
const shortlist = ranked.slice(0, Math.min(MAX_LIMIT, lim * 2));
const paid = await loadPaidSignals(net, shortlist.map(({ r }) => r.mint));
const enriched = await Promise.all(
shortlist.map(async ({ r, pre }) => {
const extra = await enrich(r.mint, r.first_seen_at);
extra.paidSignal = paid?.get(r.mint) || null;
if (!paid) extra.unavailable.push('paid_signals');
return shapeCandidate(r, pre, stats, extra, origin);
}),
);
enriched.sort((a, b) => b.momentum_score - a.momentum_score);
value = {
network: net,
window_minutes: win,
observed: stats.size,
qualified: ranked.length,
generated_at,
candidates: enriched.slice(0, lim),
};
if (!value.candidates.length) {
value.reason = stats.size
? `None of the ${stats.size} launches in the last ${win} minutes cleared the screen (top-quartile buy volume, ${MIN_BUYERS}+ buyers, no bundle or dev dump).`
: `The Coin Intelligence Engine has observed no ${net} launches in the last ${win} minutes.`;
}
if (record && value.candidates.length) await recordScoutReads(net, value.candidates);
}
cache.set(key, { at: Date.now(), value });
if (cache.size > 200) cache.delete(cache.keys().next().value);
return value;
}
export function _resetScoutCache() {
cache.clear();
_judgeStats = null;
}