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
// api/_lib/x402/pump-volume-anomaly.js
//
// Pump.fun volume-anomaly detector — the data engine behind the
// `pump_volume_anomaly` topic of POST /api/x402/crypto-intel.
//
// "Abnormal trading volume in the last hour" is defined cross-sectionally: across
// the set of currently-live pump.fun coins, we measure each coin's USD trade
// volume in the trailing window (default 1 h) and compare the busiest coin to the
// MEDIAN of its peers. A coin whose last-hour volume is a large multiple of the
// median active coin is a genuine statistical outlier — the attention/volume
// spike a sniper or oracle wants to know about before price catches up.
//
// Every byte is live: the candidate set comes from pump.fun's currently-live
// board (frontend-api-v3) and per-coin volume is summed from the real swap-API
// trade feed (swap-api.pump.fun) — the same upstreams the rest of the codebase
// already proxies (see api/_lib/pump-launch-feed.js, api/pump/[action].js). No
// mocks, no synthetic coins.
//
// The pure scoring functions (summarizeWindowUsd, median, scoreVolumeAnomaly,
// buildAnomalySignal) take plain data so they are unit-testable without network;
// detectPumpVolumeAnomaly() wires them to the live feeds.
const PUMP_FRONTEND_BASE =
process.env.PUMP_FRONTEND_BASE || 'https://frontend-api-v3.pump.fun';
const PUMP_SWAP_BASE = process.env.PUMP_SWAP_BASE || 'https://swap-api.pump.fun';
const UA = 'three.ws-x402-pump-volume/1';
// Tunables (env-overridable so production can adjust sensitivity without a deploy).
export const DEFAULTS = {
candidates: Number(process.env.PUMP_ANOMALY_CANDIDATES || 24), // coins to scan
tradeLimit: Number(process.env.PUMP_ANOMALY_TRADE_LIMIT || 100), // trades/coin
windowSec: Number(process.env.PUMP_ANOMALY_WINDOW_SEC || 3600), // trailing 1 h
ratioThreshold: Number(process.env.PUMP_ANOMALY_RATIO || 3), // anomaly when ratio ≥ this
minUsd: Number(process.env.PUMP_ANOMALY_MIN_USD || 250), // absolute volume floor
concurrency: Number(process.env.PUMP_ANOMALY_CONCURRENCY || 6),
fetchTimeoutMs: Number(process.env.PUMP_ANOMALY_TIMEOUT_MS || 6000),
};
// ── pure helpers ─────────────────────────────────────────────────────────────
function num(v) {
const n = typeof v === 'string' ? parseFloat(v) : v;
return Number.isFinite(n) ? n : null;
}
/** Parse a swap-API trade timestamp (ISO string or epoch s/ms) → ms, or null. */
function tradeTimeMs(t) {
const raw = t?.timestamp ?? t?.ts ?? null;
if (raw == null) return null;
if (typeof raw === 'number') return raw < 1e12 ? raw * 1000 : raw; // s → ms
const parsed = Date.parse(raw);
return Number.isFinite(parsed) ? parsed : null;
}
/**
* Sum the USD volume of trades that fall within [nowMs - windowSec, nowMs].
* Pure — caller supplies nowMs so it is deterministic under test.
* @returns {{ usd: number, count: number }}
*/
export function summarizeWindowUsd(trades, nowMs, windowSec = DEFAULTS.windowSec) {
if (!Array.isArray(trades)) return { usd: 0, count: 0 };
const floor = nowMs - windowSec * 1000;
let usd = 0;
let count = 0;
for (const t of trades) {
const tMs = tradeTimeMs(t);
if (tMs == null || tMs < floor || tMs > nowMs) continue;
// swap-api reports the per-trade USD notional directly on amountUsd. Only
// real USD figures count toward the volume sum — a trade without one is
// skipped rather than guessed from mismatched units.
const v = num(t.amountUsd ?? t.usd_amount);
if (v == null || v <= 0) continue;
usd += v;
count += 1;
}
return { usd, count };
}
/** Median of a numeric array (0 for empty). Pure. */
export function median(nums) {
const xs = (nums || []).filter((n) => Number.isFinite(n)).sort((a, b) => a - b);
if (!xs.length) return 0;
const mid = Math.floor(xs.length / 2);
return xs.length % 2 ? xs[mid] : (xs[mid - 1] + xs[mid]) / 2;
}
function round(n, dp = 2) {
if (!Number.isFinite(n)) return null;
const f = 10 ** dp;
return Math.round(n * f) / f;
}
/**
* Score a set of per-coin last-window volume samples into an anomaly verdict.
* @param {Array<{mint:string,name?:string,symbol?:string,window_usd:number,trade_count?:number}>} samples
* @param {object} [opts] { ratioThreshold, minUsd }
* @returns {{
* anomaly: boolean, mint: string|null, name: string|null, symbol: string|null,
* volume_ratio: number|null, top_window_usd: number|null, baseline_usd: number|null,
* candidates: number, active: number, trade_count: number|null, reason?: string
* }}
*/
export function scoreVolumeAnomaly(samples, opts = {}) {
const ratioThreshold = opts.ratioThreshold ?? DEFAULTS.ratioThreshold;
const minUsd = opts.minUsd ?? DEFAULTS.minUsd;
const list = Array.isArray(samples) ? samples : [];
const active = list
.filter((s) => s && Number.isFinite(s.window_usd) && s.window_usd > 0)
.sort((a, b) => b.window_usd - a.window_usd);
const base = {
anomaly: false,
mint: null,
name: null,
symbol: null,
volume_ratio: null,
top_window_usd: null,
baseline_usd: null,
candidates: list.length,
active: active.length,
trade_count: null,
};
// Need a population to compare against — one lone trader is not an "anomaly".
if (active.length < 3) {
return { ...base, reason: 'insufficient_active_coins' };
}
const top = active[0];
const rest = active.slice(1).map((s) => s.window_usd);
// Robust baseline: median of the peer coins. Fall back to the mean, then to the
// smallest positive peer, so a degenerate distribution can't divide by zero.
let baseline = median(rest);
if (!(baseline > 0)) baseline = rest.reduce((a, b) => a + b, 0) / rest.length;
if (!(baseline > 0)) baseline = Math.min(...rest.filter((v) => v > 0));
if (!(baseline > 0)) return { ...base, reason: 'no_peer_baseline' };
const ratio = top.window_usd / baseline;
const anomaly = ratio >= ratioThreshold && top.window_usd >= minUsd;
return {
anomaly,
mint: top.mint || null,
name: top.name || null,
symbol: top.symbol || null,
volume_ratio: round(ratio),
top_window_usd: round(top.window_usd),
baseline_usd: round(baseline),
candidates: list.length,
active: active.length,
trade_count: Number.isFinite(top.trade_count) ? top.trade_count : null,
};
}
/**
* Turn an anomaly score into the crypto-intel signal envelope (topic / signal /
* headline / rationale / confidence). Pure. A volume spike is an attention signal,
* so it maps to 'bullish'; a quiet market maps to 'neutral'.
*/
export function buildAnomalySignal(score, windowSec = DEFAULTS.windowSec) {
const mins = Math.round(windowSec / 60);
const label = score.symbol || score.name || (score.mint ? `${score.mint.slice(0, 4)}…` : 'a coin');
const usd = (n) => `$${Math.round(n || 0).toLocaleString('en-US')}`;
if (score.anomaly) {
const ratio = score.volume_ratio;
// High conviction once the spike is a large multiple of the peer median.
const highConviction = ratio > 5;
const confidence = Math.min(0.96, 0.6 + Math.min(ratio / 25, 0.36));
return {
signal: 'bullish',
conviction: highConviction ? 'high' : 'normal',
headline:
`${label} volume anomaly — ${ratio}× peer median ` +
`(${usd(score.top_window_usd)} in last ${mins}m)`,
rationale:
`Across ${score.active} actively-trading pump.fun coins, ${label} traded ` +
`${usd(score.top_window_usd)} in the last ${mins} minutes — ${ratio}× the ` +
`${usd(score.baseline_usd)} median of its peers. A volume spike of this ` +
`magnitude typically precedes a price/attention move; treat as a fresh ` +
`${highConviction ? 'high-conviction ' : ''}momentum candidate.`,
confidence: round(confidence, 4),
};
}
return {
signal: 'neutral',
conviction: 'none',
headline: `No abnormal pump.fun volume in the last ${mins}m`,
rationale:
`Scanned ${score.candidates} candidate coins (${score.active} actively trading). ` +
(score.reason === 'insufficient_active_coins'
? 'Too few active coins to establish a baseline this window.'
: `The busiest coin's volume sits within normal range of the peer median ` +
`(ratio ${score.volume_ratio ?? 'n/a'}). No outlier worth acting on.`),
confidence: 0.5,
};
}
// ── live fetch layer ─────────────────────────────────────────────────────────
function defaultFetchJson(timeoutMs) {
return async (url) => {
const ctrl = new AbortController();
const tid = setTimeout(() => ctrl.abort(), timeoutMs);
try {
const r = await fetch(url, {
signal: ctrl.signal,
headers: { accept: 'application/json', 'user-agent': UA },
});
if (!r.ok) return null;
return await r.json();
} catch {
return null;
} finally {
clearTimeout(tid);
}
};
}
/** Run fn over items with bounded concurrency, preserving order. */
async function mapLimit(items, limit, fn) {
const out = new Array(items.length);
let cursor = 0;
const workerCount = Math.max(1, Math.min(limit, items.length));
const workers = Array.from({ length: workerCount }, async () => {
for (;;) {
const idx = cursor++;
if (idx >= items.length) break;
out[idx] = await fn(items[idx], idx);
}
});
await Promise.all(workers);
return out;
}
/** Pull the live candidate coin set (currently-live board, newest-trade fallback). */
async function fetchCandidates(fetchJson, limit) {
const n = Math.min(100, Math.max(3, limit));
const live = await fetchJson(
`${PUMP_FRONTEND_BASE}/coins/currently-live?offset=0&limit=${n}&includeNsfw=false`,
);
let list = Array.isArray(live) ? live : Array.isArray(live?.coins) ? live.coins : [];
if (list.length < 3) {
// Fallback: most-recently-traded coins are the next-best "active" proxy.
const recent = await fetchJson(
`${PUMP_FRONTEND_BASE}/coins?offset=0&limit=${n}&sort=last_trade_timestamp&order=DESC&includeNsfw=false`,
);
const r = Array.isArray(recent) ? recent : Array.isArray(recent?.coins) ? recent.coins : [];
if (r.length > list.length) list = r;
}
return list
.filter((c) => c && c.mint)
.map((c) => ({ mint: c.mint, name: c.name || null, symbol: c.symbol || null }));
}
/**
* Detect the top pump.fun volume anomaly in the trailing window, live.
*
* @param {object} [opts] overrides for DEFAULTS, plus:
* nowMs — clock injection (defaults to Date.now())
* fetchJson — (url)=>Promise<json|null> injection for tests
* @returns {Promise<object>} full intel envelope (topic/signal/headline/.../anomaly/mint/volume_ratio)
* @throws {Error & {status:503}} when no live candidate data could be fetched (so the
* paid endpoint returns 503 BEFORE settlement and the buyer is never charged).
*/
export async function detectPumpVolumeAnomaly(opts = {}) {
const cfg = { ...DEFAULTS, ...opts };
const fetchJson = opts.fetchJson || defaultFetchJson(cfg.fetchTimeoutMs);
const nowMs = opts.nowMs ?? Date.now();
const candidates = await fetchCandidates(fetchJson, cfg.candidates);
if (!candidates.length) {
throw Object.assign(new Error('pump.fun live feed is temporarily unavailable'), {
status: 503,
code: 'data_unavailable',
});
}
const samples = await mapLimit(candidates, cfg.concurrency, async (c) => {
const body = await fetchJson(
`${PUMP_SWAP_BASE}/v2/coins/${c.mint}/trades?limit=${cfg.tradeLimit}`,
);
const trades = Array.isArray(body) ? body : Array.isArray(body?.trades) ? body.trades : [];
const { usd, count } = summarizeWindowUsd(trades, nowMs, cfg.windowSec);
return { ...c, window_usd: usd, trade_count: count };
});
// If every trade fetch failed (upstream swap-API down) we have no signal to
// sell — surface as 503 so the buyer is not charged for an empty verdict.
if (!samples.some((s) => s.trade_count > 0)) {
throw Object.assign(new Error('pump.fun trade feed is temporarily unavailable'), {
status: 503,
code: 'data_unavailable',
});
}
const score = scoreVolumeAnomaly(samples, cfg);
const sig = buildAnomalySignal(score, cfg.windowSec);
return {
topic: 'pump_volume_anomaly',
anomaly: score.anomaly,
mint: score.mint,
volume_ratio: score.volume_ratio,
token_name: score.name,
token_symbol: score.symbol,
top_window_usd: score.top_window_usd,
baseline_usd: score.baseline_usd,
window_sec: cfg.windowSec,
candidates_scanned: score.candidates,
active_coins: score.active,
signal: sig.signal,
conviction: sig.conviction,
headline: sig.headline,
rationale: sig.rationale,
confidence: sig.confidence,
ts: new Date(nowMs).toISOString(),
};
}
/**
* Lift a pump_volume_anomaly response into the x402_autonomous_log.signal_data /
* oracle_intel_signals shape. Shared by the registry entry's extractSignal so the
* autonomous log and the oracle dedup always agree. High-conviction spikes
* (anomaly && ratio > 5) are tagged so the sniper gate can prioritise them.
*/
export function classifyVolumeAnomaly(r) {
const o = r || {};
const ratio = num(o.volume_ratio);
const highConviction = o.anomaly === true && ratio != null && ratio > 5;
return {
topic: 'pump_volume_anomaly',
anomaly: o.anomaly === true,
mint: o.mint || null,
volume_ratio: ratio,
conviction: highConviction ? 'high' : o.anomaly === true ? 'normal' : 'none',
signal: typeof o.signal === 'string' ? o.signal : o.anomaly === true ? 'bullish' : 'neutral',
headline: typeof o.headline === 'string' ? o.headline : null,
// Bump confidence for high-conviction spikes so the oracle row the sniper
// reads reflects the escalation the task calls for.
confidence: highConviction
? Math.max(0.85, num(o.confidence) ?? 0)
: num(o.confidence),
token_symbol: o.token_symbol || null,
top_window_usd: num(o.top_window_usd),
baseline_usd: num(o.baseline_usd),
};
}