crypto-catalyst-scanner

Early bullish-momentum detector for the top-150 market-cap crypto tokens. It finds tokens that are just starting to move with relative strength versus the broader market — before they are overbought — and ranks them as actionable SIGNAL, WATCH, or NEUTRAL.

No API key. No dependencies. Pure Python standard library, public CoinGecko data.

Why this exists

Public news is mostly priced in by the time it reaches a feed. The real edge is catalyst + early momentum: spotting the price/volume footprint of a move that is just beginning, while there is still a clean entry — not chasing a candle that has already run 40%.

So this scanner does not read headlines. It reads the market's own footprint:

• Relative strength — is this token outperforming the median of the top 150 over 24h and 7d? Strength against the field, not just an absolute green candle.
• Acceleration — is the 24h move faster than the 7d trend implies? An early mover accelerates; a tired mover decelerates.
• Volume-to-market-cap ratio — fresh interest shows up as volume disproportionate to size, before price fully reflects it.
• Extension guard — if a token is already stretched (large 7d/30d run, late-RSI shape), it gets tagged WATCH, not SIGNAL: you likely missed the clean entry, wait for a pullback.

A lightweight narrative tagger (AI / RWA / DePIN / L1 / L2 / Meme) annotates each hit so you can see which sector is rotating.

Output tags

• SIGNAL — fresh early mover worth a look now. New since the last run, or materially stronger than when it last alerted.
• WATCH — strong but already extended. On your radar, but wait for a pullback.
• NEUTRAL — no edge this scan.

Install & run

git clone https://github.com/Mnorbert87/crypto-catalyst-scanner.git
cd crypto-catalyst-scanner
python3 scanner.py

That's it — no pip install, no key, no config file.

Useful flags

python3 scanner.py --top 15          # show top 15 fresh signals
python3 scanner.py --min-score 70    # only higher-conviction hits
python3 scanner.py --dedup-hours 12  # re-alert window (avoid spamming the same coin)
python3 scanner.py --json            # machine-readable output (pipe into a bot/alert)

Example (human output)

== Catalyst scan 2026-06-02T18:24:11+00:00 ==
Market regime: median 24h +1.2%  7d +4.8%  | trending=7

FRESH SIGNALS (new since last run, score>=50):
  [103.5] LIGHTER #88  $0.4210   24h +18.3 7d +41.0 30d +62.1 rel24 +17.1 accel +9.4 vmc 0.38 [AI]
  [ 60.3] ZEC     #44  $58.10    24h  +9.1 7d +12.0 30d +21.7 rel24  +7.9 accel +2.2 vmc 0.11 [-]

WATCH (strong but extended, wait for pullback):
  WIF     #62  7d +58.0 30d +120.4  (RSI-late)

The scanner keeps a small dedup state in state/alerts.json so it only re-alerts a coin when it is genuinely fresh or materially stronger — safe to run on a cron every 15–30 minutes.

Automate it

# every 20 minutes, machine-readable, into your own alert pipeline
*/20 * * * * cd /path/to/crypto-catalyst-scanner && python3 scanner.py --json >> scan.log

Roadmap

• v1.5 — optional CryptoPanic news layer (free token) to confirm a momentum signal with a real catalyst.
• v2 — per-narrative rotation score (which sector is leading the rotation right now).
• v2 — backtest harness over CoinGecko historical to tune the score weights.

Notes & gotchas

• CoinGecko's free endpoint is rate-limited. The scanner is built around a handful of calls per run; if you tighten the cron below ~10 minutes you may hit 429s.
• Scores are tuned for sensitivity (catch the move early, accept some noise). If you want fewer, higher-conviction alerts, raise --min-score.
• This is a research/signal tool, not financial advice. It tells you where to look, not what to buy.

License

MIT — see LICENSE.