nansen-cli 1.17.0 → 1.18.0

package/skills/nansen-polymarket-trader/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: nansen-polymarket-trader
+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 <market_id> --limit 5
+# → seller/buyer addresses with confirmed trade history — use one as ADDR below
+```
+
+```bash
+ADDR=<polymarket_address>
+
+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.

package/skills/nansen-portfolio-history/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: nansen-portfolio-history
+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=<address> 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.

package/skills/nansen-prediction-market/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: nansen-prediction-market
+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 <sub> [options]` (alias: `nansen research pm <sub>`)
+
+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.

package/skills/nansen-profiler/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: nansen-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 <sub> [options]`
+
+`--address` and `--chain` required for most commands.
+
+## Balance & Identity
+
+```bash
+nansen research profiler balance --address <addr> --chain ethereum
+nansen research profiler labels --address <addr> --chain ethereum
+nansen research profiler search --query "Vitalik"
+```
+
+## PnL
+
+```bash
+nansen research profiler pnl --address <addr> --chain ethereum --days 30
+nansen research profiler pnl-summary --address <addr> --chain ethereum
+```
+
+## Transactions & History
+
+```bash
+nansen research profiler transactions --address <addr> --chain ethereum --limit 20
+nansen research profiler historical-balances --address <addr> --chain solana --days 30
+```
+
+## Relationships
+
+```bash
+nansen research profiler related-wallets --address <addr> --chain ethereum
+nansen research profiler counterparties --address <addr> --chain ethereum --days 30
+```
+
+## Perps (no --chain)
+
+```bash
+nansen research profiler perp-positions --address <addr>
+nansen research profiler perp-trades --address <addr> --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 <addr> --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 <path>` with one address per line as alternative to `--addresses`.

package/skills/nansen-search/SKILL.md

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

package/skills/nansen-sm-trend/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: nansen-sm-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-smart-money/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: nansen-smart-money
+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-token/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: nansen-token
+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-discovery/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: nansen-token-discovery
+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-forensics/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: nansen-token-forensics
+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-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