diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 24a04f1..51df32d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -148,11 +148,40 @@ }, { "name": "nansen-skills", - "description": "Nansen on-chain analytics — smart money DCA tracking, wallet labels, token flow intelligence, and whale activity on Solana.", + "description": "Nansen on-chain analytics — smart money tracking, wallet profiling, token research, DeFi positions, cross-chain flows, prediction markets, and more.", "source": "./", "strict": false, "skills": [ - "./skills/nansen-dca-tracker" + "./skills/nansen-dca-tracker", + "./skills/nansen-defi-positions", + "./skills/nansen-exit-signals", + "./skills/nansen-fund-tracker", + "./skills/nansen-general-search", + "./skills/nansen-holder-analysis", + "./skills/nansen-perp-screener", + "./skills/nansen-perp-trader-profile", + "./skills/nansen-polymarket-deep-dive", + "./skills/nansen-polymarket-insider-scan", + "./skills/nansen-polymarket-trader-profile", + "./skills/nansen-portfolio-tracker", + "./skills/nansen-prediction-markets", + "./skills/nansen-sm-cross-chain-flows", + "./skills/nansen-smart-alerts", + "./skills/nansen-smart-money-alpha", + "./skills/nansen-smart-money-tracker", + "./skills/nansen-smart-money-trend", + "./skills/nansen-token-research", + "./skills/nansen-token-screener", + "./skills/nansen-token-transfer-analysis", + "./skills/nansen-trading", + "./skills/nansen-wallet-batch", + "./skills/nansen-wallet-clustering", + "./skills/nansen-wallet-deep-dive", + "./skills/nansen-wallet-keychain-migration", + "./skills/nansen-wallet-manager", + "./skills/nansen-wallet-profiler", + "./skills/nansen-web-fetcher", + "./skills/nansen-web-searcher" ] } ] diff --git a/skills/nansen-defi-positions/SKILL.md b/skills/nansen-defi-positions/SKILL.md new file mode 100644 index 0000000..ccab5c2 --- /dev/null +++ b/skills/nansen-defi-positions/SKILL.md @@ -0,0 +1,37 @@ +--- +name: nansen-defi-positions +description: "What DeFi positions does a wallet hold? Protocol-by-protocol breakdown of assets, debts, and rewards across chains." +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:*) +--- + +# DeFi Exposure + +**Answers:** "What DeFi positions does this wallet have across protocols?" + +```bash +ADDR=
+ +nansen research portfolio defi --wallet $ADDR +# → protocol_name, chain, total_value_usd, total_assets_usd, total_debts_usd, total_rewards_usd, tokens + +nansen research profiler balance --address $ADDR --chain ethereum +# → token_symbol, token_name, token_amount, value_usd per holding + +nansen research profiler balance --address $ADDR --chain base +``` + +Combine DeFi positions (lending, LPs, staking) with spot balances for a complete picture of on-chain exposure. + +Note: portfolio defi may return empty for wallets with no tracked DeFi positions. diff --git a/skills/nansen-exit-signals/SKILL.md b/skills/nansen-exit-signals/SKILL.md new file mode 100644 index 0000000..cc46dc0 --- /dev/null +++ b/skills/nansen-exit-signals/SKILL.md @@ -0,0 +1,39 @@ +--- +name: nansen-exit-signals +description: "Is smart money exiting a token I hold? Net flow direction, seller breakdown by label, and recent SM trades." +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:*) +--- + +# Exit Signal + +**Answers:** "Is smart money exiting a token I hold? Should I be worried?" + +```bash +TOKEN=
CHAIN=ethereum + +nansen research token flow-intelligence --token $TOKEN --chain $CHAIN +# → net_flow_usd per label: smart_trader, whale, exchange, fresh_wallets (negative = selling) + +nansen research token who-bought-sold --token $TOKEN --chain $CHAIN --limit 20 +# → address, address_label, bought/sold_volume_usd, trade_volume_usd + +nansen research smart-money netflow --chain $CHAIN --limit 10 +# → token_symbol, net_flow_1h/24h/7d/30d_usd, trader_count + +nansen research token dex-trades --token $TOKEN --chain $CHAIN --limit 20 +# → block_timestamp, action (BUY/SELL), trader_address_label, estimated_value_usd +``` + +Red flag: negative smart_trader_net_flow_usd + Smart Trader labels in who-bought-sold sellers = exit signal. diff --git a/skills/nansen-fund-tracker/SKILL.md b/skills/nansen-fund-tracker/SKILL.md new file mode 100644 index 0000000..dfd1326 --- /dev/null +++ b/skills/nansen-fund-tracker/SKILL.md @@ -0,0 +1,35 @@ +--- +name: nansen-fund-tracker +description: "What are crypto funds and VCs holding right now? Cross-chain fund portfolios and net accumulation signals." +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:*) +--- + +# Fund Watch + +**Answers:** "What are crypto funds and VCs holding right now?" + +```bash +nansen research smart-money holdings --chain ethereum --labels "Fund" --limit 20 +# → token_symbol, value_usd, holders_count, balance_24h_percent_change, share_of_holdings_percent + +nansen research smart-money holdings --chain solana --labels "Fund" --limit 20 + +nansen research smart-money netflow --chain ethereum --labels "Fund" --limit 10 +# → token_symbol, net_flow_1h/24h/7d/30d_usd, market_cap_usd, trader_count + +nansen research smart-money netflow --chain solana --labels "Fund" --limit 10 +``` + +Cross-reference holdings with netflow to see directional conviction. Positive net_flow_24h = active accumulation. diff --git a/skills/nansen-general-search/SKILL.md b/skills/nansen-general-search/SKILL.md new file mode 100644 index 0000000..05c9290 --- /dev/null +++ b/skills/nansen-general-search/SKILL.md @@ -0,0 +1,34 @@ +--- +name: nansen-general-search +description: Search for tokens or entities by name. Use when you have a token name and need the full address, or want to find an entity. +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:*) +--- + +# Search + +```bash +nansen research search "jupiter" --type token +nansen research search "Vitalik" --type entity --limit 5 +nansen research search "bonk" --chain solana --fields address,name,symbol,chain +``` + +| Flag | Purpose | +|------|---------| +| `--type` | `token` or `entity` | +| `--chain` | Filter by chain | +| `--limit` | Number of results (default 25, max 50) | +| `--fields` | Select specific output fields | + +Case-insensitive. Does NOT match by address — use `profiler labels` for address lookup. diff --git a/skills/nansen-holder-analysis/SKILL.md b/skills/nansen-holder-analysis/SKILL.md new file mode 100644 index 0000000..f57bc26 --- /dev/null +++ b/skills/nansen-holder-analysis/SKILL.md @@ -0,0 +1,38 @@ +--- +name: nansen-holder-analysis +description: "Is this token held by quality wallets or retail noise? SM holder ratio, flow breakdown by label, and recent buyer quality." +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:*) +--- + +# Holder Quality + +**Answers:** "Is this token held by quality wallets or retail noise?" + +```bash +TOKEN=
CHAIN=ethereum + +nansen research token holders --token $TOKEN --chain $CHAIN --smart-money --limit 20 +# → address, address_label, value_usd, ownership_percentage, balance_change_24h/7d/30d + +nansen research token flow-intelligence --token $TOKEN --chain $CHAIN +# → net_flow_usd and wallet_count per label: smart_trader, whale, exchange, fresh_wallets + +nansen research token who-bought-sold --token $TOKEN --chain $CHAIN --limit 20 +# → address, address_label, bought/sold_volume_usd, bought/sold_token_volume, trade_volume_usd +``` + +Red flag: high fresh_wallets flow + low SM holders. Green flag: Fund/Smart Trader labels in top 20. + +Note: holders endpoint does not support native/wrapped tokens. Use a specific token contract address. diff --git a/skills/nansen-perp-screener/SKILL.md b/skills/nansen-perp-screener/SKILL.md new file mode 100644 index 0000000..77dc132 --- /dev/null +++ b/skills/nansen-perp-screener/SKILL.md @@ -0,0 +1,32 @@ +--- +name: nansen-perp-screener +description: "What is the state of the Hyperliquid perp market? Top contracts by volume/OI, trader leaderboard, and SM perp 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:*) +--- + +# Perp Market Scan + +**Answers:** "What's the state of the Hyperliquid perp market right now?" + +```bash +nansen research perp screener --sort volume:desc --limit 20 +# → token_symbol, volume, buy/sell_volume, buy_sell_pressure, open_interest, funding, mark_price + +nansen research perp leaderboard --days 7 --limit 20 +# → trader_address, trader_address_label, total_pnl, roi, account_value + +nansen research smart-money perp-trades --limit 20 +# → token_symbol, side, action (Open/Close), value_usd, price_usd, trader_address_label +``` diff --git a/skills/nansen-perp-trader-profile/SKILL.md b/skills/nansen-perp-trader-profile/SKILL.md new file mode 100644 index 0000000..e7b47ce --- /dev/null +++ b/skills/nansen-perp-trader-profile/SKILL.md @@ -0,0 +1,39 @@ +--- +name: nansen-perp-trader-profile +description: "Deep dive on a Hyperliquid perp trader. Identity, open positions, recent trades, and overall PnL." +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:*) +--- + +# Perp Trader + +**Answers:** "What is this perp trader doing? What are their positions and track record?" + +```bash +ADDR=
+ +nansen research profiler labels --address $ADDR --chain ethereum +# → label, category (identity, SM labels) + +nansen research profiler perp-positions --address $ADDR +# → asset_positions, margin_summary_account_value_usd, margin_summary_total_margin_used_usd + +nansen research profiler perp-trades --address $ADDR --days 7 --limit 20 +# → timestamp, token_symbol, side, action (Open/Close/Reduce), price, size, value_usd, closed_pnl, fee_usd + +nansen research perp leaderboard --days 7 --limit 50 +# → trader_address, total_pnl, roi, account_value (check if ADDR appears) +``` + +Cross-reference perp-trades with perp-positions to see if the trader is scaling in/out. Leaderboard shows relative standing. diff --git a/skills/nansen-polymarket-deep-dive/SKILL.md b/skills/nansen-polymarket-deep-dive/SKILL.md new file mode 100644 index 0000000..12ee7df --- /dev/null +++ b/skills/nansen-polymarket-deep-dive/SKILL.md @@ -0,0 +1,50 @@ +--- +name: nansen-polymarket-deep-dive +description: "Deep dive on a Polymarket market — OHLCV, orderbook, top holders, positions, trades, and PnL leaderboard. Use when analysing a specific prediction market." +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:*) +--- + +# Prediction Market Deep Dive + +**Answers:** "What's happening in this specific market? Who holds it, who's trading it?" + +Use `market_id` from the screener (`nansen-prediction-markets` skill). + +```bash +MID= + +nansen research pm ohlcv --market-id $MID --sort period_start:desc --limit 50 +# → period_start, open, high, low, close, volume + +nansen research pm orderbook --market-id $MID +# → bids[], asks[] with price and size + +nansen research pm top-holders --market-id $MID --limit 20 +# → address, side, position_size, avg_entry_price, current_price, unrealized_pnl_usd + +nansen research pm position-detail --market-id $MID --limit 20 +# → address, side, size, avg_entry_price, current_price, pnl + +nansen research pm trades-by-market --market-id $MID --limit 20 +# → timestamp, buyer, seller, taker_action, side, size, price, usdc_value + +nansen research pm pnl-by-market --market-id $MID --limit 20 +# → address, side_held, net_buy_cost_usd, unrealized_value_usd, total_pnl_usd +``` + +Notes: +- `--market-id` is a numeric ID from the screener, not a slug. +- Works with any market ID regardless of status (active or closed/resolved). +- All addresses are Polygon (EVM). diff --git a/skills/nansen-polymarket-insider-scan/SKILL.md b/skills/nansen-polymarket-insider-scan/SKILL.md new file mode 100644 index 0000000..919a834 --- /dev/null +++ b/skills/nansen-polymarket-insider-scan/SKILL.md @@ -0,0 +1,62 @@ +--- +name: nansen-polymarket-insider-scan +description: "Scan a resolved Polymarket market for wallets exhibiting suspicious trading patterns: fresh funding, single-market focus, extreme ROI, late entry at high prices." +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:*) +--- + +# PM Suspicious Wallet Scanner + +**Answers:** "Are there wallets with suspicious trading patterns in this Polymarket market?" + +```bash +# 1. Find the resolved market +nansen research prediction-market market-screener --query "" --status closed --limit 5 +# → market_id, question, volume, last_trade_price + +# 2. Get top winners (positive PnL) — paginate if needed, keep per_page <= 10 +MID= +nansen research prediction-market pnl-by-market --market-id $MID --limit 10 +# → address (proxy), owner_address (wallet), side_held, net_buy_cost_usd, total_pnl_usd + +# 3. For each top winner, run these three calls (use proxy address for PM, owner for profiler): +PROXY= +nansen research prediction-market trades-by-address --address $PROXY --limit 100 +# → market_id, market_question, side, price, size, usdc_value, taker_action, timestamp + +OWNER= +nansen research profiler historical-balances --address $OWNER --chain polygon --days 365 --sort block_timestamp:asc --limit 100 +# → block_timestamp, value_usd, token_symbol — first non-zero value_usd = wallet funding date + +nansen research profiler labels --address $OWNER --chain polygon +# → label, category +``` + +For each winner, compute ROI = total_pnl_usd / net_buy_cost_usd * 100 (skip ROI flags if net_buy_cost_usd <= 0), then score (0–13). Within each tier group, apply only the highest matching flag: + +| Flag | Pts | Trigger | +|---|---|---| +| NEW_WALLET | 3 | First funded within 7 days of now | +| YOUNG_WALLET | 1 | First funded 8–28 days ago (skip if NEW_WALLET fires) | +| SINGLE_MARKET | 3 | trades-by-address shows only 1 distinct market_id | +| FEW_MARKETS | 1 | 2–3 distinct market_ids (skip if SINGLE_MARKET fires) | +| EXTREME_ROI | 3 | ROI >= 500% | +| HIGH_ROI | 2 | ROI 200–499% (skip if EXTREME_ROI fires) | +| LATE_ENTRY | 2 | Any trade on this market at price >= 0.80 | +| LARGE_POSITION | 2 | net_buy_cost_usd >= $10k | +| KNOWN_ENTITY | -2 | Has Nansen labels | + +Flagged at score >= 3. High risk at >= 7. High-confidence suspicious pattern: NEW_WALLET + SINGLE_MARKET + EXTREME_ROI (score 9+). + +If owner_address is invalid (e.g. "0x"), use the proxy address for profiler calls too. If historical-balances returns no records with value_usd > 0, the wallet may predate the 365-day window — treat wallet age as unknown and skip NEW_WALLET / YOUNG_WALLET flags. Pause ~1.5s between wallets to avoid rate limits. Skip wallets that error and continue scanning. diff --git a/skills/nansen-polymarket-trader-profile/SKILL.md b/skills/nansen-polymarket-trader-profile/SKILL.md new file mode 100644 index 0000000..c09e66c --- /dev/null +++ b/skills/nansen-polymarket-trader-profile/SKILL.md @@ -0,0 +1,43 @@ +--- +name: nansen-polymarket-trader-profile +description: "What is a Polymarket trader betting on? Trades by address, PnL breakdown, and market context. Use when analysing a specific Polymarket wallet." +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:*) +--- + +# Polymarket Wallet Activity + +**Answers:** "What is this Polymarket trader betting on? Are they profitable?" + +**Finding an active trader address:** Source from `trades-by-market` (guarantees trade history) rather than `top-holders` (position holders may have no recorded trades): + +```bash +# Step 1: find active traders from a market +nansen research pm trades-by-market --market-id --limit 5 +# → seller/buyer addresses with confirmed trade history — use one as ADDR below +``` + +```bash +ADDR= + +nansen research pm trades-by-address --address $ADDR --limit 20 +# → timestamp, market_question, event_title, taker_action, side, size, price, usdc_value + +nansen research pm pnl-by-address --address $ADDR --limit 20 +# → question, event_title, side_held, net_buy_cost_usd, unrealized_value_usd, total_pnl_usd, market_resolved +``` + +Note: addresses sourced from `top-holders` may return empty trade history — use `trades-by-market` to find addresses with confirmed activity. + +Look at PnL across resolved vs unresolved markets to gauge trader skill. Large positions in trending categories signal conviction. diff --git a/skills/nansen-portfolio-tracker/SKILL.md b/skills/nansen-portfolio-tracker/SKILL.md new file mode 100644 index 0000000..03b14c7 --- /dev/null +++ b/skills/nansen-portfolio-tracker/SKILL.md @@ -0,0 +1,36 @@ +--- +name: nansen-portfolio-tracker +description: "How has a wallet's portfolio changed over time? Historical balances, current snapshot, and per-token PnL." +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:*) +--- + +# Portfolio History + +**Answers:** "How has this wallet's portfolio evolved over the past month?" + +```bash +ADDR=
CHAIN=ethereum + +nansen research profiler historical-balances --address $ADDR --chain $CHAIN --days 30 --limit 20 +# → block_timestamp, token_symbol, token_amount, value_usd, chain + +nansen research profiler balance --address $ADDR --chain $CHAIN +# → token_symbol, token_name, token_amount, price_usd, value_usd + +nansen research profiler pnl --address $ADDR --chain $CHAIN --days 30 --limit 20 +# → token_symbol, pnl_usd_realised, roi_percent_realised, bought_usd, sold_usd, holding_usd, nof_buys, nof_sells +``` + +Compare historical-balances over time against current balance to see what was added/removed. PnL shows trade performance. diff --git a/skills/nansen-prediction-markets/SKILL.md b/skills/nansen-prediction-markets/SKILL.md new file mode 100644 index 0000000..fa23ece --- /dev/null +++ b/skills/nansen-prediction-markets/SKILL.md @@ -0,0 +1,47 @@ +--- +name: nansen-prediction-markets +description: "Polymarket screeners — discover trending events, top markets by volume, and search for specific markets. Use when browsing what's happening on prediction markets." +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:*) +--- + +# Prediction Market Screeners + +All commands: `nansen research prediction-market [options]` (alias: `nansen research pm `) + +No `--chain` flag needed — Polymarket runs on Polygon. + +```bash +# Top events (groups of related markets) +nansen research pm event-screener --sort-by volume_24hr --limit 20 +# → event_title, market_count, total_volume, total_volume_24hr, total_liquidity, total_open_interest, tags + +# Top markets by 24h volume +nansen research pm market-screener --sort-by volume_24hr --limit 20 +# → market_id, question, best_bid, best_ask, volume_24hr, liquidity, open_interest, unique_traders_24h + +# Search for specific markets +nansen research pm market-screener --query "bitcoin" --limit 10 + +# Find resolved/closed markets +nansen research pm market-screener --status closed --limit 10 + +# Browse categories +nansen research pm categories --pretty +# → category, active_markets, total_volume_24hr, total_open_interest +``` + +Sort options: `volume_24hr`, `volume`, `volume_1wk`, `volume_1mo`, `liquidity`, `open_interest`, `unique_traders_24h`, `age_hours` + +Screeners return active/open markets by default. Use `--status closed` for resolved markets. diff --git a/skills/nansen-sm-cross-chain-flows/SKILL.md b/skills/nansen-sm-cross-chain-flows/SKILL.md new file mode 100644 index 0000000..4e18581 --- /dev/null +++ b/skills/nansen-sm-cross-chain-flows/SKILL.md @@ -0,0 +1,33 @@ +--- +name: nansen-sm-cross-chain-flows +description: "Is SM buying this token on one chain but selling on another? Detect capital rotation." +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 Cross-Chain Flows + +**Answers:** "Is SM buying this token on one chain but selling on another? Detect capital rotation." + +```bash +TOKEN_SYMBOL= CHAINS=(ethereum solana base bnb) +for chain in "${CHAINS[@]}"; do + nansen research smart-money netflow --chain $chain --limit 200 + # Filter by token_symbol; → net_flow_1h_usd, net_flow_24h_usd, net_flow_7d_usd, net_flow_30d_usd +done +``` + +Absent from results = SM activity below threshold on that chain, not necessarily unsupported. Use --limit 200; --limit 100 silently drops mid-tier tokens. +ETH+ & SOL− = rotating from SOL→ETH. One chain positive only = chain-specific play. +24h/7d divergence across chains is the rotation signal, not 1h. diff --git a/skills/nansen-smart-alerts/SKILL.md b/skills/nansen-smart-alerts/SKILL.md new file mode 100644 index 0000000..290c6c1 --- /dev/null +++ b/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 --type --chains --telegram +nansen alerts update [--name ] [--chains ] +nansen alerts toggle --enabled|--disabled +nansen alerts delete +``` + +## Options Reference + +| Flag | Create | Update | Toggle | Delete | +|------|--------|--------|--------|--------| +| `` (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 ` (repeatable) — include specific tokens +- `--exclude-token ` (repeatable) +- `--token-sector ` / `--exclude-token-sector ` (repeatable) +- `--token-age-max ` +- `--market-cap-min/max `, `--fdv-min/max ` + +**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 ` (comma-separated) +- `--usd-min/max `, `--token-amount-min/max ` +- `--subject ` (repeatable) — addresses/entities/labels to track +- `--counterparty ` (repeatable) — requires `--subject` +- `--token ` / `--exclude-token ` (repeatable) +- `--token-sector ` / `--exclude-token-sector ` (repeatable) +- `--token-age-min/max `, `--market-cap-min/max ` +- `--exclude-from ` / `--exclude-to ` (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 ` +- `--signature-hash ` (repeatable, e.g. `0x095ea7b3` for `approve`) +- `--caller ` / `--exclude-caller ` (repeatable) +- `--contract ` / `--exclude-contract ` (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 ''` 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'` diff --git a/skills/nansen-smart-money-alpha/SKILL.md b/skills/nansen-smart-money-alpha/SKILL.md new file mode 100644 index 0000000..10cc3b8 --- /dev/null +++ b/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= +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 diff --git a/skills/nansen-smart-money-tracker/SKILL.md b/skills/nansen-smart-money-tracker/SKILL.md new file mode 100644 index 0000000..00d8f65 --- /dev/null +++ b/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 [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 --days 30` diff --git a/skills/nansen-smart-money-trend/SKILL.md b/skills/nansen-smart-money-trend/SKILL.md new file mode 100644 index 0000000..9d873fa --- /dev/null +++ b/skills/nansen-smart-money-trend/SKILL.md @@ -0,0 +1,36 @@ +--- +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:*) +--- + +# Smart Money Trend Analysis + +**Answers:** "Has SM been in this token for weeks, or did they just enter? Are they still buying?" + +```bash +TOKEN=
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. diff --git a/skills/nansen-token-research/SKILL.md b/skills/nansen-token-research/SKILL.md new file mode 100644 index 0000000..655161d --- /dev/null +++ b/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 [options]` + +`--chain` required for spot endpoints. Use `--token
` for token-specific endpoints. + +## Info & Price + +```bash +nansen research token info --token --chain solana +nansen research token ohlcv --token --chain solana --timeframe 1h +``` + +Timeframes: `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `1d`, `1w`, `1M` + +## Holders + +```bash +nansen research token holders --token --chain solana +nansen research token holders --token --chain solana --smart-money +``` + +## Flows + +```bash +nansen research token flows --token --chain solana --days 7 +nansen research token flow-intelligence --token --chain solana +nansen research token who-bought-sold --token --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 --chain solana --limit 20 +``` + +## PnL + +```bash +nansen research token pnl --token --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. diff --git a/skills/nansen-token-screener/SKILL.md b/skills/nansen-token-screener/SKILL.md new file mode 100644 index 0000000..c7cd3b9 --- /dev/null +++ b/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=
+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. diff --git a/skills/nansen-token-transfer-analysis/SKILL.md b/skills/nansen-token-transfer-analysis/SKILL.md new file mode 100644 index 0000000..1d5e6a4 --- /dev/null +++ b/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=
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. diff --git a/skills/nansen-trading/SKILL.md b/skills/nansen-trading/SKILL.md new file mode 100644 index 0000000..8fd6334 --- /dev/null +++ b/skills/nansen-trading/SKILL.md @@ -0,0 +1,104 @@ +--- +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 +``` + +## 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 — NEVER USD + +`--amount` accepts **integer base units only** (lamports, wei, etc). It is never a USD value. + +| Token | Decimals | 1 token = | +|-------|----------|-----------| +| SOL | 9 | `1000000000` | +| ETH | 18 | `1000000000000000000` | +| USDC | 6 | `1000000` | + +If the user says "$20 worth of X", you must convert USD → token amount → base units. For example, to buy $20 of SOL at $150/SOL: $20 ÷ $150 = 0.1333 SOL = 133,300,000 lamports → `--amount 133300000`. Use a price lookup (e.g. `nansen research token info`) to get the current price first. + +## 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 diff --git a/skills/nansen-wallet-batch/SKILL.md b/skills/nansen-wallet-batch/SKILL.md new file mode 100644 index 0000000..257e746 --- /dev/null +++ b/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. diff --git a/skills/nansen-wallet-clustering/SKILL.md b/skills/nansen-wallet-clustering/SKILL.md new file mode 100644 index 0000000..8bd9c25 --- /dev/null +++ b/skills/nansen-wallet-clustering/SKILL.md @@ -0,0 +1,45 @@ +--- +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=
CHAIN= # 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. diff --git a/skills/nansen-wallet-deep-dive/SKILL.md b/skills/nansen-wallet-deep-dive/SKILL.md new file mode 100644 index 0000000..50d20d6 --- /dev/null +++ b/skills/nansen-wallet-deep-dive/SKILL.md @@ -0,0 +1,45 @@ +--- +name: nansen-wallet-deep-dive +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=
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. diff --git a/skills/nansen-wallet-keychain-migration/SKILL.md b/skills/nansen-wallet-keychain-migration/SKILL.md new file mode 100644 index 0000000..d0e8696 --- /dev/null +++ b/skills/nansen-wallet-keychain-migration/SKILL.md @@ -0,0 +1,183 @@ +--- +name: nansen-wallet-keychain-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="" 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="" 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) diff --git a/skills/nansen-wallet-manager/SKILL.md b/skills/nansen-wallet-manager/SKILL.md new file mode 100644 index 0000000..062844c --- /dev/null +++ b/skills/nansen-wallet-manager/SKILL.md @@ -0,0 +1,198 @@ +--- +name: nansen-wallet-manager +description: Wallet management — create (local or Privy server-side), 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 +# Or via env var: +NANSEN_API_KEY= nansen login + +# Verify +nansen research profiler labels --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum +``` + +## Wallet Providers + +The CLI supports two wallet providers: + +| | **Local** (default) | **Privy** (server-side) | +|---|---|---| +| Key storage | Encrypted on disk | Server-side via Privy API | +| Password required | Yes (min 12 chars) | No | +| Export private keys | Yes (`wallet export`) | No — keys are managed by Privy | +| Best for | Human users, manual trading | Agents, automated workflows | +| Flag | `--provider local` (default) | `--provider privy` | +| Required env vars | `NANSEN_WALLET_PASSWORD` | `PRIVY_APP_ID` + `PRIVY_APP_SECRET` | + +## Privy Wallet Creation + +Privy wallets are server-side wallets managed by the Privy API. No password is needed — keys never touch the local machine. + +### Prerequisites + +The following environment variables must be set: + +| Var | Purpose | +|-----|---------| +| `PRIVY_APP_ID` | Privy application ID | +| `PRIVY_APP_SECRET` | Privy application secret | + +### Create a Privy wallet + +```bash +nansen wallet create --provider privy +# Or with a custom name: +nansen wallet create --name agent-wallet --provider privy +``` + +### Critical rules for agents (Privy) + +- **No password needed** — Privy manages keys server-side +- **Cannot export keys** — `wallet export` only works for local wallets +- All other operations (`list`, `show`, `send`, `delete`, `default`) work identically for both providers + +## Local Wallet Creation (Two-Step Agent Flow) + +> This section covers **local** wallet creation. For Privy server-side wallets, see the [Privy Wallet Creation](#privy-wallet-creation) section above — no password is needed. + +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="" 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 + +### Privy (server-side, no password) + +```bash +nansen wallet create --provider privy +# Or with a custom name: +nansen wallet create --name trading --provider privy +``` + +Requires `PRIVY_APP_ID` + `PRIVY_APP_SECRET` env vars. No password needed. + +### Local (encrypted on disk, password required) + +```bash +# Ask the user for a password first, then: +NANSEN_WALLET_PASSWORD="" nansen wallet create +# Or with a custom name: +NANSEN_WALLET_PASSWORD="" nansen wallet create --name trading +``` + +## List & Show + +```bash +nansen wallet list +nansen wallet show +nansen wallet default +``` + +## Send + +```bash +# Send native token (SOL, ETH) — password auto-resolved from keychain +nansen wallet send --to --amount 1.5 --chain solana + +# Send entire balance +nansen wallet send --to --chain evm --max + +# Dry run (preview, no broadcast) +nansen wallet send --to --amount 1.0 --chain evm --dry-run +``` + +## Export & Delete + +```bash +# Password auto-resolved from keychain +nansen wallet export +nansen wallet delete +``` + +## 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-keychain-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 | +| `--provider` | Wallet provider: `local` (default, encrypted on disk) or `privy` (server-side via Privy API) | +| `--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 `) | +| `PRIVY_APP_ID` | Privy application ID (required for `--provider privy`) | +| `PRIVY_APP_SECRET` | Privy application secret (required for `--provider privy`) | +| `NANSEN_WALLET_PROVIDER` | Default provider for wallet create — `local` or `privy` | +| `NANSEN_EVM_RPC` | Custom EVM RPC endpoint | +| `NANSEN_SOLANA_RPC` | Custom Solana RPC endpoint | diff --git a/skills/nansen-wallet-profiler/SKILL.md b/skills/nansen-wallet-profiler/SKILL.md new file mode 100644 index 0000000..071f4db --- /dev/null +++ b/skills/nansen-wallet-profiler/SKILL.md @@ -0,0 +1,98 @@ +--- +name: nansen-wallet-profiler +description: Wallet profiler — balance, PnL, labels, transactions, counterparties, related wallets, batch, trace, compare. Use when analysing a specific wallet address or comparing wallets. +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 Profiler + +All commands: `nansen research profiler [options]` + +`--address` and `--chain` required for most commands. + +## Balance & Identity + +```bash +nansen research profiler balance --address --chain ethereum +nansen research profiler labels --address --chain ethereum +nansen research profiler search --query "Vitalik" +``` + +## PnL + +```bash +nansen research profiler pnl --address --chain ethereum --days 30 +nansen research profiler pnl-summary --address --chain ethereum +``` + +## Transactions & History + +```bash +nansen research profiler transactions --address --chain ethereum --limit 20 +nansen research profiler historical-balances --address --chain solana --days 30 +``` + +## Relationships + +```bash +nansen research profiler related-wallets --address --chain ethereum +nansen research profiler counterparties --address --chain ethereum --days 30 +``` + +## Perps (no --chain) + +```bash +nansen research profiler perp-positions --address +nansen research profiler perp-trades --address --days 7 +``` + +## Batch, Trace & Compare + +```bash +# Batch — profile multiple wallets at once +nansen research profiler batch \ + --addresses "0xabc,0xdef" --chain ethereum \ + --include labels,balance,pnl + +# Trace — BFS multi-hop counterparty trace (makes N*width API calls) +nansen research profiler trace --address --chain ethereum --depth 2 --width 5 + +# Compare — shared counterparties and tokens between two wallets +nansen research profiler compare --addresses "0xabc,0xdef" --chain ethereum +``` + +## Flags + +| Flag | Purpose | +|------|---------| +| `--address` | Wallet address (required) | +| `--chain` | Required except for perps and search | +| `--days` | Lookback period (default 30) | +| `--limit` | Number of results | +| `--include` | Batch fields: `labels,balance,pnl` | +| `--depth` | Trace depth 1-5 (default 2) | +| `--width` | Trace width — keep low to save credits | +| `--fields` | Select specific fields | +| `--table` | Human-readable table output | +| `--format csv` | CSV export | + +## Notes + +- `pnl-summary` has no pagination support (returns aggregate stats, not a list). +- `perp-positions` has no pagination support. +- `labels` has no pagination support — the API ignores `per_page` and always returns all labels for the address. `--limit` is not available for this sub-command. +- `transactions` caps at per_page=100 (API limit). +- `trace` makes many API calls — use `--width` conservatively. +- `batch` accepts `--file ` with one address per line as alternative to `--addresses`. diff --git a/skills/nansen-web-fetcher/SKILL.md b/skills/nansen-web-fetcher/SKILL.md new file mode 100644 index 0000000..6495c10 --- /dev/null +++ b/skills/nansen-web-fetcher/SKILL.md @@ -0,0 +1,50 @@ +--- +name: nansen-web-fetcher +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`. diff --git a/skills/nansen-web-searcher/SKILL.md b/skills/nansen-web-searcher/SKILL.md new file mode 100644 index 0000000..02c0596 --- /dev/null +++ b/skills/nansen-web-searcher/SKILL.md @@ -0,0 +1,39 @@ +--- +name: nansen-web-searcher +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.