Skip to content

edycutjong/NansenNexusMCP

BranchesTags

Repository files navigation

🧠 Nansen Nexus MCP

Compound Skills Router for AI Agents — Agentic orchestration layer that pre-packages complex, multi-step Nansen workflows into single LLM tool calls.

CI Status License TypeScript MCP Node 20 Node 22 Node 24 Tools Tests Coverage Nansen CLI Docker

🔑 Why Nansen Nexus? (vs. the Official Nansen MCP)

Nansen offers an excellent official MCP server with 24 tools for raw data retrieval (smart_traders_and_funds_token_balances, token_dex_trades, address_counterparties, etc.). It's the foundation — and we build on top of it.

The problem: When LLMs like Claude or Cursor try to chain 5–10 of those raw endpoints together for a complex investigation, they:

  • 🔴 Hallucinate parameters — Nansen's own docs list 5 gotchas around inconsistent arg formats (addresses: [] vs address: "" vs wallet_address: ""), case-sensitive enums ("BUY" not "buy"), and mixed {request: {...}} wrappers.
  • 🔴 Blow up context windows — chaining 8 endpoints means 8 round-trips of JSON in/out, eating 30–50K tokens before the LLM even starts reasoning.
  • 🔴 Guess execution order — "Should I call address_related_addresses before or after address_counterparties for Sybil detection?" The LLM doesn't know.

Nansen Nexus solves this as the Agentic Orchestration Layer (Level 2):

Agentic Orchestration Architecture

Official Nansen MCP (Level 1) Nansen Nexus (Level 2)
Scope 1:1 API endpoint mapping Multi-step compound workflows
Tool count 24 raw data tools 13 compound skill tools
LLM calls needed 5–10 per investigation 1
Parameter handling LLM must know gotchas Nexus normalizes internally
Context window cost ~30–50K tokens per chain ~3–5K tokens per result
Example token_flows + address_counterparties + wallet_pnl_summary + address_related_addresses (4 calls, LLM chains) network-traversal (1 call, BFS + Sybil built in)
Caching / Rate limits Managed by caller Handled under the hood
Best for Simple, single-endpoint queries Complex forensic investigations

TL;DR: Use the official Nansen MCP for quick lookups. Use Nexus when your AI agent needs to think across multiple data sources in a single step.

🎯 What is this?

Nansen Nexus MCP is the capstone of a 4-week build challenge where 90+ developers competed to build the best Nansen CLI integrations. After shipping 4 projects, writing 698 tests, and placing 🥈 2nd Place in Week 2, the pattern became clear:

Everyone built retail dashboards. Nobody built infrastructure for AI agents.

Nexus fills that gap. It wraps Nansen's entire on-chain intelligence surface into MCP-standardized compound skills that any AI agent (Claude, Cursor, Windsurf, etc.) can invoke via JSON-RPC — turning hackathon-winning logic into reusable AI plumbing.

Why MCP?

The Nansen Growth Manager on the API / MCP team identified compound workflows as the highest-leverage integration pattern. Instead of piping raw JSON into prompts, Nexus pre-packages multi-step analytics (Sybil detection, Wyckoff classification, SM divergence scoring) as single tool calls — reducing token spend, latency, and hallucinations.

🏗️ Architecture

Nansen Nexus MCP Architecture

🧬 Origin Story

Each of the 13 tools has a lineage — either derived from our own challenge projects or aggregated from the 28 best open-source community submissions:

🏆 From Our Challenge Projects

Tool Origin Project Challenge Week
polymarket-oracle Nansen Polymarket Oracle Week 3 — First tool to use prediction market endpoints
network-traversal Project RedString Week 4 — BFS wallet forensics + 3D WebGL graph
wallet-roast Inspired by Cookd.wtf (@HeavyOT) Week 1 winner — virality > complexity
stable-shield Strategic B2B gap identified in deep analysis Institutional stablecoin parking monitor
wyckoff-screener Trading signal analysis Token phase classification

🛠 From Community Aggregation

Tool Source Repos What It Bundles
airdrop-eligibility eligibility-dashboard, onchain-activity-radar Airdrop scoring + Sybil checks
smart-money-copy-trade nansen-hunt-alpha, sm-divergence-detector, +1 High-conviction SM copy list
perp-funding-monitor apexhunter-skill, nansensei, nansen-cli-tools Funding rate anomaly detection

🚀 Quick Start

Choose your preferred way to run the MCP server: NPX (Zero Config), Make, or Docker.

Register in Claude Desktop (The Zero-Config Way)

Because Nexus is published on the global NPM registry, you do not even need to download this repository. Just add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "nansen-nexus": {
      "command": "npx",
      "args": ["-y", "nansen-nexus-mcp"],
      "env": {
        "NANSEN_API_KEY": "YOUR_NANSEN_API_KEY_HERE"
      }
    }
  }
}

Restart Claude completely, and the 13 tools will immediately appear in your chat window.

Option A: Using make (For Local Development)

The included Makefile abstracts all the setup and execution commands.

# 1. Install dependencies and create .env
make setup
# ⚠️ Edit .env and insert your NANSEN_API_KEY

# 2. Build the project
make build

# 3. Run the interactive MCP Inspector UI
make inspect

# 4. Or, run in Stdio mode (for Cursor / Claude Desktop)
make serve-stdio

Option B: Using Docker

Perfect for cloud deployments (like Cloud Run) or keeping your local environment clean. The server runs on HTTP transport by default.

# 1. Create your env file
cp .env.example .env
# ⚠️ Edit .env and insert your NANSEN_API_KEY

# 2. Build and spin up the container in the background
docker compose up --build -d

# 3. View live logs
docker compose logs -f

# 4. Shut down when finished
docker compose down

(Alternatively, you can just use make docker-up and make docker-down)

🛠️ Available Compound Skills

Each tool below is a compound skill — it internally orchestrates multiple Nansen API calls, normalizes parameters, caches results, and returns a synthesized answer in a single response.

Tool Description Key Params
smart-money-tracker Track labeled wallet movements across chains chain, timeframe, entityType
token-flow-analyzer CEX/DEX inflow/outflow analysis token, chain, flowType
wallet-profiler Full wallet dossier: labels, PnL, history address, chain, includePnl
hot-contracts-scanner Discover trending Smart Money contracts chain, timeframe, limit
nft-market-tracker NFT collection volume, floor, sweeps collection, chain, metric
network-traversal BFS wallet traversal for Sybil detection address, chain, depth
polymarket-oracle Polymarket odds vs Smart Money divergence marketId, includeHolders
stable-shield Monitor institutional stablecoin parking address, chain
wallet-roast Analyze worst trades for roasting material address, chain
wyckoff-screener Screen tokens for Wyckoff phases tokenAddress, chain
perp-funding-monitor Perp market funding rate anomalies token
smart-money-copy-trade High-conviction copy-trade signals chain, minTradeUsd
airdrop-eligibility Estimate wallet airdrop eligibility address

🔍 Example Outputs

airdrop-eligibility 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "pagination": {
          "page": 1,
          "per_page": 10,
          "is_last_page": true
        },
        "data": []
      }
    }
  }
}
hot-contracts-scanner 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": false,
    "error": "Unknown research category: hot-contracts. Available: smart-money, profiler, token, search, perp, portfolio, points, prediction-market",
    "code": "UNKNOWN",
    "status": null
  }
}
network-traversal 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "pagination": {
          "page": 1,
          "per_page": 10,
          "is_last_page": true
        },
        "data": []
      }
    }
  }
}
nft-market-tracker 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "nfts": [
        "pudgy"
      ]
    },
    "cmd": "research nft paradise",
    "args": [
      "--chain",
      "ethereum",
      "--timeframe",
      "24h",
      "--metric",
      "volume",
      "--collection",
      "0x123"
    ]
  }
}
perp-funding-monitor 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "data": [
          {
            "volume": 70088716064.8529,
            "buy_volume": 35365202382.73637,
            "sell_volume": 34723513682.11654,
            "buy_sell_pressure": 641688700.61983,
            "trader_count": 82712,
            "token_symbol": "BTC",
            "mark_price": 75669,
            "funding": -0.0000183626,
            "open_interest": 2141165415.90468,
            "previous_price_usd": 71213
          },
          {
            "volume": 6683711284.2131,
            "buy_volume": 3464331241.1264,
            "sell_volume": 3219380043.0867,
            "buy_sell_pressure": 244951198.0397,
            "trader_count": 20986,
            "token_symbol": "xyz:SP500",
            "mark_price": 5180,
            "funding": -0.0000127903,
            "open_interest": 90015100.9588,
            "previous_price_usd": 5051.49
          }
        ]
      }
    }
  }
}
polymarket-oracle 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "pagination": {
          "page": 1,
          "per_page": 10,
          "is_last_page": false
        },
        "data": [
          {
            "market_id": "1994007",
            "question": "Israel x Hezbollah ceasefire by April 18, 2026?",
            "slug": "israel-x-hezbollah-ceasefire-by-april-18-2026",
            "event_id": "242420",
            "event_title": "Israel x Hezbollah ceasefire by...?",
            "active": true,
            "closed": false,
            "end_date": "2026-04-15T00:00:00",
            "neg_risk": false,
            "tags": ["Iran", "Israel", "Geopolitics"]
          }
        ]
      }
    }
  }
}
smart-money-copy-trade 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "data": [
          {
            "chain": "ethereum",
            "block_timestamp": "2026-04-19T00:36:59",
            "transaction_hash": "0xfaaa17a02ec4cba8019f010d33f529981a5971d7dd69d5a8a190ccfdda699abc",
            "trader_address": "0xbdd705c1bea262817f6d3a5cf480cceccae8d0ab",
            "trader_address_label": "Token Millionaire",
            "token_bought_address": "0x7a76db883446022ecbc86b9280e34055ec1be05c",
            "token_sold_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "token_bought_amount": 187944.962598919,
            "token_sold_amount": 666,
            "token_bought_symbol": "RISE",
            "token_sold_symbol": "USDC",
            "token_bought_age_days": 482,
            "token_sold_age_days": 2816,
            "token_bought_market_cap": null,
            "token_sold_market_cap": 78499325560,
            "token_bought_fdv": 275882.872900164,
            "token_sold_fdv": 78499721374,
            "trade_value_usd": 665.8997310560211
          }
        ]
      }
    }
  }
}
smart-money-tracker 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "data": [
          {
            "token_address": "0x5a98fcbea516cf06857215779fd812ca3bef1b32",
            "token_symbol": "LDO",
            "net_flow_1h_usd": 0,
            "net_flow_24h_usd": 253442.34317953387,
            "net_flow_7d_usd": 253442.34317953387,
            "net_flow_30d_usd": 253442.3311766702,
            "chain": "ethereum",
            "token_sectors": [],
            "trader_count": 3,
            "token_age_days": 1949,
            "market_cap_usd": 322227915
          },
          {
            "token_address": "0x8390a1da07e376ef7add4be859ba74fb83aa02d5",
            "token_symbol": "GROK",
            "net_flow_1h_usd": 0,
            "net_flow_24h_usd": 23568.647689030906,
            "net_flow_7d_usd": 23568.647689030906
          }
        ]
      }
    }
  }
}
stable-shield 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "summary": {
          "total_value_usd": 0,
          "total_assets_usd": 0,
          "total_debts_usd": 0,
          "total_rewards_usd": 0,
          "token_count": 0,
          "protocol_count": 0
        },
        "protocols": []
      }
    }
  }
}
token-flow-analyzer 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "data": [
          {
            "public_figure_net_flow_usd": 0,
            "public_figure_avg_flow_usd": null,
            "public_figure_wallet_count": 0,
            "top_pnl_net_flow_usd": 0,
            "top_pnl_avg_flow_usd": null,
            "top_pnl_wallet_count": 0,
            "whale_net_flow_usd": 0,
            "whale_avg_flow_usd": null,
            "whale_wallet_count": 0,
            "smart_trader_net_flow_usd": 0,
            "smart_trader_avg_flow_usd": null,
            "smart_trader_wallet_count": 0,
            "exchange_net_flow_usd": 0,
            "exchange_avg_flow_usd": null,
            "exchange_wallet_count": 0,
            "fresh_wallets_net_flow_usd": 0,
            "fresh_wallets_avg_flow_usd": 0,
            "fresh_wallets_wallet_count": 0
          }
        ]
      }
    }
  }
}
wallet-profiler 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "pagination": {
          "page": 1,
          "per_page": 1,
          "is_last_page": true
        },
        "top5_tokens": [],
        "traded_token_count": 0,
        "traded_times": 0,
        "realized_pnl_usd": 0,
        "realized_pnl_percent": 0,
        "win_rate": 0
      }
    }
  }
}
wallet-roast 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "pagination": {
          "page": 1,
          "per_page": 20,
          "is_last_page": true
        },
        "data": []
      }
    }
  }
}
wyckoff-screener 
{
  "metadata": {
    "status": "historical_live",
    "source": "Nansen CLI -> MCP Nexus"
  },
  "data": {
    "success": true,
    "data": {
      "success": true,
      "data": {
        "data": {
          "name": "",
          "symbol": "",
          "contract_address": "0xd8da6bf26964af9d7eed9e03e53415dd37ae6abf",
          "logo": "",
          "token_details": {
            "token_deployment_date": "",
            "website": "",
            "x": "",
            "telegram": "",
            "market_cap_usd": 0,
            "fdv_usd": 0,
            "circulating_supply": 0,
            "total_supply": 0
          },
          "spot_metrics": {
            "volume_total_usd": 0,
            "buy_volume_usd": 0,
            "sell_volume_usd": 0,
            "total_buys": 0
          }
        }
      }
    }
  }
}

📊 Nansen CLI Endpoint Coverage

Nexus exercises 50+ unique Nansen CLI endpoints across all 13 tools — the deepest coverage of any single MCP integration:

Endpoint Family Tools Using It
research smart-money netflow/dex-trades/holdings smart-money-tracker, copy-trade, stable-shield
research token info/indicators/ohlcv/screener token-flow-analyzer, wyckoff-screener
research token flow-intelligence/who-bought-sold token-flow-analyzer, wyckoff-screener
research profiler balance/labels/pnl/trace wallet-profiler, network-traversal, wallet-roast
research profiler counterparties/related-wallets network-traversal (BFS Sybil detection)
research prediction-market * (12 sub-endpoints) polymarket-oracle
research perp screener/leaderboard perp-funding-monitor
research portfolio defi stable-shield

📂 Project Structure

src/
├── index.ts                        # Entry point
├── server/
│   └── boot.ts                     # Dual transport (stdio/HTTP) server
├── lib/
│   └── nansen-cli.ts               # CLI wrapper (child_process.execFile)
├── registry/
│   ├── auto-loader.ts              # Auto-discovery engine
│   ├── helpers.ts                  # Module loading utilities
│   ├── module-processor.ts         # Validation & registration
│   └── types.ts                    # RegisterableModule interface
├── tools/
│   ├── smart-money-tracker.ts      # Smart Money movements
│   ├── token-flow-analyzer.ts      # Token flow intelligence
│   ├── wallet-profiler.ts          # Wallet dossier
│   ├── hot-contracts-scanner.ts    # Trending contracts
│   ├── nft-market-tracker.ts       # NFT market analysis
│   ├── network-traversal.ts        # BFS Sybil detection
│   ├── polymarket-oracle.ts        # Prediction market oracle
│   ├── stable-shield.ts            # Stablecoin institutional guardian
│   ├── wallet-roast.ts             # Wallet roasting
│   ├── wyckoff-screener.ts         # Wyckoff phase classifier
│   ├── perp-funding-monitor.ts     # Perp funding anomalies
│   ├── smart-money-copy-trade.ts   # Copy-trade signals
│   └── airdrop-eligibility.ts      # Airdrop scoring
└── resources/
    └── server-status.ts            # Server health resource

All tools are auto-discovered at boot via the module registry system. Just drop a .ts file in src/tools/ and it's live.

🧪 Development

# Type-check
npm run typecheck

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Interactive REPL
npm run dev

# MCP Inspector
npm run inspect

# Generate new tool
npm run gen:tool

🐳 Docker

# Build & run
docker compose up --build

# With API key
NANSEN_API_KEY=your_key docker compose up --build

🏆 Challenge Context

This project is the 5th build in a progressive arc across the Nansen CLI Build Challenge (March–April 2026):

Week Project Result What It Proved
1 Make Alpha Unplaced Zero-dep data compilation
2 NansenTerm 🥈 2nd Place (100K Credits) Interactive TUI + live streaming
3 Polymarket Oracle Submitted Predictive SM divergence scoring
4 Project RedString Submitted Forensic 3D graph visualization
5 Nansen Nexus MCP Capstone Enterprise MCP infrastructure

Season Stats

Metric Value
Projects shipped 5
Total tests (all projects) 698+
Total TypeScript LOC ~23,000+
Nansen CLI endpoints used 50+
Best placement 🥈 2nd Place (Week 2)
Prize won 100,000 Nansen API Credits

🔗 Related Projects

Project Description
nansen-make-alpha Zero-dep Makefile alpha compiler
nansen-term Bloomberg-style TUI for Nansen CLI
nansen-polymarket-oracle SM × Polymarket divergence scoring
NansenRedString Forensic 3D wallet graph visualizer

📄 License

MIT — Built by @edycutjong for the Nansen ecosystem.

About

Compound Skills Router for AI Agents — Enterprise-grade MCP server exposing Nansen on-chain intelligence as composable AI tools.

www.npmjs.com/package/nansen-nexus-mcp

Topics

typescript crypto mcp web3 ai-agents nansen mcp-server compound-skills

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages