Nansen Token Screener

Discover trending tokens — screener, SM holdings, Nansen indicators, and flow intelligence for promising finds. Use when scanning for new tokens or screening...

Security Scan

The skill's requirements (nansen CLI + NANSEN_API_KEY) and runtime instructions match the stated purpose of querying Nansen for token discovery; nothing requested appears unrelated or excessive.

Purpose & Capability

The skill is described as a Nansen token screener and the only required pieces are the nansen CLI binary and a Nansen API key, which are exactly what that purpose requires. The skill does not request unrelated cloud credentials or access to other systems. (Note: the registry metadata has no homepage/source URL, which reduces verifiability but does not make the requirements incoherent.)

Instruction Scope

SKILL.md contains concrete nansen CLI commands (search/screener/indicators/flow) and does not instruct the agent to read arbitrary files, other environment variables, or to exfiltrate data to non-Nansen endpoints. All example commands operate via the declared CLI and token address/chain variables.

Install Mechanism

Install is an npm package (nansen-cli) that provides the nansen binary — this is a reasonable mechanism for a CLI wrapper, but npm packages execute arbitrary code at install/run time. Because the skill metadata lacks a homepage/source, verify the npm package's publisher, popularity, and source repository before installing.

Credentials

Only a single credential (NANSEN_API_KEY) is required and is the clearly primary credential for this integration. The request is proportionate to the stated functionality. Users should still use least-privilege/read-only API keys if Nansen supports that and avoid sharing the key in public contexts.

Persistence & Privilege

always: false (not force-included) and the skill does not request system-wide config paths or other skills' credentials. Model invocation is allowed but that's the platform default; nothing in the skill requests elevated or persistent system privileges.

Assessment

This skill appears coherent for querying Nansen, but take basic hygiene before installing: 1) Verify the npm package 'nansen-cli' on the npm registry and check its publisher, download counts, and linked source repo (prefer an official GitHub repo). 2) Prefer a read-only/least-privilege NANSEN_API_KEY if available. 3) Install the CLI in an isolated environment (container or VM) if you want to inspect behavior first. 4) Avoid pasting your API key into public logs, chats, or repos. 5) If you need higher assurance, review the package source code or ask the publisher for a signed release. Installing an arbitrary npm package carries moderate risk, but nothing in this skill's instructions is inconsistent with its stated purpose.

Token Discovery

Answers: "What tokens are trending and worth a deeper look?"

CHAIN=solana

# Screen top tokens by volume
nansen research token screener --chain $CHAIN --timeframe 24h --limit 20
# → token_symbol, price_usd, price_change, volume, buy_volume, market_cap_usd, fdv, liquidity, token_age_days

# Smart money only
nansen research token screener --chain $CHAIN --timeframe 24h --smart-money --limit 20

# Search within screener results (client-side filter)
nansen research token screener --chain $CHAIN --search "bonk"

# Smart money holdings — what SM wallets are holding
nansen research smart-money holdings --chain $CHAIN --labels "Smart Trader" --limit 20
# → token_symbol, value_usd, holders_count, balance_24h_percent_change, share_of_holdings_percent

# Nansen indicators for a specific token
TOKEN=<address>
nansen research token indicators --token $TOKEN --chain $CHAIN
# → risk_indicators, reward_indicators (each with score, signal, signal_percentile)

# Flow intelligence — only use for promising tokens from screener/indicators above
nansen research token flow-intelligence --token $TOKEN --chain $CHAIN
# → net_flow_usd per label: smart_trader, whale, exchange, fresh_wallets, public_figure

# Nansen Score Top Tokens — "what should I buy?" (public endpoint, any authenticated API key)
# Use this FIRST for discovery, then drill into individual tokens with `indicators` above
nansen research token top-tokens --limit 25
nansen research token top-tokens --market-cap largecap --limit 10
# → chain, token_address, token_symbol, performance_score, risk_score,
#   per-indicator contributions, market_cap_group, latest_date, last_trigger_on

Screener timeframes: 5m, 10m, 1h, 6h, 24h, 7d, 30d

Indicators: score is "bullish"/"bearish"/"neutral". signal_percentile > 70 = historically significant. Some tokens return empty indicators — not an error.

Top tokens — Nansen Score field reference

Results are pre-filtered to performance_score >= 15 server-side and returned sorted by:

1. performance_score DESC
2. market_cap_group priority (largecap → midcap → lowcap)
3. risk_score DESC
4. 24h volume DESC

So row 0 is always the strongest candidate for the filter you applied — no client-side ranking needed.

Market cap buckets (used in both the sort priority and the --market-cap filter):

• lowcap: market cap < $100M
• midcap: market cap $100M – $1B
• largecap: market cap > $1B

Every contribution is ternary — exactly one of {negative, 0, positive} per field. No partial values. Zero means "indicator didn't apply to this token" (out of scope), not "indicator was neutral".

Performance Score (Alpha — "likely to outperform BTC over 7–30d") Range: -60 to +75 (arithmetic bounds; live max is closer to +45 since no single token hits every positive indicator simultaneously). Buy threshold: >= 15. Sum of the five *_performance fields below.

Field	Contribution	Trigger	What the underlying indicator measures
price_momentum_performance	+30 / 0	upstream score bullish → +30	Price momentum, scored against separate thresholds for large-cap vs. low/mid-cap tokens.
chain_fees_performance	+30 / 0	bullish (30-day fee growth > +1%) → +30	30-day spending momentum on network fees (geometric mean of daily returns). Only tracked for a handful of L1 native tokens (e.g. ETH, TRX, AVAX, RON); always 0 for every other token.
trading_range_performance	+15 / 0	bullish (price breaks above resistance in an uptrend) → +15	14-day price trend combined with position vs. nearest support/resistance. In practice fires mostly on established tokens that have well-defined levels — can fire at any market cap, but is rare for new / low-liquidity tokens.
chain_tvl_performance	0 / -35	bearish (composite TVL growth < 0) → -35	TVL momentum composite signal. Only non-zero for chains / L2s whose TVL is tracked. No positive path exists — the field only deducts.
protocol_fees_performance	0 / -25	bearish (14-day fee growth < -3%) → -25	14-day protocol fee momentum. Only non-zero for tokens backed by protocols with measurable fee revenue. No positive path — deduction only.

Risk Score (Safety — "filters falling knives / dangerous setups") Range: -60 to +80 (arithmetic bounds). Safety threshold: > 0 (positive = safer, negative = riskier). Sum of the four *_risk fields below. For every risk field: upstream score low → positive contribution, high → negative contribution, medium/missing → 0.

Field	Contribution	What the underlying indicator measures
btc_reflexivity_risk	+40 / -20	Rolling 5-event median ratio of token drop to BTC drop on days BTC falls >3%. Ratio ≤ 1 → low → +40 (token holds up as well as or better than BTC on drawdowns). Ratio > 1 → high → -20 (token drops harder than BTC). Skipped for stablecoins and tokens with <$1M 24h volume.
liquidity_risk	+20 / -20	Ratio of on-chain liquidity to market cap (total_liquidity_usd / market_cap_usd). Higher ratio → low → +20 (deep books relative to cap). Very thin ratio → high → -20.
concentration_risk	+10 / -10	Top-10 holder concentration as a fraction of supply. < 0.12 → low → +10 (well-distributed). > 0.55 → high → -10 (whale-concentrated).
inflation_risk	+10 / -10	EMA of daily token supply inflation rate. Negative / near-zero → low → +10 (stable or deflationary supply). Strongly positive → high → -10 (high dilution). Only evaluated for tokens >= $100M market cap.

Other response fields:

• market_cap_group: lowcap / midcap / largecap — see thresholds above.
• latest_date: ISO datetime of the most recent indicator refresh for this token.
• last_trigger_on: ISO datetime of the most recent trigger across contributing indicators (MAX aggregate — individual indicators may be days-to-months stale even when this looks fresh). Use indicators on a specific token to audit per-indicator ages.

Stablecoins rank high but aren't picks. USDC, USDT, DAI, FDUSD and similar score well on chain_fees + liquidity indicators but aren't what "what should I buy" means. Filter them out of the shortlist using the canonical whitelist at nansen-dbt-ch-tokens/seeds/stablecoins_for_indicator.csv before drilling into indicators.

Typical workflow: start with top-tokens for a shortlist → drop stablecoins → run indicators on the top 3–5 to inspect individual signals and their signal_percentile → flow-intelligence only on the finalists to confirm SM conviction.

Field meanings and contribution mappings above are sourced from nansen-dbt-ch-tokens/models/indicators/api_nansen_score_indicators_all_tokens_latest.sql and per-indicator model yml files. Sign conventions and live value ranges were validated against production ClickHouse data.

Flow intelligence is credit-heavy. Use it to confirm SM conviction on tokens that already look promising from screener + indicators, not as a first pass on every token.