Rules & Methodology

LP drain percentage is calculated as:

The monitor finds the snapshot closest to now - windowSeconds and compares against current liquidity. All thresholds are checked independently; a single rugpull event can trigger multiple severity levels.

Thresholds are intentionally high to avoid false alerts from normal volatility in alpha tokens. The longer windows naturally filter out flash crashes that self-correct.

The pump & dump rule fires when both conditions are true simultaneously:

This pattern is the hallmark of a classic P&D: the token price is pumped (attracting buyers) while liquidity is simultaneously drained (the exit). Requiring both conditions together avoids false positives from legitimate rallies or routine LP adjustments.

Fires immediately when liquidity drops to near-zero from a meaningful baseline:

The minimum previous threshold prevents spam on tokens that were never meaningfully liquid. Once a token hits zero liquidity it is effectively non-tradeable.

LP concentration checks are performed on-chain against PumpSwap and Raydium AMM pools. These checks run on a distributed 8-hour cycle (one token at a time) to avoid rate limiting.

The monitor polls multiple data providers on each cycle. CoinGecko and Solscan poll every 60 seconds; Birdeye polls every 5 minutes. Each poll captures current price and total liquidity and stores the result in an in-memory ring buffer keyed by token address and provider.

Each provider maintains its own snapshot history per token (~20 snapshots, ~20 min for 60s providers, ~100 min for Birdeye). Old snapshots are evicted automatically. The buffer is lost on process restart and rebuilds within the first few poll cycles.

Rules are evaluated per provider independently. Each provider's ring buffer is checked against the rule thresholds. Raw alerts from all providers are then deduped by (token, rule) — if multiple providers trigger the same rule, they produce one consolidated alert with source agreement info.

Each (token, rule, severity) combination has an independent 5-minute cooldown to prevent alert spam during sustained events. A token can still trigger alerts for different rules or severities within the same window.

Cooldowns are in-memory and reset on process restart. This is intentional — after a restart, all suppression is lifted so legitimate events are not missed during recovery.

v2 fetches price and liquidity data from multiple independent providers and evaluates rules against each provider's data separately. This cross-verification reduces false positives from stale or inaccurate data in any single source.

After each poll cycle, raw alerts from all providers are grouped by (token, rule). If multiple providers trigger the same rule for the same token, they are consolidated into a single alert showing how many sources agree.

Partial agreement alerts are flagged with MANUAL CHECK REQUIRED since a single-source trigger may indicate data lag rather than a real event. Each source's numbers are shown in the alert for manual comparison.

Birdeye polls at a slower interval (5 min vs 60s) to conserve API credits (CU). The system checks remaining CU via Birdeye's /utils/v1/credits endpoint every 10 minutes. If remaining credits drop below 5%, Birdeye is halted permanently and a debug alert is sent. Resume manually via POST /api/providers/birdeye/resume.

LP token holder distribution is fetched directly from Solana RPC by querying the token accounts of the LP mint for each pool. PumpSwap AMM and Raydium AMM v4 pools are supported. Checks run on a distributed 8-hour cycle (one token at a time). Mantle LP concentration is not yet implemented.