nansen-cli 1.17.0 → 1.19.0

package/skills/nansen-smart-alerts/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: nansen-smart-alerts
+description: Manage smart alerts — list, create, update, toggle, delete. Use when setting up or managing token flow alerts, smart money alerts, or notification rules.
+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:*)
+---
+
+# Smart Alerts
+
+CRUD management for smart alerts. Alerts are internal-only (requires Nansen internal API key).
+
+## Quick Reference
+
+```bash
+nansen alerts list --table
+nansen alerts create --name <name> --type <type> --chains <chains> --telegram <chatId>
+nansen alerts update <id> [--name <name>] [--chains <chains>]
+nansen alerts toggle <id> --enabled|--disabled
+nansen alerts delete <id>
+```
+
+## Options Reference
+
+| Flag | Create | Update | Toggle | Delete |
+|------|--------|--------|--------|--------|
+| `<id>` (positional) | | required | required | required |
+| `--name` | required | optional | | |
+| `--type` | required | required with type-specific flags | | |
+| `--chains` | recommended | optional | | |
+| `--telegram` | chat ID | optional | | |
+| `--slack` | webhook URL | optional | | |
+| `--discord` | webhook URL | optional | | |
+| `--description` | optional | optional | | |
+| `--enabled` | | flag | flag | |
+| `--disabled` | flag | flag | flag | |
+| `--data` | optional (JSON escape hatch) | optional | | |
+
+## Alert Types
+
+### 1. `sm-token-flows` — Smart Money Token Flows
+
+Track aggregated SM inflow/outflow. At least one flow threshold should be specified.
+
+**Type-specific flags:**
+- `--inflow-1h-min/max`, `--inflow-1d-min/max`, `--inflow-7d-min/max` (USD thresholds)
+- `--outflow-1h-min/max`, `--outflow-1d-min/max`, `--outflow-7d-min/max`
+- `--netflow-1h-min/max`, `--netflow-1d-min/max`, `--netflow-7d-min/max`
+- `--token <address:chain>` (repeatable) — include specific tokens
+- `--exclude-token <address:chain>` (repeatable)
+- `--token-sector <name>` / `--exclude-token-sector <name>` (repeatable)
+- `--token-age-max <days>`
+- `--market-cap-min/max <usd>`, `--fdv-min/max <usd>`
+
+**Example:**
+```bash
+nansen alerts create \
+  --name 'SM ETH Inflow >5M' \
+  --type sm-token-flows \
+  --chains ethereum \
+  --telegram 5238612255 \
+  --inflow-1h-min 5000000 \
+  --token 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:ethereum
+```
+
+### 2. `common-token-transfer` — Token Transfer Events
+
+Track real-time transfer events matching specified criteria.
+
+**Subject types:** `address`, `entity`, `label`, `custom-label`
+Format: `--subject type:value` (e.g. `--subject label:"Centralized Exchange"`)
+
+**Type-specific flags:**
+- `--events <buy,sell,swap,send,receive>` (comma-separated)
+- `--usd-min/max <usd>`, `--token-amount-min/max <n>`
+- `--subject <type:value>` (repeatable) — addresses/entities/labels to track
+- `--counterparty <type:value>` (repeatable) — requires `--subject`
+- `--token <address:chain>` / `--exclude-token <address:chain>` (repeatable)
+- `--token-sector <name>` / `--exclude-token-sector <name>` (repeatable)
+- `--token-age-min/max <days>`, `--market-cap-min/max <usd>`
+- `--exclude-from <type:value>` / `--exclude-to <type:value>` (repeatable)
+
+**Event direction notes:**
+- `buy` for counterparties = `sell` for subjects
+- `send` for counterparties = `receive` for subjects
+- To track "any address sending to CEX": use `--subject` with `receive`, not `--counterparty` with `send`
+
+**Example:**
+```bash
+nansen alerts create \
+  --name 'Large USDC Transfers' \
+  --type common-token-transfer \
+  --chains ethereum \
+  --telegram 123456789 \
+  --events send,receive \
+  --usd-min 1000000 \
+  --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48:ethereum
+```
+
+### 3. `smart-contract-call` — Smart Contract Interactions
+
+Track contract calls matching specified criteria.
+
+**Type-specific flags:**
+- `--usd-min/max <usd>`
+- `--signature-hash <hash>` (repeatable, e.g. `0x095ea7b3` for `approve`)
+- `--caller <type:value>` / `--exclude-caller <type:value>` (repeatable)
+- `--contract <type:value>` / `--exclude-contract <type:value>` (repeatable)
+
+**Example:**
+```bash
+nansen alerts create \
+  --name 'Uniswap V3 Large Swaps' \
+  --type smart-contract-call \
+  --chains ethereum \
+  --telegram 123456789 \
+  --usd-min 1000000 \
+  --contract entity:"Uniswap V3"
+```
+
+## Notes
+
+- Chain aliases: Hyperliquid = `hyperevm`, BSC = `bnb`.
+- Multiple channels can be combined: `--telegram 123 --slack https://...`
+- `--data '<json>'` merges raw JSON on top of named flags (escape hatch for fields without named flags).
+- Alert endpoints are internal-only. Non-internal users receive 404.
+- Use single quotes for names with `$` or special characters: `--name 'SM >$1M'`

package/skills/nansen-smart-money-alpha/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: nansen-smart-money-alpha
+description: "What tokens is smart money accumulating before they pump? Token screener with SM filter cross-referenced against netflow."
+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:*)
+---
+
+# Alpha Discovery
+
+**Answers:** "What tokens is smart money accumulating before they pump?"
+
+```bash
+CHAIN=solana
+
+nansen research token screener --chain $CHAIN --timeframe 24h --smart-money --limit 20
+# → token_symbol, price_usd, price_change, volume, buy_volume, market_cap_usd, fdv, liquidity, token_age_days
+
+nansen research smart-money netflow --chain $CHAIN --labels "Smart Trader" --limit 10
+# → token_symbol, net_flow_1h/24h/7d/30d_usd, trader_count
+
+# Confirm SM flow on a specific token from screener results
+TOKEN=<address_from_screener>
+nansen research token flow-intelligence --token $TOKEN --chain $CHAIN
+# → net_flow_usd per label: smart_trader, whale, exchange, fresh_wallets
+```
+
+Cross-reference screener results with positive netflow to find early accumulation.
+
+## Source
+
+- npm: https://www.npmjs.com/package/nansen-cli
+- GitHub: https://github.com/nansen-ai/nansen-cli

package/skills/nansen-smart-money-tracker/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: nansen-smart-money-tracker
+description: Smart money tracking — netflow, trades, holdings, perp trades. Use when finding what smart money wallets are buying/selling or tracking whale activity.
+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:*)
+---
+
+# Smart Money
+
+All commands: `nansen research smart-money <sub> [options]`
+
+## Subcommands
+
+```bash
+# Netflow — what tokens are smart money accumulating?
+nansen research smart-money netflow --chain solana --limit 10
+
+# DEX trades — real-time spot trades by smart money
+nansen research smart-money dex-trades --chain solana --labels "Smart Trader" --limit 20
+
+# Holdings — aggregated SM portfolio
+nansen research smart-money holdings --chain solana --limit 10
+
+# Perp trades — Hyperliquid only (no --chain needed)
+nansen research smart-money perp-trades --limit 10
+```
+
+## Labels
+
+Filter by smart money category with `--labels`:
+
+| Label | Use case |
+|-------|----------|
+| `Fund` | Crypto funds |
+| `Smart Trader` | All-time top performers |
+| `30D Smart Trader` | Hot hands — top 30 days |
+| `90D Smart Trader` | Top 90 days |
+| `180D Smart Trader` | Top 180 days |
+| `Smart HL Perps Trader` | Top Hyperliquid perp traders |
+
+```bash
+nansen research smart-money netflow --chain solana --labels "Fund" --limit 10
+```
+
+## Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--chain` | Required for netflow/dex-trades/holdings |
+| `--labels` | Filter by SM label (quote multi-word values) |
+| `--limit` | Number of results |
+| `--sort` | Sort field:direction (e.g. `value_usd:desc`) |
+| `--fields` | Select specific fields |
+| `--table` | Human-readable table output |
+| `--format csv` | CSV export |
+
+## Notes
+
+- `perp-trades` is Hyperliquid-only. No `--chain` flag.
+- For a time-series view of SM positions: `nansen research smart-money historical-holdings --chain <chain> --days 30`

package/skills/nansen-smart-money-trend/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: nansen-smart-money-trend
+description: "Has SM been in this token for weeks, or did they just enter? Are they still buying?"
+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:*)
+---
+```bash
+TOKEN=<address> CHAIN=ethereum
+nansen research smart-money netflow --chain $CHAIN --limit 200
+# → filter by token_address; net_flow_1h_usd, net_flow_24h_usd, net_flow_7d_usd, net_flow_30d_usd
+nansen research token holders --token $TOKEN --chain $CHAIN --smart-money --limit 20
+# → address_label, value_usd, balance_change_24h, balance_change_7d, balance_change_30d
+nansen research token flow-intelligence --token $TOKEN --chain $CHAIN
+# → smart_trader_net_flow_usd, whale_net_flow_usd, fund_net_flow_usd, fresh_wallets_net_flow_usd
+nansen research token dex-trades --token $TOKEN --chain $CHAIN --limit 50
+# → block_timestamp, action, trader_address_label — find oldest SM-labeled BUY
+```
+1h/24h+ & 7d/30d+ = sustained accumulation. 24h+ & 7d− = fresh entry.
+24h− & 7d+ = reducing. All negative = distribution.

package/skills/nansen-token-research/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: nansen-token-research
+description: Token deep dive — info, OHLCV, holders, flows, flow intelligence, who bought/sold, DEX trades, PnL, perp trades, perp positions, perp PnL leaderboard. Use when researching a specific token in depth.
+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:*)
+---
+
+# Token Deep Dive
+
+All commands: `nansen research token <sub> [options]`
+
+`--chain` required for spot endpoints. Use `--token <address>` for token-specific endpoints.
+
+## Info & Price
+
+```bash
+nansen research token info --token <addr> --chain solana
+nansen research token ohlcv --token <addr> --chain solana --timeframe 1h
+```
+
+Timeframes: `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `1d`, `1w`, `1M`
+
+## Holders
+
+```bash
+nansen research token holders --token <addr> --chain solana
+nansen research token holders --token <addr> --chain solana --smart-money
+```
+
+## Flows
+
+```bash
+nansen research token flows --token <addr> --chain solana --days 7
+nansen research token flow-intelligence --token <addr> --chain solana
+nansen research token who-bought-sold --token <addr> --chain solana
+```
+
+`flow-intelligence` breaks down by label: whales, smart traders, exchanges, fresh wallets, public figures.
+
+## DEX Trades
+
+```bash
+nansen research token dex-trades --token <addr> --chain solana --limit 20
+```
+
+## PnL
+
+```bash
+nansen research token pnl --token <addr> --chain solana --sort total_pnl_usd:desc
+```
+
+## Perps (no --chain)
+
+```bash
+nansen research token perp-trades --symbol ETH --days 7
+nansen research token perp-positions --symbol BTC
+nansen research token perp-pnl-leaderboard --symbol SOL
+```
+
+## Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--chain` | Required for spot endpoints (ethereum, solana, base, etc.) |
+| `--token` | Token address (alias: `--token-address`) |
+| `--symbol` | Token symbol for perp endpoints (e.g. BTC) |
+| `--timeframe` | OHLCV interval |
+| `--smart-money` | Filter to SM wallets only (holders) |
+| `--days` | Lookback period (default 30) |
+| `--sort` | Sort field:direction (e.g. `total_pnl_usd:desc`) |
+| `--fields` | Select specific fields |
+| `--table` | Human-readable table output |
+| `--format csv` | CSV export |
+
+## Notes
+
+- Perp endpoints use `--symbol` (e.g. BTC), not `--token`.
+- `holders --smart-money` returns UNSUPPORTED_FILTER for tokens without SM tracking.
+- `flow-intelligence` may return all-zero flows for illiquid tokens.

package/skills/nansen-token-screener/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: nansen-token-screener
+description: "Discover trending tokens — screener, SM holdings, Nansen indicators, and flow intelligence for promising finds. Use when scanning for new tokens or screening what's hot."
+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:*)
+---
+
+# Token Discovery
+
+**Answers:** "What tokens are trending and worth a deeper look?"
+
+```bash
+CHAIN=solana
+
+# Screen top tokens by volume
+nansen research token screener --chain $CHAIN --timeframe 24h --limit 20
+# → token_symbol, price_usd, price_change, volume, buy_volume, market_cap_usd, fdv, liquidity, token_age_days
+
+# Smart money only
+nansen research token screener --chain $CHAIN --timeframe 24h --smart-money --limit 20
+
+# Search within screener results (client-side filter)
+nansen research token screener --chain $CHAIN --search "bonk"
+
+# Smart money holdings — what SM wallets are holding
+nansen research smart-money holdings --chain $CHAIN --labels "Smart Trader" --limit 20
+# → token_symbol, value_usd, holders_count, balance_24h_percent_change, share_of_holdings_percent
+
+# Nansen indicators for a specific token
+TOKEN=<address>
+nansen research token indicators --token $TOKEN --chain $CHAIN
+# → risk_indicators, reward_indicators (each with score, signal, signal_percentile)
+
+# Flow intelligence — only use for promising tokens from screener/indicators above
+nansen research token flow-intelligence --token $TOKEN --chain $CHAIN
+# → net_flow_usd per label: smart_trader, whale, exchange, fresh_wallets, public_figure
+```
+
+Screener timeframes: `5m`, `10m`, `1h`, `6h`, `24h`, `7d`, `30d`
+
+Indicators: score is "bullish"/"bearish"/"neutral". signal_percentile > 70 = historically significant. Some tokens return empty indicators — not an error.
+
+Flow intelligence is credit-heavy. Use it to confirm SM conviction on tokens that already look promising from screener + indicators, not as a first pass on every token.

package/skills/nansen-token-transfer-analysis/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: nansen-token-transfer-analysis
+description: "Where is this token moving and why? Large transfers, flow trends over time, and breakdown by wallet label."
+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:*)
+---
+
+# Token Forensics
+
+**Answers:** "Where is this token moving? Who is sending it and where?"
+
+```bash
+TOKEN=<address> CHAIN=ethereum
+# Examples: UNI on ethereum (0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984)
+#           BONK on solana (DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263)
+# Note: token flows does NOT support stablecoins (USDC, USDT, etc.) — use non-stablecoin tokens
+
+nansen research token transfers --token $TOKEN --chain $CHAIN --days 7 --limit 20
+# → from_address_label, to_address_label, transfer_amount, transfer_value_usd
+
+nansen research token flows --token $TOKEN --chain $CHAIN --days 7 --limit 20
+# → date, price_usd, holders_count, total_inflows_count, total_outflows_count
+# ⚠ Returns HTTP 422 for stablecoins — skip this command if TOKEN is a stablecoin
+
+nansen research token flow-intelligence --token $TOKEN --chain $CHAIN
+# → net_flow_usd per label: smart_trader, whale, exchange, fresh_wallets, public_figure
+```
+
+Rising exchange_net_flow + large transfers to exchange addresses = potential sell pressure. Fresh wallet inflows may signal new interest or wash trading.

package/skills/nansen-trading/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: nansen-trading
+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-manager 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-batch/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: nansen-wallet-batch
+description: "Which of these addresses are smart money? Batch-profile a list in one call."
+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:*)
+---
+```bash
+ADDRESSES="0xaddr1,0xaddr2,0xaddr3,..." CHAIN=ethereum
+nansen research profiler batch --addresses "$ADDRESSES" --chain $CHAIN --include labels,balance
+# → .data.{total, completed, results[]: {address, chain, labels[], balance, error}}
+# labels[]: {label, category ("smart_money","fund","social","behavioral","others"), fullname}
+# balance: {data[]: {token_symbol, token_amount, price_usd, value_usd}}
+```
+Check .error per result — invalid addresses return an error message, not a crash. Skip those.
+Keep addresses where any label.category == "smart_money" or "fund". Omit balance for faster checks.

package/skills/nansen-wallet-clustering/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-clustering/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: nansen-wallet-clustering
+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.