{"openapi":"3.1.0","info":{"title":"CabalLens — Solana Cabal & Fake-PnL Wallet Forensics","version":"1.0.0","description":"Industrial-grade Solana on-chain behavioral intelligence. Collapses top-20 non-LP token holders by tracing 2-hop genesis SOL funding ancestry, exposes hidden insider sybil clusters, and audits copy-trade fake-PnL mirages. Free triage via peek, $0.005 deep audits via x402 micropayments.","x-guidance":"Machine-payable 2-hop stealth cabal & copy-wallet fake-PnL forensics for Solana AI agents. Query GET /api/x402/peek?target={mintOrWallet} for free risk triage. Pay $0.005 via x402 USDC for full forensic graph on GET /api/x402/cabal?mint={mint} and GET /api/x402/wallet?address={address}.","contact":{"name":"CabalLens Security","email":"security@caballens.com","url":"https://caballens.vercel.app"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://caballens.vercel.app","description":"Live CabalLens Production Node"}],"tags":[{"name":"Forensics","description":"Solana 2-hop token cabal clustering and copy-wallet fake-PnL audits."},{"name":"B2A Payments","description":"x402 v2 micropayments (USDC on Base & Solana) and prepaid credit keys."},{"name":"Discovery & Telemetry","description":"Model Context Protocol (MCP 2026-07-28), live trending tokens, and health metrics."}],"paths":{"/health":{"get":{"tags":["Discovery & Telemetry"],"summary":"System Health & Uptime","description":"Returns health status of the RPC pool and payment subsystems.","operationId":"getHealth","security":[],"responses":{"200":{"description":"System healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"uptime":{"type":"number"},"timestamp":{"type":"string"}}}}}}}}},"/api/x402/peek":{"get":{"tags":["Forensics"],"summary":"Free Risk Peek ($0.00)","description":"Instant (<100ms cached) behavioral risk triage for any Solana token mint or trader wallet. Returns verdict (CLEAN, ELEVATED_CABAL, CRITICAL_TRAP, COPY_SAFE, etc.), top cluster %, and recommended next tool.","operationId":"peekCabalRiskGet","security":[],"parameters":[{"name":"target","in":"query","required":true,"schema":{"type":"string"},"description":"Base58 Solana token mint address or wallet public key.","example":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["token","wallet"],"default":"token"},"description":"Whether the target is an SPL token mint or a trader wallet."}],"responses":{"200":{"description":"Fast triage assessment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeekResponse"}}}},"400":{"description":"Bad Request: Missing required target parameter."},"429":{"description":"Too Many Requests: Free tier rate limit exceeded."}}},"post":{"tags":["Forensics"],"summary":"Free Risk Peek via POST ($0.00)","description":"JSON POST variant of free behavioral risk triage.","operationId":"peekCabalRiskPost","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target"],"properties":{"target":{"type":"string"},"kind":{"type":"string","enum":["token","wallet"],"default":"token"}}}}}},"responses":{"200":{"description":"Fast triage assessment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeekResponse"}}}},"429":{"description":"Rate limit exceeded."}}}},"/api/x402/cabal":{"get":{"tags":["Forensics"],"summary":"Deep Token Cabal & 2-Hop Ancestry Audit ($0.005)","description":"Exposes linked insider wallet clusters by tracing 2-hop genesis SOL funding ancestry of top-20 non-LP token holders. Requires $0.0050 USDC settlement via x402 v2.","operationId":"auditTokenCabal","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"security":[{"x402":[]}],"parameters":[{"name":"mint","in":"query","required":true,"schema":{"type":"string"},"description":"Base58 SPL token mint address to audit.","example":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"},{"name":"forceFresh","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Bypass 45-second cache and re-query live Solana Mainnet RPC."}],"responses":{"200":{"description":"Full forensic token cabal audit result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CabalAuditResult"}}}}}},"402":{"description":"Payment Required: Spec-exact x402 v2 challenge","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 JSON challenge object"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402ChallengeResponse"}}}}}},"post":{"tags":["Forensics"],"summary":"Deep Token Cabal & 2-Hop Ancestry Audit via POST ($0.005)","description":"JSON POST variant of 2-hop genesis token cabal audit. Requires $0.0050 USDC settlement via x402 v2.","operationId":"auditTokenCabalPost","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"security":[{"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mint"],"properties":{"mint":{"type":"string","description":"Base58 SPL token mint address"},"forceFresh":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Full forensic token cabal audit result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CabalAuditResult"}}}}}},"402":{"description":"Payment Required: Spec-exact x402 v2 challenge","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 JSON challenge object"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402ChallengeResponse"}}}}}}},"/api/x402/wallet":{"get":{"tags":["Forensics"],"summary":"Deep Copy-Wallet Fake-PnL & Wash-Loop Audit ($0.005)","description":"Audits advertised Smart Money wallets to expose zero-cost token seeding, wash loops, and illiquid mirage portfolios. Requires $0.0050 USDC via x402 v2.","operationId":"auditCopyWallet","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"security":[{"x402":[]}],"parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"},"description":"Base58 Solana trader wallet address to evaluate."},{"name":"forceFresh","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Bypass 120-second cache and re-query live Solana Mainnet RPC."}],"responses":{"200":{"description":"Full forensic wallet copyability report","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/WalletAuditResult"}}}}}},"402":{"description":"Payment Required: Spec-exact x402 v2 challenge","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 JSON challenge object"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402ChallengeResponse"}}}}}},"post":{"tags":["Forensics"],"summary":"Deep Copy-Wallet Fake-PnL & Wash-Loop Audit via POST ($0.005)","description":"JSON POST variant of copy-trading wallet forensics and fake-PnL audit. Requires $0.0050 USDC via x402 v2.","operationId":"auditCopyWalletPost","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"security":[{"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string","description":"Base58 Solana trader wallet address"},"forceFresh":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Full forensic wallet copyability report","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/WalletAuditResult"}}}}}},"402":{"description":"Payment Required: Spec-exact x402 v2 challenge","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 JSON challenge object"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402ChallengeResponse"}}}}}}},"/api/mcp":{"get":{"tags":["Discovery & Telemetry"],"summary":"MCP Server Transport Discovery","description":"Returns server capabilities and discovery manifest under Model Context Protocol.","operationId":"mcpDiscovery","security":[],"responses":{"200":{"description":"MCP server manifest","content":{"application/json":{"schema":{"type":"object","properties":{"protocolVersion":{"type":"string","example":"2026-07-28"},"server":{"type":"object"},"tools":{"type":"array","items":{"type":"object"}}}}}}}}},"post":{"tags":["Discovery & Telemetry"],"summary":"Stateless Streamable MCP Handler (2026-07-28 & 2025 fallback)","description":"Stateless Streamable HTTP JSON-RPC 2.0 endpoint implementing Model Context Protocol (MCP 2026-07-28).","operationId":"mcpRpcHandler","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","example":"2.0"},"method":{"type":"string","example":"tools/call"},"id":{"type":["string","number"],"example":1},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 tool result or discovery probe","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":["string","number"]},"result":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/keys/trial":{"get":{"tags":["B2A Payments"],"summary":"Trial Credit Key Information","description":"Returns trial key balance allocation policy and minting guidelines.","operationId":"getTrialKeyInfo","security":[],"responses":{"200":{"description":"Trial key guidelines","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"type":"string"},"trialCreditsUsd":{"type":"number","example":0.015},"unlocksIncluded":{"type":"number","example":3}}}}}}}},"post":{"tags":["B2A Payments"],"summary":"Mint Free Trial Credit Key","description":"Issues a rate-limited cl_trial_... API key pre-loaded with 3 forensic unlocks ($0.015) in durable storage.","operationId":"mintTrialKey","security":[],"responses":{"200":{"description":"Minted trial key credentials","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"key":{"type":"string","example":"cl_trial_587fee9a74..."},"balanceMicroUsd":{"type":"number","example":15000},"remainingUnlocks":{"type":"number","example":3}}}}}},"429":{"description":"Rate limit: 1 key per hour per client IP."}}}},"/api/keys/balance":{"get":{"tags":["B2A Payments"],"summary":"Check Credit Key Balance","description":"Returns remaining unlock credits and usage metrics for a prepaid or trial cl_... API key.","operationId":"checkKeyBalance","security":[],"responses":{"200":{"description":"API key balance details","content":{"application/json":{"schema":{"type":"object","properties":{"keyPrefix":{"type":"string","example":"cl_live_9a7..."},"balanceMicroUsd":{"type":"number","example":50000},"balanceUsd":{"type":"string","example":"$0.0500"},"remainingUnlocks":{"type":"number","example":10},"totalUnlocks":{"type":"number","example":3},"isTrial":{"type":"boolean","example":false},"lastUsedAt":{"type":"string"}}}}}},"401":{"description":"Unauthorized: Missing or invalid Authorization Bearer key."}}}},"/api/keys/purchase":{"get":{"tags":["B2A Payments"],"summary":"Purchase Plans & Solana Pay Specs","description":"Returns on-chain purchase tiers and Solana Pay checkout URIs.","operationId":"getPurchasePlans","security":[],"responses":{"200":{"description":"Active purchase plans and recipient address","content":{"application/json":{"schema":{"type":"object","properties":{"recipientWallet":{"type":"string"},"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"priceUsd":{"type":"number"},"unlocks":{"type":"number"},"solAmount":{"type":"string"},"usdcAmount":{"type":"string"},"solanaPaySolUri":{"type":"string"},"solanaPayUsdcUri":{"type":"string"}}}}}}}}}}},"post":{"tags":["B2A Payments"],"summary":"Verify On-Chain Purchase & Issue Pro Key","description":"Verifies a Solana Mainnet transfer and issues a permanent cl_live_... API key.","operationId":"verifyAndIssueKey","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["signature","tier"],"properties":{"signature":{"type":"string","description":"Base58 Solana Mainnet transfer transaction signature"},"tier":{"type":"string","enum":["starter","pro","whale"]},"currency":{"type":"string","enum":["SOL","USDC"],"default":"SOL"}}}}}},"responses":{"200":{"description":"Permanent API key minted with credit allocation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"key":{"type":"string","example":"cl_live_38bf8c..."},"balanceMicroUsd":{"type":"number","example":6000000},"remainingUnlocks":{"type":"number","example":1200}}}}}},"402":{"description":"Verification failed or insufficient payment"}}}},"/api/trending":{"get":{"tags":["Discovery & Telemetry"],"summary":"Live Solana Trending Tokens","description":"Fetches live trending and boosted Solana tokens from DexScreener for 1-click forensic audits.","operationId":"getTrendingTokens","security":[],"responses":{"200":{"description":"Live trending tokens array","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"type":"object","properties":{"mint":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"priceUsd":{"type":"number"},"liquidityUsd":{"type":"number"},"fdvUsd":{"type":"number"},"volume24hUsd":{"type":"number"},"url":{"type":"string"}}}}}}}}}}}},"/api/telemetry":{"get":{"tags":["Discovery & Telemetry"],"summary":"RPC Pool Health & Platform Telemetry","description":"Returns real-time RPC node latencies, error circuit breakers, and anonymized audit counts.","operationId":"getTelemetry","security":[],"responses":{"200":{"description":"System telemetry and RPC metrics","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"healthy"},"poolSize":{"type":"number"},"activeRpc":{"type":"string"},"totalQueries":{"type":"number"},"uptimeSeconds":{"type":"number"}}}}}}}}}},"components":{"securitySchemes":{"x402":{"type":"apiKey","name":"PAYMENT-SIGNATURE","in":"header","description":"x402 v2 payment signature containing atomic authorization for settlement."}},"schemas":{"PeekResponse":{"type":"object","properties":{"target":{"type":"string"},"kind":{"type":"string","enum":["token","wallet"]},"verdict":{"type":"string"},"headlineWarning":{"type":"string"},"confidence":{"type":"number"},"recommendedNextTool":{"type":"string"},"deepAuditCostUsd":{"type":"string","example":"0.005"},"deepAuditUrl":{"type":"string"},"disclaimer":{"type":"string"}}},"CabalAuditResult":{"type":"object","properties":{"mint":{"type":"string"},"tokenName":{"type":"string"},"tokenSymbol":{"type":"string"},"marketData":{"type":"object"},"mintSafety":{"type":"object"},"concentration":{"type":"object","properties":{"reportedTop10Pct":{"type":"number"},"trueLinkedCabalPct":{"type":"number"},"largestSingleCabalPct":{"type":"number"},"uniqueNonLpHoldersCount":{"type":"number"},"totalClustersDetected":{"type":"number"}}},"clusters":{"type":"array","items":{"type":"object"}},"topHolders":{"type":"array","items":{"type":"object"}},"verdict":{"type":"string","enum":["CLEAN","ELEVATED_CABAL","CRITICAL_TRAP"]},"cabalRiskScore":{"type":"number"},"maxRecommendedPositionSol":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"}},"confidence":{"type":"number"},"evidence":{"type":"array","items":{"type":"object"}},"heuristicVersion":{"type":"string"},"slot":{"type":"number"},"disclaimer":{"type":"string"},"recommendedNextTool":{"type":"string"},"auditedAt":{"type":"string"},"cached":{"type":"boolean"}}},"WalletAuditResult":{"type":"object","properties":{"walletAddress":{"type":"string"},"solBalance":{"type":"number"},"copyabilityScore":{"type":"number"},"verdict":{"type":"string","enum":["COPY_SAFE","UNCOPYABLE_HFT_SNIPER","BAIT_OR_SPOOF_TRAP"]},"riskLevel":{"type":"string","enum":["LOW","MEDIUM","CRITICAL"]},"metrics":{"type":"object","properties":{"totalParsedTransactions":{"type":"number"},"totalTrades":{"type":"number"},"inboundSeededTransfers":{"type":"number"},"spoofedPnlRatioPct":{"type":"number"},"circularWashLoopCount":{"type":"number"},"medianHoldTimeSeconds":{"type":"number"},"sniperEntryRatioPct":{"type":"number"},"realizableLiquidityHaircutPct":{"type":"number"}}},"portfolio":{"type":"object"},"recentTrades":{"type":"array","items":{"type":"object"}},"warnings":{"type":"array","items":{"type":"string"}},"confidence":{"type":"number"},"evidence":{"type":"array","items":{"type":"object"}},"heuristicVersion":{"type":"string"},"slot":{"type":"number"},"disclaimer":{"type":"string"},"recommendedNextTool":{"type":"string"},"auditedAt":{"type":"string"},"cached":{"type":"boolean"}}},"X402ChallengeResponse":{"type":"object","properties":{"x402Version":{"type":"integer","example":2},"error":{"type":"string","example":"Payment required"},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"serviceName":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"iconUrl":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"amount":{"type":"string","example":"5000"},"asset":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer","example":60},"extra":{"type":"object"}}}}}}}}}