/nansen-token-screener

name: nansen-token-screener
description: "Discover trending tokens — screener, SM holdings, Nansen indicators, and flow intelligence for promising finds. Use when scanning for new tokens or screening what's hot."
metadata:
  openclaw:
    requires:
      bins:
        - nansen
    primaryEnv: NANSEN_API_KEY
    install:
      - kind: node
        package: nansen-cli
        bins: [nansen]
allowed-tools: Bash(nansen:*)

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](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-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. | 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-ca