{"id":45025680,"url":"https://github.com/nansen-ai/nansen-cli","last_synced_at":"2026-05-26T07:02:22.027Z","repository":{"id":335599559,"uuid":"1146425250","full_name":"nansen-ai/nansen-cli","owner":"nansen-ai","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-06T10:22:51.000Z","size":1993,"stargazers_count":115,"open_issues_count":11,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-06T10:24:08.822Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nansen-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-31T04:28:14.000Z","updated_at":"2026-04-06T01:52:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nansen-ai/nansen-cli","commit_stats":null,"previous_names":["askeluv/nansen-cli","nansen-ai/nansen-cli"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/nansen-ai/nansen-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nansen-ai%2Fnansen-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nansen-ai%2Fnansen-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nansen-ai%2Fnansen-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nansen-ai%2Fnansen-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nansen-ai","download_url":"https://codeload.github.com/nansen-ai/nansen-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nansen-ai%2Fnansen-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31477013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T14:34:32.243Z","status":"ssl_error","status_checked_at":"2026-04-06T14:34:31.723Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-19T03:09:44.282Z","updated_at":"2026-05-26T07:02:22.019Z","avatar_url":"https://github.com/nansen-ai.png","language":"JavaScript","funding_links":[],"categories":["Data and Web"],"sub_categories":[],"readme":"# Nansen CLI\n\n[![npm version](https://img.shields.io/npm/v/nansen-cli.svg)](https://www.npmjs.com/package/nansen-cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003e **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`.\n\nUse 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.\n\n## Installation\n\n```bash\nnpm install -g nansen-cli\nnpx skills add nansen-ai/nansen-cli  # load agent skill files\n```\n\n## Auth\n\nThree options — pick whichever fits your setup:\n\n1. **API key** (subscription):\n   ```bash\n   nansen login --api-key \u003ckey\u003e   # save key to ~/.nansen/config.json\n   nansen login --human           # interactive prompt\n   export NANSEN_API_KEY=...      # env var (highest priority)\n   nansen logout                  # remove saved key\n   ```\n   Get your API key at [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup).\n\n2. **x402 micropayment** (no key needed): `nansen wallet create`, fund with USDC on Base or Solana, or USDT0 on X Layer, then call any endpoint — the CLI signs `Payment-Signature` headers automatically on 402 responses. See [Wallet](#wallet).\n\n3. **MPP via tempo** (no key needed): install the [tempo CLI](https://docs.tempo.xyz) separately, run `tempo wallet login` to set up, then call the Nansen API through `tempo request`. The Nansen API selects the MPP rail when it sees `Authorization: Payment ...`. See [MPP / Tempo](#mpp--tempo) below.\n\n## Commands\n\n```\nnansen research \u003ccategory\u003e \u003csubcommand\u003e [options]\nnansen agent \"\u003cquestion\u003e\"             # AI research agent (200 credits, Pro)\nnansen agent \"\u003cquestion\u003e\" --expert    # deeper analysis (750 credits, Pro)\nnansen trade quote --chain solana --from SOL --to USDC --amount 1000000000\nnansen trade execute --quote \u003cquoteId\u003e\nnansen wallet \u003csubcommand\u003e [options]\nnansen schema [command] [--pretty]    # full command reference (no API key needed)\n```\n\n**Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`, `points`\n\n**Trade:** `quote`, `execute`, `bridge-status`, `limit-order` — DEX swaps on Solana and Base, cross-chain bridges, and Solana limit orders.\n\n**Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local or Privy server-side wallets (EVM + Solana).\n\nRun `nansen schema --pretty` for the full subcommand and field reference.\n\n## Trading\n\nDEX swaps on `solana` and `base`. Two-step: quote then execute.\n\n```bash\nnansen trade quote --chain solana --from SOL --to USDC --amount 1000000000\nnansen trade execute --quote \u003cquoteId\u003e\n```\n\nCross-chain swaps work the same way — add `--to-chain`. Bridge providers (Li.Fi or Relay) are selected automatically based on best price.\n\n```bash\nnansen trade quote --chain base --to-chain solana --from ETH --to SOL --amount 0.0003 --amount-unit token\nnansen trade execute --quote \u003cquoteId\u003e                # signed broadcast\nnansen trade execute --quote \u003cquoteId\u003e --gasless      # Relay-only: solver pays gas\nnansen trade bridge-status --tx-hash \u003chash\u003e --from-chain base --to-chain solana\n```\n\nAmounts 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 \u003cname\u003e`.\n\n## Limit Orders\n\nNative price-triggered orders on **Solana**. Four subcommands:\n\n```bash\nnansen trade limit-order create \\\n  --from SOL --to USDC \\\n  --amount 1.5 \\\n  --trigger-mint SOL --trigger-condition below --trigger-price 80 \\\n  --slippage-bps 300 --expires 7d\n\nnansen trade limit-order list                    # all orders\nnansen trade limit-order list --state active     # only open\nnansen trade limit-order list --state past       # filled or cancelled\nnansen trade limit-order cancel --order \u003corderId\u003e\nnansen trade limit-order update --order \u003corderId\u003e --trigger-price 85\n```\n\n`--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.\n\nFor 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.\n\n## Wallet\n\n```bash\nnansen wallet create --name my-wallet        # local keypair (EVM + Solana)\nnansen wallet create --name my-wallet --provider privy  # server-side via Privy\nnansen wallet list\nnansen wallet default \u003cname\u003e\nnansen wallet send --wallet \u003cname\u003e --to \u003caddr\u003e --amount \u003cn\u003e --chain \u003cchain\u003e\n```\n\n**Local wallets** are password-encrypted. Set `NANSEN_WALLET_PASSWORD` to skip the prompt.\n\n**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).\n\n## MPP / Tempo\n\nThe 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.\n\n**One-time setup:**\n\n```bash\n# 1. Install the tempo CLI\ncurl -fsSL https://tempo.xyz/install | bash\n# 2. Log in + fund the tempo wallet\ntempo wallet login\ntempo wallet fund     # follow the on-screen instructions to deposit USDC\n```\n\n**Calling the Nansen API via tempo:**\n\n```bash\ntempo request POST https://api.nansen.ai/api/v1/smart-money/netflow \\\n  --json '{\"chains\":[\"solana\"],\"pagination\":{\"page\":1,\"page_size\":10}}'\n```\n\n`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.\n\n**When to use which rail:**\n\n| Situation | Rail |\n|---|---|\n| You have a subscription | API key |\n| You want anonymous pay-per-call with a Base/Solana wallet you already manage | x402 (`nansen wallet`) |\n| You hold USDT0 on X Layer and want to pay from there | x402 (`nansen wallet`) |\n| You already use tempo for other paid APIs, or want micropayments without managing your own wallet keys | MPP (`tempo request`) |\n\n\u003e 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.\n\n## Key Options\n\n| Option | Description |\n|--------|-------------|\n| `--chain \u003cchain\u003e` | Blockchain to query |\n| `--limit \u003cn\u003e` | Result count |\n| `--timeframe \u003ctf\u003e` | Time window: `5m` `1h` `6h` `24h` `7d` `30d` |\n| `--fields \u003clist\u003e` | Comma-separated fields (reduces response size) |\n| `--sort \u003cfield:dir\u003e` | Sort results, e.g. `--sort value_usd:desc` |\n| `--pretty` | Human-readable JSON |\n| `--table` | Table format |\n| `--stream` | NDJSON output for large results |\n| `--labels \u003clabel\u003e` | Smart Money label filter |\n| `--smart-money` | Filter for Smart Money addresses only |\n\n## Supported Chains\n\n`ethereum` `solana` `base` `bnb` `arbitrum` `polygon` `optimism` `avalanche` `linea` `scroll` `mantle` `ronin` `sei` `plasma` `sonic` `monad` `hyperevm` `iotaevm`\n\n\u003e Run `nansen schema` to get the current chain list (source of truth).\n\n## Agent Tips\n\n**Reduce token burn with `--fields`:**\n```bash\nnansen research smart-money netflow --chain solana --fields token_symbol,net_flow_usd --limit 10\n```\n\n**Use `--stream` for large results** — outputs NDJSON instead of buffering a giant array.\n\n**ENS names** work anywhere `--address` is accepted: `--address vitalik.eth`\n\n## Output Format\n\n```json\n{ \"success\": true,  \"data\": \u003capi_response\u003e }\n{ \"success\": false, \"error\": \"message\", \"code\": \"ERROR_CODE\", \"status\": 401 }\n```\n\n**Critical error codes:**\n\n| Code | Action |\n|------|--------|\n| `CREDITS_EXHAUSTED` | Stop all API calls immediately. Check [app.nansen.ai](https://app.nansen.ai). |\n| `UNAUTHORIZED` | Wrong or missing key. Re-auth. |\n| `RATE_LIMITED` | Auto-retried by CLI. |\n| `UNSUPPORTED_FILTER` | Remove the filter and retry. |\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| `command not found` | `npm install -g nansen-cli` |\n| `UNAUTHORIZED` after login | `cat ~/.nansen/config.json` or set `NANSEN_API_KEY` |\n| Empty perp results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |\n| `UNSUPPORTED_FILTER` on token holders | Remove `--smart-money` — not all tokens have that data. |\n| Huge JSON response | Use `--fields` to select columns. |\n\n## Development\n\n```bash\nnpm test              # mocked tests, no API key needed\nnpm run test:live     # live API (needs NANSEN_API_KEY)\n```\n\nSee [AGENTS.md](AGENTS.md) for architecture and contributor guidance.\n\n## License\n\n[MIT](LICENSE) © [Nansen](https://nansen.ai)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnansen-ai%2Fnansen-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnansen-ai%2Fnansen-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnansen-ai%2Fnansen-cli/lists"}