{"openapi":"3.1.0","info":{"title":"CabalLens Solana Behavioral Forensics & Guarded Swap Protocol","version":"1.0.0","description":"Industrial-grade Solana on-chain behavioral intelligence. Collapses top-25 token holders by tracing 2-hop genesis SOL funding ancestry, detects sybil clusters, audits copy-trade fake-PnL mirages, and compiles guarded Jupiter swaps embedding a 50 bps platform fee directly on-chain.","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":"Anurag Srivastava","email":"igeekanurag@gmail.com","url":"https://caballens.vercel.app/"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"x-agentcash-guidance":{"llmsTxtUrl":"https://caballens.vercel.app//llms.txt"},"servers":[{"url":"https://caballens.vercel.app/","description":"Live CabalLens Production & Local Node"}],"tags":[{"name":"Forensics","description":"Solana 2-hop token cabal clustering and copy-wallet fake-PnL audits."},{"name":"Execution","description":"Pre-checked Jupiter VersionedTransaction swap compilation with 50 bps platform fee."},{"name":"B2A Payments","description":"x402 Foundation v2 micropayments (USDC) and prepaid credit keys."},{"name":"Discovery & Telemetry","description":"Model Context Protocol (MCP), live trending pools, and RPC health metrics."}],"paths":{"/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), headline score (0-100), and max safe trade size in SOL.","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"},"example":{"target":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263","kind":"token","tokenName":"Bonk","tokenSymbol":"Bonk","verdict":"CLEAN","cabalRiskScore":0,"headlineWarning":"Token exhibits standard holder distribution.","reportedTop10Pct":38.93,"trueLinkedCabalPct":0,"poolLiquidityUsd":297368,"maxSafeTradeSol":46.95,"unlockPriceUsd":"0.005","unlockUrl":"https://caballens.vercel.app//api/x402/cabal?mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}}}},"400":{"description":"Bad Request: Missing or invalid target address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"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), headline score (0-100), and max safe trade size in SOL.","operationId":"peekCabalRiskPost","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target"],"properties":{"target":{"type":"string","description":"Base58 Solana token mint address or wallet public key.","example":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"},"kind":{"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"},"example":{"target":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263","kind":"token","tokenName":"Bonk","tokenSymbol":"Bonk","verdict":"CLEAN","cabalRiskScore":0,"headlineWarning":"Token exhibits standard holder distribution.","reportedTop10Pct":38.93,"trueLinkedCabalPct":0,"poolLiquidityUsd":297368,"maxSafeTradeSol":46.95,"unlockPriceUsd":"0.005","unlockUrl":"https://caballens.vercel.app//api/x402/cabal?mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}}}},"400":{"description":"Bad Request: Missing or invalid target address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/x402/cabal":{"get":{"tags":["Forensics","B2A Payments"],"summary":"Deep Token Cabal Audit ($0.005 via x402 / cl_ key)","description":"Exhaustive 2-hop genesis SOL ancestry traversal. Dissects Token-2022 TLV binary metadata (PermanentDelegate, TransferHook, TransferFee), groups top-20 non-LP holders via Disjoint-Set clustering, and exposes true insider cabal ownership vs reported top-10 concentration.","operationId":"auditTokenCabal","security":[{"BearerAuth":[]},{}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"mint","in":"query","required":true,"schema":{"type":"string"},"description":"Solana 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 RPCs."}],"responses":{"200":{"description":"Full forensic cabal audit graph","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64-encoded settlement receipt for x402 v2."},"X-PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Settlement receipt ID."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CabalAuditResult"},"settlement":{"$ref":"#/components/schemas/SettlementInfo"}}}}}},"400":{"description":"Bad Request: Missing or invalid token mint address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required: Return standard x402 v2 challenge.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 payment requirements."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Standard HTTP 402 challenge header."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402ChallengeResponse"}}}}}}},"/api/x402/wallet":{"get":{"tags":["Forensics","B2A Payments"],"summary":"Copy-Wallet PnL Forensics ($0.005 via x402 / cl_ key)","description":"Audits advertised 'Smart Money' wallets for artificial PnL manufacturing: inbound zero-cost token seeding, wash-trading loops, uncopyable Slot-0 sniper latency, and Follower-Dump bait traps.","operationId":"auditCopyWallet","security":[{"BearerAuth":[]},{}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"},"description":"Solana wallet public key to audit.","example":"675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"},{"name":"forceFresh","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Bypass 120-second cache."}],"responses":{"200":{"description":"Copyability audit report","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/WalletAuditResult"},"settlement":{"$ref":"#/components/schemas/SettlementInfo"}}}}}},"400":{"description":"Bad Request: Missing or invalid wallet address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required: Return standard x402 v2 challenge.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402ChallengeResponse"}}}}}}},"/api/swap/compile":{"get":{"tags":["Execution"],"summary":"Guarded Swap Information & Parameters","description":"Returns schema and instructions for compiling guarded swaps with safety pre-checks.","operationId":"getSwapInfo","security":[],"responses":{"200":{"description":"Parameters and usage instructions","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"method":{"type":"string"},"requiredParameters":{"type":"array","items":{"type":"string"}},"optionalParameters":{"type":"array","items":{"type":"string"}}}}}}}}},"post":{"tags":["Execution"],"summary":"Compile Guarded Jupiter Swap (50 bps platform fee)","description":"Runs CabalLens safety pre-checks on the target token and compiles an unsigned Jupiter V6 VersionedTransaction embedding our 50 bps platform referral fee. Automatically blocks execution if target is flagged as CRITICAL_TRAP.","operationId":"compileGuardedSwap","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userPublicKey","outputMint","amountLamports"],"properties":{"userPublicKey":{"type":"string","description":"Base58 public key of the signer executing the swap.","example":"So11111111111111111111111111111111111111112"},"outputMint":{"type":"string","description":"Base58 SPL token mint to acquire.","example":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"},"amountLamports":{"type":"number","description":"Input amount in lamports (1 SOL = 1,000,000,000).","example":500000000},"inputMint":{"type":"string","default":"So11111111111111111111111111111111111111112","description":"Input token mint (default: native SOL)."},"slippageBps":{"type":"number","default":100,"description":"Maximum allowable slippage in basis points."},"forceOverride":{"type":"boolean","default":false,"description":"Override safety gate to compile even if cabal risk is high."}}}}}},"responses":{"200":{"description":"Compiled unsigned swap transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapCompileResult"}}}},"400":{"description":"Bad Request: Missing required parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/mcp":{"get":{"tags":["Discovery & Telemetry"],"summary":"MCP Server Transport Discovery","description":"Returns server info, capabilities, and tool declarations.","operationId":"mcpDiscovery","security":[],"responses":{"200":{"description":"MCP server manifest"}}},"post":{"tags":["Discovery & Telemetry"],"summary":"Stateless Streamable MCP Handler","description":"JSON-RPC 2.0 endpoint implementing Model Context Protocol (MCP) version 2024-11-05 for autonomous AI agents.","operationId":"mcpRpcHandler","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":"string","example":"1"},"method":{"type":"string","enum":["initialize","tools/list","tools/call","prompts/list","resources/list"]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response"}}}},"/api/keys/trial":{"get":{"tags":["B2A Payments"],"summary":"Trial Credit Key Information","description":"Returns trial key balance allocation policy and automated minting instructions.","operationId":"getTrialKeyInfo","security":[],"responses":{"200":{"description":"Trial key minting instructions and usage guidelines"}}},"post":{"tags":["B2A Payments"],"summary":"Mint Free Trial Credit Key","description":"Issues a rate-limited cl_trial_... API key pre-loaded with 3 free forensic unlocks ($0.015) for autonomous agent onboarding.","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},"instructions":{"type":"string"}}}}}},"429":{"description":"Rate limit: 1 key per minute per client IP."}}}},"/api/keys/purchase":{"get":{"tags":["B2A Payments"],"summary":"Purchase Plans & Solana Pay Specs","description":"Returns on-chain purchase tiers ($1, $5, $20) and Solana Pay URI checkout specs.","operationId":"getPurchasePlans","security":[],"responses":{"200":{"description":"Active purchase plans and recipient address"}}},"post":{"tags":["B2A Payments"],"summary":"Verify On-Chain Purchase & Issue Pro Key","description":"Verifies a Solana Mainnet transfer transaction to 7QAmK5Rkn1Sma2rDYMFKA7x591c75fFuGDw8Qwge5vaG and issues a permanent cl_live_... API key pre-loaded with forensic unlocks.","operationId":"verifyAndIssueKey","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["signature"],"properties":{"signature":{"type":"string","description":"Solana transaction signature"},"tier":{"type":"string","enum":["starter","pro","whale"],"default":"starter"},"currency":{"type":"string","enum":["SOL","USDC"],"default":"SOL"}}}}}},"responses":{"200":{"description":"Permanent API key minted with credit allocation"},"402":{"description":"Transaction verification failed or insufficient payment"}}}},"/api/trending":{"get":{"tags":["Discovery & Telemetry"],"summary":"Live Trending Solana Pools","description":"Returns live boosted and high-volume Solana pools from DexScreener for 1-click audit.","operationId":"getTrendingPools","security":[],"responses":{"200":{"description":"List of active trending pairs"}}},"post":{"tags":["Discovery & Telemetry"],"summary":"Live Trending Solana Pools (POST probe)","description":"Returns live boosted and high-volume Solana pools from DexScreener for 1-click audit.","operationId":"postTrendingPools","security":[],"responses":{"200":{"description":"List of active trending pairs"}}}},"/api/telemetry":{"get":{"tags":["Discovery & Telemetry"],"summary":"Protocol Financial & RPC Telemetry","description":"Returns live RPC node latency metrics and real-time ledger settlement volume.","operationId":"getTelemetry","security":[],"responses":{"200":{"description":"Telemetry snapshot"}}},"post":{"tags":["Discovery & Telemetry"],"summary":"Protocol Financial & RPC Telemetry (POST probe)","description":"Returns live RPC node latency metrics and real-time ledger settlement volume.","operationId":"postTelemetry","security":[],"responses":{"200":{"description":"Telemetry snapshot"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"cl_trial_...","description":"Prepaid or trial API credit key pre-loaded via /api/keys/trial."},"X402PaymentV2":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 Foundation v2 standard cryptographic payment signature header."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"SettlementInfo":{"type":"object","properties":{"rail":{"type":"string","example":"x402_base_usdc"},"payer":{"type":"string","example":"0x7099... or cl_trial_..."},"costUsd":{"type":"string","example":"$0.0050"},"receiptId":{"type":"string","example":"rec_x402_173084..."}}},"PeekResponse":{"type":"object","properties":{"target":{"type":"string"},"kind":{"type":"string"},"tokenName":{"type":"string"},"tokenSymbol":{"type":"string"},"verdict":{"type":"string","enum":["CLEAN","ELEVATED_CABAL","CRITICAL_TRAP"]},"cabalRiskScore":{"type":"number","minimum":0,"maximum":100},"headlineWarning":{"type":"string"},"reportedTop10Pct":{"type":"number"},"trueLinkedCabalPct":{"type":"number"},"poolLiquidityUsd":{"type":"number"},"maxSafeTradeSol":{"type":"number"},"unlockPriceUsd":{"type":"string"},"unlockUrl":{"type":"string"}}},"CabalAuditResult":{"type":"object","properties":{"mint":{"type":"string"},"tokenName":{"type":"string"},"tokenSymbol":{"type":"string"},"verdict":{"type":"string","enum":["CLEAN","ELEVATED_CABAL","CRITICAL_TRAP"]},"cabalRiskScore":{"type":"number"},"maxRecommendedPositionSol":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"}},"concentration":{"type":"object","properties":{"reportedTop10Pct":{"type":"number"},"trueLinkedCabalPct":{"type":"number"},"largestSingleCabalPct":{"type":"number"},"totalClustersDetected":{"type":"number"}}},"mintSafety":{"type":"object","properties":{"isToken2022":{"type":"boolean"},"mintAuthorityRevoked":{"type":"boolean"},"freezeAuthorityRevoked":{"type":"boolean"},"hasPermanentDelegate":{"type":"boolean"},"hasTransferHook":{"type":"boolean"},"hasTransferFee":{"type":"boolean"}}},"clusters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"wallets":{"type":"array","items":{"type":"string"}},"combinedSupplyPct":{"type":"number"},"primaryFunder":{"type":"string","nullable":true},"reason":{"type":"string"}}}}}},"WalletAuditResult":{"type":"object","properties":{"walletAddress":{"type":"string"},"verdict":{"type":"string","enum":["COPY_SAFE","UNCOPYABLE_HFT_SNIPER","BAIT_OR_SPOOF_TRAP"]},"copyabilityScore":{"type":"number"},"riskLevel":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object","properties":{"totalSwaps":{"type":"number"},"spoofedPnlRatioPct":{"type":"number"},"medianHoldSeconds":{"type":"number"},"medianEntrySlotLag":{"type":"number"}}}}},"SwapCompileResult":{"type":"object","properties":{"safeToExecute":{"type":"boolean"},"cabalRiskScore":{"type":"number"},"verdict":{"type":"string"},"quote":{"type":"object","nullable":true,"properties":{"inAmount":{"type":"string"},"outAmount":{"type":"string"},"priceImpactPct":{"type":"string"}}},"swapTransactionBase64":{"type":"string","nullable":true},"feeConfig":{"type":"object","properties":{"platformFeeBps":{"type":"number"},"feeAccount":{"type":"string","nullable":true},"estimatedIntegratorRevenueSol":{"type":"number"}}},"warnings":{"type":"array","items":{"type":"string"}}}},"X402ChallengeResponse":{"type":"object","properties":{"x402Version":{"type":"number","example":2},"error":{"type":"string"},"amountUsd":{"type":"string"},"grossMicroUsd":{"type":"number"},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"number"}}}},"settlementRails":{"type":"array","items":{"type":"object"}}}}}}}