Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nansen-ai--nansen-cli/badge.svg)](/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

i

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.

  1. # Nansen CLI
  2. [![npm version](https://img.shields.io/npm/v/nansen-cli.svg)](https://www.npmjs.com/package/nansen-cli)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. > **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`.
  5. 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.
  6. ## Installation
  7. ```bash
  8. npm install -g nansen-cli
  9. npx -y skills add nansen-ai/nansen-cli --skill "*" -y # install every agent skill, no prompts
  10. ```
  11. Without `--skill "*" -y`, `skills add` opens a picker: space selects a skill, enter confirms.
  12. ## Feedback
  13. Send product feedback to Nansen with your configured API key or login session:
  14. ```json
  15. {
  16. "category": "missing_capability",
  17. "description": "I need to compare labels across 50 wallets but cannot find a bulk lookup.",
  18. "goal": "Compare labels across a wallet list."
  19. }
  20. ```
  21. `category` and `description` are required. `category` is one of `bug`,
  22. `data_quality`, `documentation`, `missing_capability`, `usability` or `other`.
  23. A feature request or product gap is `missing_capability`. `description` says
  24. what happened and what was needed, in up to 2,000 characters. Optional fields
  25. are `endpoint` and `tool` (up to 256 characters each), `goal`,
  26. `expected_behavior`, `observed_behavior` and `workaround` (up to 2,000
  27. characters each), `request_ids` (up to 10 of your own request IDs) and
  28. `client` (`{"name": ..., "version": ...}`, attribution only). The API rejects
  29. any other field or category with a 422, so leave out fields such as `title`,
  30. `summary` or `severity`. Write plain sentences without Markdown or code
  31. formatting. `nansen feedback submit --help` prints the same list.
  32. Save the report as `feedback.json`. Omit the ID to save private recovery data before sending:
  33. ```bash
  34. nansen feedback submit --file feedback.json --json
  35. nansen feedback resume --json
  36. nansen feedback get fb_123 --json
  37. ```
  38. `resume` uses the saved ID and exact report bytes, even if the input file is gone.
  39. Changing the account, API environment or report stops replay. After confirmation,
  40. `resume` reads the receipt without sending another report. To deliberately start
  41. another report, use `feedback submit --new --file feedback.json`.
  42. One recovery entry lives in `~/.nansen/feedback/recovery.json`, with private
  43. permissions and a process lock. Confirmed receipts remove report content and keep
  44. only the submission ID, feedback ID, account, environment and expiry. Feedback
  45. recovery operations erase expired data when they next open the journal. Pending
  46. reports expire after one calendar year. No cleanup runs while the CLI is closed.
  47. `nansen feedback forget` erases local recovery data
  48. offline, leaving a content-free marker that prevents accidental replay. It does
  49. not delete your input file or a report on the server. A missing or erased server
  50. receipt also clears the local entry. Validation rejections erase the saved payload;
  51. correct the input and use --new to submit again. Forget also erases damaged journals.
  52. Do not back up pending report content.
  53. Automatic IDs require POSIX private storage and the optional native locking
  54. binding. On Windows or when storage cannot be secured, supply a caller-managed
  55. `--submission-id report-123` and keep that ID and the unchanged file for retries.
  56. This explicit-ID path does not save a local report. Recovery format version 1
  57. survives upgrades; unsupported or damaged journals stop rather than start fresh.
  58. Older explicit-ID-only CLI releases do not read recovery journals; finish recovery
  59. with a supporting version before rolling back.
  60. Remove `--json` for human output. `received` means
  61. saved, `reviewed` means triaged, and `closed` means review is complete. Review does
  62. not promise a fix or a date.
  63. Feedback is free, with seven accepted reports per account each week, resetting
  64. Monday at 00:00 UTC. An exhausted allowance exits with its reset time; accepted
  65. IDs can still be replayed. Feedback bypasses caching and payment fallback.
  66. Remove secrets and unnecessary personal details from your report. A backend
  67. without feedback support reports an unavailable capability.
  68. New submissions may be paused before release or during an outage. HTTP 503 with
  69. `reason: feedback_admissions_paused` means this attempt accepted no new report
  70. and used no weekly allowance. Tell the user feedback is unavailable, then stop;
  71. do not keep retrying or ask for approval again in the same session. Keep the ID
  72. and unchanged file for a later retry. Accepted-ID replays and receipt reads
  73. remain available during a pause.
  74. Agents should check the saved account preference before sending feedback on their
  75. own. If enabled, they may send without asking again, subject to their host's
  76. controls. If off, unset or unavailable, show the proposed report and ask first.
  77. Approval for one report does not change the preference. Never enable it
  78. automatically. Use `nansen feedback preferences --json` for a fresh account read
  79. before each new automatic report. Without `--json`, it prints a human summary.
  80. Reads use no credits or report quota. Change the lasting choice in Superapp settings.
  81. An explicit user request to send the report needs no additional preference
  82. check. The submit command sends the report without an interactive prompt.
  83. HTTP 403 with `reason: feedback_not_enabled` means feedback is not enabled for
  84. this account. Stop automatic retries. Approval or an enabled preference does
  85. not override rollout. Keep the ID and unchanged report for recovery; an earlier
  86. uncertain attempt remains uncertain. Never switch accounts or pay to bypass denial.
  87. ## Auth
  88. Pick one of three ways to authenticate and pay for API calls.
  89. **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.
  90. ```bash
  91. nansen login
  92. ```
  93. **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.
  94. ```bash
  95. NANSEN_WALLET_PASSWORD='<your-wallet-password>' nansen wallet create --name my-wallet
  96. ```
  97. **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):
  98. ```bash
  99. tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
  100. ```
  101. [docs/auth.md](docs/auth.md) covers headless setup, saving an API key, browser-session storage and how x402 payment works with each credential.
  102. ## Verify your MCP setup
  103. For the hosted Nansen MCP server, verify server reachability and the supplied API key on the paid data path with:
  104. ```bash
  105. npx -y nansen-cli mcp verify # uses the saved key or NANSEN_API_KEY
  106. ```
  107. 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.”
  108. ## Commands
  109. ```
  110. nansen research <category> <subcommand> [options]
  111. nansen agent "<question>" # AI research agent (100 credits)
  112. nansen agent "<question>" --expert # deeper analysis (400 credits)
  113. nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
  114. nansen trade execute --quote <quoteId>
  115. nansen wallet <subcommand> [options]
  116. nansen mcp install <client> # add the Nansen MCP server to Claude Code/Desktop or Cursor
  117. nansen completion <bash|zsh|fish> # shell completions (no API key needed)
  118. nansen schema [command] [--pretty] # full command reference (no API key needed)
  119. nansen cache stats # what the local caches hold (no API key needed)
  120. ```
  121. **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`
  122. 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.
  123. **Direct research subcommands:**
  124. - `nansen research chain-rank [--days 7|30|365] [--chain-type all|evm]` — rank chains by growth metrics
  125. - `nansen research token-sectors` — list token sectors available for filtering
  126. - `nansen research address-premium-labels --address <addr> [--chain <chain>] [--page <n>] [--limit <n>]` — get all labels for an address, including premium labels
  127. - `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
  128. - `nansen research position-intelligence --symbol <symbol>` — aggregate Hyperliquid positions by trader cohort
  129. - `nansen research perp-pnl-summary --address <addr> --from-date <date> --to-date <date>` — summarize realized Hyperliquid PnL for an address
  130. - `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
  131. Plus the `historical-*` point-in-time commands — run `nansen research help` for the full list.
  132. **Trade:** `quote`, `execute`, `bridge-status`, `limit-order` — DEX swaps on Solana and Base, cross-chain bridges, and Solana limit orders.
  133. **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send`, `forget-password`, `secure` — local or Privy server-side wallets (EVM + Solana).
  134. **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:
  135. ```bash
  136. nansen alerts create --name 'ETH SM inflow' --type sm-token-flows --chains ethereum --inflow-1h-min 1000000 \
  137. --webhook https://example.com/hook --webhook-secret-stdin < webhook-secret.txt
  138. NANSEN_WEBHOOK_SECRET="$(cat webhook-secret.txt)" nansen alerts update <id> --webhook https://example.com/hook
  139. ```
  140. `--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`.
  141. Run `nansen schema --pretty` for the full subcommand and field reference.
  142. ## MCP
  143. <!-- 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. -->
  144. Connect any MCP client to Nansen's streamable HTTP server:
  145. - **Endpoint:** `https://mcp.nansen.ai/ra/mcp`
  146. - **Authentication:** `NANSEN-API-KEY` header
  147. - **API key:** [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup)
  148. 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:
  149. ```bash
  150. nansen mcp install claude-code # ~/.claude.json (user scope)
  151. nansen mcp install claude-desktop # macOS/Windows only; bridges via pinned mcp-remote
  152. nansen mcp install cursor # ~/.cursor/mcp.json
  153. nansen mcp install cursor --dry-run # print what would be written (key redacted)
  154. nansen mcp uninstall <client> # remove the entry (add --dry-run to preview)
  155. ```
  156. 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.
  157. **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).
  158. **One-command (Claude Code):**
  159. ```bash
  160. claude mcp add --transport http nansen https://mcp.nansen.ai/ra/mcp --header "NANSEN-API-KEY: <your-key>"
  161. ```
  162. **Manual (any streamable-HTTP client):** for example, add this to Cursor's `~/.cursor/mcp.json`:
  163. ```json
  164. {
  165. "mcpServers": {
  166. "nansen": {
  167. "url": "https://mcp.nansen.ai/ra/mcp",
  168. "headers": {
  169. "NANSEN-API-KEY": "<your-key>"
  170. }
  171. }
  172. }
  173. }
  174. ```
  175. **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:
  176. ```json
  177. {
  178. "mcpServers": {
  179. "nansen": {
  180. "command": "npx",
  181. "args": [
  182. "-y",
  183. "mcp-remote@0.2.1",
  184. "https://mcp.nansen.ai/ra/mcp",
  185. "--header",
  186. "NANSEN-API-KEY:${NANSEN_API_KEY}"
  187. ],
  188. "env": {
  189. "NANSEN_API_KEY": "<your-key>"
  190. }
  191. }
  192. }
  193. }
  194. ```
  195. `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).
  196. **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.
  197. <!-- END GENERATED: mcp -->
  198. ## Trading
  199. DEX swaps on `solana` and `base`. Two-step: quote then execute.
  200. ```bash
  201. nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
  202. nansen trade execute --quote <quoteId>
  203. ```
  204. Cross-chain swaps work the same way — add `--to-chain`. Bridge providers (Li.Fi or Relay) are selected automatically based on best price.
  205. ```bash
  206. nansen trade quote --chain base --to-chain solana --from ETH --to SOL --amount 0.0003 --amount-unit token
  207. nansen trade execute --quote <quoteId> # signed broadcast
  208. nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
  209. ```
  210. ### Before broadcasting
  211. `trade execute`, `bridge execute`, and the signing limit-order operations (`limit-order create` and `limit-order cancel`) accept:
  212. ```bash
  213. nansen trade execute --quote <quoteId> --dry-run # validate + print the plan, broadcast nothing
  214. nansen trade execute --quote <quoteId> --yes # skip the confirmation prompt (also: -y)
  215. nansen trade limit-order create ... --dry-run # preview intent; no API request or signature
  216. nansen trade limit-order cancel --order <id> --dry-run # does not request/consume a cancellation tx
  217. ```
  218. `--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.
  219. 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.
  220. 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.
  221. 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.
  222. 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.
  223. | Exit code | Meaning |
  224. |-----------|---------|
  225. | `0` | Broadcast succeeded, or the dry run completed |
  226. | `1` | Declined at the confirmation prompt, refused by `NANSEN_REQUIRE_CONFIRM`, or the execution failed |
  227. 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>`.
  228. ## Limit Orders
  229. Native price-triggered orders on **Solana**. Four subcommands:
  230. ```bash
  231. nansen trade limit-order create \
  232. --from SOL --to USDC \
  233. --amount 1.5 \
  234. --trigger-mint SOL --trigger-condition below --trigger-price 80 \
  235. --slippage-bps 300 --expires 7d
  236. nansen trade limit-order list # all orders
  237. nansen trade limit-order list --state active # only open
  238. nansen trade limit-order list --state past # filled or cancelled
  239. nansen trade limit-order cancel --order <orderId>
  240. nansen trade limit-order update --order <orderId> --trigger-price 85
  241. ```
  242. `--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.
  243. 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.
  244. 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.
  245. ## Perpetuals
  246. 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).
  247. ```bash
  248. nansen perp meta --filter ETH # list assets + max leverage
  249. nansen perp order --symbol ETH --side buy --size 0.1 --price 1600 --type limit
  250. nansen perp order --symbol BTC --side sell --size 0.001 --price 95000 --type market \
  251. --take-profit 90000 --stop-loss 98000
  252. nansen perp close --symbol ETH --size 0.1 --price 1600 --side sell # sell closes a long
  253. nansen perp cancel --symbol ETH --oid <orderId>
  254. nansen perp leverage --symbol ETH --leverage 5 --margin-type cross # or isolated
  255. nansen perp transfer --direction spot-to-perp --amount 25 # Spot<->Perps (or perp-to-spot)
  256. nansen perp positions
  257. nansen perp account # value, unrealized PnL, margin, spot USDC
  258. ```
  259. `--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.
  260. ## Bridge
  261. 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.
  262. ```bash
  263. nansen bridge quote --from-chain base --to-chain hyperliquid --from-token USDC --amount 1000000
  264. nansen bridge execute --quote <quoteId>
  265. nansen bridge execute --quote <quoteId> --dry-run # preview, nothing is broadcast
  266. nansen bridge execute --quote <quoteId> --nonce 20 --priority-fee 5 # replace a stuck EVM deposit
  267. nansen bridge status --request-id <id>
  268. ```
  269. 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.
  270. ## Wallet
  271. ```bash
  272. nansen wallet create --name my-wallet # local keypair (EVM + Solana)
  273. nansen wallet create --name my-wallet --provider privy # server-side via Privy
  274. nansen wallet list
  275. nansen wallet default <name>
  276. nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
  277. nansen wallet send --to <addr> --amount 25 --chain base --token USDC # USDC, USDT or a token address
  278. nansen wallet secure # move a password from .credentials or the env var into the OS keychain
  279. nansen wallet forget-password # drop the saved password from every store
  280. ```
  281. **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.
  282. ```bash
  283. NANSEN_WALLET_PASSWORD='<password-from-user>' nansen wallet create --name my-wallet
  284. ```
  285. `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`.
  286. **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).
  287. ## MPP / Tempo
  288. 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.
  289. **One-time setup:**
  290. ```bash
  291. # 1. Install the tempo CLI
  292. curl -fsSL https://tempo.xyz/install | bash
  293. # 2. Log in + fund the tempo wallet
  294. tempo wallet login
  295. tempo wallet fund # follow the on-screen instructions to deposit USDC
  296. ```
  297. **Calling the Nansen API via tempo:**
  298. ```bash
  299. tempo request -X POST https://api.nansen.ai/api/v1/smart-money/netflow \
  300. --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
  301. ```
  302. `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.
  303. **When to use which rail:**
  304. | Situation | Rail |
  305. |---|---|
  306. | You have a subscription | API key |
  307. | You want anonymous pay-per-call with a Base/Solana wallet you already manage | x402 (`nansen wallet`) |
  308. | You hold USDT0 on X Layer and want to pay from there | x402 (`nansen wallet`) |
  309. | You already use tempo for other paid APIs, or want micropayments without managing your own wallet keys | MPP (`tempo request`) |
  310. > 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.
  311. ## Shell Completions
  312. Tab-completion for commands, subcommands, flags, and the values a flag accepts:
  313. ```bash
  314. # bash
  315. echo 'eval "$(nansen completion bash)"' >> ~/.bashrc
  316. # or system-wide: nansen completion bash > /etc/bash_completion.d/nansen
  317. # zsh
  318. nansen completion zsh > "${fpath[1]}/_nansen" && compinit
  319. # or, in ~/.zshrc after the compinit line: eval "$(nansen completion zsh)"
  320. # fish
  321. nansen completion fish > ~/.config/fish/completions/nansen.fish
  322. ```
  323. The scripts are generated from the same schema as `nansen schema`, so they cover
  324. every nested subcommand and stay in step with the CLI. Nothing is written to
  325. disk and no network call is made — the script goes to stdout. Re-run the command
  326. after upgrading the CLI to pick up new commands.
  327. ## Key Options
  328. | Option | Description |
  329. |--------|-------------|
  330. | `--chain <chain>` | Blockchain to query |
  331. | `--limit <n>` | Result count |
  332. | `--timeframe <tf>` | Time window: `5m` `1h` `6h` `24h` `7d` `30d` |
  333. | `--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 |
  334. | `--sort <field:dir>` | Sort results, e.g. `--sort value_usd:desc` |
  335. | `--pretty` | Human-readable JSON |
  336. | `--table` | Table format |
  337. | `--stream` | NDJSON output for large results |
  338. | `--paginate` | Fetch every page of a list command (alias `--all`); bound with `--max-pages <n>` (default 10; ignored without pagination) |
  339. | `--labels <label>` | Smart Money label filter |
  340. | `--smart-money` | Filter for Smart Money addresses only |
  341. | `--cache` | Serve this invocation from the local cache (see [Caching](#caching)) |
  342. | `--no-cache` | Bypass the cache for this invocation |
  343. | `--debug` | Trace every HTTP request on stderr (see [Debugging](#debugging)) |
  344. ## Caching
  345. Response caching is **off by default** and opt-in per invocation:
  346. ```bash
  347. nansen research token screener --chain solana --cache # cache this result
  348. nansen research token screener --chain solana --cache --cache-ttl 60
  349. nansen research token screener --chain solana --cache --no-cache # veto: always live
  350. ```
  351. `NANSEN_NO_CACHE=1` does the same as `--no-cache` without a flag, for wrappers
  352. that cannot change the command line.
  353. With `--cache` on, every read the CLI makes through the Nansen API client is
  354. cached — all of `nansen research ...`, plus `alerts list` and `alerts get`.
  355. Never cached: `account`, `web search`, the `alerts`
  356. create/update/toggle/delete commands, `agent`, every `trade`, `bridge`, `wallet`
  357. and `mcp` command, and `perp` trading. The analytics commands `perp screener`
  358. and `perp leaderboard` are cached.
  359. Inspect and clear what is on disk:
  360. ```bash
  361. nansen cache stats # entries, size, age, effective TTL per cache
  362. nansen cache stats --json # the same numbers as an object
  363. nansen cache clear # delete cached API responses
  364. nansen cache clear cost-map # or update-check, or all
  365. ```
  366. `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.
  367. | Cache | Location | TTL |
  368. |-------|----------|-----|
  369. | `responses` | `~/.nansen/cache` | `--cache-ttl`, default 300s |
  370. | `cost-map` | `~/.nansen/cost-map.json` | 24h |
  371. | `update-check` | `~/.nansen/update-check.json` | 24h |
  372. ## Debugging
  373. `--debug` (or `NANSEN_DEBUG=1`) prints HTTP trace events to **stderr**, so stdout stays pure JSON/CSV and stays pipeable:
  374. ```bash
  375. nansen research token screener --chain solana --debug
  376. nansen research token screener --chain solana 2>trace.log | jq . # trace to a file, JSON to jq
  377. ```
  378. ```
  379. [nansen:debug] http.request method=POST url=https://api.nansen.ai/api/v1/token-screener attempt=1/4
  380. [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
  381. [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
  382. [nansen:debug] http.request method=POST url=https://api.nansen.ai/api/v1/token-screener attempt=2/4
  383. [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
  384. ```
  385. Events: `http.request`, `http.response`, `http.retry`, `http.error`, `http.cache_hit` (answered from the local cache, no request made).
  386. 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.
  387. **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.
  388. ## Supported Chains
  389. `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`
  390. > Run `nansen schema` to get the current chain list (source of truth).
  391. ## Agent Tips
  392. **Reduce token burn with `--fields`:**
  393. ```bash
  394. nansen research smart-money netflow --chain solana --fields token_symbol,net_flow_usd --limit 10
  395. ```
  396. **Use `--stream` for large results** — outputs NDJSON instead of buffering a giant array.
  397. **Use `--paginate` to fetch every page** of a list command in one call instead of looping over `--page`:
  398. ```bash
  399. nansen smart-money netflow --chain solana --limit 100 --paginate --max-pages 5
  400. ```
  401. `--limit` is the page size and `--max-pages` (default 10; ignored without pagination) caps the number of requests — every page is a
  402. separate, separately billed API call. Server completion metadata (`total_pages`, `total`, or
  403. `is_last_page`) is honoured so a known final page is not fetched again. Rows are de-duplicated and
  404. the response gains
  405. `pagination: { page, pages_fetched, next_page, complete }`; when `complete` is `false`, resume with
  406. `--page <next_page>`. The stderr credit summary totals the live page requests; cached pages are not
  407. counted as charges. Traversal trusts the server's `total`; if a live dataset changes or reports
  408. inconsistent totals while pages are being fetched, later rows can be omitted. Combine with
  409. `--stream` for NDJSON.
  410. **ENS names** work anywhere `--address` is accepted: `--address vitalik.eth`
  411. ## Output Format
  412. ### Migrating row output from 1.46.0 to 2.0.0
  413. `--table`, `--format csv`, and `--stream` now render each item in a nested
  414. `data.data` array as a separate row or NDJSON line, even without `--paginate`.
  415. For example, if `nansen token screener --format csv` receives this response body:
  416. ```json
  417. {"data":{"data":[{"a":1},{"a":2}]}}
  418. ```
  419. The CSV output changes from one row containing the nested object as a JSON string:
  420. ```csv
  421. data
  422. "{""data"":[{""a"":1},{""a"":2}]}"
  423. ```
  424. to two rows with the item field as the header:
  425. ```csv
  426. a
  427. 1
  428. 2
  429. ```
  430. `--table` makes the same one-to-two-row change. `--stream` changes from one
  431. NDJSON line for the enclosing object to one line per item. A single unambiguous
  432. descriptive top-level array, such as `trades` or `holdings`, also expands into
  433. individual rows or lines. Older versions rendered its enclosing object as one
  434. row or line. Envelopes with multiple candidate data arrays remain unexpanded.
  435. Default JSON output still contains the complete response body.
  436. ### Response envelope
  437. ```json
  438. { "success": true, "data": <api_response> }
  439. { "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "requestId": "...", "details": { ... } }
  440. ```
  441. **Critical error codes:**
  442. | Code | Action |
  443. |------|--------|
  444. | `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). |
  445. | `UNAUTHORIZED` | The API rejected the key (the connection works). Re-auth. |
  446. | `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. |
  447. | `INVALID_PARAMS` / `MISSING_PARAM` | Fix the option or field named in `details.param` and `details.errors[]` (each `{ field, message, code }`), then retry. |
  448. | `UNKNOWN_COMMAND` | The command or subcommand does not exist; the message suggests the closest one. |
  449. | `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
  450. | `UNSUPPORTED_FILTER` | Remove the filter and retry. |
  451. | `PLAN_UPGRADE_REQUIRED` | The endpoint or option needs a higher subscription plan. Do not retry. |
  452. | `GEO_BLOCKED` | Not available in your region. Do not retry. |
  453. | `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
  454. | `COMMAND_UNAVAILABLE` | The command is no longer available. For points leaderboard, run `nansen research` to explore other analytics commands. |
  455. 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.
  456. 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`.
  457. `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.
  458. **Error metadata.** When the API reports them, `details` carries:
  459. | Field | Meaning |
  460. |-------|---------|
  461. | `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. |
  462. | `credits` | `used`, `remaining`, `cost` (the authoritative charge for this call) |
  463. | `rateLimit` | `limit`, `remaining`, `resetSeconds` |
  464. Any field may be absent or `null`, meaning unknown — never assume zero. A low-balance warning goes to **stderr**, so stdout stays pure JSON.
  465. ## Troubleshooting
  466. | Symptom | Fix |
  467. |---------|-----|
  468. | `command not found` | `npm install -g nansen-cli` |
  469. | 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 |
  470. | `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 |
  471. | 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 |
  472. | Anything else misbehaving | `nansen doctor` checks your whole setup (auth, wallets, caches, connectivity) with a fix per finding |
  473. | Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
  474. | `perp` _trading_ prints the usage banner | Trading needs `--symbol BTC` (`--coin` also works); see the Perpetuals section. |
  475. | `UNSUPPORTED_FILTER` on token holders | Remove `--smart-money` — not all tokens have that data. |
  476. | Huge JSON response | Use `--fields` to select columns. |
  477. ## Development
  478. ```bash
  479. npm test # mocked tests, no API key needed
  480. npm run test:live # live API (needs NANSEN_API_KEY)
  481. ```
  482. See [AGENTS.md](AGENTS.md) for architecture and contributor guidance.
  483. ## License
  484. [MIT](LICENSE) © [Nansen](https://nansen.ai)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.