Nansen CLI

Overview

The Nansen CLI (nansen-cli) is a command-line interface for the Nansen API. All output is structured JSON, making it ideal for AI agents, scripts, and automation pipelines.

npm install -g nansen-cli

Or run without installing:

npx nansen-cli help

Source code: github.com/nansen-ai/nansen-cli

Authentication

The CLI uses the same API key as the REST API. Two options, in priority order:

Environment variable (recommended for agents and CI):

export NANSEN_API_KEY=your-api-key

Interactive login (persistent):

nansen login

Verify it works:

nansen schema | head -1

schema is free and requires no API key -- if you get JSON back, the CLI is installed correctly.

Quick Start

# Trending tokens on Solana
nansen token screener --chain solana --timeframe 24h

# Smart Money flows
nansen smart-money netflow --chain solana

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

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

Schema Discovery

The CLI is fully self-documenting via nansen schema. This requires no API key and returns a machine-readable JSON reference of all commands, options, return fields, and supported chains.

nansen schema --pretty                    # Full schema
nansen schema smart-money --pretty        # Single command group

Example: query supported chains:

nansen schema | jq '.supportedChains'

Agents should use nansen schema as the source of truth for available commands and options.

Output Format

All responses use a consistent JSON envelope:

{
  "success": true,
  "data": { ... }
}

Errors include a machine-readable code:

{
  "success": false,
  "error": "Invalid API key",
  "code": "UNAUTHORIZED",
  "status": 401
}

Key error codes: UNAUTHORIZED, CREDITS_EXHAUSTED, RATE_LIMITED, INVALID_ADDRESS, UNSUPPORTED_FILTER. See Error Handling for the full list.

Tips for AI Agents

Use schema for self-discovery. Agents should call nansen schema at the start of a session to learn available commands, options, and supported chains -- it costs zero credits.

Use --fields to reduce response size. Large JSON responses waste agent context tokens.

nansen smart-money netflow --chain solana --fields token_symbol,net_flow_usd --limit 10

Use --stream for large result sets. Processes results line-by-line instead of buffering the entire response.

nansen token dex-trades --chain solana --limit 100 --stream

Budget credits carefully. Most calls cost 1 credit. schema and help are free. If you get CREDITS_EXHAUSTED, stop all calls immediately.