Package Exports

nansen-cli
nansen-cli/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (nansen-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Nansen CLI

Built by agents, for agents. Command-line interface for the Nansen API with structured JSON output.

Installation

npm install -g nansen-cli
npx skills add nansen-ai/nansen-cli  # load agent skill files

Auth

nansen login              # interactive — saves to ~/.nansen/config.json
export NANSEN_API_KEY=... # or env var (highest priority)

Get your API key at app.nansen.ai/api. AI agents can use the Agent Setup flow instead.

Commands

nansen research <category> <subcommand> [options]
nansen trade <subcommand> [options]
nansen wallet <subcommand> [options]
nansen schema [command] [--pretty]    # full command reference (no API key needed)

Research categories: smart-money (sm), token (tgm), profiler (prof), portfolio (port), search, perp, points

Trade: quote, execute — DEX swaps via LiFi/Jupiter.

Wallet: create, list, show, export, default, delete, send — local keypairs (EVM + Solana).

Run nansen schema --pretty for the full subcommand and field reference.

Key Options

Option	Description
`--chain <chain>`	Blockchain to query
`--limit <n>`	Result count
`--timeframe <tf>`	Time window: `5m` `1h` `6h` `24h` `7d` `30d`
`--fields <list>`	Comma-separated fields (reduces response size)
`--sort <field:dir>`	Sort results, e.g. `--sort value_usd:desc`
`--pretty`	Human-readable JSON
`--table`	Table format
`--stream`	NDJSON output for large results
`--labels <label>`	Smart Money label filter
`--smart-money`	Filter for Smart Money addresses only

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 Tips

Reduce token burn with --fields:

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

Use --stream for large results — outputs NDJSON instead of buffering a giant array.

ENS names work anywhere --address is accepted: --address vitalik.eth

Output Format

{ "success": true,  "data": <api_response> }
{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401 }

Critical error codes:

Code	Action
`CREDITS_EXHAUSTED`	Stop all API calls immediately. Check app.nansen.ai.
`UNAUTHORIZED`	Wrong or missing key. Re-auth.
`RATE_LIMITED`	Auto-retried by CLI.
`UNSUPPORTED_FILTER`	Remove the filter and retry.

Troubleshooting

Symptom	Fix
`command not found`	`npm install -g nansen-cli`
`UNAUTHORIZED` after login	`cat ~/.nansen/config.json` or set `NANSEN_API_KEY`
Empty perp results	Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only.
`UNSUPPORTED_FILTER` on token holders	Remove `--smart-money` — not all tokens have that data.
Huge JSON response	Use `--fields` to select columns.

Development

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

See AGENTS.md for architecture and contributor guidance.

nansen-cli