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

Option 1: Interactive login (recommended)

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

Option 2: Environment variable

export NANSEN_API_KEY=your-api-key

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

Quick Start

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

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

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

# Search for an entity
nansen profiler search --query "Vitalik Buterin" --pretty

Commands

smart-money - Smart Money Analytics

Track trading and holding activity of sophisticated market participants.

| Subcommand | Description | |------------|-------------| | netflow | Net capital flows (inflows vs outflows) | | dex-trades | Real-time DEX trading activity | | perp-trades | Perpetual trading on Hyperliquid | | holdings | Aggregated token balances | | dcas | DCA strategies on Jupiter | | historical-holdings | Historical holdings over time |

Smart Money Labels:

• Fund - Institutional investment funds
• Smart Trader - Historically profitable traders
• 30D Smart Trader - Top performers (30-day window)
• 90D Smart Trader - Top performers (90-day window)
• 180D Smart Trader - Top performers (180-day window)
• Smart HL Perps Trader - Profitable Hyperliquid traders

profiler - Wallet Profiling

Detailed information about any blockchain address.

| Subcommand | Description | |------------|-------------| | balance | Current token holdings | | labels | Behavioral and entity labels | | transactions | Transaction history | | pnl | PnL and trade performance | | search | Search for entities by name | | historical-balances | Historical balances over time | | related-wallets | Find wallets related to an address | | counterparties | Top counterparties by volume | | pnl-summary | Summarized PnL metrics | | perp-positions | Current perpetual positions | | perp-trades | Perpetual trading history |

token - Token God Mode

Deep analytics for any token.

| Subcommand | Description | |------------|-------------| | screener | Discover and filter tokens | | holders | Token holder analysis | | flows | Token flow metrics | | dex-trades | DEX trading activity | | pnl | PnL leaderboard | | who-bought-sold | Recent buyers and sellers | | flow-intelligence | Detailed flow intelligence by label | | transfers | Token transfer history | | jup-dca | Jupiter DCA orders for token | | perp-trades | Perp trades by token symbol | | perp-positions | Open perp positions by token symbol | | perp-pnl-leaderboard | Perp PnL leaderboard by token |

portfolio - Portfolio Analytics

| Subcommand | Description | |------------|-------------| | defi | DeFi holdings across protocols |

schema - Schema Discovery

Output JSON schema for agent introspection. No API key required.

# Get full schema
nansen schema --pretty

# Get schema for specific command
nansen schema smart-money --pretty

Returns command definitions, option types/defaults, supported chains, and smart money labels.

cache - Cache Management

Manage the local response cache.

# Clear all cached responses
nansen cache clear

Options

| Option | Description | |--------|-------------| | --pretty | Format JSON output for readability | | --table | Format output as human-readable table | | --fields <list> | Comma-separated fields to include (reduces response size) | | --cache | Enable response caching | | --no-cache | Bypass cache for this request | | --cache-ttl <s> | Cache TTL in seconds (default: 300) | | --stream | Output as JSON lines (NDJSON) for incremental processing | | --chain <chain> | Blockchain to query | | --chains <json> | Multiple chains as JSON array | | --limit <n> | Number of results | | --days <n> | Date range in days (default: 30) | | --sort <field:dir> | Sort results (e.g., --sort value_usd:desc) | | --symbol <sym> | Token symbol for perp endpoints (e.g., BTC, ETH) | | --filters <json> | Filter criteria as JSON | | --order-by <json> | Sort order as JSON array (advanced) | | --labels <label> | Smart Money label filter | | --smart-money | Filter for Smart Money only | | --timeframe <tf> | Time window (5m, 10m, 1h, 6h, 24h, 7d, 30d) |

Supported Chains

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

AI Agent Integration

This CLI is built specifically for AI agents. Every design decision prioritizes agent usability.

Why agents love it:

• Structured Output: All responses are JSON with consistent schema — no parsing HTML or unstructured text
• Predictable Errors: Errors include status codes and actionable details agents can handle programmatically
• Zero Config: Works with just an API key — no complex setup
• Composable: Commands can be chained with shell pipes
• Discoverable: help commands at every level for agent introspection

// Success response
{
  "success": true,
  "data": {
    "results": [...],
    "pagination": {...}
  }
}

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

Examples

# Get trending tokens as a table, sorted by volume
nansen token screener --chain solana --sort buy_volume:desc --table

# Get Smart Money DEX trades from Funds only
nansen smart-money dex-trades --chain ethereum --labels Fund --table

# Get token holders with Smart Money filter
nansen token holders --token So11111111111111111111111111111111111111112 --chain solana --smart-money

# Get historical holdings for the past 7 days
nansen smart-money historical-holdings --chain solana --days 7

# Get BTC perpetual positions on Hyperliquid
nansen token perp-positions --symbol BTC --pretty

# Get top PnL traders for a token, sorted by realized PnL
nansen token pnl --token JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN --chain solana --days 30 --sort pnl_usd:desc --table

# Filter response to specific fields (reduces tokens for AI agents)
nansen smart-money netflow --chain solana --fields token_symbol,net_flow_usd,chain

# Get schema for agent introspection
nansen schema --pretty
nansen schema token --pretty

Development

# Run tests (mocked, no API key needed)
npm test

# Run with coverage
npm run test:coverage

# Run against live API
NANSEN_API_KEY=your-key npm run test:live

See CONTRIBUTING.md for development guidelines.

AI contributors: See CLAUDE.md for agent-specific guidance on contributing to this repo.

API Coverage

| Category | Endpoints | Coverage | |----------|-----------|----------| | Smart Money | 6 | 100% | | Profiler | 11 | 100% | | Token God Mode | 12 | 100% | | Portfolio | 1 | 100% | | Total | 30 | 100% |

License

MIT © Nansen