nansen-cli 1.16.1 → 1.18.0

package/skills/nansen-trade/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: nansen-trade
+description: Execute DEX swaps on Solana or Base. Use when buying or selling a token, getting a swap quote, or executing a trade.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+        - NANSEN_WALLET_PASSWORD
+      bins:
+        - nansen
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*)
+---
+
+# Trade
+
+Two-step flow: quote then execute. **Trades are irreversible once on-chain.**
+
+**Prerequisite:** You need a wallet first. Run `nansen wallet create` before trading.
+
+## Quote
+
+```bash
+nansen trade quote \
+  --chain solana \
+  --from SOL \
+  --to USDC \
+  --amount 1000000000
+```
+
+Symbols resolve automatically: `SOL`, `ETH`, `USDC`, `USDT`, `WETH`. Raw addresses also work.
+
+## Execute
+
+```bash
+nansen trade execute --quote <quote-id>
+```
+
+## Agent pattern
+
+```bash
+# Pipe quote ID directly into execute
+quote_id=$(nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000 2>&1 | grep "Quote ID:" | awk '{print $NF}')
+nansen trade execute --quote "$quote_id"
+```
+
+## Common Token Addresses
+
+| Token | Chain | Address |
+|-------|-------|---------|
+| SOL | Solana | `So11111111111111111111111111111111111111112` |
+| USDC | Solana | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
+| ETH | Base | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` |
+| USDC | Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+
+## Amounts are in base units
+
+| Token | Decimals | 1 token = |
+|-------|----------|-----------|
+| SOL | 9 | `1000000000` |
+| ETH | 18 | `1000000000000000000` |
+| USDC | 6 | `1000000` |
+
+## Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--chain` | `solana` or `base` |
+| `--from` | Source token (symbol or address) |
+| `--to` | Destination token (symbol or address) |
+| `--amount` | Amount in base units (integer) |
+| `--wallet` | Wallet name (default: default wallet) |
+| `--slippage` | Slippage tolerance as decimal (e.g. 0.03) |
+| `--quote` | Quote ID for execute |
+| `--no-simulate` | Skip pre-broadcast simulation |
+
+## Environment Variables
+
+| Var | Purpose |
+|-----|---------|
+| `NANSEN_WALLET_PASSWORD` | **Required for `trade execute`.** Wallet encryption password — persisted in `~/.nansen/.env`. Source before executing: `source ~/.nansen/.env && nansen trade execute ...` |
+| `NANSEN_API_KEY` | API key (also set via `nansen login`) |
+
+> **Agents:** Never hold a wallet password only in session memory. If `NANSEN_WALLET_PASSWORD` is not in `~/.nansen/.env`, follow the setup flow in the nansen-wallet skill Password Policy to generate and persist one before proceeding.
+
+## Notes
+
+- Quotes expire after ~1 hour. If execute fails, get a fresh quote.
+- A wallet is required even for quotes (the API builds sender-specific transactions).
+- ERC-20 swaps may require an approval step — execute handles this automatically.
+
+## Source
+
+- npm: https://www.npmjs.com/package/nansen-cli
+- GitHub: https://github.com/nansen-ai/nansen-cli

package/skills/nansen-wallet/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: nansen-wallet
+description: Wallet management — create, list, show, export, send, delete. Use when creating wallets, checking balances, or sending tokens.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+      bins:
+        - nansen
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*)
+---
+
+# Wallet
+
+## Auth Setup
+
+```bash
+# Save API key (non-interactive)
+nansen login --api-key <key>
+# Or via env var:
+NANSEN_API_KEY=<key> nansen login
+
+# Verify
+nansen research profiler labels --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum
+```
+
+## Wallet Creation (Two-Step Agent Flow)
+
+Wallet creation requires a password from the **human user**. The agent must NOT generate or store the password itself.
+
+> **Step 1 (Agent → Human):** Ask the user to provide a wallet password (minimum 12 characters).
+>
+> **Step 2 (Agent executes):** Run the create command with the password the user gave you.
+
+```bash
+NANSEN_WALLET_PASSWORD="<password_from_user>" nansen wallet create
+```
+
+After creation, the CLI automatically saves the password:
+- **OS keychain** (macOS Keychain, Linux secret-tool, Windows Credential Manager) — secure, preferred
+- **~/.nansen/wallets/.credentials file** — insecure fallback when no keychain is available (e.g. containers, CI)
+
+**All future wallet operations retrieve the password automatically** — no env var or human input needed.
+
+If the `.credentials` file fallback is used, the CLI prints a warning on every operation. To migrate to secure storage later, run `nansen wallet secure`.
+
+### Password resolution order (automatic)
+
+1. `NANSEN_WALLET_PASSWORD` env var (if set)
+2. OS keychain (saved automatically on wallet create)
+3. `~/.nansen/wallets/.credentials` file (insecure fallback, with warning)
+4. Structured JSON error with instructions (if none available)
+
+### Critical rules for agents
+
+- **NEVER generate a password yourself** — always ask the human user
+- **NEVER store the password** in files, memory, logs, or conversation history
+- **NEVER use `--human` flag** — that enables interactive prompts which agents cannot handle
+- After wallet creation, you do NOT need the password for future operations — the keychain handles it
+- If you get a `PASSWORD_REQUIRED` error, ask the user to provide their password again
+
+## Create
+
+```bash
+# Ask the user for a password first, then:
+NANSEN_WALLET_PASSWORD="<password_from_user>" nansen wallet create
+# Or with a custom name:
+NANSEN_WALLET_PASSWORD="<password_from_user>" nansen wallet create --name trading
+```
+
+## List & Show
+
+```bash
+nansen wallet list
+nansen wallet show <name>
+nansen wallet default <name>
+```
+
+## Send
+
+```bash
+# Send native token (SOL, ETH) — password auto-resolved from keychain
+nansen wallet send --to <addr> --amount 1.5 --chain solana
+
+# Send entire balance
+nansen wallet send --to <addr> --chain evm --max
+
+# Dry run (preview, no broadcast)
+nansen wallet send --to <addr> --amount 1.0 --chain evm --dry-run
+```
+
+## Export & Delete
+
+```bash
+# Password auto-resolved from keychain
+nansen wallet export <name>
+nansen wallet delete <name>
+```
+
+## Forget Password
+
+```bash
+# Remove saved password from all stores (keychain + .credentials file)
+nansen wallet forget-password
+```
+
+## Migrate to Secure Storage
+
+```bash
+nansen wallet secure
+```
+
+For detailed migration steps (from `~/.nansen/.env`, `.credentials`, or env-var-only setups), see the **nansen-wallet-migration** skill.
+
+## Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--to` | Recipient address |
+| `--amount` | Amount to send |
+| `--chain` | `evm` or `solana` |
+| `--max` | Send entire balance |
+| `--dry-run` | Preview without broadcasting |
+| `--human` | Enable interactive prompts (human terminal use only — agents must NOT use this) |
+| `--unsafe-no-password` | Skip encryption (keys stored in plaintext — NOT recommended) |
+
+## Environment Variables
+
+| Var | Purpose |
+|-----|---------|
+| `NANSEN_WALLET_PASSWORD` | Wallet encryption password — only needed for initial `wallet create`. After that, the OS keychain handles it. |
+| `NANSEN_API_KEY` | API key (also set via `nansen login --api-key <key>`) |
+| `NANSEN_EVM_RPC` | Custom EVM RPC endpoint |
+| `NANSEN_SOLANA_RPC` | Custom Solana RPC endpoint |

package/skills/nansen-wallet-analysis/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: nansen-wallet-analysis
+description: "Who is this wallet and what have they been doing? Identity labels, balance, PnL summary, recent transactions, perp positions, and counterparties."
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+      bins:
+        - nansen
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*)
+---
+
+# Wallet Analysis
+
+**Answers:** "Who is this wallet and what have they been doing?"
+
+```bash
+ADDR=<address> CHAIN=ethereum
+
+nansen research profiler labels --address $ADDR --chain $CHAIN
+# → label, category (e.g. "Smart Trader", "Fund", "Public Figure", ENS names)
+
+nansen research profiler balance --address $ADDR --chain $CHAIN
+# → token_symbol, token_name, token_amount, price_usd, value_usd per holding
+
+nansen research profiler pnl-summary --address $ADDR --chain $CHAIN --days 30
+# → realized_pnl_usd, realized_pnl_percent, win_rate, traded_token_count, traded_times, top5_tokens
+
+nansen research profiler transactions --address $ADDR --chain $CHAIN --limit 20
+# → block_timestamp, method, tokens_sent, tokens_received, volume_usd, source_type
+
+nansen research profiler perp-positions --address $ADDR
+# → asset_positions, margin_summary_account_value_usd, margin_summary_total_margin_used_usd
+
+nansen research profiler counterparties --address $ADDR --chain $CHAIN --days 30
+# → counterparty_address, counterparty_address_label, interaction_count, total_volume_usd, volume_in/out_usd
+```
+
+perp-positions returns Hyperliquid data — returns empty if the wallet has no open perps.

package/skills/nansen-wallet-attribution/REFERENCE.md

@@ -0,0 +1,43 @@
+# Wallet Attribution — Reference
+
+## Expansion Protocol
+
+Run steps 1-2 on the seed address. For every new address found, ask the human:
+**"Found `<addr>` via `<signal>` (`<label>`). Want me to query it?"**
+On confirm, re-run steps 1-2 on it. Reserve step 3 (counterparties) for the seed address only.
+
+**Stop expanding when:** address is a known protocol/CEX · confidence is Low · already visited · cluster > 10 wallets.
+
+## Attribution Rules
+
+- CEX withdrawal → wallet owner (NOT the CEX)
+- Smart account/DCA bot → end-user who funds it (NOT the protocol)
+- Safe deployer ≠ owner — identical signer sets across Safes = same controller
+
+## Confidence Scoring
+
+| Confidence | Signals |
+|------------|---------|
+| **High** | First Funder / shared Safe signers / same CEX deposit address |
+| **Medium** | Coordinated balance movements / related-wallets + label match |
+| **Exclude** | ENS alone, single CEX withdrawal, single deployer |
+
+## Output Format
+
+`address` · `owner` · `confidence (H/M/L)` · `signals` · `role`
+
+## L2 Coverage
+
+When step 3 returns sparse results on a mainnet EVM address, extend to L2s (4 calls):
+
+```bash
+for CHAIN in base arbitrum optimism polygon; do
+  nansen research profiler counterparties --address $ADDR --chain $CHAIN --days 365
+done
+```
+
+## Cost Warnings
+
+- `trace` is credit-heavy; keep `--width 3` or lower
+- L2 counterparty checks above add 4 API calls per address
+- Historical balances reveal past holdings on drained wallets — useful fingerprint

package/skills/nansen-wallet-attribution/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: nansen-wallet-attribution
+description: "Cluster and attribute related wallets — funding chains, shared signers, CEX deposit patterns. Use when tracing wallet ownership, comparing two wallets, finding wallet relationships, governance voters, or related address clusters."
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+      bins:
+        - nansen
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*)
+---
+
+# Wallet Attribution
+
+**Answers:** "Who controls this wallet? Are these wallets related?"
+
+Chain: `0x` → `--chain ethereum` (also base, arbitrum, optimism, polygon). Base58 → `--chain solana`.
+
+```bash
+ADDR=<address> CHAIN=<ethereum|solana|base|...>  # detect from address format above
+# 1. Identity
+nansen research profiler labels --address $ADDR --chain $CHAIN
+# 2. Related wallets (paginate with --page N)
+nansen research profiler related-wallets --address $ADDR --chain $CHAIN
+# 3. Counterparties (paginate with --page N; widen with --days 365 if empty)
+nansen research profiler counterparties --address $ADDR --chain $CHAIN --days 90
+# 4. Batch profile cluster
+nansen research profiler batch --addresses "addr1,addr2" --chain $CHAIN --include labels,balance,pnl
+# 5. Compare pairs → shared_counterparties, shared_tokens, balances
+nansen research profiler compare --addresses "addr1,addr2" --chain $CHAIN
+# 6. Historical balances (fingerprint drained wallets)
+nansen research profiler historical-balances --address $ADDR --chain $CHAIN --days 90
+# 7. Multi-hop trace (credit-heavy — keep --width ≤3)
+nansen research profiler trace --address $ADDR --chain $CHAIN --depth 2 --width 3
+```
+
+**Expansion:** Run steps 1-2 on seed. For each new address found, ask the human before querying. Reserve step 3 for seed only.
+**Stop when:** known protocol/CEX · Low confidence · already visited · cluster > 10 wallets.
+**Confidence:** High = first funder / shared Safe signers / same CEX deposit. Medium = coordinated movements / related-wallets + label match. Exclude = ENS only, single CEX withdrawal, single deployer.
+Full attribution rules in REFERENCE.md.

package/skills/nansen-wallet-migration/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: nansen-wallet-migration
+description: Migrate an existing nansen-cli wallet from insecure password storage (env files, .credentials) to the new secure keychain-backed flow.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+      bins:
+        - nansen
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*)
+---
+
+# Wallet Migration — Old Flow to Secure Keychain
+
+Use this skill when a user already has a nansen-cli wallet set up with the
+**old** password storage method and wants to migrate to the new secure flow.
+
+## When to use
+
+- User mentions they stored their password in `~/.nansen/.env`, a `.env` file, or `memory.md`
+- User gets the stderr warning: `⚠ Password loaded from insecure .credentials file`
+- User asks to "secure my wallet" or "migrate to keychain"
+- User created a wallet before the keychain update was released
+
+## Detect current state
+
+`wallet show` only displays addresses and does NOT load or check the password.
+To detect the actual password situation, check for stored password sources:
+
+```bash
+# 1. Check if a wallet exists at all
+nansen wallet list 2>&1
+
+# 2. Check for insecure password stores
+ls -la ~/.nansen/.env 2>/dev/null && echo "FOUND: ~/.nansen/.env (insecure)"
+ls -la ~/.nansen/wallets/.credentials 2>/dev/null && echo "FOUND: .credentials file (insecure)"
+
+# 3. Try an operation that requires the password (without setting env var)
+nansen wallet export default 2>&1
+```
+
+Interpret the `export` output:
+- `⚠ Password loaded from ~/.nansen/wallets/.credentials` on stderr → needs migration (Path B)
+- Export succeeds silently → password is in keychain, no migration needed
+- `PASSWORD_REQUIRED` JSON error → password not persisted anywhere (Path C or D)
+
+## Migration paths
+
+### Path A: Password in `~/.nansen/.env` (old skill pattern)
+
+The previous wallet skill told agents to write the password to `~/.nansen/.env`.
+
+**Step 1 — Ask the human for their password:**
+
+> "Your wallet password is currently stored in ~/.nansen/.env, which is insecure.
+> I can migrate it to your OS keychain. Please confirm the password you used when
+> creating the wallet, or I can read it from ~/.nansen/.env if you authorize it."
+
+**Step 2 — Migrate:**
+
+The `source` and `nansen wallet secure` MUST run in the same shell so the env
+var is available to the node process:
+
+```bash
+source ~/.nansen/.env 2>/dev/null && nansen wallet secure
+```
+
+**Step 3 — Verify the password actually decrypts the wallet:**
+
+```bash
+# Unset env var to prove keychain works, then export to verify decryption
+unset NANSEN_WALLET_PASSWORD
+nansen wallet export default 2>&1
+```
+
+If export succeeds (shows private keys), the migration worked. If it shows
+`Incorrect password`, the wrong password was migrated — run `nansen wallet
+forget-password` and retry with the correct password.
+
+**Step 4 — Clean up the insecure file:**
+
+```bash
+rm -f ~/.nansen/.env
+```
+
+### Path B: Password in `.credentials` file (auto-saved fallback)
+
+This happens when `wallet create` couldn't access the OS keychain (containers, CI).
+
+```bash
+nansen wallet secure
+```
+
+If the keychain is still unavailable (e.g. containerized Linux without D-Bus),
+`nansen wallet secure` will explain the situation and suggest alternatives.
+
+After migrating, verify decryption works:
+
+```bash
+nansen wallet export default 2>&1
+```
+
+### Path C: Password only in `NANSEN_WALLET_PASSWORD` env var
+
+```bash
+# Persist the env var password to keychain
+nansen wallet secure
+```
+
+Then verify without the env var:
+
+```bash
+unset NANSEN_WALLET_PASSWORD
+nansen wallet export default 2>&1
+```
+
+### Path D: Password lost entirely
+
+The password cannot be recovered. The wallet's private keys are encrypted with
+AES-256-GCM and the password is not stored anywhere recoverable.
+
+**Tell the human:**
+
+> "Your wallet password cannot be recovered. If you have funds in this wallet,
+> they may be inaccessible. You can create a new wallet and transfer any remaining
+> accessible funds."
+
+```bash
+# Create a fresh wallet (human must provide a new password)
+NANSEN_WALLET_PASSWORD="<new_password_from_user>" nansen wallet create --name new-wallet
+```
+
+## Post-migration verification
+
+After any migration, confirm the password was migrated correctly by proving
+the keychain password can actually decrypt the wallet:
+
+```bash
+# Unset env var to prove keychain works
+unset NANSEN_WALLET_PASSWORD
+
+# This MUST succeed — it proves the keychain password decrypts the wallet
+nansen wallet export default 2>&1
+```
+
+If export shows `Incorrect password`, the wrong password was saved to the
+keychain. Fix with:
+
+```bash
+nansen wallet forget-password
+NANSEN_WALLET_PASSWORD="<correct_password>" nansen wallet secure
+```
+
+If `stderr` still shows the `.credentials` warning, the keychain migration did
+not succeed — check if the OS keychain service is running (`secret-tool` on Linux,
+`security` on macOS).
+
+## Forget password (all stores)
+
+If the user wants to remove their persisted password entirely:
+
+```bash
+nansen wallet forget-password
+```
+
+This clears the password from both OS keychain and `.credentials` file. Future
+wallet operations will require `NANSEN_WALLET_PASSWORD` env var or re-running
+`nansen wallet secure`.
+
+## Critical rules for agents
+
+- **NEVER generate a password** — always ask the human
+- **NEVER store the password** in files, memory, logs, or conversation history
+- **NEVER use `--human` flag** — interactive prompts break agents
+- If the human authorizes reading `~/.nansen/.env`, read it in the same command
+  (`source ~/.nansen/.env && nansen wallet secure`) — do not echo or log the value
+- **ALWAYS verify after migration** with `nansen wallet export default` — `wallet show` does NOT prove the password works (it never loads the password)

package/skills/nansen-web-fetch/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: nansen-web-fetch
+description: Fetch and analyze content from one or more URLs using AI (Gemini 2.5 Flash). Use when you have specific URLs and need to extract or summarize their content. Pairs well with `nansen web search` results.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+      bins:
+        - nansen
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*)
+---
+
+# Web Fetch
+
+Fetch and analyze content from one or more URLs using Gemini 2.5 Flash with URL context.
+
+```bash
+nansen web fetch https://nansen.ai --question "What products does Nansen offer?"
+nansen web fetch --url https://example.com --url https://other.com --question "Compare these two sites"
+nansen web fetch https://docs.uniswap.org/contracts/v4/overview --question "What changed in v4?"
+```
+
+Positional args and `--url` flags can be combined — all become URLs to fetch.
+
+| Flag | Values | Default | Purpose |
+|------|--------|---------|---------|
+| `--url` | URL | — | URL to fetch (repeatable for multiple URLs, up to 20) |
+| `--question` | string | **required** | Question to answer about the URL content |
+| `--pretty` | flag | off | Human-readable JSON |
+
+Returns:
+- `analysis` — AI-generated answer to your question
+- `retrieved_urls` — URLs successfully fetched
+- `failed_urls` — URLs that could not be retrieved
+
+**Tip:** Combine with `web search` — search first to find relevant URLs, then fetch to get full content.
+
+```bash
+# Find and analyze in two steps
+nansen web search "uniswap v4 launch" --num-results 3 --fields link
+nansen web fetch https://blog.uniswap.org/... --question "What are the key changes?"
+```
+
+**Note:** 30s timeout. Paywalled or bot-blocked pages may appear in `failed_urls`.

package/skills/nansen-web-search/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: nansen-web-search
+description: Search the web for one or more queries in parallel. Use when you need current information, news, prices, or any web content to complement on-chain Nansen data.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+      bins:
+        - nansen
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*)
+---
+
+# Web Search
+
+Search the web for one or more queries in parallel via the Serper API.
+
+```bash
+nansen web search "bitcoin price"
+nansen web search "solana ecosystem news" --num-results 5
+nansen web search --query "ethereum ETF" --query "bitcoin ETF" --num-results 3
+```
+
+Positional args and `--query` flags can be combined — all become queries.
+
+| Flag | Values | Default | Purpose |
+|------|--------|---------|---------|
+| `--query` | string | — | Query string (repeatable for multiple queries) |
+| `--num-results` | 1–20 | 10 | Results per query |
+| `--pretty` | flag | off | Human-readable JSON |
+
+Returns `results[]` — one entry per query, each with `organic[]` (title, link, snippet, date) and optional `knowledge_graph`.
+
+**Note:** Some domains are excluded from results (paywalled/unfetchable sites like bloomberg.com, twitter.com). Use `nansen web fetch` to retrieve content from specific URLs.