nansen-cli

Nansen CLI

Built by agents, for agents. Command-line interface for the Nansen API, designed for AI agents to research on-chain data, manage wallets, and trade through nansen trade.

Use it for both analytics and execution: nansen research ... returns structured on-chain data, while nansen trade quote / nansen trade execute handle DEX swaps on Solana and Base, including cross-chain bridges.

Installation

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

Feedback

Send product feedback to Nansen with your configured API key or login session:

{
  "category": "missing_capability",
  "description": "I need to compare labels across 50 wallets but cannot find a bulk lookup.",
  "goal": "Compare labels across a wallet list."
}

Save the report as feedback.json. Omit the ID to save private recovery data before sending:

nansen feedback submit --file feedback.json --json
nansen feedback resume --json
nansen feedback get fb_123 --json

resume uses the saved ID and exact report bytes, even if the input file is gone. Changing the account, API environment or report stops replay. After confirmation, resume reads the receipt without sending another report. To deliberately start another report, use feedback submit --new --file feedback.json.

One recovery entry lives in ~/.nansen/feedback/recovery.json, with private permissions and a process lock. Confirmed receipts remove report content and keep only the submission ID, feedback ID, account, environment and expiry. Feedback recovery operations erase expired data when they next open the journal. Pending reports expire after one calendar year. No cleanup runs while the CLI is closed. nansen feedback forget erases local recovery data offline, leaving a content-free marker that prevents accidental replay. It does not delete your input file or a report on the server. A missing or erased server receipt also clears the local entry. Validation rejections erase the saved payload; correct the input and use --new to submit again. Forget also erases damaged journals. Do not back up pending report content.

Automatic IDs require POSIX private storage and the optional native locking binding. On Windows or when storage cannot be secured, supply a caller-managed --submission-id report-123 and keep that ID and the unchanged file for retries. This explicit-ID path does not save a local report. Recovery format version 1 survives upgrades; unsupported or damaged journals stop rather than start fresh. Older explicit-ID-only CLI releases do not read recovery journals; finish recovery with a supporting version before rolling back.

Remove --json for human output. received means saved, reviewed means triaged, and closed means review is complete. Review does not promise a fix or a date.

Feedback is free, with seven accepted reports per account each week, resetting Monday at 00:00 UTC. An exhausted allowance exits with its reset time; accepted IDs can still be replayed. Feedback bypasses caching and payment fallback. Remove secrets and unnecessary personal details from your report. A backend without feedback support reports an unavailable capability.

New submissions may be paused before release or during an outage. HTTP 503 with reason: feedback_admissions_paused means this attempt accepted no new report and used no weekly allowance. Tell the user feedback is unavailable, then stop; do not keep retrying or ask for approval again in the same session. Keep the ID and unchanged file for a later retry. Accepted-ID replays and receipt reads remain available during a pause.

Agents should check the saved account preference before sending feedback on their own. If enabled, they may send without asking again, subject to their host's controls. If off, unset or unavailable, show the proposed report and ask first. Approval for one report does not change the preference. Never enable it automatically. Use nansen feedback preferences --json for a fresh account read before each new automatic report. Without --json, it prints a human summary. Reads use no credits or report quota. Change the lasting choice in Superapp settings. An explicit user request to send the report needs no additional preference check. The submit command sends the report without an interactive prompt.

HTTP 403 with reason: feedback_not_enabled means feedback is not enabled for this account. Stop automatic retries. Approval or an enabled preference does not override rollout. Keep the ID and unchanged report for recovery; an earlier uncertain attempt remains uncertain. Never switch accounts or pay to bypass denial.

Auth

Plain nansen login requests fresh browser approval and saves a session automatically. No API-key copying or PEM setup is needed. Selected sessions renew automatically; rejected or uncertain renewal requires fresh login.

nansen login                 # approve the displayed code, account and CLI
nansen login --no-browser    # approve on another device; same storage requirements
nansen auth status           # offline, cached/unverified credential selection
nansen account               # free live check, including with zero research credits
nansen logout                # clear saved API auth; preserve wallets and environment keys

Browser login is available in Nansen CLI 2.0.0 and enabled in production. Saved browser sessions are currently qualified on macOS arm64 in a local GUI Terminal with an unlocked login Keychain and local home directory. Other platforms and terminal environments still need qualification. See storage, supported scope and recovery. Email/password and Google sign-in are supported by the device-flow contract. Apple device sign-in remains deferred.

Existing API-key users can run commands directly with NANSEN_API_KEY. It overrides the saved session, even after successful browser login. To deliberately save an injected key, use explicit nansen login --human; without an environment key this prompts in a human terminal. nansen login --api-key <key> remains available but puts the key in shell history. Saved-auth mutations require the native lock binding. Get a conventional key at agent setup; MCP installation exports a separate persistent API key; it does not export browser sessions.

For automation, pipe a key from your secret manager into nansen login --api-key-stdin, or redirect a protected key file:

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

This reads one key (up to 4096 bytes, with an optional trailing newline), verifies it, and saves it without printing it. Input must close within 30 seconds. --json prints one saved event with the effective credential source; errors exit nonzero. As with existing API-key login, the key is stored in ~/.nansen/config.json using an atomic write with owner-only file permissions (0600 on POSIX), not in the OS keychain. The native lock binding is required for saving credentials. It does not create an account or issue a key. Avoid commands containing literal secrets, which may enter shell history. Do not combine it with --api-key, --human, or --no-browser. An existing NANSEN_API_KEY still overrides the saved credential until you unset it.

Wallet and micropayment options:

• x402: create and fund a wallet with USDC on Base/Solana or USDT0 on X Layer. API keys, browser sessions and anonymous requests can all pay a supported HTTP 402 challenge under the same wallet policy and spending limits. The paid retry sends Payment-Signature without the account credential. Authentication or authorization failures never trigger payment. Explicit manual API-key payment signatures remain supported.
• MPP: install the separate tempo CLI and use tempo request. Browser login does not configure a wallet, sign MPP credentials or purchase credits. See MPP / Tempo.

Verify your MCP setup

For the hosted Nansen MCP server, verify server reachability and the supplied API key on the paid data path with:

npx -y nansen-cli mcp verify  # uses the saved key or NANSEN_API_KEY

The check calls tools/list for reachability, then calls the paid nansen_score_top_tokens canary tool. A successful canary costs about 1 credit; tool listings and free tools alone do not prove that a key works. The CLI cannot inspect the key inside your MCP client, so make sure this same key is in the client's NANSEN-API-KEY header. For the final client-config check, ask your client: “Use the nansen_score_top_tokens tool.”

Commands

nansen research <category> <subcommand> [options]
nansen agent "<question>"             # AI research agent (200 credits, Pro)
nansen agent "<question>" --expert    # deeper analysis (750 credits, Pro)
nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
nansen trade execute --quote <quoteId>
nansen wallet <subcommand> [options]
nansen mcp install <client>           # add the Nansen MCP server to Claude Code/Desktop or Cursor
nansen completion <bash|zsh|fish>     # shell completions (no API key needed)
nansen schema [command] [--pretty]    # full command reference (no API key needed)
nansen cache stats                    # what the local caches hold (no API key needed)

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

The points leaderboard API has been removed. nansen research points leaderboard and the legacy command nansen points leaderboard return success: false with code COMMAND_UNAVAILABLE and exit status 1, without making an API request.

Direct research subcommands:

• nansen research chain-rank [--timeframe-days 7|30|365] [--chain-type all|evm] — rank chains by growth metrics
• nansen research token-sectors — list token sectors available for filtering
• nansen research address-premium-labels --address <addr> [--chain <chain>] [--page <n>] [--limit <n>] — get all labels for an address, including premium labels
• nansen research smart-money-pnl-leaderboard [--chains c1,c2] [--timeframe-days 1|7|30|90|180] [--filters '<json>'] [--sort <field[:asc|desc]>] [--page <n>] [--limit <n>] — rank smart money wallets by PnL
• nansen research position-intelligence --symbol <symbol> — aggregate Hyperliquid positions by trader cohort
• nansen research perp-pnl-summary --address <addr> --from-date <date> --to-date <date> — summarize realized Hyperliquid PnL for an address
• nansen research transaction-with-token-transfer-lookup --transaction-hash <hash> [--chain <chain>] [--block-timestamp "YYYY-MM-DD HH:MM:SS"] — look up a transaction and its token/NFT transfers

Plus the historical-* point-in-time commands — run nansen research help for the full list.

Trade: quote, execute, bridge-status, limit-order — DEX swaps on Solana and Base, cross-chain bridges, and Solana limit orders.

Wallet: create, list, show, export, default, delete, send, forget-password, secure — local or Privy server-side wallets (EVM + Solana).

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

Browser login compatibility and scope

Browser login requests nansen:api for the same account/API permissions as a pasted API key, including smart-alert CRUD, public agent, portfolio, web, beta and existing trading API operations. The same endpoint ownership, plan, credit, quota, sanctions and geographic checks apply. Existing OAuth/MCP nansen:read grants keep their existing semantics. Wallet signing remains separate.