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
// agent-sniper — entry scoring. Pure, no I/O.
//
// Given an enriched mint event (from connectPumpFunFeed) and a strategy row,
// decide whether the agent should snipe it. Returns { pass, score, reasons }.
// `reasons` always explains the verdict — kept on skipped events too so the
// logs show WHY a mint was passed over, which is what you stare at when tuning.
import { learnedScore } from './intel/learn.js';
import { assessMarketRealness } from '../../api/_lib/market-realness.js';
function n(v) {
if (v == null) return null;
const x = Number(v);
return Number.isFinite(x) ? x : null;
}
function envNum(k) {
const v = process.env[k];
if (v == null || v === '') return null;
const x = Number(v);
return Number.isFinite(x) ? x : null;
}
// Fleet-wide market-cap SAFETY BAND. Set these on the worker to enforce a band
// across EVERY agent at once, without editing each stored strategy — the fix for a
// fleet that was armed with no market-cap bounds and is buying $4k dust. A
// per-strategy min/max only TIGHTENS this band, it can never loosen it. Unset =
// no clamp (legacy behaviour). e.g. SNIPER_MIN_MC_FLOOR_USD=10000,
// SNIPER_MAX_MC_CEIL_USD=100000 to enforce the 10k–100k rule everywhere.
//
// NOTE: on a blind `new_mint` snipe the create-event market cap is ~$4k, so a
// 10k floor correctly rejects brand-new launches — to actually BUY inside the
// band, the strategy must use the `intel_confirmed` trigger, which scores a coin
// AFTER it has pumped into range. That is the intended, non-rug entry.
const MC_FLOOR = envNum('SNIPER_MIN_MC_FLOOR_USD');
const MC_CEIL = envNum('SNIPER_MAX_MC_CEIL_USD');
// Combine a per-strategy bound with the fleet band: min tightens UP, max tightens DOWN.
function tightenMin(stratMin, floor) {
if (stratMin == null) return floor;
if (floor == null) return stratMin;
return Math.max(stratMin, floor);
}
function tightenMax(stratMax, ceil) {
if (stratMax == null) return ceil;
if (ceil == null) return stratMax;
return Math.min(stratMax, ceil);
}
/**
* Market-cap band gate — the single source of truth for the owner's "buy only
* $10k–$100k" rule. The effective band is the per-strategy bound tightened by the
* fleet-wide safety band (SNIPER_MIN_MC_FLOOR_USD / SNIPER_MAX_MC_CEIL_USD). It
* FAILS CLOSED: an unknown market cap fails the min gate, because we must never
* buy blind into a band we can't even price the coin into — that was the rug hole.
* Returns a skip reason string when out of band (or unknown while a min exists),
* or null when the coin is inside the band / no band is configured.
*
* Shared by scoreMint, scoreIntel, AND the executeBuy chokepoint so EVERY trigger
* path (new_mint / intel / alpha / first_claim / radar / swarm) enforces the same
* rule — not just the two scorers that happened to implement it.
*/
export function marketCapBandReason(mcUsdRaw, strat) {
const mcUsd = n(mcUsdRaw);
const minMc = tightenMin(n(strat.min_market_cap_usd), MC_FLOOR);
const maxMc = tightenMax(n(strat.max_market_cap_usd), MC_CEIL);
if (minMc != null && (mcUsd == null || mcUsd < minMc)) return `mc_below_min:${mcUsd ?? 'n/a'}<${minMc}`;
if (maxMc != null && mcUsd != null && mcUsd > maxMc) return `mc_above_max:${Math.round(mcUsd)}>${maxMc}`;
return null;
}
/**
* @param {object} mint enriched PumpPortal mint event
* @param {object} strat agent_sniper_strategies row
* @returns {{ pass: boolean, score: number, reasons: string[] }}
*/
export function scoreMint(mint, strat) {
const reasons = [];
let score = 0;
// ── hard filters (any failure → skip) ────────────────────────────────────
if (strat.require_sol_quote && mint.is_usdc_pair) {
return { pass: false, score: 0, reasons: ['quote_not_sol'] };
}
const bandReason = marketCapBandReason(mint.market_cap_usd, strat);
if (bandReason) return { pass: false, score: 0, reasons: [bandReason] };
const launches = n(mint.creator_launches);
const graduated = n(mint.creator_graduated);
const maxLaunches = n(strat.max_creator_launches);
const minGrad = n(strat.min_creator_graduated);
// Serial-rugger guard, FAIL CLOSED: many launches → skip; and if a launch cap
// is set but the creator's history couldn't be read (enrich timeout), skip too
// rather than let a serial rugger slip through on a null. Matches the fail-closed
// launch gate in api/_lib/agent-strategy-runtime.js.
if (maxLaunches != null && (launches == null || launches > maxLaunches)) {
return { pass: false, score: 0, reasons: [launches == null ? 'creator_launches_unknown' : 'creator_too_many_launches'] };
}
if (minGrad != null && (graduated == null || graduated < minGrad)) {
return { pass: false, score: 0, reasons: ['creator_too_few_graduated'] };
}
const hasSocials = !!(mint.twitter || mint.telegram || mint.website);
if (strat.require_socials && !hasSocials) {
return { pass: false, score: 0, reasons: ['no_socials'] };
}
// ── soft signals (contribute to score; tie-break / future ranking) ───────
if (hasSocials) { score += 1; reasons.push('has_socials'); }
if (graduated != null && graduated > 0) { score += graduated; reasons.push(`creator_graduated:${graduated}`); }
const initBuy = n(mint.initial_buy_sol);
if (initBuy != null && initBuy >= 1) { score += 1; reasons.push(`initial_buy:${initBuy.toFixed(2)}sol`); }
const mcUsd = n(mint.market_cap_usd);
if (mcUsd != null) reasons.push(`mc_usd:${Math.round(mcUsd)}`);
return { pass: true, score, reasons };
}
/**
* Decide whether to buy a coin AFTER the Coin Intelligence Engine has finished
* observing it. Drives `trigger='intel_confirmed'` strategies. Unlike scoreMint
* (which fires blind on the create event), this has the full picture: bundle
* likelihood, organic score, concentration, dev behaviour, classification, and
* the learned weights. It can afford to be picky — a passed-over coin costs
* nothing, a bundle-rug costs real SOL.
*
* @param {object} rec finished intel record (from intel/watcher.js)
* @param {object} strat agent_sniper_strategies row (trigger=intel_confirmed)
* @param {object|null} weights learned weights (from intel/store.getLearnedWeights)
* @returns {{ pass: boolean, score: number, reasons: string[] }}
*/
export function scoreIntel(rec, strat, weights = null) {
const reasons = [];
const s = rec?.signals || {};
// ── hard gates ───────────────────────────────────────────────────────────
// Market-cap band first — this is the trigger meant to buy INSIDE the band
// (a coin observed after it pumped into range), so the fleet band applies here
// too. Unknown mcap fails a min gate: never buy what we can't price into band.
const bandReason = marketCapBandReason(rec.market_cap_usd, strat);
if (bandReason) return { pass: false, score: 0, reasons: [bandReason] };
const minQ = n(strat.min_quality_score);
if (minQ != null && (rec.quality_score == null || rec.quality_score < minQ)) {
return { pass: false, score: 0, reasons: [`quality_below_min:${rec.quality_score}`] };
}
const maxBundle = n(strat.max_bundle_score);
if (maxBundle != null && s.bundle_score != null && s.bundle_score > maxBundle) {
return { pass: false, score: 0, reasons: [`bundle_above_max:${s.bundle_score}`] };
}
const maxConc = n(strat.max_concentration_top1);
if (maxConc != null && s.concentration_top1 != null && s.concentration_top1 > maxConc) {
return { pass: false, score: 0, reasons: [`whale_concentration:${s.concentration_top1}`] };
}
// avoid_dev_dump defaults true (column default) — treat undefined as true.
if (strat.avoid_dev_dump !== false && s.dev_sold) {
return { pass: false, score: 0, reasons: ['dev_dumped'] };
}
const cats = Array.isArray(strat.allowed_categories) ? strat.allowed_categories.filter(Boolean) : [];
if (cats.length && rec.category && !cats.includes(rec.category)) {
return { pass: false, score: 0, reasons: [`category_excluded:${rec.category}`] };
}
// Reuse the new-mint hard filters that still apply post-observation.
if (strat.require_socials && !(rec.twitter || rec.telegram || rec.website)) {
return { pass: false, score: 0, reasons: ['no_socials'] };
}
// Market-realness gate (the painted-stairstep defense). A big candle that then
// stairsteps up on a handful of wallets with no sellers is a chart painted to
// trap momentum bots; in the platform's own 62k labeled outcomes a genuine
// two-sided market (>=20 buyers & >=5 sellers) wins 52% vs a ~12% base, while a
// painted one-sided rise barely beats a coin flip. Two optional per-strategy
// hard gates, off by default so existing arms are unchanged:
// require_two_sided_market — demand the proven two-sided bar before buying.
// min_unique_sellers — demand a floor of real sellers (a two-sided market).
const market = assessMarketRealness(s);
if (strat.require_two_sided_market === true && !market.twoSided) {
return { pass: false, score: 0, reasons: [`not_two_sided:${market.read}`] };
}
const minSellers = n(strat.min_unique_sellers);
if (minSellers != null && (market.sellers == null || market.sellers < minSellers)) {
return { pass: false, score: 0, reasons: [`too_few_sellers:${market.sellers ?? 0}<${minSellers}`] };
}
// Smart-money gate (task 03). `rec.smart_money` is the live graph read attached
// by the worker (getSmartMoneyForMint). It honours two optional strategy knobs:
// require_smart_money — demand at least one reputable, non-sybil buyer.
// min_smart_money_score — demand the coin's 0..100 pedigree score clears a bar.
// Both skip silently when the graph hasn't scored this coin yet (computed:false)
// — a brand-new coin lacks history; the other gates still protect the snipe.
const sm = rec.smart_money || null;
const smComputed = !!(sm && sm.computed);
if (smComputed) {
if (strat.require_smart_money === true && (sm.count ?? 0) < 1) {
return { pass: false, score: 0, reasons: ['no_smart_money'] };
}
const minSm = n(strat.min_smart_money_score);
if (minSm != null && (n(sm.smart_money_score) ?? 0) < minSm) {
return { pass: false, score: 0, reasons: [`smart_money_below_min:${sm.smart_money_score}<${minSm}`] };
}
}
// ── score: baseline quality + learned model + organic, minus risk ─────────
let score = (rec.quality_score ?? 0) / 100;
reasons.push(`quality:${rec.quality_score}`);
if (s.organic_score != null) { score += s.organic_score * 0.5; reasons.push(`organic:${s.organic_score}`); }
if (s.bundle_score != null) { score -= s.bundle_score * 0.5; if (s.bundle_score >= 0.4) reasons.push(`bundle:${s.bundle_score}`); }
const learned = learnedScore(s, weights);
if (learned != null) { score += learned; reasons.push(`learned:${learned}`); }
// Market realness: reward a genuine two-sided market, drag a painted stairstep.
// Always on (no knob) so EVERY intel arm's ranking reflects the single strongest
// signal in the data, centered so a neutral market neither helps nor hurts.
if (market.buyers != null && !market.flags.includes('insufficient_trades')) {
score += (market.realness - 0.5) * 0.8;
if (market.twoSided) reasons.push('two_sided');
if (market.painted) reasons.push(`painted:${market.read}`);
}
// Smart-money lifts the score (proven money in) and a dominant sybil cluster
// drags it (a manufactured "wide base"). Pure contribution — no I/O here.
if (smComputed) {
const smScore = n(sm.smart_money_score) ?? 0;
const smCount = sm.count ?? 0;
if (smCount > 0) { score += Math.min(0.5, (smScore / 100) * 0.5); reasons.push(`smart_money:${smScore}/${smCount}`); }
if (sm.sybil_flag) { score -= 0.4; reasons.push('sybil_cluster'); }
}
if (rec.category) reasons.push(`cat:${rec.category}`);
for (const flag of rec.risk_flags || []) reasons.push(`flag:${flag}`);
return { pass: true, score: Number(score.toFixed(4)), reasons };
}