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.

feat(market): detect market anomalies from live sources, store them, and serve them through a cron and an x402 endpoint

nirholas35afe5904f06
diff --git a/api/_lib/market-anomaly-sources.js b/api/_lib/market-anomaly-sources.js
new file mode 100644
index 000000000..2bbea0ac0
--- /dev/null
+++ b/api/_lib/market-anomaly-sources.js
@@ -0,0 +1,97 @@
+// Real series for the market anomaly engine (api/_lib/market-anomaly.js).
+// Every loader returns ascending { t, v } points built from the same upstreams
+// the /markets pages and paid market-data endpoints run on: no sample data.
+//
+// price CoinGecko 7d hourly sparkline via fetchMarketsTable
+// tvl DeFiLlama historicalChainTvl/Solana (daily)
+// stablecoin supply DeFiLlama stablecoincharts/Solana (daily circulating USD)
+// stablecoin peg DeFiLlama stablecoins board via buildStablecoins
+// funding Hyperliquid fundingHistory per perp (hourly)
+// open interest Hyperliquid metaAndAssetCtxs snapshots, persisted by the
+// cron in market_anomaly_samples (no public history exists)
+
+import { fetchMarketsTable } from './market-fallbacks.js';
+import { fetchUpstreamJson } from './upstream-fetch.js';
+import { hlInfo, fetchHyperliquidPerps } from './hyperliquid.js';
+import { buildStablecoins } from '../defi/stablecoins.js';
+
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+const UA = { headers: { accept: 'application/json', 'user-agent': 'three.ws/1.0' } };
+
+export const SOLANA_CHAIN = 'Solana';
+/** Coins scored by the price processor (top by market cap). */
+export const PRICE_COINS = 100;
+/** Perps scored by the funding and open interest processors (top by volume). */
+export const PERP_COUNT = 20;
+const FUNDING_WINDOW_MS = 7 * DAY;
+
+/** @returns {Promise<{ subject: string, points: { t: number, v: number }[] }[]>} */
+export async function loadPriceSeries() {
+ const { rows } = await fetchMarketsTable({ page: 1, perPage: PRICE_COINS, category: '' });
+ const now = Date.now();
+ const out = [];
+ for (const r of rows) {
+ const spark = Array.isArray(r.sparkline) ? r.sparkline.filter((n) => Number.isFinite(n)) : [];
+ if (!r.id || spark.length < 2) continue;
+ // The sparkline is evenly spaced hourly samples ending now.
+ const points = spark.map((v, i) => ({ t: now - (spark.length - 1 - i) * HOUR, v }));
+ out.push({ subject: r.symbol ? String(r.symbol).toUpperCase() : r.id, points });
+ }
+ return out;
+}
+
+/** Daily Solana DeFi TVL. Drops the in-progress final day only if it is partial. */
+export async function loadSolanaTvlSeries() {
+ const raw = await fetchUpstreamJson(
+ `https://api.llama.fi/v2/historicalChainTvl/${SOLANA_CHAIN}`,
+ UA,
+ { name: 'defillama:chain-tvl', timeoutMs: 15_000, attempts: 2 },
+ );
+ if (!Array.isArray(raw)) throw new Error('unexpected chain TVL shape');
+ const points = raw
+ .map((p) => ({ t: Number(p.date) * 1000, v: Number(p.tvl) }))
+ .filter((p) => Number.isFinite(p.t) && Number.isFinite(p.v) && p.v > 0);
+ return [{ subject: SOLANA_CHAIN, points: points.slice(-120) }];
+}
+
+/** Daily Solana stablecoin circulating supply, in USD. */
+export async function loadSolanaStablecoinSupplySeries() {
+ const raw = await fetchUpstreamJson(
+ `https://stablecoins.llama.fi/stablecoincharts/${SOLANA_CHAIN}`,
+ UA,
+ { name: 'defillama:stablecoin-chart', timeoutMs: 15_000, attempts: 2 },
+ );
+ if (!Array.isArray(raw)) throw new Error('unexpected stablecoin chart shape');
+ const points = raw
+ .map((p) => ({ t: Number(p.date) * 1000, v: Number(p.totalCirculatingUSD?.peggedUSD) }))
+ .filter((p) => Number.isFinite(p.t) && Number.isFinite(p.v) && p.v > 0);
+ return [{ subject: SOLANA_CHAIN, points: points.slice(-120) }];
+}
+
+/** Current stablecoin board (price, peg type, circulating USD) for the peg check. */
+export async function loadStablecoinBoard() {
+ const board = await buildStablecoins();
+ return board.stablecoins;
+}
+
+/** Top perps by 24h volume with their current mark price and USD open interest. */
+export async function loadPerpSnapshot() {
+ const rows = await fetchHyperliquidPerps();
+ return rows.slice(0, PERP_COUNT).map((r) => ({
+ coin: r.index_id,
+ symbol: r.symbol,
+ funding_rate_8h_pct: r.funding_rate,
+ open_interest_usd: r.open_interest,
+ }));
+}
+
+/** Hourly funding history (8h-equivalent percent) for one perp over the last 7 days. */
+export async function loadFundingSeries(coin) {
+ const rows = await hlInfo({ type: 'fundingHistory', coin, startTime: Date.now() - FUNDING_WINDOW_MS });
+ if (!Array.isArray(rows)) throw new Error('unexpected fundingHistory shape');
+ const points = rows
+ .map((r) => ({ t: Number(r.time), v: Number(r.fundingRate) * 8 * 100 }))
+ .filter((p) => Number.isFinite(p.t) && Number.isFinite(p.v));
+ return { subject: `${coin}-USD`, points };
+}
diff --git a/api/_lib/market-anomaly-store.js b/api/_lib/market-anomaly-store.js
new file mode 100644
index 000000000..4381b5810
--- /dev/null
+++ b/api/_lib/market-anomaly-store.js
@@ -0,0 +1,50 @@
+// Read side of the market anomaly feed: recent rows from market_anomaly_events,
+// shaped for the paid /api/x402/market-anomalies endpoint and the market_anomaly
+// alert rules. The write side is api/cron/market-anomalies.js.
+
+import { sql } from './db.js';
+import { PROCESSORS, SEVERITIES } from './market-anomaly.js';
+
+const SEVERITY_FLOOR = Object.freeze({
+ medium: ['medium', 'high', 'critical'],
+ high: ['high', 'critical'],
+ critical: ['critical'],
+});
+
+export function shapeEvent(r) {
+ return {
+ id: Number(r.id),
+ processor: r.processor,
+ subject: r.subject,
+ metric: r.metric,
+ severity: r.severity,
+ direction: r.direction,
+ value: r.value != null ? Number(r.value) : null,
+ baseline: r.baseline != null ? Number(r.baseline) : null,
+ change_pct: r.change_pct != null ? Number(r.change_pct) : null,
+ score: r.score != null ? Number(r.score) : null,
+ detectors: Array.isArray(r.detectors) ? r.detectors : [],
+ summary: r.summary,
+ observed_at: new Date(r.observed_at).toISOString(),
+ };
+}
+
+/**
+ * @param {{ processor?: string, processors?: string[], severity?: string, subject?: string, hours?: number, limit?: number, sinceId?: number }} q
+ */
+export async function queryMarketAnomalies({ processor = '', processors = null, severity = 'medium', subject = '', hours = 24, limit = 50, sinceId = 0 } = {}) {
+ const procs = processors?.length ? processors : processor ? [processor] : null;
+ const rows = await sql`
+ select id, processor, subject, metric, severity, direction, value, baseline, change_pct, score, detectors, summary, observed_at
+ from market_anomaly_events
+ where created_at > now() - make_interval(hours => ${hours})
+ and id > ${sinceId}
+ and severity = any(${SEVERITY_FLOOR[severity] || SEVERITY_FLOOR.medium}::text[])
+ and (${procs}::text[] is null or processor = any(${procs}::text[]))
+ and (${subject} = '' or lower(subject) = lower(${subject}))
+ order by id desc
+ limit ${limit}
+ `;
+ const events = rows.map(shapeEvent);
+ return { events, count: events.length, hours, min_severity: severity, processors: [...PROCESSORS], severities: [...SEVERITIES] };
+}
diff --git a/api/_lib/market-anomaly.js b/api/_lib/market-anomaly.js
new file mode 100644
index 000000000..da902a2da
--- /dev/null
+++ b/api/_lib/market-anomaly.js
@@ -0,0 +1,317 @@
+// Market anomaly detection: the pure engine. No DB, no network, no env, so every
+// verdict is a deterministic function of the series it is handed and can be
+// unit-tested on recorded data (tests/market-anomaly.test.js).
+//
+// This is the market-side sibling of api/_lib/wallet-anomaly.js (which scores a
+// single agent's outbound spend). Three statistical detectors run over a time
+// series, and a processor turns their agreement into a labelled anomaly:
+//
+// modified z-score median/MAD based (Iglewicz-Hoaglin), robust to the very
+// outliers it is hunting; flags |M| >= 3.5
+// EWMA deviation exponentially weighted mean and variance, so a series
+// that has been drifting is judged against its recent
+// regime rather than its whole history
+// rate of change plain percent move over the window, the magnitude gate
+// that keeps a statistically odd but economically tiny
+// wiggle (a stablecoin supply moving 0.01%) from firing
+//
+// A processor fires when a statistical detector AND the magnitude gate agree.
+// Sparse series are refused with a reason instead of scored (a z-score over six
+// points is noise): see MIN_POINTS and the `skipped` result.
+//
+// Series are ascending arrays of { t: epoch ms, v: number }. Fetching them is
+// api/_lib/market-anomaly-sources.js; persisting events is
+// api/cron/market-anomalies.js.
+
+export const MODIFIED_Z_THRESHOLD = 3.5;
+export const EWMA_Z_THRESHOLD = 3;
+export const EWMA_LAMBDA = 0.2;
+const MAD_SCALE = 0.6745;
+const MEAN_AD_SCALE = 1.253314;
+/** Fewest history observations a z-score may be computed over. */
+export const MIN_POINTS = 24;
+
+export const SEVERITIES = Object.freeze(['medium', 'high', 'critical']);
+const SEVERITY_RANK = Object.freeze({ medium: 1, high: 2, critical: 3 });
+
+export const PROCESSORS = Object.freeze(['price', 'tvl', 'stablecoin_supply', 'stablecoin_peg', 'funding', 'open_interest']);
+
+/** @param {number} severity @param {string} min */
+export function meetsSeverity(severity, min) {
+ return (SEVERITY_RANK[severity] || 0) >= (SEVERITY_RANK[min] || 0);
+}
+
+const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+
+export function median(values) {
+ if (!values.length) return NaN;
+ const s = [...values].sort((a, b) => a - b);
+ const mid = s.length >> 1;
+ return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+
+/**
+ * Modified z-score of `x` against `history`. Falls back to the mean absolute
+ * deviation when more than half the history is identical (MAD = 0), the case
+ * for a flat series. Returns null when the history has no spread at all, since
+ * any deviation from a constant is infinitely surprising and not a usable score.
+ * @param {number[]} history
+ * @param {number} x
+ * @returns {{ score: number, median: number, spread: number } | null}
+ */
+export function modifiedZScore(history, x) {
+ const h = history.filter(finite);
+ if (h.length < 2 || !finite(x)) return null;
+ const med = median(h);
+ const mad = median(h.map((v) => Math.abs(v - med)));
+ if (mad > 0) return { score: (MAD_SCALE * (x - med)) / mad, median: med, spread: mad / MAD_SCALE };
+ const meanAd = h.reduce((a, v) => a + Math.abs(v - med), 0) / h.length;
+ if (meanAd > 0) return { score: (x - med) / (MEAN_AD_SCALE * meanAd), median: med, spread: MEAN_AD_SCALE * meanAd };
+ return null;
+}
+
+/**
+ * Deviation of `x` from the exponentially weighted mean of `history`, in units
+ * of the exponentially weighted standard deviation.
+ * @param {number[]} history
+ * @param {number} x
+ * @param {number} [lambda] weight on the newest observation, 0 to 1
+ * @returns {{ score: number, mean: number, sigma: number } | null}
+ */
+export function ewmaDeviation(history, x, lambda = EWMA_LAMBDA) {
+ const h = history.filter(finite);
+ if (h.length < 2 || !finite(x)) return null;
+ let mean = h[0];
+ let variance = 0;
+ for (let i = 1; i < h.length; i++) {
+ const d = h[i] - mean;
+ mean += lambda * d;
+ variance = (1 - lambda) * (variance + lambda * d * d);
+ }
+ const sigma = Math.sqrt(variance);
+ if (!(sigma > 0)) return null;
+ return { score: (x - mean) / sigma, mean, sigma };
+}
+
+/** Percent change from `prev` to `now`; null when `prev` is not a positive base. */
+export function rateOfChange(prev, now) {
+ if (!finite(prev) || !finite(now) || prev <= 0) return null;
+ return ((now - prev) / prev) * 100;
+}
+
+/**
+ * Severity from the strongest statistical score and the size of the move.
+ * Both must clear their rung; the lower of the two decides, so a huge z on a
+ * 1% move stays "medium".
+ */
+export function classify(absScore, absChangePct, gates) {
+ const [mid, hi, crit] = gates;
+ const byScore = absScore >= 8 ? 3 : absScore >= 5 ? 2 : 1;
+ const byMove = absChangePct >= crit ? 3 : absChangePct >= hi ? 2 : absChangePct >= mid ? 1 : 0;
+ const rank = Math.min(byScore, byMove);
+ return rank >= 3 ? 'critical' : rank === 2 ? 'high' : rank === 1 ? 'medium' : null;
+}
+
+/**
+ * Rolling `lookback`-step returns of a series, in percent, newest last.
+ * @param {{ t: number, v: number }[]} points
+ * @param {number} lookback
+ */
+export function windowReturns(points, lookback) {
+ const out = [];
+ for (let i = lookback; i < points.length; i++) {
+ const r = rateOfChange(points[i - lookback].v, points[i].v);
+ if (r != null) out.push({ t: points[i].t, r });
+ }
+ return out;
+}
+
+/**
+ * @typedef {Object} SeriesSpec
+ * @property {string} processor one of PROCESSORS
+ * @property {string} subject what the series describes (coin id, chain, symbol)
+ * @property {string} metric human metric name
+ * @property {'returns'|'levels'} mode score the window return, or the level itself
+ * @property {number} [lookback] steps per return window (returns mode)
+ * @property {number} minChangePct magnitude gate: smallest |move| (returns) or |level| (levels)
+ * @property {[number, number, number]} severityGates |move| rungs for medium, high, critical
+ * @property {number} bucketMs dedupe bucket: one event per series per bucket
+ * @property {number} [minPoints]
+ * @property {string} [unit] 'pct' for percent-valued levels, else ''
+ */
+
+/**
+ * Run the detectors over one series.
+ * @param {SeriesSpec} spec
+ * @param {{ t: number, v: number }[]} rawPoints ascending
+ * @returns {{ anomaly: object } | { skipped: string, have: number, need: number } | { anomaly: null }}
+ */
+export function detectSeries(spec, rawPoints) {
+ const points = rawPoints.filter((p) => p && finite(p.t) && finite(p.v)).sort((a, b) => a.t - b.t);
+ const lookback = spec.mode === 'returns' ? Math.max(1, spec.lookback || 1) : 0;
+ const need = (spec.minPoints ?? MIN_POINTS) + lookback + 1;
+ if (points.length < need) {
+ return { skipped: 'insufficient_history', have: points.length, need };
+ }
+
+ let history;
+ let x;
+ let changePct;
+ let baselineLevel;
+ if (spec.mode === 'returns') {
+ const rets = windowReturns(points, lookback);
+ if (rets.length < (spec.minPoints ?? MIN_POINTS) + 1) {
+ return { skipped: 'insufficient_history', have: rets.length, need: (spec.minPoints ?? MIN_POINTS) + 1 };
+ }
+ x = rets[rets.length - 1].r;
+ history = rets.slice(0, -1).map((p) => p.r);
+ changePct = x;
+ baselineLevel = points[points.length - 1 - lookback].v;
+ } else {
+ x = points[points.length - 1].v;
+ history = points.slice(0, -1).map((p) => p.v);
+ changePct = null;
+ baselineLevel = median(history);
+ }
+
+ const mz = modifiedZScore(history, x);
+ const ew = ewmaDeviation(history, x);
+ if (!mz && !ew) return { skipped: 'flat_history', have: points.length, need };
+
+ const magnitude = spec.mode === 'returns' ? Math.abs(changePct) : Math.abs(x);
+ if (magnitude < spec.minChangePct) return { anomaly: null };
+
+ const mzHit = mz && Math.abs(mz.score) >= MODIFIED_Z_THRESHOLD;
+ const ewHit = ew && Math.abs(ew.score) >= EWMA_Z_THRESHOLD;
+ if (!mzHit && !ewHit) return { anomaly: null };
+
+ const score = Math.max(mzHit ? Math.abs(mz.score) : 0, ewHit ? Math.abs(ew.score) : 0);
+ const signed = (mzHit ? mz.score : ew.score) ?? 0;
+ const severity = classify(score, magnitude, spec.severityGates);
+ if (!severity) return { anomaly: null };
+
+ const last = points[points.length - 1];
+ return {
+ anomaly: {
+ processor: spec.processor,
+ subject: spec.subject,
+ metric: spec.metric,
+ severity,
+ direction: (spec.mode === 'returns' ? changePct : signed) >= 0 ? 'up' : 'down',
+ value: last.v,
+ baseline: baselineLevel,
+ change_pct: round(changePct ?? x - baselineLevel, 3),
+ score: round(score, 2),
+ detectors: [mzHit && 'modified_z', ewHit && 'ewma', 'rate_of_change'].filter(Boolean),
+ observed_at: new Date(last.t).toISOString(),
+ event_key: `${spec.processor}:${spec.subject}:${spec.metric}:${Math.floor(last.t / spec.bucketMs)}`,
+ summary: summarize(spec, last.v, baselineLevel, changePct, x),
+ },
+ };
+}
+
+function round(n, dp) {
+ const f = 10 ** dp;
+ return Math.round(n * f) / f;
+}
+
+const compact = (n) => {
+ const a = Math.abs(n);
+ if (a >= 1e9) return `${(n / 1e9).toFixed(2)}B`;
+ if (a >= 1e6) return `${(n / 1e6).toFixed(2)}M`;
+ if (a >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+ return a >= 1 ? n.toFixed(2) : n.toPrecision(3);
+};
+
+function summarize(spec, value, baseline, changePct, level) {
+ if (spec.mode === 'returns') {
+ const dir = changePct >= 0 ? 'rose' : 'fell';
+ return `${spec.subject} ${spec.metric} ${dir} ${Math.abs(changePct).toFixed(2)}% over the last ${spec.windowLabel || 'window'}, to ${compact(value)} (from ${compact(baseline)})`;
+ }
+ return `${spec.subject} ${spec.metric} at ${level.toFixed(4)}${spec.unit === 'pct' ? '%' : ''} against a typical ${baseline.toFixed(4)}${spec.unit === 'pct' ? '%' : ''}`;
+}
+
+// ── Processors: one per data source, each pure over the series it is given ──
+
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+
+/** Hourly coin price series (CoinGecko 7d sparkline, 168 points). */
+export const PRICE_SPEC = Object.freeze({
+ processor: 'price', metric: 'price', mode: 'returns', lookback: 4, windowLabel: '4 hours',
+ minChangePct: 4, severityGates: [4, 8, 15], bucketMs: 6 * HOUR,
+});
+/** Daily Solana DeFi TVL. */
+export const TVL_SPEC = Object.freeze({
+ processor: 'tvl', metric: 'TVL', mode: 'returns', lookback: 1, windowLabel: 'day',
+ minChangePct: 5, severityGates: [5, 10, 20], bucketMs: DAY,
+});
+/** Daily Solana stablecoin circulating supply. */
+export const STABLE_SUPPLY_SPEC = Object.freeze({
+ processor: 'stablecoin_supply', metric: 'stablecoin supply', mode: 'returns', lookback: 1, windowLabel: 'day',
+ minChangePct: 1.5, severityGates: [1.5, 4, 8], bucketMs: DAY,
+});
+/** Hourly perp funding, as the 8h-equivalent percent (api/_lib/hyperliquid.js units). */
+export const FUNDING_SPEC = Object.freeze({
+ processor: 'funding', metric: 'funding rate (8h)', mode: 'levels', unit: 'pct',
+ minChangePct: 0.05, severityGates: [0.05, 0.1, 0.25], bucketMs: 8 * HOUR,
+});
+/** Open interest snapshots written by the cron itself. */
+export const OPEN_INTEREST_SPEC = Object.freeze({
+ processor: 'open_interest', metric: 'open interest', mode: 'returns', lookback: 4, windowLabel: 'hour',
+ minChangePct: 10, severityGates: [10, 20, 40], bucketMs: 4 * HOUR,
+});
+
+/**
+ * Stablecoin peg check: a point-in-time price has no series, so this is a plain
+ * threshold on |price - 1|, severity by depth. Only USD-pegged assets with real
+ * float are judged; a thin experimental coin trading at $0.97 is not news.
+ * @param {{ symbol: string, price: number|null, peg_type: string|null, circulating_usd: number }} coin
+ * @param {number} [now]
+ */
+export const PEG_MIN_CIRCULATING_USD = 10_000_000;
+export function detectPegDeviation(coin, now = Date.now()) {
+ if (!coin || coin.peg_type !== 'peggedUSD' || !finite(coin.price) || coin.price <= 0) return null;
+ if (!(coin.circulating_usd >= PEG_MIN_CIRCULATING_USD)) return null;
+ const devPct = (coin.price - 1) * 100;
+ const abs = Math.abs(devPct);
+ const severity = abs >= 3 ? 'critical' : abs >= 1 ? 'high' : abs >= 0.5 ? 'medium' : null;
+ if (!severity) return null;
+ const bucketMs = 12 * HOUR;
+ return {
+ processor: 'stablecoin_peg',
+ subject: coin.symbol,
+ metric: 'peg',
+ severity,
+ direction: devPct >= 0 ? 'up' : 'down',
+ value: coin.price,
+ baseline: 1,
+ change_pct: round(devPct, 3),
+ score: round(abs, 2),
+ detectors: ['peg_threshold'],
+ observed_at: new Date(now).toISOString(),
+ event_key: `stablecoin_peg:${coin.symbol}:peg:${Math.floor(now / bucketMs)}`,
+ summary: `${coin.symbol} is trading at $${coin.price.toFixed(4)}, ${abs.toFixed(2)}% ${devPct < 0 ? 'below' : 'above'} its $1 peg`,
+ };
+}
+
+/**
+ * Run a spec over many subjects' series. Returns the anomalies and a skip log
+ * (one entry per series refused as too sparse or flat) so a thin source is
+ * visible rather than silently scoring nothing.
+ * @param {SeriesSpec} spec spec without a subject
+ * @param {{ subject: string, points: { t: number, v: number }[] }[]} seriesList
+ */
+export function detectMany(spec, seriesList) {
+ const anomalies = [];
+ const skipped = [];
+ for (const s of seriesList) {
+ const r = detectSeries({ ...spec, subject: s.subject }, s.points);
+ if ('anomaly' in r) {
+ if (r.anomaly) anomalies.push(r.anomaly);
+ } else {
+ skipped.push({ processor: spec.processor, subject: s.subject, reason: r.skipped, have: r.have, need: r.need });
+ }
+ }
+ return { anomalies, skipped };
+}
diff --git a/api/cron/market-anomalies.js b/api/cron/market-anomalies.js
new file mode 100644
index 000000000..1ebb8249a
--- /dev/null
+++ b/api/cron/market-anomalies.js
@@ -0,0 +1,181 @@
+// GET /api/cron/market-anomalies: scan live market series for anomalies and
+// write them to market_anomaly_events.
+//
+// Runs every 15 minutes. Each processor loads its real series (see
+// api/_lib/market-anomaly-sources.js), the detectors in api/_lib/market-anomaly.js
+// score it, and new events are inserted with ON CONFLICT DO NOTHING on the
+// event_key time bucket, so a persisting condition writes once per bucket. A
+// processor whose source is down is reported in `errors` and never blocks the
+// others; a series too short or flat to score is reported in `skipped` with the
+// reason. Perp open interest has no public history, so every tick also appends a
+// snapshot to market_anomaly_samples and that accumulated series is what the
+// open_interest processor scores. Events feed the paid /api/x402/market-anomalies
+// endpoint and the market_anomaly alert rules (api/_lib/pump-alert-runner.js).
+// Docs: docs/market-anomalies.md.
+
+import { json, wrapCron, method } from '../_lib/http.js';
+import { requireCron } from '../_lib/cron-auth.js';
+import { sql } from '../_lib/db.js';
+import {
+ PROCESSORS,
+ PRICE_SPEC,
+ TVL_SPEC,
+ STABLE_SUPPLY_SPEC,
+ FUNDING_SPEC,
+ OPEN_INTEREST_SPEC,
+ detectMany,
+ detectPegDeviation,
+} from '../_lib/market-anomaly.js';
+import {
+ loadPriceSeries,
+ loadSolanaTvlSeries,
+ loadSolanaStablecoinSupplySeries,
+ loadStablecoinBoard,
+ loadPerpSnapshot,
+ loadFundingSeries,
+} from '../_lib/market-anomaly-sources.js';
+
+const SAMPLE_RETENTION = '14 days';
+const OI_METRIC = 'open_interest_usd';
+const OI_HISTORY_LIMIT = 400;
+const CONCURRENCY = 6;
+
+async function pool(items, fn) {
+ const out = new Array(items.length);
+ let next = 0;
+ await Promise.all(
+ Array.from({ length: Math.min(CONCURRENCY, items.length) }, async () => {
+ while (next < items.length) {
+ const i = next++;
+ out[i] = await fn(items[i]);
+ }
+ }),
+ );
+ return out;
+}
+
+/** Append this tick's OI snapshot and return each perp's accumulated series. */
+async function openInterestSeries(perps) {
+ const live = perps.filter((p) => Number.isFinite(p.open_interest_usd) && p.open_interest_usd > 0);
+ for (const p of live) {
+ await sql`
+ insert into market_anomaly_samples (metric, subject, value)
+ values (${OI_METRIC}, ${p.symbol}, ${p.open_interest_usd})
+ on conflict do nothing
+ `;
+ }
+ await sql`delete from market_anomaly_samples where sampled_at < now() - ${SAMPLE_RETENTION}::interval`;
+ return pool(live, async (p) => {
+ const rows = await sql`
+ select extract(epoch from sampled_at) * 1000 as t, value
+ from market_anomaly_samples
+ where metric = ${OI_METRIC} and subject = ${p.symbol}
+ order by sampled_at desc
+ limit ${OI_HISTORY_LIMIT}
+ `;
+ return {
+ subject: p.symbol,
+ points: rows.reverse().map((r) => ({ t: Number(r.t), v: Number(r.value) })),
+ };
+ });
+}
+
+/**
+ * Run every processor once. Returns the anomalies found plus per-processor
+ * skip and error logs; persistence is the caller's step.
+ */
+export async function scanMarkets() {
+ const anomalies = [];
+ const skipped = [];
+ const errors = [];
+ const stats = {};
+
+ const run = async (name, fn) => {
+ try {
+ const r = await fn();
+ stats[name] = r.scored;
+ anomalies.push(...r.anomalies);
+ skipped.push(...(r.skipped || []));
+ } catch (err) {
+ errors.push({ processor: name, error: err?.message || String(err) });
+ }
+ };
+
+ const series = (spec) => async (load) => {
+ const list = await load();
+ const r = detectMany(spec, list);
+ return { scored: list.length - r.skipped.length, ...r };
+ };
+
+ await Promise.all([
+ run('price', async () => series(PRICE_SPEC)(loadPriceSeries)),
+ run('tvl', async () => series(TVL_SPEC)(loadSolanaTvlSeries)),
+ run('stablecoin_supply', async () => series(STABLE_SUPPLY_SPEC)(loadSolanaStablecoinSupplySeries)),
+ run('stablecoin_peg', async () => {
+ const board = await loadStablecoinBoard();
+ const found = board.map((c) => detectPegDeviation(c)).filter(Boolean);
+ return { scored: board.length, anomalies: found };
+ }),
+ run('funding', async () => {
+ const perps = await loadPerpSnapshot();
+ const list = (await pool(perps, async (p) => {
+ try {
+ return await loadFundingSeries(p.coin);
+ } catch {
+ return null;
+ }
+ })).filter(Boolean);
+ if (!list.length) throw new Error('no funding history returned');
+ const r = detectMany(FUNDING_SPEC, list);
+ return { scored: list.length - r.skipped.length, ...r };
+ }),
+ run('open_interest', async () => {
+ const perps = await loadPerpSnapshot();
+ const list = await openInterestSeries(perps);
+ const r = detectMany(OPEN_INTEREST_SPEC, list);
+ return { scored: list.length - r.skipped.length, ...r };
+ }),
+ ]);
+
+ return { anomalies, skipped, errors, stats };
+}
+
+/** Insert new events; returns the rows that were actually new. */
+export async function persistAnomalies(anomalies) {
+ const fresh = [];
+ for (const a of anomalies) {
+ const [row] = await sql`
+ insert into market_anomaly_events
+ (event_key, processor, subject, metric, severity, direction, value, baseline, change_pct, score, detectors, summary, observed_at)
+ values
+ (${a.event_key}, ${a.processor}, ${a.subject}, ${a.metric}, ${a.severity}, ${a.direction}, ${a.value}, ${a.baseline},
+ ${a.change_pct}, ${a.score}, ${JSON.stringify(a.detectors)}::jsonb, ${a.summary}, ${a.observed_at})
+ on conflict (event_key) do nothing
+ returning id
+ `;
+ if (row) fresh.push({ ...a, id: Number(row.id) });
+ }
+ return fresh;
+}
+
+export default wrapCron(async (req, res) => {
+ if (!method(req, res, ['GET', 'POST'])) return;
+ if (!requireCron(req, res)) return;
+
+ const scan = await scanMarkets();
+ const fresh = await persistAnomalies(scan.anomalies);
+
+ for (const s of scan.skipped) {
+ console.warn(`[market-anomalies] skip ${s.processor}/${s.subject}: ${s.reason} (have ${s.have}, need ${s.need})`);
+ }
+ return json(res, 200, {
+ ok: scan.errors.length < PROCESSORS.length,
+ scored: scan.stats,
+ detected: scan.anomalies.length,
+ written: fresh.length,
+ events: fresh,
+ skipped: scan.skipped.length,
+ skipped_detail: scan.skipped.slice(0, 50),
+ errors: scan.errors,
+ });
+});
diff --git a/api/x402/market-anomalies.js b/api/x402/market-anomalies.js
new file mode 100644
index 000000000..6b1b5d38e
--- /dev/null
+++ b/api/x402/market-anomalies.js
@@ -0,0 +1,6 @@
+// GET /api/x402/market-anomalies, paid Market Data API (x402, USDC on Solana/Base).
+// Thin route shell: the category registry + shared factory in
+// api/_lib/market-data/ define the price, discovery listing, and handler.
+import { marketEndpoint } from '../_lib/market-data/endpoint.js';
+
+export default marketEndpoint('market-anomalies');
diff --git a/tests/fixtures/market-anomaly/hyperliquid-sol-funding-hourly.json b/tests/fixtures/market-anomaly/hyperliquid-sol-funding-hourly.json
new file mode 100644
index 000000000..18200c51b
--- /dev/null
+++ b/tests/fixtures/market-anomaly/hyperliquid-sol-funding-hourly.json
@@ -0,0 +1 @@
+[{"t":1792188000007,"v":0.00674696},{"t":1792191600029,"v":0.0053494400000000004},{"t":1792195200116,"v":-0.00023232},{"t":1792198800083,"v":0.0033649599999999997},{"t":1792202400105,"v":-0.00239504},{"t":1792206000080,"v":-0.00222136},{"t":1792209600067,"v":0.00221088},{"t":1792213200014,"v":0.00295672},{"t":1792216800053,"v":0.00359448},{"t":1792220400018,"v":0.00129456},{"t":1792224000014,"v":0.00776616},{"t":1792227600055,"v":0.01},{"t":1792231200000,"v":0.01},{"t":1792234800052,"v":0.0073948},{"t":1792238400072,"v":0.00576424},{"t":1792242000055,"v":-0.00302712},{"t":1792245600046,"v":-0.00579992},{"t":1792249200046,"v":-0.00470784},{"t":1792252800013,"v":-0.0037057600000000002},{"t":1792256400036,"v":-0.0115036},{"t":1792260000069,"v":-0.00151224},{"t":1792263600008,"v":-0.00289216},{"t":1792267200059,"v":-0.0019279999999999998},{"t":1792270800000,"v":0.00068512},{"t":1792274400003,"v":-8.824e-05},{"t":1792278000018,"v":-0.00798616},{"t":1792281600074,"v":-0.00812176},{"t":1792285200060,"v":0.004166319999999999},{"t":1792288800034,"v":0.006535839999999999},{"t":1792292400034,"v":0.00475128},{"t":1792296000020,"v":-0.00031776},{"t":1792299600040,"v":0.00453384},{"t":1792303200025,"v":0.0017456799999999999},{"t":1792306800035,"v":-0.00141888},{"t":1792310400065,"v":0.0014548},{"t":1792314000068,"v":-0.00374024},{"t":1792317600044,"v":0.0037323200000000003},{"t":1792321200036,"v":0.00630616},{"t":1792324800019,"v":-0.00424544},{"t":1792328400028,"v":-0.007046320000000001},{"t":1792332000030,"v":-0.0112064},{"t":1792335600015,"v":-0.01507872},{"t":1792339200062,"v":-0.01146048},{"t":1792342800037,"v":-0.0075864800000000005},{"t":1792346400003,"v":-0.01156296},{"t":1792350000036,"v":-0.00641448},{"t":1792353600021,"v":-0.0127112},{"t":1792357200000,"v":-0.00244632},{"t":1792360800059,"v":0.00608368},{"t":1792364400013,"v":0.01},{"t":1792368000123,"v":0.00904208},{"t":1792371600050,"v":0.0007470399999999999},{"t":1792375200013,"v":-0.00237128},{"t":1792378800019,"v":-0.00768016},{"t":1792382400031,"v":-0.0019761600000000002},{"t":1792386000034,"v":0.0038476799999999996},{"t":1792389600028,"v":0.0020849600000000003},{"t":1792393200025,"v":0.00336576},{"t":1792396800057,"v":0.0017824000000000002},{"t":1792400400052,"v":-0.00467288},{"t":1792404000055,"v":0.0025104800000000003},{"t":1792407600029,"v":0.00259336},{"t":1792411200078,"v":0.0009884800000000001},{"t":1792414800001,"v":0.00814016},{"t":1792418400035,"v":0.00636312},{"t":1792422000075,"v":0.00585288},{"t":1792425600048,"v":0.0039064},{"t":1792429200059,"v":0.005603599999999999},{"t":1792432800139,"v":0.00329264},{"t":1792436400047,"v":0.01},{"t":1792440000021,"v":0.01},{"t":1792443600032,"v":0.0007459999999999999},{"t":1792447200044,"v":0.0058187199999999994},{"t":1792450800035,"v":0.01},{"t":1792454400021,"v":0.008544},{"t":1792458000051,"v":0.00366248},{"t":1792461600017,"v":0.00368296},{"t":1792465200036,"v":0.0090352},{"t":1792468800083,"v":0.01},{"t":1792472400019,"v":0.01},{"t":1792476000082,"v":0.007691440000000001},{"t":1792479600040,"v":0.01},{"t":1792483200015,"v":0.0063928000000000006},{"t":1792486800015,"v":0.003252},{"t":1792490400080,"v":-0.00081024},{"t":1792494000005,"v":0.00139736},{"t":1792497600028,"v":0.00080048},{"t":1792501200005,"v":0.0030029600000000003},{"t":1792504800017,"v":0.005381680000000001},{"t":1792508400072,"v":0.01},{"t":1792512000127,"v":0.008104400000000001},{"t":1792515600064,"v":0.00164656},{"t":1792519200003,"v":0.0067612},{"t":1792522800023,"v":0.0041432},{"t":1792526400056,"v":0.00589048},{"t":1792530000025,"v":0.01},{"t":1792533600036,"v":0.008795599999999999},{"t":1792537200033,"v":0.01},{"t":1792540800018,"v":0.01},{"t":1792544400010,"v":0.01},{"t":1792548000038,"v":0.01},{"t":1792551600024,"v":0.01},{"t":1792555200001,"v":0.00451928},{"t":1792558800062,"v":0.00596},{"t":1792562400060,"v":0.00827488},{"t":1792566000039,"v":0.01},{"t":1792569600060,"v":0.01},{"t":1792573200065,"v":0.01},{"t":1792576800031,"v":0.01},{"t":1792580400014,"v":0.007127280000000001},{"t":1792584000021,"v":0.01},{"t":1792587600016,"v":0.00934184},{"t":1792591200024,"v":0.01},{"t":1792594800018,"v":0.00805008},{"t":1792598400016,"v":0.01},{"t":1792602000015,"v":0.01},{"t":1792605600062,"v":0.01},{"t":1792609200034,"v":0.01},{"t":1792612800043,"v":0.01},{"t":1792616400039,"v":0.01},{"t":1792620000057,"v":0.01},{"t":1792623600055,"v":0.01},{"t":1792627200022,"v":0.01},{"t":1792630800071,"v":0.01},{"t":1792634400025,"v":0.01},{"t":1792638000000,"v":0.01},{"t":1792641600024,"v":0.01},{"t":1792645200026,"v":0.01},{"t":1792648800004,"v":0.01},{"t":1792652400006,"v":0.0066901600000000006},{"t":1792656000035,"v":0.0077214399999999996},{"t":1792659600028,"v":0.00595024},{"t":1792663200098,"v":0.01},{"t":1792666800022,"v":0.00813968},{"t":1792670400026,"v":0.00626128},{"t":1792674000048,"v":0.01},{"t":1792677600081,"v":0.01},{"t":1792681200049,"v":0.01},{"t":1792684800017,"v":0.01},{"t":1792688400041,"v":0.01},{"t":1792692000027,"v":0.01},{"t":1792695600054,"v":0.00865992},{"t":1792699200015,"v":0.01},{"t":1792702800004,"v":0.01},{"t":1792706400037,"v":0.00637704},{"t":1792710000057,"v":0.01},{"t":1792713600026,"v":0.01},{"t":1792717200073,"v":0.01},{"t":1792720800013,"v":0.01},{"t":1792724400035,"v":0.01},{"t":1792728000043,"v":0.01},{"t":1792731600003,"v":0.008742399999999999},{"t":1792735200053,"v":0.01},{"t":1792738800023,"v":0.01},{"t":1792742400057,"v":0.01},{"t":1792746000030,"v":0.01},{"t":1792749600058,"v":0.01},{"t":1792753200089,"v":0.01},{"t":1792756800048,"v":0.01},{"t":1792760400012,"v":0.01},{"t":1792764000008,"v":0.01},{"t":1792767600007,"v":0.01},{"t":1792771200055,"v":0.01},{"t":1792774800042,"v":0.01},{"t":1792778400045,"v":0.01},{"t":1792782000001,"v":0.01},{"t":1792785600059,"v":0.01},{"t":1792789200075,"v":0.01}]
\ No newline at end of file
diff --git a/tests/fixtures/market-anomaly/solana-stablecoin-supply-daily.json b/tests/fixtures/market-anomaly/solana-stablecoin-supply-daily.json
new file mode 100644
index 000000000..40278f7f3
--- /dev/null
+++ b/tests/fixtures/market-anomaly/solana-stablecoin-supply-daily.json
@@ -0,0 +1 @@
+[{"t":1784160000000,"v":14565335399},{"t":1784246400000,"v":14983766735},{"t":1784332800000,"v":15282191941},{"t":1784419200000,"v":15341658425},{"t":1784505600000,"v":15365130397},{"t":1784592000000,"v":15435479088},{"t":1784678400000,"v":15510263523},{"t":1784764800000,"v":16503700180},{"t":1784851200000,"v":16564604620},{"t":1784937600000,"v":16685114633},{"t":1785024000000,"v":16609589298},{"t":1785110400000,"v":16526340001},{"t":1785196800000,"v":15699289893},{"t":1785283200000,"v":15875126471},{"t":1785369600000,"v":15938854390},{"t":1785456000000,"v":15944611215},{"t":1785542400000,"v":15943037152},{"t":1785628800000,"v":15883936508},{"t":1785715200000,"v":15825899387},{"t":1785801600000,"v":16007538847},{"t":1785888000000,"v":16151473139},{"t":1785974400000,"v":15803765288},{"t":1786060800000,"v":15854797288},{"t":1786147200000,"v":15826164475},{"t":1786233600000,"v":15850167750},{"t":1786320000000,"v":15903521059},{"t":1786406400000,"v":15909321230},{"t":1786492800000,"v":15833014068},{"t":1786579200000,"v":15698762918},{"t":1786665600000,"v":15681431198},{"t":1786752000000,"v":15589205203},{"t":1786838400000,"v":15581202657},{"t":1786924800000,"v":15587186061},{"t":1787011200000,"v":15584589371},{"t":1787097600000,"v":15601634101},{"t":1787184000000,"v":15914726165},{"t":1787270400000,"v":16068169914},{"t":1787356800000,"v":15945752545},{"t":1787443200000,"v":15963115185},{"t":1787529600000,"v":16032731227},{"t":1787616000000,"v":16012940976},{"t":1787702400000,"v":15904450927},{"t":1787788800000,"v":15904848844},{"t":1787875200000,"v":15999717648},{"t":1787961600000,"v":15904527313},{"t":1788048000000,"v":15782661052},{"t":1788134400000,"v":15789289481},{"t":1788220800000,"v":15686058383},{"t":1788307200000,"v":15605359215},{"t":1788393600000,"v":15909970836},{"t":1788480000000,"v":16382323585},{"t":1788566400000,"v":16360001919},{"t":1788652800000,"v":16437610137},{"t":1788739200000,"v":16494800917},{"t":1788825600000,"v":16449747241},{"t":1788912000000,"v":16385444133},{"t":1788998400000,"v":16361323156},{"t":1789084800000,"v":16113543219},{"t":1789171200000,"v":16355562290},{"t":1789257600000,"v":16276423589},{"t":1789344000000,"v":16108787035},{"t":1789430400000,"v":16144916817},{"t":1789516800000,"v":15717620063},{"t":1789603200000,"v":15523951393},{"t":1789689600000,"v":15467288008},{"t":1789776000000,"v":15628402795},{"t":1789862400000,"v":15562235727},{"t":1789948800000,"v":15665125007},{"t":1790035200000,"v":16930708420},{"t":1790121600000,"v":16639055433},{"t":1790208000000,"v":16184101483},{"t":1790294400000,"v":17447745282},{"t":1790380800000,"v":16750315075},{"t":1790467200000,"v":16563233432},{"t":1790553600000,"v":16483132253},{"t":1790640000000,"v":16417220762},{"t":1790726400000,"v":16243635851},{"t":1790812800000,"v":16159970707},{"t":1790899200000,"v":16341282987},{"t":1790985600000,"v":16709799292},{"t":1791072000000,"v":16641498080},{"t":1791158400000,"v":16644715567},{"t":1791244800000,"v":16807838661},{"t":1791331200000,"v":16664355453},{"t":1791417600000,"v":16354917068},{"t":1791504000000,"v":16129229430},{"t":1791590400000,"v":16174656220},{"t":1791676800000,"v":16153147548},{"t":1791763200000,"v":16106623257},{"t":1791849600000,"v":15993490851},{"t":1791936000000,"v":16249756054},{"t":1792022400000,"v":15986083973},{"t":1792108800000,"v":16161221627},{"t":1792195200000,"v":15958551196},{"t":1792281600000,"v":15826992667},{"t":1792368000000,"v":15768323797},{"t":1792454400000,"v":15844290160},{"t":1792540800000,"v":15938173502},{"t":1792627200000,"v":16081945432},{"t":1792713600000,"v":15881847625.9}]
\ No newline at end of file
diff --git a/tests/fixtures/market-anomaly/solana-tvl-daily.json b/tests/fixtures/market-anomaly/solana-tvl-daily.json
new file mode 100644
index 000000000..4841a4a07
--- /dev/null
+++ b/tests/fixtures/market-anomaly/solana-tvl-daily.json
@@ -0,0 +1 @@
+[{"t":1784160000000,"v":4909167000},{"t":1784246400000,"v":4828913437},{"t":1784332800000,"v":4806538183},{"t":1784419200000,"v":4851093495},{"t":1784505600000,"v":4853820814},{"t":1784592000000,"v":4956236249},{"t":1784678400000,"v":4976106718},{"t":1784764800000,"v":4953032601},{"t":1784851200000,"v":4909464102},{"t":1784937600000,"v":4774280978},{"t":1785024000000,"v":4824834374},{"t":1785110400000,"v":4903996652},{"t":1785196800000,"v":4800328557},{"t":1785283200000,"v":4776208065},{"t":1785369600000,"v":4779988972},{"t":1785456000000,"v":4810153587},{"t":1785542400000,"v":4735869971},{"t":1785628800000,"v":4704328517},{"t":1785715200000,"v":4727528242},{"t":1785801600000,"v":4750038424},{"t":1785888000000,"v":4790469306},{"t":1785974400000,"v":4790746268},{"t":1786060800000,"v":4707551063},{"t":1786147200000,"v":4734146237},{"t":1786233600000,"v":4793619119},{"t":1786320000000,"v":4838846669},{"t":1786406400000,"v":4824009341},{"t":1786492800000,"v":4848436500},{"t":1786579200000,"v":4808400713},{"t":1786665600000,"v":4822436083},{"t":1786752000000,"v":4801982159},{"t":1786838400000,"v":4794263405},{"t":1786924800000,"v":4762461024},{"t":1787011200000,"v":4835210087},{"t":1787097600000,"v":4881856957},{"t":1787184000000,"v":5211365631},{"t":1787270400000,"v":5317321789},{"t":1787356800000,"v":5537143263},{"t":1787443200000,"v":5542931052},{"t":1787529600000,"v":5546853858},{"t":1787616000000,"v":5722818596},{"t":1787702400000,"v":5591914928},{"t":1787788800000,"v":5759465353},{"t":1787875200000,"v":5998945060},{"t":1787961600000,"v":5855308714},{"t":1788048000000,"v":5896927382},{"t":1788134400000,"v":5773406310},{"t":1788220800000,"v":5970549390},{"t":1788307200000,"v":5633696362},{"t":1788393600000,"v":5687048346},{"t":1788480000000,"v":5905397648},{"t":1788566400000,"v":5845683273},{"t":1788652800000,"v":5892851880},{"t":1788739200000,"v":5979176416},{"t":1788825600000,"v":5897779124},{"t":1788912000000,"v":5929208097},{"t":1788998400000,"v":5831775580},{"t":1789084800000,"v":5725994807},{"t":1789171200000,"v":5874347663},{"t":1789257600000,"v":5881167858},{"t":1789344000000,"v":5810382198},{"t":1789430400000,"v":5893308408},{"t":1789516800000,"v":5699476153},{"t":1789603200000,"v":5756866027},{"t":1789689600000,"v":5871750319},{"t":1789776000000,"v":6280272394},{"t":1789862400000,"v":6150861762},{"t":1789948800000,"v":6180440509},{"t":1790035200000,"v":6433710322},{"t":1790121600000,"v":6502389625},{"t":1790208000000,"v":6365136928},{"t":1790294400000,"v":6455922620},{"t":1790380800000,"v":6606805782},{"t":1790467200000,"v":6595088609},{"t":1790553600000,"v":6609100135},{"t":1790640000000,"v":6427469904},{"t":1790726400000,"v":6484533082},{"t":1790812800000,"v":6424788257},{"t":1790899200000,"v":6472628038},{"t":1790985600000,"v":6501097563},{"t":1791072000000,"v":6488973360},{"t":1791158400000,"v":6594657908},{"t":1791244800000,"v":6577705775},{"t":1791331200000,"v":6594912820},{"t":1791417600000,"v":6422329978},{"t":1791504000000,"v":6178718881},{"t":1791590400000,"v":6159558711},{"t":1791676800000,"v":6181106607},{"t":1791763200000,"v":6223125387},{"t":1791849600000,"v":5980034799},{"t":1791936000000,"v":6015039880},{"t":1792022400000,"v":5934839591},{"t":1792108800000,"v":5980950441},{"t":1792195200000,"v":5924234495},{"t":1792281600000,"v":5896063301},{"t":1792368000000,"v":5851238346},{"t":1792454400000,"v":5847044743},{"t":1792540800000,"v":5965594197},{"t":1792627200000,"v":5978249699},{"t":1792713600000,"v":5815440794}]
\ No newline at end of file
diff --git a/tests/market-anomaly.test.js b/tests/market-anomaly.test.js
new file mode 100644
index 000000000..983f45707
--- /dev/null
+++ b/tests/market-anomaly.test.js
@@ -0,0 +1,292 @@
+// Unit tests for api/_lib/market-anomaly.js, the pure market anomaly engine.
+//
+// The series under tests/fixtures/market-anomaly/ are recorded from the live
+// upstreams the scanner reads (DeFiLlama Solana TVL and stablecoin supply,
+// Hyperliquid SOL funding history). Recorded tails must score clean; shocks
+// are appended to them as one extra observation so the test states exactly
+// what the detectors are asked to catch.
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import {
+ median,
+ modifiedZScore,
+ ewmaDeviation,
+ rateOfChange,
+ classify,
+ windowReturns,
+ detectSeries,
+ detectMany,
+ detectPegDeviation,
+ meetsSeverity,
+ TVL_SPEC,
+ STABLE_SUPPLY_SPEC,
+ FUNDING_SPEC,
+ PRICE_SPEC,
+ OPEN_INTEREST_SPEC,
+ MIN_POINTS,
+} from '../api/_lib/market-anomaly.js';
+import {
+ marketAnomalyMatchesRule,
+ buildMarketAnomalyPayload,
+ formatAlertSummary,
+ deriveRuleLabel,
+} from '../api/_lib/pump-alert-eval.js';
+import { createRuleSchema, validateUpdate, normalizeForKind } from '../api/alerts/_rules.js';
+
+const load = (name) =>
+ JSON.parse(readFileSync(new URL(`./fixtures/market-anomaly/${name}.json`, import.meta.url), 'utf8'));
+const tvl = load('solana-tvl-daily');
+const supply = load('solana-stablecoin-supply-daily');
+const funding = load('hyperliquid-sol-funding-hourly');
+
+const DAY = 86_400_000;
+const HOUR = 3_600_000;
+const shock = (points, factor, step) => {
+ const last = points[points.length - 1];
+ return [...points, { t: last.t + step, v: last.v * factor }];
+};
+const spec = (base, subject) => ({ ...base, subject });
+
+describe('statistics', () => {
+ it('median handles odd, even and empty input', () => {
+ expect(median([3, 1, 2])).toBe(2);
+ expect(median([4, 1, 3, 2])).toBe(2.5);
+ expect(median([])).toBeNaN();
+ });
+
+ it('modifiedZScore flags an outlier and spares an inlier', () => {
+ const h = [10, 11, 9, 10, 10, 12, 8, 10, 11, 9];
+ expect(Math.abs(modifiedZScore(h, 10.5).score)).toBeLessThan(1);
+ expect(modifiedZScore(h, 30).score).toBeGreaterThan(3.5);
+ expect(modifiedZScore(h, -10).score).toBeLessThan(-3.5);
+ });
+
+ it('modifiedZScore falls back to mean absolute deviation when MAD is zero, and refuses a constant series', () => {
+ const mostlyFlat = [5, 5, 5, 5, 5, 5, 6];
+ expect(modifiedZScore(mostlyFlat, 9).score).toBeGreaterThan(3.5);
+ expect(modifiedZScore([5, 5, 5, 5], 9)).toBeNull();
+ expect(modifiedZScore([1], 2)).toBeNull();
+ expect(modifiedZScore([1, 2, 3], NaN)).toBeNull();
+ });
+
+ it('ewmaDeviation tracks a drifting regime', () => {
+ const drift = Array.from({ length: 40 }, (_, i) => 100 + i + (i % 2 ? 0.3 : -0.3));
+ expect(Math.abs(ewmaDeviation(drift, 141).score)).toBeLessThan(3);
+ expect(ewmaDeviation(drift, 200).score).toBeGreaterThan(3);
+ expect(ewmaDeviation([2, 2, 2, 2], 3)).toBeNull();
+ });
+
+ it('rateOfChange is a percent move and refuses a non-positive base', () => {
+ expect(rateOfChange(100, 110)).toBeCloseTo(10);
+ expect(rateOfChange(100, 75)).toBeCloseTo(-25);
+ expect(rateOfChange(0, 5)).toBeNull();
+ expect(rateOfChange(-1, 5)).toBeNull();
+ });
+
+ it('windowReturns builds overlapping lookback returns', () => {
+ const pts = [100, 110, 121, 133.1].map((v, i) => ({ t: i, v }));
+ const r1 = windowReturns(pts, 1);
+ expect(r1).toHaveLength(3);
+ expect(r1[0].r).toBeCloseTo(10);
+ expect(windowReturns(pts, 2)[0].r).toBeCloseTo(21);
+ });
+
+ it('classify takes the lower rung of score and move', () => {
+ expect(classify(20, 5, [5, 10, 20])).toBe('medium');
+ expect(classify(4, 50, [5, 10, 20])).toBe('medium');
+ expect(classify(6, 12, [5, 10, 20])).toBe('high');
+ expect(classify(9, 25, [5, 10, 20])).toBe('critical');
+ expect(classify(9, 1, [5, 10, 20])).toBeNull();
+ });
+
+ it('meetsSeverity orders medium < high < critical', () => {
+ expect(meetsSeverity('critical', 'high')).toBe(true);
+ expect(meetsSeverity('medium', 'high')).toBe(false);
+ expect(meetsSeverity('high', 'high')).toBe(true);
+ });
+});
+
+describe('recorded Solana TVL', () => {
+ it('the recorded tail is not an anomaly', () => {
+ const r = detectSeries(spec(TVL_SPEC, 'Solana'), tvl);
+ expect(r.anomaly).toBeNull();
+ });
+
+ it('a one-day 28% collapse is critical and points down', () => {
+ const r = detectSeries(spec(TVL_SPEC, 'Solana'), shock(tvl, 0.72, DAY));
+ expect(r.anomaly).toMatchObject({ processor: 'tvl', subject: 'Solana', severity: 'critical', direction: 'down' });
+ expect(r.anomaly.change_pct).toBeCloseTo(-28, 0);
+ expect(r.anomaly.detectors).toContain('modified_z');
+ expect(r.anomaly.summary).toMatch(/fell 28\.\d+%/);
+ });
+
+ it('a statistically odd but sub-gate move is not reported', () => {
+ const r = detectSeries(spec(TVL_SPEC, 'Solana'), shock(tvl, 1.02, DAY));
+ expect(r.anomaly).toBeNull();
+ });
+});
+
+describe('recorded Solana stablecoin supply', () => {
+ it('the recorded tail is not an anomaly', () => {
+ expect(detectSeries(spec(STABLE_SUPPLY_SPEC, 'Solana'), supply).anomaly).toBeNull();
+ });
+
+ it('a 9% supply drop (mass redemption) is flagged high or critical', () => {
+ const r = detectSeries(spec(STABLE_SUPPLY_SPEC, 'Solana'), shock(supply, 0.91, DAY));
+ expect(['high', 'critical']).toContain(r.anomaly.severity);
+ expect(r.anomaly.direction).toBe('down');
+ });
+});
+
+describe('recorded Hyperliquid SOL funding', () => {
+ it('the recorded week is not an anomaly', () => {
+ expect(detectSeries(spec(FUNDING_SPEC, 'SOL-USD'), funding).anomaly).toBeNull();
+ });
+
+ it('a funding print of 0.4% per 8h is flagged and keeps its sign', () => {
+ const last = funding[funding.length - 1];
+ const up = detectSeries(spec(FUNDING_SPEC, 'SOL-USD'), [...funding, { t: last.t + HOUR, v: 0.4 }]);
+ expect(up.anomaly).toMatchObject({ processor: 'funding', direction: 'up' });
+ expect(['high', 'critical']).toContain(up.anomaly.severity);
+ const down = detectSeries(spec(FUNDING_SPEC, 'SOL-USD'), [...funding, { t: last.t + HOUR, v: -0.4 }]);
+ expect(down.anomaly.direction).toBe('down');
+ });
+});
+
+describe('hourly price and open interest', () => {
+ const hourly = Array.from({ length: 168 }, (_, i) => ({ t: i * HOUR, v: 100 + Math.sin(i / 5) * 0.8 + (i % 3) * 0.1 }));
+
+ it('a quiet hourly series is clean', () => {
+ expect(detectSeries(spec(PRICE_SPEC, 'SYN'), hourly).anomaly).toBeNull();
+ });
+
+ it('a 20% four-hour dump is critical', () => {
+ const last = hourly[hourly.length - 1];
+ const pts = [...hourly.slice(0, -4), ...[0.97, 0.92, 0.86, 0.8].map((f, i) => ({ t: last.t + (i - 3) * HOUR, v: 100 * f }))];
+ const r = detectSeries(spec(PRICE_SPEC, 'SYN'), pts);
+ expect(r.anomaly).toMatchObject({ severity: 'critical', direction: 'down' });
+ });
+
+ it('an open interest surge of 60% in four snapshots is flagged', () => {
+ const oi = Array.from({ length: 80 }, (_, i) => ({ t: i * 900_000, v: 1_000_000 + (i % 4) * 5_000 }));
+ const n = oi.length;
+ const pts = [...oi.slice(0, n - 1), { t: oi[n - 1].t, v: oi[n - 5].v * 1.6 }];
+ const r = detectSeries(spec(OPEN_INTEREST_SPEC, 'SYN-USD'), pts);
+ expect(r.anomaly).toMatchObject({ processor: 'open_interest', direction: 'up' });
+ });
+});
+
+describe('sparse and flat series', () => {
+ it('skips a series shorter than the minimum window instead of scoring it', () => {
+ const few = tvl.slice(0, 10);
+ const r = detectSeries(spec(TVL_SPEC, 'Solana'), few);
+ expect(r).toMatchObject({ skipped: 'insufficient_history', have: 10 });
+ expect(r.need).toBeGreaterThan(MIN_POINTS);
+ });
+
+ it('skips a perfectly flat series with a reason', () => {
+ const flat = Array.from({ length: 60 }, (_, i) => ({ t: i * DAY, v: 1000 }));
+ const r = detectSeries(spec(TVL_SPEC, 'Flat'), shock(flat, 0.5, DAY));
+ expect(r.skipped).toBe('flat_history');
+ });
+
+ it('ignores non-finite points', () => {
+ const dirty = [...tvl, { t: NaN, v: 1 }, { t: 1, v: Infinity }];
+ expect(detectSeries(spec(TVL_SPEC, 'Solana'), dirty).anomaly).toBeNull();
+ });
+
+ it('detectMany returns anomalies and a skip log', () => {
+ const out = detectMany(TVL_SPEC, [
+ { subject: 'Solana', points: shock(tvl, 0.7, DAY) },
+ { subject: 'Thin', points: tvl.slice(0, 5) },
+ ]);
+ expect(out.anomalies).toHaveLength(1);
+ expect(out.skipped).toEqual([{ processor: 'tvl', subject: 'Thin', reason: 'insufficient_history', have: 5, need: expect.any(Number) }]);
+ });
+});
+
+describe('event keys', () => {
+ it('is stable within a bucket and changes across buckets', () => {
+ const a = detectSeries(spec(TVL_SPEC, 'Solana'), shock(tvl, 0.7, DAY)).anomaly;
+ const b = detectSeries(spec(TVL_SPEC, 'Solana'), shock(tvl, 0.65, DAY)).anomaly;
+ expect(a.event_key).toBe(b.event_key);
+ const c = detectSeries(spec(TVL_SPEC, 'Solana'), shock(tvl, 0.7, 2 * DAY)).anomaly;
+ expect(c.event_key).not.toBe(a.event_key);
+ });
+});
+
+describe('stablecoin peg', () => {
+ const coin = (over) => ({ symbol: 'SYNUSD', price: 1, peg_type: 'peggedUSD', circulating_usd: 5e9, ...over });
+ const NOW = Date.UTC(2026, 9, 23, 12);
+
+ it('on-peg and in-tolerance coins are quiet', () => {
+ expect(detectPegDeviation(coin({ price: 0.9995 }), NOW)).toBeNull();
+ expect(detectPegDeviation(coin({ price: 1.004 }), NOW)).toBeNull();
+ });
+
+ it('grades depth: 0.7% medium, 1.5% high, 8% critical', () => {
+ expect(detectPegDeviation(coin({ price: 0.993 }), NOW).severity).toBe('medium');
+ expect(detectPegDeviation(coin({ price: 0.985 }), NOW).severity).toBe('high');
+ const crit = detectPegDeviation(coin({ price: 0.92 }), NOW);
+ expect(crit).toMatchObject({ severity: 'critical', direction: 'down', processor: 'stablecoin_peg' });
+ expect(crit.summary).toMatch(/8\.00% below its \$1 peg/);
+ });
+
+ it('judges only USD pegs with real float and a usable price', () => {
+ expect(detectPegDeviation(coin({ peg_type: 'peggedEUR', price: 0.5 }), NOW)).toBeNull();
+ expect(detectPegDeviation(coin({ circulating_usd: 1_000_000, price: 0.9 }), NOW)).toBeNull();
+ expect(detectPegDeviation(coin({ price: null }), NOW)).toBeNull();
+ expect(detectPegDeviation(null, NOW)).toBeNull();
+ });
+
+ it('keys one event per 12 hour bucket', () => {
+ const a = detectPegDeviation(coin({ price: 0.9 }), NOW);
+ const b = detectPegDeviation(coin({ price: 0.89 }), NOW + HOUR);
+ const c = detectPegDeviation(coin({ price: 0.9 }), NOW + 13 * HOUR);
+ expect(a.event_key).toBe(b.event_key);
+ expect(a.event_key).not.toBe(c.event_key);
+ });
+});
+
+describe('market_anomaly alert rules', () => {
+ const event = { id: 7, processor: 'stablecoin_peg', subject: 'SYNUSD', metric: 'peg', severity: 'critical', direction: 'down', value: 0.92, baseline: 1, change_pct: -8, score: 8, summary: 'SYNUSD is trading at $0.9200, 8.00% below its $1 peg', observed_at: '2026-10-23T12:00:00.000Z' };
+ const rule = (filters) => ({ id: 'r1', kind: 'market_anomaly', filters });
+
+ it('defaults to high severity and above across every processor', () => {
+ expect(marketAnomalyMatchesRule(rule(null), event)).toBe(true);
+ expect(marketAnomalyMatchesRule(rule(null), { ...event, severity: 'medium' })).toBe(false);
+ });
+
+ it('honours processors, min_severity and subject filters', () => {
+ expect(marketAnomalyMatchesRule(rule({ processors: ['funding'] }), event)).toBe(false);
+ expect(marketAnomalyMatchesRule(rule({ processors: ['stablecoin_peg', 'tvl'] }), event)).toBe(true);
+ expect(marketAnomalyMatchesRule(rule({ min_severity: 'medium' }), { ...event, severity: 'medium' })).toBe(true);
+ expect(marketAnomalyMatchesRule(rule({ subject: 'synusd' }), event)).toBe(true);
+ expect(marketAnomalyMatchesRule(rule({ subject: 'other' }), event)).toBe(false);
+ expect(marketAnomalyMatchesRule({ ...rule(null), kind: 'whale_buy' }, event)).toBe(false);
+ });
+
+ it('builds a deduping payload and readable summary and label', () => {
+ const p = buildMarketAnomalyPayload(rule(null), event);
+ expect(p).toMatchObject({ kind: 'market_anomaly', event_id: 'anomaly:7', severity: 'critical', processor: 'stablecoin_peg' });
+ expect(formatAlertSummary(p)).toContain('below its $1 peg');
+ expect(deriveRuleLabel({ kind: 'market_anomaly', filters: { min_severity: 'critical', processors: ['tvl'] } })).toBe('Market anomalies · critical+ · tvl');
+ });
+
+ it('API validation accepts a bare rule and filters, and rejects a target or unknown filter keys', () => {
+ expect(createRuleSchema.safeParse({ kind: 'market_anomaly' }).success).toBe(true);
+ expect(createRuleSchema.safeParse({ kind: 'market_anomaly', filters: { processors: ['tvl'], min_severity: 'high' } }).success).toBe(true);
+ expect(createRuleSchema.safeParse({ kind: 'market_anomaly', filters: { processors: ['nope'] } }).success).toBe(false);
+ expect(createRuleSchema.safeParse({ kind: 'market_anomaly', filters: { bogus: 1 } }).success).toBe(false);
+ const withTarget = createRuleSchema.safeParse({ kind: 'market_anomaly', target_mint: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump' });
+ expect(withTarget.success).toBe(false);
+ });
+
+ it('keeps anomaly filters on update and clears them when the kind changes', () => {
+ expect(normalizeForKind({ kind: 'market_anomaly', filters: { min_severity: 'high' } }).filters).toEqual({ min_severity: 'high' });
+ expect(normalizeForKind({ kind: 'graduation', filters: { min_severity: 'high' } }).filters).toBeNull();
+ const upd = validateUpdate({ kind: 'market_anomaly', filters: null, deliver_in_app: true, cooldown_seconds: 300, enabled: true }, { filters: { min_severity: 'critical' } });
+ expect(upd.ok).toBe(true);
+ });
+});