@0xprotovox/deficlaw 0.1.1 → 0.3.0

package/README.md

@@ -1,4 +1,4 @@
-# DefiClaw
+# deficlaw
 
 **The first open-source DeFi MCP server for Claude Code.**
 
@@ -7,13 +7,13 @@ Analyze any Solana token in seconds. Holder intelligence, risk scoring, smart mo
 ```
 > "analyze token 3oQwNvAfZMuPWjVPC12ukY7RPA9JiGwLod6Pr4Lkpump"
 
-═══ SUMMARY ═══
+=== SUMMARY ===
 POKE6900 is a 9mo old PumpSwap token with $25.9K liquidity and $34.5K market cap.
 53 diamond hands (53.0%), strong holder conviction.
 Only 18.0% of holders are in profit, most are underwater with avg loss of $844 per wallet.
 Buy pressure is strong at 3.3:1 ratio (1093 buys vs 395 sells), accumulation phase.
 Contract looks safe: mint and freeze authorities revoked.
-🟢 Lower risk profile based on available data.
+Lower risk profile based on available data.
 ```
 
 ## Why deficlaw?
@@ -23,22 +23,31 @@ Claude Code can write code, fix bugs, deploy apps. But ask it "what's the price
 **deficlaw fixes that.** It gives Claude Code real-time access to DeFi data across Solana and 10+ chains.
 
 - **Token Analysis** with holder intelligence, risk scoring, KOL tracking
+- **Token Search** by name or symbol across all chains
+- **New Launches** detection with age, mcap, liquidity data
 - **Real-time Prices** from DexScreener across all major chains
 - **Trending Tokens** with volume, liquidity, and boost data
 - **Top Traders** showing who made and lost money on any token
 - **Contract Security** checking mint/freeze authority on Solana
-- **1.5 second** full analysis (not 11 seconds like browser-based scrapers)
+- **Actionable Verdicts** (BUY/SELL/NEUTRAL/AVOID) based on combined data signals
+- **~1.5 second** full analysis (not 11 seconds like browser-based scrapers)
 - **Zero config** - no API keys, no wallets, no accounts needed
 
-## Quick Start
+## Install
+
+### Option A: npm (recommended)
+
+```bash
+npm install -g @0xprotovox/deficlaw
+claude mcp add defi -- deficlaw
+```
+
+### Option B: From source
 
 ```bash
-# Clone and build
 git clone https://github.com/0xprotovox/deficlaw.git
 cd deficlaw
 npm install && npm run build
-
-# Add to Claude Code
 claude mcp add defi -- node /path/to/deficlaw/dist/index.js
 ```
 
@@ -47,6 +56,8 @@ Then just ask Claude naturally:
 ```
 > "analyze this token: 3oQw...pump"
 > "what's the price of BONK?"
+> "search for BONK token"
+> "show me new launches on solana in the last 30 minutes"
 > "show me trending tokens on solana"
 > "who made money on JUP token?"
 ```
@@ -79,14 +90,51 @@ Full token analysis with holder intelligence, risk scoring, and human-readable s
 - KOL list with Twitter handles
 - Human-readable summary with actionable insights
 
+### `search_token`
+
+Search for tokens by name or symbol. Returns top matches across all chains.
+
+```
+> "search for BONK"
+
+Results:
+1. Bonk (BONK) -- solana -- $0.000024 -- $1.8B mcap
+2. BonkBot (BONK) -- ethereum -- $0.00001 -- $2M mcap
+```
+
+**Input:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | string | required | Token name or symbol |
+| `chain` | string | all | Filter by chain |
+| `limit` | number | `10` | Results to return (1-20) |
+
+### `get_new_launches`
+
+Get recently created tokens on a blockchain, sorted by creation time.
+
+```
+> "new launches on solana last 30 minutes"
+
+1. NEWTOKEN -- 12m old -- $0.001 -- $50K mcap -- $15K liq
+2. LAUNCH2 -- 25m old -- $0.0005 -- $20K mcap -- $8K liq
+```
+
+**Input:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `chain` | string | `"solana"` | Blockchain |
+| `max_age_minutes` | number | `60` | Max token age in minutes (5-1440) |
+| `limit` | number | `20` | Tokens to return (1-50) |
+
 ### `get_price`
 
-Quick price lookup. Sub-second response.
+Quick price lookup. Sub-second response. Supports both token addresses and name/symbol search.
 
 ```
 > "price of So11111112222..."
 
-BONK — $0.000024 (+5.2% 24h)
+BONK -- $0.000024 (+5.2% 24h)
 Volume: $142M | Liquidity: $12M | MCap: $1.8B
 ```
 
@@ -97,9 +145,9 @@ Trending and boosted tokens on any chain.
 ```
 > "trending tokens on solana"
 
-1. BONK — $0.000024 (+12%) — $142M volume
-2. WIF  — $0.89 (-2.1%)   — $89M volume
-3. JUP  — $0.94 (+3.5%)   — $45M volume
+1. BONK -- $0.000024 (+12%) -- $142M volume
+2. WIF  -- $0.89 (-2.1%)   -- $89M volume
+3. JUP  -- $0.94 (+3.5%)   -- $45M volume
 ...
 ```
 
@@ -110,13 +158,13 @@ Who made and lost money on a token. Winners, losers, PnL, tags.
 ```
 > "who profited on this token?"
 
-🏆 Top Winners:
-1. CR5N... — +$680 (+124%) 🟢 still holding
-2. EsRB... — +$166 (+16%) 💎 diamond hands
+Top Winners:
+1. CR5N... -- +$680 (+124%) still holding
+2. EsRB... -- +$166 (+16%) diamond hands
 
-💀 Top Losers:
-1. BgeeV... — -$7,548 (-65%) 💎 diamond hands (!)
-2. 5vqid... — -$5,420 (-50%) gmgn user
+Top Losers:
+1. BgeeV... -- -$7,548 (-65%) diamond hands (!)
+2. 5vqid... -- -$5,420 (-50%) gmgn user
 ```
 
 ## Data Sources
@@ -141,34 +189,36 @@ Holder analysis (GMGN) currently supports **Solana** tokens.
 
 ## Risk Scoring
 
-The risk scorer analyzes 6 dimensions to produce a 0-100 score:
+The risk scorer analyzes 8 dimensions to produce a 0-100 score:
 
-| Dimension | Weight | What it checks |
-|-----------|--------|----------------|
-| Liquidity | 25% | Pool depth in USD |
-| Token Age | 10% | Time since creation |
-| Holder Concentration | 20% | Top 10 holder % |
-| Dev Wallet | 20% | Dev holdings and selling behavior |
-| Fresh Wallets | 15% | New wallet % (possible wash/bundle) |
-| Sniper Activity | 10% | Bot/sniper wallets in top holders |
+| Dimension | Max Points | What it checks |
+|-----------|-----------|----------------|
+| Liquidity | 22 | Pool depth in USD |
+| Token Age | 10 | Time since creation |
+| Volume Anomalies | 8 | Wash trading signals, vol/mcap ratio |
+| Holder Concentration | 18 | Top 10 holder % |
+| Dev Wallet | 15 | Dev holdings and selling behavior |
+| Fresh Wallets | 12 | New wallet % (possible wash/bundle) |
+| Sniper Activity | 10 | Bot/sniper wallets in top holders |
+| Contract Security | 5 | Mint/freeze authority status |
 
-**Levels:** 🟢 LOW (0-19) | 🟡 MEDIUM (20-44) | 🟠 HIGH (45-69) | 🔴 CRITICAL (70-100)
+**Levels:** LOW (0-19) | MEDIUM (20-44) | HIGH (45-69) | CRITICAL (70-100)
 
 ## Architecture
 
 ```
-Claude Code ←→ MCP stdio ←→ deficlaw server
-                                 │
-                    ┌────────────┼────────────┐
-                    │            │            │
+Claude Code <-> MCP stdio <-> deficlaw server
+                                 |
+                    +------------+------------+
+                    |            |            |
               DexScreener    GMGN API    Solana RPC
               (prices)     (holders)    (security)
 ```
 
 - **MCP SDK** for Claude Code integration
 - **curl-based GMGN fetcher** bypasses Cloudflare (Playwright fallback if needed)
-- **In-memory TTL cache** prevents rate limiting
-- **Rate limiter** for DexScreener (150 req/min)
+- **In-memory TTL cache** with automatic cleanup prevents rate limiting
+- **Rate limiter** with retry logic for DexScreener (150 req/min)
 - **TypeScript** with full type safety
 
 ## Configuration
@@ -178,6 +228,9 @@ Claude Code ←→ MCP stdio ←→ deficlaw server
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Custom Solana RPC endpoint |
+| `DEFICLAW_CACHE_TTL` | `120000` (2 min) | GMGN holder cache TTL in milliseconds |
+| `DEFICLAW_PRICE_CACHE_TTL` | `30000` (30s) | Price cache TTL in milliseconds |
+| `DEBUG` | (unset) | Set to `deficlaw` to enable debug logging to stderr |
 
 ### Claude Code Config
 
@@ -187,29 +240,50 @@ Add to your project's `.mcp.json`:
 {
   "mcpServers": {
     "defi": {
-      "command": "node",
-      "args": ["/path/to/deficlaw/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@0xprotovox/deficlaw"],
       "env": {
-        "SOLANA_RPC_URL": "https://your-rpc.com"
+        "SOLANA_RPC_URL": "https://your-rpc.com",
+        "DEFICLAW_CACHE_TTL": "120000",
+        "DEFICLAW_PRICE_CACHE_TTL": "30000",
+        "DEBUG": "deficlaw"
       }
     }
   }
 }
 ```
 
+Or if installed from source:
+
+```json
+{
+  "mcpServers": {
+    "defi": {
+      "command": "node",
+      "args": ["/path/to/deficlaw/dist/index.js"]
+    }
+  }
+}
+```
+
 ## Roadmap
 
 - [x] Token analysis with holder intelligence
-- [x] Risk scoring (6 dimensions)
+- [x] Risk scoring (8 dimensions)
 - [x] Contract security checks
 - [x] KOL detection with Twitter handles
 - [x] Human-readable AI summary
 - [x] Top traders (winners/losers)
-- [ ] Token search by name/symbol
+- [x] npm package (`npm install -g @0xprotovox/deficlaw`)
+- [x] Token search by name/symbol
+- [x] New launches detection
+- [x] Actionable verdict (BUY/SELL/NEUTRAL/AVOID)
+- [x] Configurable cache TTL via env vars
+- [x] Debug logging (DEBUG=deficlaw)
+- [x] Non-blocking async GMGN fetches
 - [ ] Slippage estimation (Jupiter quotes)
 - [ ] Token comparison (side by side)
 - [ ] Multi-chain holder analysis
-- [ ] npm package (`npm install -g deficlaw`)
 - [ ] Price alerts via MCP resources
 
 ## Built With

package/dist/analysis/formatOutput.d.ts

@@ -1,4 +1,115 @@
 /**
- * Format analysis output — clean, readable, both summary + detailed numbers
+ * Format analysis output as clean, readable plain text.
+ * Both human-readable summary and detailed numbers.
  */
-export declare function formatAnalysis(data: any): string;
+interface AnalysisData {
+    summary?: string;
+    token: {
+        name: string;
+        symbol: string;
+        chain: string;
+        address: string;
+        age?: string;
+        createdAt?: string;
+    };
+    price: {
+        usd: number;
+        change5m?: number;
+        change1h: number;
+        change6h?: number;
+        change24h: number;
+    };
+    market: {
+        marketCap: number;
+        fdv: number;
+        liquidity: number;
+        volume24h: number;
+        volume6h?: number;
+        volume1h: number;
+        volume5m?: number;
+        volumeLiquidityRatio?: number;
+        dex: string;
+        pairAddress: string;
+    };
+    security?: {
+        mintAuthority: string;
+        freezeAuthority: string;
+        supply: number;
+        decimals: number;
+    };
+    risk: {
+        score: number;
+        level: string;
+        flags?: {
+            severity: string;
+            message: string;
+        }[];
+    };
+    holders?: {
+        total: number;
+        concentration: {
+            top5Pct: number;
+            top10Pct: number;
+            top20Pct: number;
+        };
+        categories: Record<string, number>;
+        sentiment: {
+            profitableHolders: number;
+            losingHolders: number;
+            profitRatio: number;
+            totalPnlUsd: number;
+            totalCostUsd: number;
+            avgPnlPerHolder: number;
+        };
+        pressure: {
+            totalBuyTx: number;
+            totalSellTx: number;
+            buySellRatio: number;
+        };
+        devWallet?: {
+            address: string;
+            holdingPercent: number;
+            pnl: number;
+            status: string;
+        } | null;
+        topHolders: {
+            address: string;
+            tags: string[];
+            supplyPercent: number;
+            valueUsd: number;
+            pnl: number;
+            profitMultiple?: number;
+            buyTx?: number;
+            sellTx?: number;
+            isDeployer?: boolean;
+            isFreshWallet?: boolean;
+            twitterHandle?: string | null;
+        }[];
+    };
+    lpDetection?: {
+        lpAddress: string;
+        lpPercent: number;
+        realTopHolder?: {
+            address: string;
+            percent: number;
+        } | null;
+    };
+    kols?: {
+        address?: string;
+        twitterHandle?: string | null;
+        pnl: number;
+        status: string;
+        tags: string[];
+    }[];
+    socials?: {
+        websites?: string[];
+        twitter?: string | null;
+        telegram?: string | null;
+    };
+    meta: {
+        sources: string[];
+        fetchTimeMs: number;
+    };
+}
+export declare function formatAnalysis(data: AnalysisData): string;
+export {};