CabalLens — Solana Forensics MCP

2-hop genesis funder cabal detection, copy-wallet fake-PnL auditing, and free meme-coin triage on Solana with x402 settlement.

GitHub

Hosted MCP Server

npx add-mcp 'https://caballens.vercel.app/api/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

CabalLens (`apps/caballens`)

Solana Multi-Hop Stealth Cabal & Copy-Wallet Forensics Protocol with Guarded Swap Routing

1. Executive Summary & Value Proposition

CabalLens is a zero-capital-risk, Day-0 revenue-generating Solana behavioral forensics and guarded swap protocol designed for autonomous crypto trading agents (MCP + x402 micropayments) and human traders (50 bps Jupiter Safe-Swap Terminal).

Why Traditional Scanners Fail (The 94% Loss Rate)

Static contract scanners (RugCheck 100/100, Phantom warning banners) evaluate static bytecode flags: MintAuthority == null, FreezeAuthority == null, and burned LP. Scammers adapt by creating contract-perfect tokens while executing on-chain behavioral fraud:

2-Hop Stealth Cabals: The deployer funds 15–30 fresh wallets through 2-hop intermediate dispensers. These wallets purchase 50%+ of the token supply across Slot 0 and Slot 1, while naive holder tables display: "Top holder owns 2.8% (Safe!)." Minutes later, the cabal executes synchronized sells, draining the liquidity pool.
Copy-Trade Fake-PnL & Follower-Dump Bait Wallets: "Smart money" wallets display 90%+ win rates on leaderboards by receiving zero-cost token transfers from sibling deployers. When copy-trading bots and retail follow their buys, sibling wallets dump their supply directly into the copy-bots' slippage tolerance.

CabalLens deterministically exposes both traps using 100% free Solana Mainnet RPC data (<1.8s cold, <40ms cached) with zero paid wrapper APIs.

2. Interactive Documentation & Autonomous Machine Discovery

CabalLens implements the full suite of modern machine discoverability specifications:

Endpoint	Standard / Format	Description
`/docs`	Interactive Scalar Playground	Tier-1 interactive API documentation, schema explorer, and live request builder
`/api/openapi.json`	OpenAPI 3.1.0	Full JSON Schema models for all requests, responses, 402 challenges, and errors
`/api/mcp`	MCP Streamable Server	Stateless Streamable HTTP MCP (protocol version `2024-11-05`) with `GET` and `POST`
`/.well-known/mcp.json`	MCP Manifest	Declares transport URL, auth methods, and complete tool JSON schemas
`/.well-known/mcp/server.json`	MCP Server Specification	Official 2025/2026 Model Context Protocol location
`/.well-known/x402`	x402 Foundation v2	Multi-chain payment rails (Base `eip155:8453` and Solana `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)
`/.well-known/agent.json`	Agent-to-Agent (A2A)	Machine manifest declaring crypto capabilities, pricing, and execution rails
`/llms.txt`	llmstxt.org Specification	Curated markdown index for LLM agents (Claude Code, Cursor, Aider, Perplexity)
`/llms-full.txt`	Unabridged Agent Manual	Complete single-fetch technical guide with TypeScript, Python, and cURL snippets
`smithery.yaml`	Smithery MCP Registry	Ready for 1-click Smithery agent indexing
`glama.json`	Glama MCP Directory	Valid schema configuration for Glama MCP explorer
`server.json`	MCP Index Specification	Official Model Context Protocol repository manifest

3. x402 Foundation v2 Protocol Specification

CabalLens strictly adheres to the x402 Foundation v2 internet-native payment specification:

Wire Protocol Flow

Unpaid Request: Client queries GET /api/x402/cabal?mint=...

402 Payment Required Challenge:

Header PAYMENT-REQUIRED: Base64-encoded JSON representing payment requirements:

{
  "x402Version": "2.0.0",
  "network": "eip155:8453",
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "symbol": "USDC",
  "amount": "5000",
  "payTo": "0xe72850212b1B01e3d5474732b99019D0943AbCc9",
  "facilitator": "https://facilitator.payai.network",
  "resourceType": "token_cabal_audit",
  "targetId": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "altNetworks": [
    {
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "amount": "5000",
      "payTo": "7QAmK5Rkn1Sma2rDYMFKA7x591c75fFuGDw8Qwge5vaG"
    }
  ]
}

Header WWW-Authenticate: x402 network="eip155:8453", payTo="0xe72850212b1B01e3d5474732b99019D0943AbCc9", amount="5000"

Client Settlement: Client attaches PAYMENT-SIGNATURE: <base64_sig> (v2) or Authorization: Bearer cl_...
Fulfillment (200 OK):
- Server returns forensic payload with PAYMENT-RESPONSE header containing the Base64 settlement receipt.

4. MCP Tools Reference

1. `peek_cabal_risk` (Free — `$0.00`)

Instant triage checking whether a Solana token has insider cabal control or a wallet is an uncopyable bait-trap.

{
  "target": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "kind": "token"
}

2. `audit_token_cabal` (`$0.005` USDC or Prepaid Key)

Deep 2-hop genesis SOL ancestry and sybil cluster audit. Traverses parent funding trees and groups wallets using Disjoint-Set Union-Find.

{
  "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "forceFresh": false
}

3. `audit_copy_wallet` (`$0.005` USDC or Prepaid Key)

Deep copy-trading audit. Exposes zero-cost token transfer spoofing, wash trading loops, hold durations, and copyability score.

{
  "walletAddress": "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8",
  "forceFresh": false
}

4. `compile_guarded_swap` (`50 bps` on-chain)

Compiles an unsigned Jupiter V6 VersionedTransaction swap embedding our 50 bps platform referral fee. Automatically blocks transaction compilation if the target token is flagged as CRITICAL_TRAP.

{
  "userPublicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "outputMint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "amountLamports": 500000000,
  "slippageBps": 100
}

5. Quickstart & Integration Examples

Claude Desktop & Cursor Integration

Add CabalLens to your claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "caballens": {
      "url": "http://localhost:3001/api/mcp",
      "headers": {
        "Authorization": "Bearer cl_trial_your_key_here"
      }
    }
  }
}

ElizaOS Plugin Integration

Add CabalLens to any ElizaOS agent runtime:

import { cabalLensPlugin } from "@/lib/agents/elizaos-plugin";

export const defaultCharacter = {
  name: "SolanaSafeTrader",
  plugins: [cabalLensPlugin],
};

Direct cURL Flow (Zero Human Touch)

# 1. Claim instant trial key (3 free unlocks)
KEY=$(curl -s -X POST "http://localhost:3001/api/keys/trial" | jq -r .key)

# 2. Run deep token cabal audit
curl -s -H "Authorization: Bearer $KEY" \
  "http://localhost:3001/api/x402/cabal?mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" | jq .

# 3. Check remaining key balance
curl -s -H "Authorization: Bearer $KEY" \
  "http://localhost:3001/api/keys/balance" | jq .

6. Architecture & Free RPC Mesh

flowchart TD
    Agent[Autonomous Agent / Trader] --> Gate[CabalLens Gateway :3001]
    Gate --> ScalarDocs[Interactive Scalar Docs /docs]
    Gate --> MCP[Streamable MCP /api/mcp]
    Gate --> X402[x402 v2 Gate /api/x402]
    Gate --> SafeSwap[Jupiter 50 bps Swap Compiler]

    subgraph Core Engine
        RpcPool[SolanaRpcPool Multi-Node Failover]
        Tlv[Token-2022 TLV Decoder]
        UnionFind[Disjoint-Set Funder Clusterer]
        Ledger[In-Memory / Upstash Credit Ledger]
    end

    MCP --> UnionFind
    X402 --> UnionFind
    SafeSwap --> UnionFind

    UnionFind --> RpcPool
    Tlv --> RpcPool

    RpcPool --> RPC1[Solana-Official Mainnet RPC]
    RpcPool --> RPC2[PublicNode Solana RPC]
    RpcPool --> RPC3[Ankr Solana RPC]

7. Day-0 Go-Live & Distribution Execution Plan

Model Context Protocol Registry Indexing:
- Execute npx -y @smithery/cli publish to list CabalLens on Smithery.
- Submit glama.json to Glama MCP index (https://glama.ai/mcp/servers).
- Open PR on modelcontextprotocol/servers official repository.
ElizaOS & Solana Agent Ecosystem Outreach:
- Release @caballens/elizaos-plugin targeting autonomous trading agent creators on Virtuals Protocol and ai16z.
- Submit PR to sendaifun/solana-agent-kit adding CabalLens to the native security toolset.
Interactive Developer Experience:
- Developers and bot builders test endpoints live at /docs without cloning or installing dependencies.

8. Verification & Test Suite

Run the full verification suite:

# Strict Typecheck
npm run typecheck

# Vitest Unit + Live Solana Mainnet Tests (13 tests)
npm test

# Production Build
npm run build