nansen-cli 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.18.0
+
+### Minor Changes
+
+- [#265](https://github.com/nansen-ai/nansen-cli/pull/265) [`c3de691`](https://github.com/nansen-ai/nansen-cli/commit/c3de6914dcdd29f54d027f0cc415c23dd646c003) Thanks [@TimNooren](https://github.com/TimNooren)! - Add `nansen alerts` command for managing smart alerts (list, create, update, toggle, delete).
+
+  Supports three alert types: `sm-token-flows`, `common-token-transfer`, and `smart-contract-call`.
+  Named flags (`--inflow-1h-min`, `--chains`, `--telegram`, etc.) let you build alerts without raw JSON;
+  a `--data` escape hatch is available for full config overrides.
+
+  Also adds a `nansen-alerts` skill for agent integration.
+
+- [#295](https://github.com/nansen-ai/nansen-cli/pull/295) [`3ddcbde`](https://github.com/nansen-ai/nansen-cli/commit/3ddcbdec50d55e4477cd3f53c5064126dbd8580a) Thanks [@kome12](https://github.com/kome12)! - feat: add `nansen web search` and `nansen web fetch` commands (ECINT-6393)
+
+  - `nansen web search <query> [query...]` — search the web for one or more queries in parallel via `/api/v1/search/web-search`
+  - `nansen web fetch <url> [url...] --question <q>` — fetch and analyze URL content with AI via `/api/v1/search/web-fetch`
+
+### Patch Changes
+
+- [#293](https://github.com/nansen-ai/nansen-cli/pull/293) [`bcd95a8`](https://github.com/nansen-ai/nansen-cli/commit/bcd95a88942e96018337ae6b7de9f2abdbdc3464) Thanks [@TimNooren](https://github.com/TimNooren)! - Add default values for all required alert data fields to match backend schema
+
+- [#265](https://github.com/nansen-ai/nansen-cli/pull/265) [`c3de691`](https://github.com/nansen-ai/nansen-cli/commit/c3de6914dcdd29f54d027f0cc415c23dd646c003) Thanks [@TimNooren](https://github.com/TimNooren)! - Fix `alerts list` filtering (`--type`, `--enabled`, `--disabled`, `--chain`, `--token-address`, `--limit`, `--offset`).
+
+  Filters were sent as query params but silently ignored by the API. Now applied client-side after fetching all alerts.
+
+- [#301](https://github.com/nansen-ai/nansen-cli/pull/301) [`cda6796`](https://github.com/nansen-ai/nansen-cli/commit/cda6796642c588965111c53c583af2b21444d30b) Thanks [@kome12](https://github.com/kome12)! - fix: add missing openclaw metadata to 19 skills
+
+- [#294](https://github.com/nansen-ai/nansen-cli/pull/294) [`8a1cc7b`](https://github.com/nansen-ai/nansen-cli/commit/8a1cc7bdfbd9597860384dfd40fd28705e5c947c) Thanks [@yodablocks](https://github.com/yodablocks)! - fix: include skills/ directory in published npm package
+
 ## 1.17.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "src/*.js",
     "src/*.json",
+    "skills/**",
     "CHANGELOG.md"
   ],
   "scripts": {

package/skills/nansen-alerts/SKILL.md

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

@@ -0,0 +1,43 @@
+---
+name: nansen-alpha-discovery
+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-batch-wallet/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: nansen-batch-wallet
+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-cross-chain-flow/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: nansen-cross-chain-flow
+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:*)
+---
+```bash
+TOKEN_SYMBOL=<symbol e.g. "AAVE"> 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.

package/skills/nansen-dca-watch/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: nansen-dca-watch
+description: "What tokens are whales dollar-cost averaging into? Jupiter DCA strategies by smart money and target token fundamentals."
+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:*)
+---
+
+# DCA Watch
+
+**Answers:** "What tokens are whales dollar-cost averaging into on Solana?"
+
+```bash
+nansen research smart-money dcas --limit 20
+# → trader_address, trader_address_label, input/output_token_symbol, deposit_value_usd, dca_status, dca_created_at
+
+# For each top DCA target, check token fundamentals
+TARGET=<output_token_address>
+nansen research token info --token $TARGET --chain solana
+# → name, symbol, price, market_cap, token_details
+
+nansen research token flow-intelligence --token $TARGET --chain solana
+# → net_flow_usd per label: smart_trader, whale, exchange, fresh_wallets
+```
+
+To see DCA strategies targeting a specific token: `nansen research token jup-dca --token $TARGET`
+
+DCAs show long-term conviction — SM DCA targets with positive smart_trader_net_flow = high-confidence accumulation.

package/skills/nansen-defi-exposure/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: nansen-defi-exposure
+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=<address>
+
+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.

package/skills/nansen-exit-signal/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: nansen-exit-signal
+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=<address> 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.

package/skills/nansen-fund-watch/SKILL.md

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

package/skills/nansen-holder-quality/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: nansen-holder-quality
+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=<address> 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.

package/skills/nansen-perp-scan/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: nansen-perp-scan
+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
+```

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

@@ -0,0 +1,39 @@
+---
+name: nansen-perp-trader
+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=<address>
+
+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.

package/skills/nansen-pm-deep-dive/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: nansen-pm-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-market` skill).
+
+```bash
+MID=<market_id>
+
+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).

package/skills/nansen-pm-insider-scan/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: nansen-pm-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 "<market name>" --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=<market_id>
+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=<address_from_pnl>
+nansen research prediction-market trades-by-address --address $PROXY --limit 100
+# → market_id, market_question, side, price, size, usdc_value, taker_action, timestamp
+
+OWNER=<owner_address_from_pnl>
+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.