0.4.0

deficlaw

The first open-source DeFi MCP server for Claude Code.

Analyze any token in seconds. Holder intelligence, risk scoring, smart money tracking, KOL detection, slippage estimation, contract security. Zero API keys required.

> "analyze Jupiter token"

JUP is a 2.2y old Meteora token with $1.2M liquidity and $525.1M market cap.
Top 5 wallets control 61.5% of supply, very concentrated.
30 diamond hands among holders, decent conviction.
Contract looks safe: mint and freeze authorities revoked.
10 KOLs tracked: 5 holding, 5 selling.

Risk: 18/100 [LOW]
VERDICT: NEUTRAL — Mixed signals: 2 bull vs 2 bear.
Sources: dexscreener + gmgn + solana-rpc | 1.1s

Why deficlaw?

Claude Code can write code, fix bugs, deploy apps. But ask it "what's the price of BONK?" and it says "I don't have real-time data."

deficlaw fixes that. 9 tools, 3 data sources, zero config.

Install

npm install -g @0xprotovox/deficlaw
claude mcp add defi -- deficlaw

That's it. No API keys, no config files, no accounts needed.

git clone https://github.com/0xprotovox/deficlaw.git
cd deficlaw && npm install && npm run build
claude mcp add defi -- node /path/to/deficlaw/dist/index.js

Quick Start

Once installed, just type naturally in Claude Code:

Prices (fastest, ~50ms cached / ~300ms first call)

> what's the price of BONK?
> price of JUP
> how much is SOL right now?

Full Analysis (~1.1s with holders + risk + verdict)

> analyze token JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN
> deep analyze BONK
> is this token safe? EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Quick Scan (~350ms, price + risk only, no holders)

> quick analyze So11111...
> give me a quick look at this token

Search, Trending, New Launches

> search for BONK
> what's trending on solana?
> show new launches on solana in the last 30 minutes

Top Traders & Comparison

> who profited on this token?
> compare JUP vs BONK

Slippage & Security

> estimate slippage for buying this token
> is this token contract safe?

Tools Reference

analyze_token

Full token analysis with holder intelligence, risk scoring, and human-readable summary.

Returns: Token info, price (5m/1h/6h/24h), market data (mcap, fdv, volume, liquidity), contract security, risk score (0-100), holder concentration, holder categories (diamond hands, snipers, KOLs, fresh wallets, insiders, smart money), buy/sell pressure, dev wallet status, top 20 holders with PnL, KOL list, socials, actionable verdict (BUY/SELL/NEUTRAL/AVOID).

get_price

Sub-second price lookup. Accepts both addresses and name/symbol searches.

search_token

Search tokens by name or symbol across all chains.

get_trending

Trending and boosted tokens with price enrichment.

get_new_launches

Recently created tokens sorted by creation time.

get_top_traders

Who made and lost money on a token. Shows winners and losers with PnL, tags, and Twitter handles.

estimate_slippage

Jupiter-based price impact estimation for $50, $100, $500, $1000 buys. Solana only.

compare_tokens

Side-by-side comparison of two tokens: price, mcap, volume, liquidity, age, holders.

get_token_security

Quick contract security check. Solana only.

Returns: Mint authority status, freeze authority status, total supply, decimals, and a SAFE/CAUTION/DANGEROUS verdict.

Architecture

Claude Code
    |
    | MCP stdio
    v
+------------------+
|    deficlaw       |
|    MCP Server     |
|                  |
|  +-- Cache ----+ |      +--------------+
|  | TTL-based   | | ---> | DexScreener  |  prices, volume,
|  | in-memory   | |      | (free API)   |  liquidity, pairs
|  +-------------+ |      +--------------+
|                  |
|  +-- Risk ----+  |      +--------------+
|  | 8-dimension | | ---> | GMGN         |  holders, KOLs,
|  | scorer      | |      | (curl/PW)    |  tags, PnL
|  +-------------+ |      +--------------+
|                  |
|  +-- Summary --+ |      +--------------+
|  | Rule-based  | | ---> | Solana RPC   |  mint/freeze auth,
|  | generator   | |      | (free)       |  supply, LP detect
|  +-------------+ |      +--------------+
|                  |
|  +-- Jupiter --+ |      +--------------+
|  | Quote API   | | ---> | Jupiter      |  slippage quotes,
|  | client      | |      | (free API)   |  route planning
|  +-------------+ |      +--------------+
+------------------+

Key design decisions:

• curl-based GMGN fetcher bypasses Cloudflare TLS fingerprinting (Playwright fallback if curl is blocked)
• TTL-based in-memory cache with automatic cleanup prevents rate limiting and keeps responses fast
• Rate limiter with exponential backoff and retry logic for DexScreener (200ms min interval)
• Parallel fetching where possible (holders + security run simultaneously)
• All free APIs, no keys needed

Performance

Benchmarked on real tokens (BONK), averaged across multiple runs:

Risk Scoring

The composite risk scorer analyzes 8 dimensions to produce a 0-100 score:

Risk Levels:

Configuration

All environment variables are optional. deficlaw works out of the box with zero config.

Claude Code Config

Add to your project's .mcp.json:

{
  "mcpServers": {
    "defi": {
      "command": "npx",
      "args": ["-y", "@0xprotovox/deficlaw"]
    }
  }
}

{
  "mcpServers": {
    "defi": {
      "command": "npx",
      "args": ["-y", "@0xprotovox/deficlaw"],
      "env": {
        "SOLANA_RPC_URL": "https://your-rpc.com",
        "DEFICLAW_CACHE_TTL": "120000",
        "DEFICLAW_PRICE_CACHE_TTL": "30000",
        "DEBUG": "deficlaw"
      }
    }
  }
}

Supported Chains

Prices and trending work on all DexScreener-supported chains: Solana, Ethereum, Base, BSC, Arbitrum, Polygon, Avalanche, Optimism, Fantom, and more.

Holder analysis (GMGN) currently supports Solana tokens.

Slippage estimation (Jupiter) supports Solana tokens.

Roadmap

• Token analysis with holder intelligence
• Risk scoring (8 dimensions, 0-100)
• Contract security checks (mint/freeze authority)
• KOL detection with Twitter handles
• Human-readable AI summary with actionable insights
• Top traders (winners/losers with PnL)
• Token search by name/symbol
• New launches detection
• Actionable verdict (BUY/SELL/NEUTRAL/AVOID)
• Slippage estimation (Jupiter quotes)
• Token comparison (side by side)
• Configurable cache TTL via env vars
• Debug logging (DEBUG=deficlaw)
• LP pool detection in top holders
• Multi-chain holder analysis (Ethereum, Base)
• Price alerts via MCP resources
• Wallet portfolio analysis
• Historical price charts
• DEX aggregator integration for trade execution

Contributing

Contributions welcome! Here's how:

1. Fork the repo
2. Create your branch (git checkout -b feature/my-feature)
3. Make changes and ensure npx tsc --noEmit passes with zero errors
4. Run benchmarks (npm test) to verify nothing regressed
5. Commit and open a PR

Development setup:

git clone https://github.com/0xprotovox/deficlaw.git
cd deficlaw
npm install
npm run build    # compile TypeScript
npm test         # run speed benchmarks
npm run dev      # run from source with tsx

Built With

• Model Context Protocol SDK - MCP server framework
• DexScreener API - Price and market data
• GMGN - Holder intelligence
• Jupiter Quote API - Slippage estimation
• TypeScript, Zod, Node.js 18+

License

MIT

Author

@0xprotovox - Twitter | GitHub

20 years building software. Now building AI trading agents and DeFi tools.