Nansen CLI

Overview

The Nansen CLI (nansen-cli) is a command-line interface for the Nansen API. Research commands return structured JSON by default. Login and other operational commands also support human-readable output.

npm install -g nansen-cli

Or run without installing:

npx nansen-cli help

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

Authentication

First confirm that the CLI is installed:

nansen --version

--version needs no credential. Use version 2.0.0 or newer for browser login.

Browser login is enabled in production. Plain nansen login opens a browser and asks you to approve the CLI for your Nansen account. Check the displayed code, account, client, and requested access before approving. The CLI then verifies the account and saves a renewable session in your operating system's credential store. You do not need to copy an API key. Sign in with email and password or Google. Apple sign-in is not supported by this flow.

nansen login

If the CLI cannot open a browser on the same machine, start the approval flow without launching one automatically:

nansen login --no-browser

Open the displayed link on another device and approve the matching code. The terminal does not need an inbound callback, but it still needs access to a supported, unlocked credential store.

Browser login requires Nansen CLI 2.0 or newer. The initial release is qualified only for macOS on Apple silicon, a local Terminal in a GUI login session, an unlocked login Keychain, and a local home directory. Background agents, SSH sessions, and network or synchronized home directories are not qualified. Linux remote-terminal qualification is pending, and Windows is not included in the initial release. API-key commands remain available on those systems.

If Keychain is locked, unlock it and retry. Repeating browser approval does not repair credential-store access. See the browser-login recovery guide for storage, renewal, and uncertain logout failures.

Check which credential the CLI will use, then verify it against the API:

nansen auth status
nansen account

auth status is an offline check. It labels saved account and expiry details as cached and unverified. account is the free live API check.

Ordinary commands renew a selected browser session automatically without opening the browser. If renewal is rejected or its result is uncertain, run a fresh nansen login.

Existing API keys still work for direct commands and automation:

export NANSEN_API_KEY=your-api-key

NANSEN_API_KEY takes priority over a saved browser session. If it is set when you complete browser login, the CLI saves the new session but continues using the environment key until you unset it.

When upgrading from CLI 1.x, note that plain nansen login no longer saves an environment key or prompts for an API key. Direct commands using NANSEN_API_KEY need no migration. To save a key, use an explicit legacy mode: --human, --api-key, or --api-key-stdin.

nansen login --human saves NANSEN_API_KEY when the variable is set. Unset it first to enter the key through a masked interactive prompt:

unset NANSEN_API_KEY
nansen login --human

For automation, pipe a key from your secret manager or redirect a protected key file:

nansen login --api-key-stdin --json < /path/to/protected-api-key

nansen login --api-key <key> also remains available, but the key may be recorded in shell history. Plain nansen login never copies NANSEN_API_KEY into saved configuration. Failed or cancelled browser login preserves the previously saved local credential. A lost final response is not proof that the server issued no session; follow the recovery guide if approval completed but login did not finish locally.

To sign out:

nansen logout

Logout removes saved API authentication and attempts to revoke a saved browser session. It does not unset environment variables, remove wallets or wallet passwords, revoke independently managed API keys, or sign out other devices. Local removal, a server retirement receipt, and API rejection are separate outcomes, so revocation may not take effect immediately. If the credential store is locked or remote retirement is unconfirmed, follow the recovery guide and treat the session as potentially usable.

Quick Start

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

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

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

# Search for an entity
nansen research search "Vitalik Buterin" --type entity

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

Research commands use this JSON envelope by default. --table, --format csv, --fields and --stream change the output shape:

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

Research 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. These are the CLI's own codes: it maps the HTTP API's lowercase code values onto them, so they differ from the codes listed in Error Handling.

Human login output is not a single JSON response. nansen login --json and non-TTY login emit newline-delimited JSON events: normally a pending approval event followed by one terminal result. A preflight error emits only the terminal error. nansen auth status reports cached selection without contacting the API.

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 research smart-money netflow --chain solana --fields token_symbol,net_flow_usd --limit 10

Use --stream for line-oriented tools. Emits each returned record as an NDJSON line. This is an output format, not a guarantee that the API response is fetched without buffering.

nansen research token dex-trades --chain ethereum \
  --token 0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9 \
  --limit 100 --stream

Budget credits and payments. Research costs vary by endpoint. schema, help, login verification and account are free. A supported HTTP 402 challenge can trigger automatic x402 payment from a configured wallet, subject to wallet authorization, payment policy and spending limits. The paid retry sends only the payment credential; it does not top up account credits or change saved authentication. Authentication, authorization and renewal failures never trigger payment. If a command returns CREDITS_EXHAUSTED, stop and ask the user how to proceed. See the payment behavior.