Flow Scanner

Flow Scanner is a decision layer on top of Nansen.

Nansen Token Screener is great at surfacing activity. Flow Scanner takes that raw universe, removes obvious structural noise, and re-ranks what remains by accumulation quality.

The goal: identify where capital is committing, separate from where it is merely rotating through.

---

Preview

Scan view

Inspect view

---

What it does

Flow Scanner starts from tgm/token-screener, then:

• removes obvious non-target assets like stablecoins, wrapped majors, stock/synthetic tokens, and other structural noise

• applies minimum quality gates

• evaluates each survivor using:

  • flow strength (how much capital is actually entering)
  • flow acceleration vs baseline (is flow increasing vs recent history)
  • buyer breadth / independence (many distinct wallets vs one dominant buyer)
  • cohort quality (who is buying — smart money, whales, profitable wallets)

• applies penalties for:

  • concentrated wallet activity (one or two wallets dominating flow)
  • churn (high buy + sell activity with little net position change)
  • contract/protocol-heavy flow (likely liquidity, routing, or mechanical activity)
  • fresh-wallet dominance (new wallets driving most of the flow)
  • other low-conviction patterns

• returns a ranked list of accumulation candidates

It also supports a drill-down view for a single token, showing:

• cohort breakdown (flow split by wallet types like smart money and whales)
• persistence / flow quality (whether accumulation is consistent over time)
• breadth / independence (how distributed the buying is)
• score drivers and penalties (what pushed the score up or down)
• a short human-readable summary

Why this exists

Raw flow is not enough.

A token can look active for several reasons:

• wrappers and synthetic assets
• exchange mechanics
• market making
• liquidity management
• one-wallet dominance
• noisy retail rotation

Flow Scanner tries to filter that out and answer a more useful question:

does this look like real accumulation?

Product shape

Flow Scanner has two views:

Scan

A clean ranked list of tokens by accumulation quality.

This is the fast decision surface.

Inspect

A token-level drill-down explaining why a token ranked where it did.

This is the trust layer.

Example workflow

Scan

node scan.mjs --chain solana

Example output:

FLOW SCANNER — Top Accumulation Candidates

#  Token      Score   Status      Confidence  Breadth  Cohort         Flow Δ
1  HYPE       76      Building    High        Mixed    Whales         +$3.2M
2  PUMP       66      Building    High        Mixed    Smart Money    +$1.3M
3  BAN        63      Mixed       High        Mixed    Whales         +$303K

Inspect

node inspect.mjs HYPE --chain solana

Example output:

HYPE — solana

Score:       76 / 100
Status:      Building
Confidence:  High
Breadth:     Mixed
Cohort:      Whales
Flow Δ:      +$4.21M

Persistence: Strong (4/5 recent windows positive)
Acceleration: +296% vs baseline
Exchange: Net outflow (supportive)

Summary:
Quality cohort flow is positive (+$4.21M). Primary driver: whales.
Data coverage is good and signals are consistent. Elevated churn
suggests some positions are being rotated, not just accumulated.

Scoring philosophy

Flow Scanner is intentionally rule-based.

It does not try to be a black-box model.

The score is based on four main components:

• flow strength
• flow acceleration vs baseline
• independence / breadth
• cohort quality

It then applies boosts and penalties to avoid obvious false positives.

Status bands

• 80–100 → Accumulating
• 65–79 → Building
• 50–64 → Mixed
• <50 → Weak

Confidence labels

• High
• Medium
• Low

Confidence is separate from score.

Design principles

• raw flow is not enough
• ranking should not equal raw screener order
• opinionated filtering is a feature, not a bug
• the scan view should feel like a decision tool, not a dashboard
• the inspect view should explain, not overwhelm

Current scope

Included

• Nansen Token Screener as candidate source
• filtering layer
• rule-based accumulation ranking
• scan view
• inspect view

Not included

• copy trading
• execution
• alerts
• backtesting engine
• giant multi-panel dashboards
• machine learning scoring

Tech notes

This project uses Nansen CLI/API data to build a normalized screening + ranking pipeline.

Nansen API Usage

Flow Scanner uses multiple Nansen endpoints to construct a structured view of token flows:

• tgm/token-screener — candidate universe
• tgm/flow-intelligence — cohort-level flows
• tgm/flows — time-series flow data
• tgm/who-bought-sold — top buyers and sellers
• tgm/holders — holder distribution and changes
• profiler/labels — wallet labeling
• profiler/related-wallets — clustering / relationships
• profiler/counterparties — interaction patterns

These are combined into a normalized dataset before filtering and scoring. Total API calls per run exceed 10 due to per-wallet enrichment.

Note: Some endpoints have partial availability depending on chain and token type. The system is designed to degrade gracefully when certain fields are missing.

Important implementation notes:

• some endpoints have partial or chain-specific limitations
• Solana profiler depth may degrade gracefully on some wallets
• exchange CEX/DEX split fields are not assumed to be consistently available
• the scanner is designed to remain usable even when some secondary fields are missing

Repo structure

flow-scanner/
├── src/
├── output/
├── cache/
├── build-specs/
├── scan.mjs
├── inspect.mjs
└── README.md

Running locally

node scan.mjs --chain ethereum node scan.mjs --chain solana node inspect.mjs HYPE --chain solana

One-line summary

Token Screener shows activity. Flow Scanner ranks accumulation quality.