Nansen Token

Nansen Token — Token God Mode

Deep analytics for any token: holders, flows, trades, PnL, and discovery.

When This Skill Activates

• "Who holds $TOKEN?" / "Top holders"
• "Screen tokens by smart money"
• "Token flows" / "Who's buying/selling?"
• "PnL leaderboard for $TOKEN"

⚠️ Token Address Resolution

Most commands need a contract address. If user gives a ticker:

nansen token screener --chain <chain> --search <SYMBOL> --limit 10
# Returns tokens matching the symbol/name. Use the token_address from results.

Tip: --search does client-side filtering. For broad discovery, omit --search and use --sort volume:desc.

Command Routing

Perp commands (perp-trades, perp-positions, perp-pnl-leaderboard) use --symbol instead of --token. See nansen-hyperliquid.

⚠️ Known Issues

• `token flows` and `token who-bought-sold` require --date '{"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}' — without it, the API returns an error.
• `token jup-dca` — Solana only. Use a non-native Solana token address (e.g., JUP, BONK). Native tokens like wSOL are rejected by the API.

Response Field Notes (actual API vs schema)

• `token screener` returns: buy_volume, sell_volume, volume, netflow, price_usd, price_change, market_cap_usd, fdv, liquidity, token_age_days, etc. (NOT holder_count/smart_money_holders)
• `token dex-trades` returns: action, block_timestamp, estimated_swap_price_usd, estimated_value_usd, token_address, token_amount, traded_token_address, trader_address, trader_address_label, transaction_hash (NOT tx_hash/wallet_address/side)
• `token pnl` returns: trader_address, trader_address_label, pnl_usd_realised, pnl_usd_unrealised, pnl_usd_total, roi_percent_*, holding_amount, nof_trades (NOT wallet_address/labels)
• `token transfers` returns: from_address, from_address_label, to_address, to_address_label, transfer_amount, transfer_value_usd, transaction_hash, block_timestamp (NOT tx_hash/from/to)
• `token flow-intelligence` returns single object with *_net_flow_usd, *_avg_flow_usd, *_wallet_count for each label group (public_figure, top_pnl, whale, smart_trader, exchange, fresh_wallets)

Examples

# Screen tokens on Ethereum by smart money
nansen token screener --chain ethereum --smart-money --sort nof_traders:desc --limit 20 --table

# Top WETH holders (smart money only)
nansen token holders --token 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 --chain ethereum --smart-money --limit 20 --table

# Token flows (--date is required!)
nansen token flows --token 0x... --chain ethereum --date '{"from": "2026-02-01", "to": "2026-02-15"}' --table

# Who's buying/selling? (--date is required!)
nansen token who-bought-sold --token 0x... --chain ethereum --date '{"from": "2026-02-01", "to": "2026-02-15"}' --table

# PnL leaderboard
nansen token pnl --token 0x... --chain ethereum --sort pnl_usd_realised:desc --limit 20 --table

# Flow intelligence by label
nansen token flow-intelligence --token 0x... --chain ethereum --days 7

Discovery Workflow

1. Screener → find tokens 2. Holders → who holds? 3. DEX Trades → activity 4. PnL → profits 5. Transfers → movement

References

• Command parameters: references/commands.md (token section)
• Example response: references/examples/token-holders.json
• Cached schema: references/schema.json

API-Only Endpoints (No CLI Command)

These endpoints work via direct API call but have no CLI command:

Token Information (/api/v1/tgm/token-information)

Detailed token metadata + spot metrics (volume, buys/sells, liquidity, holders).

curl -s -X POST -H "apikey: $NANSEN_API_KEY" -H "Content-Type: application/json" \
  -d '{"token_address":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2","chain":"ethereum","timeframe":"1d"}' \
  "https://api.nansen.ai/api/v1/tgm/token-information"

Params: token_address (req), chain (req), timeframe (req: 5m|1h|6h|12h|1d|7d) Returns: name, symbol, logo, market_cap, fdv, supply, spot_metrics (volume, buys/sells, liquidity, holders)

MCP-Only Tools (Not available via CLI or REST API)

These tools exist only in the Nansen MCP server:

• `token_ohlcv` — OHLCV candlestick data for a token
• `token_quant_scores` — Quantitative scoring for a token (momentum, volatility, etc.)
• `nansen_score_top_tokens` — Top tokens ranked by Nansen Score

To use these, connect via MCP (see docs.nansen.ai).

Attribution

📊 Data by Nansen