diff --git a/skills/nansen-convergence-scanner/REFERENCE.md b/skills/nansen-convergence-scanner/REFERENCE.md new file mode 100644 index 00000000..1c55da9e --- /dev/null +++ b/skills/nansen-convergence-scanner/REFERENCE.md @@ -0,0 +1,61 @@ +# Convergence Scanner — Reference + +## Why convergence matters + +Individual wallet tracking shows one actor's opinion. Convergence detects when **multiple unrelated actors independently reach the same conclusion** — a qualitatively stronger signal than any single whale trade. + +A Fund, a Smart Trader, and an independent whale all accumulating the same token within the same window is not coordination — it's market wisdom emerging from independent analysis. + +## Independence Protocol + +Run Phase 3 for every pair of addresses on the same token. Skip the token if ANY pair fails independence: + +1. `profiler related-wallets` on address A — if B appears, **same entity** +2. `profiler compare` on A,B — if `shared_counterparties >= 3`, **likely same entity** +3. `profiler labels` on both — if identical labels AND same first funder, **same entity** + +**Independent = passes all three tests.** + +## Label diversity scoring + +Convergence is stronger when entities have different label types: + +| Mix | Multiplier | Rationale | +|-----|-----------|-----------| +| Fund + Smart Trader | 1.5x | Different strategies, same conclusion | +| Fund + Whale | 1.3x | Informed + size | +| Smart Trader + Fresh Wallet | 1.0x | Fresh could be noise | +| Same label on both | 0.8x | Possible coordination despite independence tests | + +## Multi-chain convergence + +When the same token trades on multiple chains (e.g., ETH on ethereum + arbitrum + base), extend the scan: + +```bash +for CHAIN in ethereum base arbitrum; do + nansen research smart-money netflow --chain $CHAIN --limit 20 --fields token_symbol,token_address,net_flow_usd +done +``` + +Cross-chain convergence (SM buying on ethereum AND base) is an even stronger signal than same-chain convergence. + +## False positives to filter + +- **Stablecoins** — USDC/USDT/DAI will always show multiple SM addresses. Exclude them. +- **Wrapped natives** — WETH/WSOL are operational, not directional. Exclude them. +- **Airdrop farming** — Multiple addresses buying a new token on launch day. Check if addresses were created recently (`profiler labels` → "Fresh Wallet"). If all are fresh → likely farm, not convergence. +- **Market maker flows** — Addresses labeled "Market Maker" are providing liquidity, not taking directional bets. Exclude them from convergence counting. + +## Conviction boost + +When convergence is confirmed, the implied conviction of related signals should increase: +- **Moderate** (2 entities): +10 to any prior conviction score on this token +- **Strong** (3+ entities): +15, capped at 95 +- **Very strong** (3+ with label diversity): +20, capped at 95 + +## Cost warnings + +- Each candidate pair costs 3-4 API calls for independence verification +- A token with 5 SM addresses = 10 pairs = up to 40 calls — cap at 3 pairs per token +- Use `--fields` on Phase 1 calls to reduce response size +- `profiler compare` may return sparse data for wallets with few on-chain interactions diff --git a/skills/nansen-convergence-scanner/SKILL.md b/skills/nansen-convergence-scanner/SKILL.md new file mode 100644 index 00000000..633a3528 --- /dev/null +++ b/skills/nansen-convergence-scanner/SKILL.md @@ -0,0 +1,104 @@ +--- +name: nansen-convergence-scanner +description: "Detect when multiple independent smart money entities accumulate the same token. The highest-alpha signal: unrelated actors independently reaching the same conclusion." +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:*) +--- + +# Convergence Scanner + +**Answers:** "Are multiple independent smart money actors converging on the same token?" + +Chain: `0x` → `--chain ethereum` (also base, arbitrum, optimism, polygon). Base58 → `--chain solana`. + +## Workflow + +```bash +CHAIN=solana # or ethereum, base + +# ── Phase 1: Collect SM activity ──────────────────────────── +# 1. Smart money netflow — who's accumulating? +nansen research smart-money netflow --chain $CHAIN --limit 20 --fields token_symbol,token_address,net_flow_usd +# 2. SM DEX trades — who's buying on-chain right now? +nansen research smart-money dex-trades --chain $CHAIN --limit 30 --fields token_symbol,token_address,maker,taker,value_usd + +# ── Phase 2: Group by token ──────────────────────────────── +# From results, find tokens with 2+ DISTINCT wallet addresses. +# These are convergence candidates. + +# ── Phase 3: Verify independence ──────────────────────────── +# For each candidate token with addresses ADDR_A and ADDR_B: +ADDR_A= +ADDR_B= + +# 3a. Check if they're related (same entity = NOT convergence) +nansen research profiler related-wallets --address $ADDR_A --chain $CHAIN +# If ADDR_B appears in ADDR_A's related wallets → same entity, skip. + +# 3b. Compare directly — shared counterparties + tokens +nansen research profiler compare --addresses "$ADDR_A,$ADDR_B" --chain $CHAIN +# If shared_counterparties >= 3 → likely same entity, skip. + +# 3c. Label both — different entity types strengthens signal +nansen research profiler labels --address $ADDR_A --chain $CHAIN +nansen research profiler labels --address $ADDR_B --chain $CHAIN + +# ── Phase 4: Enrich convergence signal ────────────────────── +TOKEN= +# 4a. Token fundamentals +nansen research token info --token $TOKEN --chain $CHAIN +# 4b. Flow breakdown by label (Fund, Smart Trader, Whale, etc.) +nansen research token flow-intelligence --token $TOKEN --chain $CHAIN +``` + +## Independence test + +Two addresses are **independent** when ALL of these hold: +- Address B is NOT in address A's `related-wallets` +- `profiler compare` shows < 3 shared counterparties +- They have different labels (Fund vs Smart Trader strengthens signal) + +If any test fails → same entity, not convergence. + +## Signal strength + +| Independent entities | Strength | Action | +|---------------------|----------|--------| +| 2 | Moderate | Flag for review | +| 3+ | Strong | High-priority alert | +| 3+ with different label types | Very strong | Highest conviction signal | + +## Output format + +For each convergence signal, report: + +- **Token**: symbol, address, chain +- **Entity count**: number of independent actors +- **Actors**: address, label, direction (buy/sell), value +- **Independence proof**: no related-wallets link, < 3 shared counterparties +- **Flow context**: token flow-intelligence breakdown (which label categories are buying) + +## Credit cost + +Per convergence scan: ~6-12 CLI calls. +- Phase 1: 2 calls (netflow + dex-trades) +- Phase 3: 3-4 calls per candidate pair (related-wallets + compare + labels) +- Phase 4: 2 calls per confirmed signal (info + flow-intelligence) + +Keep `--limit` low to control costs. Most scans find 0-3 convergence candidates. + +## Source + +- npm: https://www.npmjs.com/package/nansen-cli +- GitHub: https://github.com/nansen-ai/nansen-cli