Cabal-Hunter Scan Cabal API

openapi: 3.2.0
info:
  title: Cabal-Hunter Scan Cabal API
  version: 1.1.0
  description: On-chain Solana token safety scanner for AI trading agents and bots. Given a Solana mint address it traces coordinated wallet funding, same-block bundle buys, serial-launcher deployers and same-block coordinated dumps, and returns one Exit-Liquidity Risk verdict (recommendation + 0-100 cabal_score) BEFORE you buy. Call it before any Solana swap. risk_level HIGH (or cabal_score >= 65) means strong coordinated-control signals were observed. Tokens you already hold can be watched with POST /api/watch, which pushes a webhook if the price falls 12%+ or liquidity falls 18%+ between checks 15 seconds apart. This is on-chain evidence, not financial advice, and not a safety rating. 5 free scans, no signup — then 250/month free with an email; then $0.01 USDC per scan via x402.
  contact:
    name: Cabal-Hunter
    url: https://api.cabal-hunter.com/
    email: paulf280@gmail.com
servers:
- url: https://api.cabal-hunter.com
tags:
- name: Scan Cabal
paths:
  /api/scan-cabal:
    get:
      operationId: scanCabalGet
      summary: Scan a Solana mint for cabal / rug / bundle risk (GET)
      description: Returns the full Exit-Liquidity Risk analysis for a Solana token. Use before buying/swapping. 5 free scans, no signup — then 250/month free with an email.
      parameters:
      - name: mintAddress
        in: query
        required: true
        schema:
          type: string
        description: Base58 Solana token mint address
      responses:
        '200':
          description: Cabal analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CabalReport'
      tags:
      - Scan Cabal
    post:
      operationId: scanCabal
      summary: Scan a Solana mint for cabal / rug / bundle risk
      description: Primary endpoint. Pass a mint address; get risk_level (HIGH | ELEVATED | LOW_SIGNAL), a 0-100 cabal_score, the deployer track record and on-chain evidence. LOW_SIGNAL means our checks did not fire — it is NOT a safety rating, and most tokens lose value regardless. Signals only, not financial advice.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mintAddress
              properties:
                mintAddress:
                  type: string
                  description: Base58 Solana token mint address
      responses:
        '200':
          description: Cabal analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CabalReport'
      tags:
      - Scan Cabal
components:
  schemas:
    CabalReport:
      type: object
      properties:
        mint:
          type: string
        risk_level:
          type: string
          enum:
          - HIGH
          - ELEVATED
          - LOW_SIGNAL
          description: 'What we observed. HIGH = strong coordinated-control signals. LOW_SIGNAL = our checks did not fire, which is NOT a safety rating: most tokens lose value anyway.'
        disclaimer:
          type: string
          description: Always returned. On-chain signals, not financial advice.
        recommendation:
          type: string
          enum:
          - SAFE
          - REVIEW
          - AVOID
          description: DEPRECATED — prefer risk_level. Values are frozen because existing agents gate on the literal string AVOID; renaming them would fail open.
        cabal_score:
          type: integer
          description: 0-100. >=65 HIGH risk, >=35 caution.
        risk:
          type: string
          enum:
          - HIGH
          - MEDIUM
          - CLEAN
        is_controlled:
          type: boolean
          description: true when score >= 35 (insiders positioned to dump).
        confidence:
          type: string
          enum:
          - HIGH
          - LOW
          description: Confidence in THIS scan's completeness (HIGH when wallets_checked >= 5). Check the validator's own output, not just the verdict.
        scan_complete:
          type: boolean
          description: True only when the trace had enough coverage. A SAFE result with scan_complete=false is auto-downgraded to REVIEW — never trust a clean verdict from an incomplete scan.
        wallets_checked:
          type: integer
          description: Holder wallets actually traced — the scan-depth signal. Low = shallow/sparse trace, treat a clean result as suspect.
        analysis_time_ms:
          type: integer
          description: Processing latency; with 'source', lets the caller gauge data completeness.
        liquidity_usd:
          type: number
          description: Live liquidity (USD) on the deepest pair.
        market_cap:
          type: number
          description: Live market cap (USD).
        honeypot_risk:
          type: string
          enum:
          - LOW
          - HIGH
          description: 'Solana-native honeypot verdict: live freeze authority or Token-2022 fee/hook/delegate traps'
        mint_authority_revoked:
          type: boolean
        freeze_authority_revoked:
          type: boolean
        token2022_risks:
          type: array
          items:
            type: string
        exit_liquidity_risk:
          type: boolean
          description: True when liquidity is too thin vs market cap to exit without heavy slippage — the soft-rug / dev-dump risk, independent of cabal coordination.
        verdict:
          type: string
          description: Plain-English summary.
        time_sync:
          type: boolean
          description: Same-block bundled buy group detected.
        coordinated_exit:
          type: boolean
          description: Same-block coordinated dump detected.
        top_holder_pct:
          type: number
        deployer:
          type: object
          description: '{ creator, tokens_launched, dead, sampled, dead_pct, verdict, reputation, best_peak_usd, median_peak_usd, pump_and_dumps, dead_on_arrival, still_alive }. Launch history covers pump.fun, Raydium, Orca, Meteora and PumpSwap; a launch counts only where the transaction created the mint, so re-minting an existing token is never counted. verdict FIRST_LAUNCH = checked, no earlier launches found; verdict UNKNOWN = the history could not be established and is NOT a clean record. Paid: launches[] — full per-launch trajectory (mint, symbol, peak_mcap_usd, now_mcap_usd, drawdown_from_peak, status).'
        coordinated_clusters:
          type: array
          items:
            type: object
          description: Scored coordination groups with evidence_txs[].
        filtered_clusters:
          type: array
          items:
            type: object
          description: CEX/infra groups excluded from the score.
        top_reasons:
          type: array
          items:
            type: string
        free_queries_remaining:
          type: integer
        source:
          type: string
          enum:
          - pre_indexed
          - real_time
        computed_at:
          type: number
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Cabal-Hunter key. Required for watch endpoints so a watch belongs to exactly one caller.
    x402Payment:
      type: apiKey
      in: header
      name: X-Payment-Signature
      description: Solana USDC payment tx signature (x402). Omit for the 5 anonymous scans/month, or use a free key (one email) for 250/month per IP.