# CabalLens (v1.0.0) — Complete Autonomous Agent Integration Manual

## 1. Protocol Architecture & Behavioral Fraud Mechanics

### 1.1 The Problem
Static contract scanners only check byte-level mint authorities and freeze authorities. Cabal operators deploy tokens with revoked authorities but control >50% of the supply through 2-hop genesis funding trees.
Similarly, advertised "smart money" copy-trading wallets manufacture 90%+ win rates by receiving zero-cost token transfers from sibling deployers.

### 1.2 Deterministic Forensic Engine
- **2-Hop Genesis SOL Ancestry:** Traces the top 20 non-LP token holders back 2 funding hops using Solana Mainnet RPCs and groups them using Disjoint-Set Union-Find.
- **Token-2022 TLV Dissection:** Inspects extensions including PermanentDelegate, TransferHook, and TransferFee to block weaponized mints.
- **Copy-Wallet Forensics:** Audits historical swaps to identify zero-cost token seeding, wash loops, and follower-dump timing traps.

---

## 2. API & MCP Tool Specifications

### Tool 1: peek_cabal_risk (Cost: $0.00 Free)
Endpoint: POST https://caballens.vercel.app//api/x402/peek or MCP method 'tools/call' with name 'peek_cabal_risk'
Request:
```json
{
  "target": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "kind": "token"
}
```
Response:
```json
{
  "target": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "kind": "token",
  "tokenSymbol": "Bonk",
  "verdict": "CLEAN",
  "cabalRiskScore": 12,
  "headlineWarning": "Standard distribution detected.",
  "reportedTop10Pct": 14.2,
  "trueLinkedCabalPct": 16.5,
  "maxSafeTradeSol": 5.0,
  "unlockPriceUsd": "0.005"
}
```

### Tool 2: audit_token_cabal (Cost: $0.005 via x402 / cl_ key)
Endpoint: GET https://caballens.vercel.app//api/x402/cabal?mint={mint} or MCP method 'tools/call'
Authentication: Header 'Authorization: Bearer cl_...' or 'X-Payment: <x402-sig>'
Returns full cluster graph, sybil wallet addresses, and max safe trade size in SOL.

### Tool 3: audit_copy_wallet (Cost: $0.005 via x402 / cl_ key)
Endpoint: GET https://caballens.vercel.app//api/x402/wallet?address={address} or MCP method 'tools/call'
Authentication: Header 'Authorization: Bearer cl_...' or 'X-Payment: <x402-sig>'
Returns copyabilityScore (0-100), spoofedPnlRatioPct, medianHoldSeconds, and verdict.

### Tool 4: compile_guarded_swap (Cost: $0.00 API, 50 bps on-chain fee)
Endpoint: POST https://caballens.vercel.app//api/swap/compile or MCP method 'tools/call'
Request:
```json
{
  "userPublicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "outputMint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "amountLamports": 500000000,
  "slippageBps": 100
}
```
Returns unsigned Jupiter VersionedTransaction base64 string embedding our 50 bps platform fee.

---

## 3. Autonomous Onboarding for Agents

### Step 1: Claim Free Trial Key (Zero Human Intervention)
```bash
curl -X POST "https://caballens.vercel.app//api/keys/trial"
```
Response:
```json
{
  "success": true,
  "key": "cl_trial_9a8f2e7c...",
  "balanceMicroUsd": 15000,
  "remainingUnlocks": 3
}
```

### Step 2: Query Paid Audit with Bearer Key
```bash
curl -H "Authorization: Bearer cl_trial_9a8f2e7c..." \
  "https://caballens.vercel.app//api/x402/cabal?mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
```

### Step 3: MCP Configuration for Claude Desktop / Cursor
Add to your config:
```json
{
  "mcpServers": {
    "caballens": {
      "url": "https://caballens.vercel.app//api/mcp",
      "headers": {
        "Authorization": "Bearer cl_trial_..."
      }
    }
  }
}
```

---

## 4. ElizaOS & Autonomous Framework Integration
Import the CabalLens plugin into your ElizaOS runtime:
```typescript
import { cabalLensPlugin } from "@/lib/agents/elizaos-plugin";

export const agent = {
  plugins: [cabalLensPlugin],
};
```