Nansen CLI

Built by agents, for agents. We prioritize the best possible AI agent experience.

Command-line interface for the Nansen API with structured JSON output, designed for AI agents and automation.

Installation

# Install globally via npm
npm install -g nansen-cli

# Or run directly with npx
npx nansen-cli help

# Or clone and install locally
git clone https://github.com/nansen-ai/nansen-cli.git
cd nansen-cli
npm install
npm link

Configuration

For AI Agents (Recommended)

Use the AI Agent Setup flow:

1. Your agent will ask you to visit: app.nansen.ai/auth/agent-setup
2. Sign in with your Nansen account
3. Copy the message shown
4. Paste it back to your agent

Your agent saves the key and handles everything else automatically.

Manual Setup

Option 1: Interactive login

nansen login
# Enter your API key when prompted
# ✓ Saved to ~/.nansen/config.json

Option 2: Environment variable (best for agents)

export NANSEN_API_KEY=your-api-key

Option 3: Direct config file

mkdir -p ~/.nansen && echo '{"apiKey":"<key>","baseUrl":"https://api.nansen.ai"}' > ~/.nansen/config.json && chmod 600 ~/.nansen/config.json

Get your API key at app.nansen.ai/api.

Auth Priority

1. NANSEN_API_KEY env var (highest)
2. ~/.nansen/config.json file
3. Interactive prompt

Verify It Works

# Check CLI is installed (no API key needed):
nansen schema | head -1

# Verify API access:
nansen research token screener --chain solana --limit 1

Quick Start

# Get trending tokens on Solana
nansen research token screener --chain solana --timeframe 24h --pretty

# Check Smart Money activity
nansen research smart-money netflow --chain solana --pretty

# Profile a wallet
nansen research profiler balance --address 0x28c6c06298d514db089934071355e5743bf21d60 --chain ethereum --pretty

# Search for tokens/entities
nansen research search "Vitalik Buterin" --pretty

Commands

All analytics live under nansen research, trading under nansen trade, and wallet management under nansen wallet.

research - Research & Analytics

nansen research <category> <subcommand> [options]

Category aliases: sm (smart-money), tgm (token), prof (profiler), port (portfolio)

research smart-money - Smart Money Analytics

Track trading and holding activity of sophisticated market participants.

Smart Money Labels: Fund, Smart Trader, 30D Smart Trader, 90D Smart Trader, 180D Smart Trader, Smart HL Perps Trader

research profiler - Wallet Profiling

ENS Name Resolution: You can use .eth names anywhere an --address is accepted:

nansen research profiler balance --address vitalik.eth
nansen research profiler labels --address nansen.eth --chain ethereum
nansen research profiler transactions --address vitalik.eth --table

ENS names are automatically resolved to 0x addresses via public APIs (with onchain RPC fallback). Works on all EVM chains. The resolved name and address are included as _ens metadata in JSON output.

research token - Token God Mode

research search / research perp / research portfolio / research points

See nansen research help or nansen schema --pretty for full details.

trade - DEX Trading

# Get a swap quote
nansen trade quote --from USDC --to SOL --amount 10 --chain solana

# Execute the swap
nansen trade execute --from USDC --to SOL --amount 10 --chain solana

wallet - Local Wallet Management

Wallets are passwordless by default (keys stored like SSH keys). Set NANSEN_WALLET_PASSWORD env var for encryption at rest.

schema - Schema Discovery

No API key required. Machine-readable command reference for agent introspection.

nansen schema --pretty                    # All commands
nansen schema research --pretty           # Research commands

Deprecated Flat Commands

The old flat commands (nansen smart-money, nansen token, nansen profiler, nansen search, nansen perp, nansen portfolio, nansen points, nansen quote, nansen execute) still work but print a deprecation warning to stderr. Use the new research and trade namespaces instead.

Options

Supported Chains

ethereum solana base bnb arbitrum polygon optimism avalanche linea scroll zksync mantle ronin sei plasma sonic unichain monad hyperevm iotaevm

Run nansen schema to get the current chain list (source of truth).

Agent-Optimized Patterns

Reduce Token Burn with --fields

# ❌ Returns everything (huge JSON, wastes agent context)
nansen research smart-money netflow --chain solana

# ✅ Only what you need
nansen research smart-money netflow --chain solana --fields token_symbol,net_flow_usd,chain --limit 10

Use --stream for Large Results

# NDJSON mode — process line by line, don't buffer giant arrays
nansen research token dex-trades --chain solana --limit 100 --stream

x402 Micropayments

When the API returns a 402 Payment Required, the CLI automatically handles payment if a funded wallet exists:

1. CLI detects 402 response with payment requirements
2. Signs a USDC payment ($0.05/call) using your wallet
3. Retries the request with the payment signature
4. Falls back from EVM to Solana if first network has insufficient funds

# Fund your wallet, then API calls auto-pay
nansen wallet create
# Send USDC to the displayed address
nansen research smart-money netflow --chain solana  # auto-pays if no API key

Pagination

Use --limit N to control result count. The CLI always fetches page 1 (there is no --page flag).

Detecting the last page: If results returned < your --limit, you've reached the end.

Output Format

Response envelope

// Success
{ "success": true, "data": <raw_api_response> }

// Error
{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": {...} }

Response shapes vary by endpoint

The data field structure differs across endpoints:

--table and --stream handle this automatically. For raw JSON parsing:

nansen research smart-money netflow --chain solana | jq 'keys, .data | keys'

Error codes

Troubleshooting

Development

npm test              # Run tests (mocked, no API key needed)
npm run test:coverage # With coverage
npm run test:live     # Against live API (needs NANSEN_API_KEY)

See AGENTS.md for contributor guidance (architecture, testing patterns, style guide).

API Coverage

License

MIT © Nansen