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.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nansen-ai/nansen-cli with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nansen-ai/nansen-cli'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/nansen-ai--nansen-cli)HTML
<a href="/listings/nansen-ai--nansen-cli"><img src="/api/listings/nansen-ai--nansen-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
npm install -g nansen-cli npx skills add nansen-ai/nansen-cli # load agent skill files
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 650 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # Nansen CLI
- [](https://www.npmjs.com/package/nansen-cli)
- [](https://opensource.org/licenses/MIT)
- > **Built by agents, for agents.** Command-line interface for the [Nansen API](https://docs.nansen.ai), 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
- ```bash
- npm install -g nansen-cli
- npx -y skills add nansen-ai/nansen-cli --skill "*" -y # install every agent skill, no prompts
- ```
- Without `--skill "*" -y`, `skills add` opens a picker: space selects a skill, enter confirms.
- ## Feedback
- Send product feedback to Nansen with your configured API key or login session:
- ```json
- {
- "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."
- }
- ```
- `category` and `description` are required. `category` is one of `bug`,
- `data_quality`, `documentation`, `missing_capability`, `usability` or `other`.
- A feature request or product gap is `missing_capability`. `description` says
- what happened and what was needed, in up to 2,000 characters. Optional fields
- are `endpoint` and `tool` (up to 256 characters each), `goal`,
- `expected_behavior`, `observed_behavior` and `workaround` (up to 2,000
- characters each), `request_ids` (up to 10 of your own request IDs) and
- `client` (`{"name": ..., "version": ...}`, attribution only). The API rejects
- any other field or category with a 422, so leave out fields such as `title`,
- `summary` or `severity`. Write plain sentences without Markdown or code
- formatting. `nansen feedback submit --help` prints the same list.
- Save the report as `feedback.json`. Omit the ID to save private recovery data before sending:
- ```bash
- 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
- Pick one of three ways to authenticate and pay for API calls.
- **Nansen account.** Calls use your account's plan and credits. `nansen login` approves the CLI in your browser and saves a session. On a server, in a container or in CI, set `NANSEN_API_KEY` to a key from [the API page](https://app.nansen.ai/api) instead.
- ```bash
- nansen login
- ```
- **x402.** Pay per call from a CLI wallet funded with USDC on Base or Solana, or USDT0 on X Layer. When the API answers with HTTP 402, the CLI pays from your default wallet and retries. Each payment is capped at $1.00 by default; set `NANSEN_X402_MAX_AMOUNT` to change it. Your first wallet becomes the default. The wallet needs a password of at least 12 characters. The CLI saves it for later payments, in the OS keychain when one is available.
- ```bash
- NANSEN_WALLET_PASSWORD='<your-wallet-password>' nansen wallet create --name my-wallet
- ```
- **MPP via tempo.** Pay per call through the separate [tempo CLI](https://docs.tempo.xyz). The Nansen CLI does not sign MPP payments. After the [one-time tempo setup](#mpp--tempo):
- ```bash
- tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
- ```
- [docs/auth.md](docs/auth.md) covers headless setup, saving an API key, browser-session storage and how x402 payment works with each credential.
- ## Verify your MCP setup
- For the hosted Nansen MCP server, verify server reachability and the supplied API key on the paid data path with:
- ```bash
- 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 (100 credits)
- nansen agent "<question>" --expert # deeper analysis (400 credits)
- 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 (with `--help` too). The command is no longer listed in `nansen schema`, help or completions.
- **Direct research subcommands:**
- - `nansen research chain-rank [--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] [--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).
- **Alerts:** `list`, `create`, `update`, `toggle`, `delete` — smart alerts delivered to Telegram, Slack, Discord or a webhook. Give a webhook's signing secret through stdin or the environment, not on the command line, so it stays out of shell history and the process list:
- ```bash
- nansen alerts create --name 'ETH SM inflow' --type sm-token-flows --chains ethereum --inflow-1h-min 1000000 \
- --webhook https://example.com/hook --webhook-secret-stdin < webhook-secret.txt
- NANSEN_WEBHOOK_SECRET="$(cat webhook-secret.txt)" nansen alerts update <id> --webhook https://example.com/hook
- ```
- `--webhook-secret <secret>` still works. It cannot be combined with `--webhook-secret-stdin`, and either flag overrides `NANSEN_WEBHOOK_SECRET`, which is read only when `--webhook` is given. Alerts output redacts channel credentials unless you pass `--reveal`.
- Run `nansen schema --pretty` for the full subcommand and field reference.
- ## MCP
- <!-- BEGIN GENERATED: mcp. Do not edit by hand. Edit src/mcp-client-config.json (values) or scripts/templates/readme-mcp.md (prose), not README.md, then run: npm run mcp:generate. -->
- Connect any MCP client to Nansen's streamable HTTP server:
- - **Endpoint:** `https://mcp.nansen.ai/ra/mcp`
- - **Authentication:** `NANSEN-API-KEY` header
- - **API key:** [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup)
- One-step install of the hosted [Nansen MCP server](https://docs.nansen.ai/mcp/overview) (`https://mcp.nansen.ai/ra/mcp`) into a local MCP client:
- ```bash
- nansen mcp install claude-code # ~/.claude.json (user scope)
- nansen mcp install claude-desktop # macOS/Windows only; bridges via pinned mcp-remote
- nansen mcp install cursor # ~/.cursor/mcp.json
- nansen mcp install cursor --dry-run # print what would be written (key redacted)
- nansen mcp uninstall <client> # remove the entry (add --dry-run to preview)
- ```
- Uses the API key from `nansen login --human` / `NANSEN_API_KEY`; re-run `install` after rotating your key. Writes are merge-only and atomic: existing servers and settings are preserved, a `.bak` copy is written before every install or uninstall, and the CLI refuses to touch a config it can't parse. Note the client config stores the API key in plaintext — new files are created with `0600` permissions. Restart the client after installing.
- **Manual setup**, for other clients or if you would rather not use the CLI — the paths below, and the connection docs at [docs.nansen.ai/mcp/connecting](https://docs.nansen.ai/mcp/connecting).
- **One-command (Claude Code):**
- ```bash
- claude mcp add --transport http nansen https://mcp.nansen.ai/ra/mcp --header "NANSEN-API-KEY: <your-key>"
- ```
- **Manual (any streamable-HTTP client):** for example, add this to Cursor's `~/.cursor/mcp.json`:
- ```json
- {
- "mcpServers": {
- "nansen": {
- "url": "https://mcp.nansen.ai/ra/mcp",
- "headers": {
- "NANSEN-API-KEY": "<your-key>"
- }
- }
- }
- }
- ```
- **Manual (stdio-only clients):** use `mcp-remote` as a bridge. Keep the header name and value in a single `args` entry, and keep the key in `env` rather than in the argument list — `mcp-remote` substitutes `${NANSEN_API_KEY}` from the environment:
- ```json
- {
- "mcpServers": {
- "nansen": {
- "command": "npx",
- "args": [
- "-y",
- "mcp-remote@0.2.1",
- "https://mcp.nansen.ai/ra/mcp",
- "--header",
- "NANSEN-API-KEY:${NANSEN_API_KEY}"
- ],
- "env": {
- "NANSEN_API_KEY": "<your-key>"
- }
- }
- }
- }
- ```
- `mcp-remote` is pinned to an exact version rather than `@latest` because the bridge handles your API key on every request, and `npx` would otherwise pull a new release automatically. `0.2.1` is the version this config is tested against. A weekly check reports when a newer release exists; to bump the pin, review the release and follow [MCP client config](AGENTS.md#mcp-client-config).
- **Claude Tag (Claude in Slack):** an admin must attach a plugin whose `.mcp.json` points at `https://mcp.nansen.ai/ra/mcp` and add a custom credential allowing the host `mcp.nansen.ai`. See the [Claude Tag custom-connections documentation](https://claude.com/docs/claude-tag/admins/connections/custom). Per-user fallback: use Claude Code or Claude Desktop.
- <!-- END GENERATED: mcp -->
- ## Trading
- DEX swaps on `solana` and `base`. Two-step: quote then execute.
- ```bash
- nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
- nansen trade execute --quote <quoteId>
- ```
- Cross-chain swaps work the same way — add `--to-chain`. Bridge providers (Li.Fi or Relay) are selected automatically based on best price.
- ```bash
- nansen trade quote --chain base --to-chain solana --from ETH --to SOL --amount 0.0003 --amount-unit token
- nansen trade execute --quote <quoteId> # signed broadcast
- nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
- ```
- ### Before broadcasting
- `trade execute`, `bridge execute`, and the signing limit-order operations (`limit-order create` and `limit-order cancel`) accept:
- ```bash
- nansen trade execute --quote <quoteId> --dry-run # validate + print the plan, broadcast nothing
- nansen trade execute --quote <quoteId> --yes # skip the confirmation prompt (also: -y)
- nansen trade limit-order create ... --dry-run # preview intent; no API request or signature
- nansen trade limit-order cancel --order <id> --dry-run # does not request/consume a cancellation tx
- ```
- `--dry-run` runs every sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints what *would* be sent (chain, tokens, amounts, recipient, approvals, fees); and stops before wallet credentials, signing, or broadcast — no wallet password needed, the quote stays usable, exit code 0. Real execution still resolves and revalidates the live signer before signing.
- On EVM, both commands refuse a transaction whose worst-case gas cost (fee cap × gas limit) is above 1 ETH, before anything is signed, approvals included. That is a backstop against an anomalous quote, the same kind of cap geth and reth apply to `eth_sendTransaction`. `--max-tx-fee <eth>` changes it, and `--max-tx-fee 0` turns it off. WalletConnect transactions are not checked, since the wallet shows the fee before signing.
- For limit orders, `--dry-run` is a non-consuming intent preview built from locally validated arguments and the wallet's public address. It returns before limit-order authentication, custom-token metadata RPC lookups, transaction crafting, transaction signing, or final submission. Create preview does not submit an order; cancel preview does not request or consume the API's one-time cancellation transaction. Real execution performs the existing transaction and outcome validation after acknowledgement.
- When stdin is an interactive terminal, each guarded command prints its plan and asks for confirmation first (`Broadcast this transaction?`, `Create this limit order?`, or `Cancel this limit order?`); anything but `y`/`yes` aborts with exit code 1 and nothing signed. `--yes`, `-y`, or `NANSEN_YES=1` skips only the question. **When stdin is not a terminal — agents, CI, pipes — nothing changes: the command proceeds without prompting**, and `--yes` is accepted as a no-op so it is always safe to pass.
- To make an agent stop for your go-ahead, set `NANSEN_REQUIRE_CONFIRM=1` in its environment. Then, when stdin is not a terminal, every guarded command (`trade execute`, `bridge execute`, `trade limit-order create`/`cancel`, `perp order`/`close`/`cancel`/`leverage`/`transfer`/`approve-builder-fee`) run without `--yes` or `NANSEN_YES=1` fails with exit code 1 and code `CONFIRMATION_REQUIRED` before it makes any request or signs anything. `--dry-run` still previews. Unset (the default), behaviour is unchanged.
- | Exit code | Meaning |
- |-----------|---------|
- | `0` | Broadcast succeeded, or the dry run completed |
- | `1` | Declined at the confirmation prompt, refused by `NANSEN_REQUIRE_CONFIRM`, or the execution failed |
- Amounts are in base units (lamports, wei) by default — use `--amount-unit token|usd|percent` for friendlier inputs. Common symbols (`SOL`, `ETH`, `USDC`, `USDT`) resolve automatically. A wallet is required — set one with `nansen wallet default <name>`.
- ## Limit Orders
- Native price-triggered orders on **Solana**. Four subcommands:
- ```bash
- nansen trade limit-order create \
- --from SOL --to USDC \
- --amount 1.5 \
- --trigger-mint SOL --trigger-condition below --trigger-price 80 \
- --slippage-bps 300 --expires 7d
- nansen trade limit-order list # all orders
- nansen trade limit-order list --state active # only open
- nansen trade limit-order list --state past # filled or cancelled
- nansen trade limit-order cancel --order <orderId>
- nansen trade limit-order update --order <orderId> --trigger-price 85
- ```
- `--amount` is in token units (`1.5` = 1.5 SOL). `--slippage-bps` is basis points (`300` = 3%, `100` = 1%); omit for auto. Minimum order value ~$10 (server-enforced). Local, Privy, and WalletConnect wallets all work.
- Add `--dry-run` to `create` or `cancel` for a no-API, no-signature intent preview. In an interactive terminal these two commands otherwise ask for confirmation; pass `--yes`/`-y` (or set `NANSEN_YES=1`) to skip the prompt. Non-TTY automation remains unprompted.
- For EVM chains, there's no native limit-order surface — pair an external venue's resting order with a `common-token-transfer` smart alert on the settlement wallet as a best-effort fill signal. See the `nansen-limit-orders` skill for details.
- ## Perpetuals
- Hyperliquid perpetual trading via `nansen perp`. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as DEX trading (requires an EVM wallet). Select the asset with `--symbol` (`--coin` is accepted as an alias).
- ```bash
- nansen perp meta --filter ETH # list assets + max leverage
- nansen perp order --symbol ETH --side buy --size 0.1 --price 1600 --type limit
- nansen perp order --symbol BTC --side sell --size 0.001 --price 95000 --type market \
- --take-profit 90000 --stop-loss 98000
- nansen perp close --symbol ETH --size 0.1 --price 1600 --side sell # sell closes a long
- nansen perp cancel --symbol ETH --oid <orderId>
- nansen perp leverage --symbol ETH --leverage 5 --margin-type cross # or isolated
- nansen perp transfer --direction spot-to-perp --amount 25 # Spot<->Perps (or perp-to-spot)
- nansen perp positions
- nansen perp account # value, unrealized PnL, margin, spot USDC
- ```
- `--side` is `buy`/`long` or `sell`/`short` to open (`buy`/`sell` to close); `--tif` is `Gtc`/`Ioc`/`Alo`; `--slippage` is a decimal in `[0,1]`; `--leverage` is a whole integer capped at the asset max. Perp orders are irreversible once signed: add `--dry-run` to `order`, `close`, `cancel`, `leverage`, `transfer` or `approve-builder-fee` to print the plan without signing anything. In an interactive terminal these commands ask for confirmation first (`--yes`/`-y` or `NANSEN_YES=1` skips it); off a terminal they submit without asking, as before. USDC sent to a wallet via Hyperliquid's **Send** lands in the **Spot** balance (shown as `Spot USDC`); move it to Perps with `perp transfer` before trading. `perp positions` prints each position's leverage and margin mode next to Hyperliquid's liquidation price (`lev=1x cross liq=1.37`). On cross margin the liquidation price depends on the whole account's equity, so even a 1x position can have one close to the market price; `liq=n/a` means the exchange reports no liquidation price. See the `nansen-trading` skill for details.
- ## Bridge
- Move USDC between EVM chains and Hyperliquid via `nansen bridge`. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as perps and DEX trading. Quotes are written to a local file and executed by id; execution signs and broadcasts.
- ```bash
- nansen bridge quote --from-chain base --to-chain hyperliquid --from-token USDC --amount 1000000
- nansen bridge execute --quote <quoteId>
- nansen bridge execute --quote <quoteId> --dry-run # preview, nothing is broadcast
- nansen bridge execute --quote <quoteId> --nonce 20 --priority-fee 5 # replace a stuck EVM deposit
- nansen bridge status --request-id <id>
- ```
- Supported routes: `base → hyperliquid` (deposit), and `hyperliquid → base`/`ethereum`/`arbitrum` (withdraw). Deposits broadcast an EVM transaction locally, so only Base is offered on the deposit side; run `nansen bridge help` for the current list. `--amount` is a base-unit integer by default; pass `--amount-unit token` for a human amount. `--recipient` defaults to the wallet's own EVM address. `--priority-fee`/`--max-fee` (gwei) and `--nonce` apply only to EVM deposit legs and let a stuck transaction be replaced. Bridge transfers are irreversible once signed, so `bridge execute` takes the same `--dry-run` and `--yes`/`NANSEN_YES` gate as `trade execute` (see [Before broadcasting](#before-broadcasting)); on a multi-step transfer, a dry run stops before the first step.
- ## Wallet
- ```bash
- nansen wallet create --name my-wallet # local keypair (EVM + Solana)
- nansen wallet create --name my-wallet --provider privy # server-side via Privy
- nansen wallet list
- nansen wallet default <name>
- nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
- nansen wallet send --to <addr> --amount 25 --chain base --token USDC # USDC, USDT or a token address
- nansen wallet secure # move a password from .credentials or the env var into the OS keychain
- nansen wallet forget-password # drop the saved password from every store
- ```
- **Local wallets** are encrypted with a password of at least 12 characters. `wallet create` reads it from `NANSEN_WALLET_PASSWORD`, or reuses the password an earlier `wallet create` saved, and does not prompt; without one the command fails with `PASSWORD_REQUIRED` (agents: ask the user for a password, never make one up). When no password is set or saved, pass `--human` to be prompted for one in an interactive terminal. On success the CLI saves the password to the OS keychain, or to `~/.nansen/wallets/.credentials` (plaintext) when no keychain is available, and later wallet commands read it from there. If neither can be written, the wallet is still created but the password is not saved: keep `NANSEN_WALLET_PASSWORD` set for every later wallet command. `nansen wallet secure` moves a password from that file or the env var into the keychain.
- ```bash
- NANSEN_WALLET_PASSWORD='<password-from-user>' nansen wallet create --name my-wallet
- ```
- `wallet send --token` takes `USDC`, `USDT` or a token contract (EVM) or mint (Solana) address; omit it to send the native currency. `--chain` is `evm` (Ethereum), `ethereum`, `base` or `solana`.
- **Privy wallets** are server-side — no password, no local key storage. Requires `PRIVY_APP_ID` and `PRIVY_APP_SECRET` env vars. Get credentials at [dashboard.privy.io](https://dashboard.privy.io).
- ## MPP / Tempo
- The Nansen API supports [MPP](https://mpp.dev/protocol) (Tempo's stablecoin payment rail) as an alternative to API keys and x402. MPP is handled by the **separate** [tempo CLI](https://docs.tempo.xyz) — `nansen-cli` itself does not sign MPP credentials. You use the two CLIs side-by-side.
- **One-time setup:**
- ```bash
- # 1. Install the tempo CLI
- curl -fsSL https://tempo.xyz/install | bash
- # 2. Log in + fund the tempo wallet
- tempo wallet login
- tempo wallet fund # follow the on-screen instructions to deposit USDC
- ```
- **Calling the Nansen API via tempo:**
- ```bash
- tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow \
- --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
- ```
- `tempo request` handles the full `Authorization: Payment` challenge/response: on a 402 with `WWW-Authenticate: Payment ...` it signs a Tempo credential, retries, and surfaces the `Payment-Receipt` header on success.
- **When to use which rail:**
- | Situation | Rail |
- |---|---|
- | You have a subscription | API key |
- | You want anonymous pay-per-call with a Base/Solana wallet you already manage | x402 (`nansen wallet`) |
- | You hold USDT0 on X Layer and want to pay from there | x402 (`nansen wallet`) |
- | You already use tempo for other paid APIs, or want micropayments without managing your own wallet keys | MPP (`tempo request`) |
- > Note: MPP is server-side opt-in (`MPP_ENABLED=true` on the API). It's available on dev today and rolling out to prod — if `tempo request` returns a non-MPP 402, fall back to x402 or an API key.
- ## Shell Completions
- Tab-completion for commands, subcommands, flags, and the values a flag accepts:
- ```bash
- # bash
- echo 'eval "$(nansen completion bash)"' >> ~/.bashrc
- # or system-wide: nansen completion bash > /etc/bash_completion.d/nansen
- # zsh
- nansen completion zsh > "${fpath[1]}/_nansen" && compinit
- # or, in ~/.zshrc after the compinit line: eval "$(nansen completion zsh)"
- # fish
- nansen completion fish > ~/.config/fish/completions/nansen.fish
- ```
- The scripts are generated from the same schema as `nansen schema`, so they cover
- every nested subcommand and stay in step with the CLI. Nothing is written to
- disk and no network call is made — the script goes to stdout. Re-run the command
- after upgrading the CLI to pick up new commands.
- ## 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); a bare name matches at any depth, a dotted path such as `data.results.address` only at that position |
- | `--sort <field:dir>` | Sort results, e.g. `--sort value_usd:desc` |
- | `--pretty` | Human-readable JSON |
- | `--table` | Table format |
- | `--stream` | NDJSON output for large results |
- | `--paginate` | Fetch every page of a list command (alias `--all`); bound with `--max-pages <n>` (default 10; ignored without pagination) |
- | `--labels <label>` | Smart Money label filter |
- | `--smart-money` | Filter for Smart Money addresses only |
- | `--cache` | Serve this invocation from the local cache (see [Caching](#caching)) |
- | `--no-cache` | Bypass the cache for this invocation |
- | `--debug` | Trace every HTTP request on stderr (see [Debugging](#debugging)) |
- ## Caching
- Response caching is **off by default** and opt-in per invocation:
- ```bash
- nansen research token screener --chain solana --cache # cache this result
- nansen research token screener --chain solana --cache --cache-ttl 60
- nansen research token screener --chain solana --cache --no-cache # veto: always live
- ```
- `NANSEN_NO_CACHE=1` does the same as `--no-cache` without a flag, for wrappers
- that cannot change the command line.
- With `--cache` on, every read the CLI makes through the Nansen API client is
- cached — all of `nansen research ...`, plus `alerts list` and `alerts get`.
- Never cached: `account`, `web search`, the `alerts`
- create/update/toggle/delete commands, `agent`, every `trade`, `bridge`, `wallet`
- and `mcp` command, and `perp` trading. The analytics commands `perp screener`
- and `perp leaderboard` are cached.
- Inspect and clear what is on disk:
- ```bash
- nansen cache stats # entries, size, age, effective TTL per cache
- nansen cache stats --json # the same numbers as an object
- nansen cache clear # delete cached API responses
- nansen cache clear cost-map # or update-check, or all
- ```
- `nansen cache stats` reports totals and ages. It reads timestamp metadata but does not print cached payloads, request parameters, or cache keys. `nansen cache clear` deletes only files in the selected cache. Credentials, wallets, saved quotes, and config are never changed. CLI startup loads the saved config as usual.
- | Cache | Location | TTL |
- |-------|----------|-----|
- | `responses` | `~/.nansen/cache` | `--cache-ttl`, default 300s |
- | `cost-map` | `~/.nansen/cost-map.json` | 24h |
- | `update-check` | `~/.nansen/update-check.json` | 24h |
- ## Debugging
- `--debug` (or `NANSEN_DEBUG=1`) prints HTTP trace events to **stderr**, so stdout stays pure JSON/CSV and stays pipeable:
- ```bash
- nansen research token screener --chain solana --debug
- nansen research token screener --chain solana 2>trace.log | jq . # trace to a file, JSON to jq
- ```
- ```
- [nansen:debug] http.request method=POST url=https://api.nansen.ai/api/v1/token-screener attempt=1/4
- [nansen:debug] http.response method=POST url=https://api.nansen.ai/api/v1/token-screener status=429 duration_ms=182 request_id=6f1c0f2a-0000-4000-8000-0000000000aa attempt=1
- [nansen:debug] http.retry method=POST url=https://api.nansen.ai/api/v1/token-screener status=429 attempt=1 reason=retry-after delay_ms=1100 retry_after_ms=1000
- [nansen:debug] http.request method=POST url=https://api.nansen.ai/api/v1/token-screener attempt=2/4
- [nansen:debug] http.response method=POST url=https://api.nansen.ai/api/v1/token-screener status=200 duration_ms=143 request_id=6f1c0f2a-0000-4000-8000-0000000000ab attempt=2
- ```
- Events: `http.request`, `http.response`, `http.retry`, `http.error`, `http.cache_hit` (answered from the local cache, no request made).
- For `http.response`, `duration_ms` is the elapsed time from starting the attempt until response headers arrive (time to first byte / TTFB). It deliberately excludes downloading and parsing the response body. For `http.error`, `duration_ms` is the elapsed time until the transport failed before any response headers arrived.
- **What the trace never contains.** No API keys, wallet keys, mnemonics or payment signatures; no `Authorization`, `apikey` or `Payment-Signature` header values (header values are not traced at all); no request or response bodies. Query-string values are blanked whenever the parameter name mentions a key, token, secret, signature, password or auth, and any remaining credential-shaped value is blanked too. This intentionally includes public identifiers under names such as `token` and `token_address`, so use the original command—not the trace alone—to confirm which token was queried. Redaction deliberately fails closed: bare 64-character hex URL segments and long opaque/base58 identifiers are hidden even when they are public transaction, block, or Solana signature identifiers, because they are indistinguishable from key material without endpoint-specific assumptions. Long values are truncated. Paste a trace into a bug report as-is — but a quick read before you share is always wise.
- ## Supported Chains
- `algorand` `aptos` `arbitrum` `arc` `avalanche` `base` `bitcoin` `bitlayer` `bnb` `chiliz` `citrea` `ethereum` `gravity` `hyperevm` `hyperliquid` `injective` `iotaevm` `linea` `mantle` `mantra` `monad` `near` `optimism` `plasma` `polygon` `robinhood` `sei` `solana` `sonic` `stacks` `starknet` `stellar` `sui` `ton` `tron` `viction`
- > Run `nansen schema` to get the current chain list (source of truth).
- ## Agent Tips
- **Reduce token burn with `--fields`:**
- ```bash
- 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.
- **Use `--paginate` to fetch every page** of a list command in one call instead of looping over `--page`:
- ```bash
- nansen smart-money netflow --chain solana --limit 100 --paginate --max-pages 5
- ```
- `--limit` is the page size and `--max-pages` (default 10; ignored without pagination) caps the number of requests — every page is a
- separate, separately billed API call. Server completion metadata (`total_pages`, `total`, or
- `is_last_page`) is honoured so a known final page is not fetched again. Rows are de-duplicated and
- the response gains
- `pagination: { page, pages_fetched, next_page, complete }`; when `complete` is `false`, resume with
- `--page <next_page>`. The stderr credit summary totals the live page requests; cached pages are not
- counted as charges. Traversal trusts the server's `total`; if a live dataset changes or reports
- inconsistent totals while pages are being fetched, later rows can be omitted. Combine with
- `--stream` for NDJSON.
- **ENS names** work anywhere `--address` is accepted: `--address vitalik.eth`
- ## Output Format
- ### Migrating row output from 1.46.0 to 2.0.0
- `--table`, `--format csv`, and `--stream` now render each item in a nested
- `data.data` array as a separate row or NDJSON line, even without `--paginate`.
- For example, if `nansen token screener --format csv` receives this response body:
- ```json
- {"data":{"data":[{"a":1},{"a":2}]}}
- ```
- The CSV output changes from one row containing the nested object as a JSON string:
- ```csv
- data
- "{""data"":[{""a"":1},{""a"":2}]}"
- ```
- to two rows with the item field as the header:
- ```csv
- a
- 1
- 2
- ```
- `--table` makes the same one-to-two-row change. `--stream` changes from one
- NDJSON line for the enclosing object to one line per item. A single unambiguous
- descriptive top-level array, such as `trades` or `holdings`, also expands into
- individual rows or lines. Older versions rendered its enclosing object as one
- row or line. Envelopes with multiple candidate data arrays remain unexpanded.
- Default JSON output still contains the complete response body.
- ### Response envelope
- ```json
- { "success": true, "data": <api_response> }
- { "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "requestId": "...", "details": { ... } }
- ```
- **Critical error codes:**
- | Code | Action |
- |------|--------|
- | `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api?tab=api](https://app.nansen.ai/api?tab=api). |
- | `UNAUTHORIZED` | The API rejected the key (the connection works). Re-auth. |
- | `NETWORK_ERROR` | The CLI could not reach the API, so the key was not checked. Fix the connection (`nansen doctor`); do not replace the key. |
- | `INVALID_PARAMS` / `MISSING_PARAM` | Fix the option or field named in `details.param` and `details.errors[]` (each `{ field, message, code }`), then retry. |
- | `UNKNOWN_COMMAND` | The command or subcommand does not exist; the message suggests the closest one. |
- | `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
- | `UNSUPPORTED_FILTER` | Remove the filter and retry. |
- | `PLAN_UPGRADE_REQUIRED` | The endpoint or option needs a higher subscription plan. Do not retry. |
- | `GEO_BLOCKED` | Not available in your region. Do not retry. |
- | `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
- | `COMMAND_UNAVAILABLE` | The command is no longer available. For points leaderboard, run `nansen research` to explore other analytics commands. |
- Every failure exits 1. The full list of codes is in [docs/error-codes.md](docs/error-codes.md). Every code documented on the API's [error-handling page](https://docs.nansen.ai/getting-started/error-handling) maps onto a stable CLI error code; a code the CLI does not recognise is passed through unchanged.
- Research commands check their options before calling the API: an unknown or ignored option, a missing required option, a bad value or a chain the endpoint does not accept fails locally with the option named. `nansen schema <command>` lists each command's options and `supportedChains`.
- `nansen research profiler trace` fails with the original API error if the root lookup fails, rather than reporting an empty graph as a success. Once the root lookup succeeds, later lookups remain best-effort: a failed branch is skipped while traversal continues through the others.
- **Error metadata.** When the API reports them, `details` carries:
- | Field | Meaning |
- |-------|---------|
- | `requestId` | Identifies this call end to end. Quote it in any support report. Opaque — do not parse it. Also hoisted to the top level of the error envelope. |
- | `credits` | `used`, `remaining`, `cost` (the authoritative charge for this call) |
- | `rateLimit` | `limit`, `remaining`, `resetSeconds` |
- Any field may be absent or `null`, meaning unknown — never assume zero. A low-balance warning goes to **stderr**, so stdout stays pure JSON.
- ## Troubleshooting
- | Symptom | Fix |
- |---------|-----|
- | `command not found` | `npm install -g nansen-cli` |
- | Global install reports an older version | Check `node -v` first: current releases need Node.js >= 22. On an older Node, `npm i -g nansen-cli` installs the newest release that still supports it without an error, and `npm i -g nansen-cli@latest` installs the current release with an `EBADENGINE` warning (or fails under `engine-strict`). Upgrade Node, then run `npm i -g nansen-cli@latest --registry=https://registry.npmjs.org/ --prefer-online` and check `which -a nansen` for stale binaries |
- | `UNAUTHORIZED` after login | `nansen auth status` shows the effective credential and cached/unverified session metadata. Correct an invalid environment key first; browser login does not override it. Use fresh `nansen login` for a rejected session, or explicit legacy key setup for integration credentials |
- | MCP client lists tools but paid calls fail | Run `npx -y nansen-cli mcp verify` with the saved key or `NANSEN_API_KEY`, and ensure that same key is in the client's `NANSEN-API-KEY` header |
- | Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
- | Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
- | `perp` _trading_ prints the usage banner | Trading needs `--symbol BTC` (`--coin` also works); see the Perpetuals section. |
- | `UNSUPPORTED_FILTER` on token holders | Remove `--smart-money` — not all tokens have that data. |
- | Huge JSON response | Use `--fields` to select columns. |
- ## Development
- ```bash
- npm test # mocked tests, no API key needed
- npm run test:live # live API (needs NANSEN_API_KEY)
- ```
- See [AGENTS.md](AGENTS.md) for architecture and contributor guidance.
- ## License
- [MIT](LICENSE) © [Nansen](https://nansen.ai)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.