Nansen Token Screener

Authentication

Browser login requests nansen:api for API-key-equivalent account API permissions; existing OAuth/MCP nansen:read semantics and separate wallet authorization are unchanged.

Before any research command or loop, require an explicitly selected API key or saved browser session. Run nansen auth status first. Its cached/unverified metadata does not prove credential validity or unlocked storage. Cached access-token expiry alone does not mean the session is unusable: the CLI normally renews a selected session automatically during an already-authorized research task, without another consent request or a separate account check. Stop on anonymous selection, invalid authentication state, blocked or uncertain renewal/cleanup, or an actual authentication failure, including rejected or expired refresh authority. Follow the CLI error guidance; use the free nansen account check when troubleshooting calls for it. Do not unset a failed key, erase a session or switch to anonymous access to retry.

Use nansen login for fresh browser approval within the documented platform scope, or configure a conventional API key. NANSEN_API_KEY overrides the saved session. OpenClaw's optional primaryEnv mapping preserves configured API-key injection; it is not a required-key gate or proof of authentication. Normal credits and entitlements apply. Login does not purchase credits. Browser login is available in CLI 2.0.0 within the macOS arm64 preview scope.

API keys and browser sessions use the same automatic x402 payment behavior: a supported HTTP 402 challenge can spend funds from the configured wallet under existing wallet authorization, payment policy and spending limits. Each call, including calls in loops, can incur a payment. Authentication, authorization and session-renewal failures never trigger payment; login verification and nansen account never pay automatically. Anonymous x402 remains available as a separate paid workflow requiring explicit user intent and payment setup. Do not run this research workflow anonymously or switch to anonymous access after authentication fails.

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 over the fetched candidates).
# Check _meta.search: complete=false means lower-ranked tokens were not searched —
# widen with --limit 1000 or --paginate, or narrow with --filters.
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?" (account API endpoint; normal entitlements apply)
# 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.