Cabal-Hunter Screen List API

openapi: 3.2.0
info:
  title: Cabal-Hunter Screen List 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: Screen List
paths:
  /api/screen-list:
    get:
      operationId: listScreenList
      summary: List the wallets on your private screen list
      description: 'A paid add-on. Your list is private to your key: wallets and labels are yours alone, and nothing is published. Requires X-API-Key with the Screen List enabled; without it the response is 402 with error screen_list_not_enabled.'
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Your wallets, newest first, with count and max
        '401':
          description: Missing API key
        '402':
          description: The Screen List add-on is not enabled on this key
      tags:
      - Screen List
    post:
      operationId: addScreenListWallet
      summary: Add a wallet to your screen list (or relabel one already on it)
      description: 'From then on every scan you run also reports whether this wallet holds the token or funded a detected cluster — as observations, never as claims about who the wallet belongs to. Addresses are validated strictly (base58, 32-44 chars): a lookalike string that could never match is refused with the reason, not stored silently. A list holds up to 500 wallets.'
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - wallet
              properties:
                wallet:
                  type: string
                  description: Base58 Solana wallet address
                label:
                  type: string
                  description: Your own note, up to 60 chars — shown only back to you
      responses:
        '200':
          description: Added (or relabelled), with the new count
        '400':
          description: Not a valid Solana address
        '401':
          description: Missing API key
        '402':
          description: The Screen List add-on is not enabled on this key
        '409':
          description: The list is full — remove a wallet before adding another
      tags:
      - Screen List
    delete:
      operationId: clearScreenList
      summary: Clear your screen list (DELETE /api/screen-list/{wallet} removes one)
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Removed
        '401':
          description: Missing API key
        '402':
          description: Not enabled on this key
      tags:
      - Screen List
  /api/screen-list/checkout:
    post:
      operationId: enableScreenList
      summary: Enable the Screen List add-on on your key ($9/month, card)
      description: Returns a Stripe Checkout url; completing it switches the add-on on for exactly the key that made this call — nothing new is minted and there is nothing to copy. Cancel anytime from the billing portal; access follows the subscription.
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: A checkout url to complete in the browser
        '401':
          description: Missing API key
        '404':
          description: Unknown key
        '409':
          description: Already enabled on this key
      tags:
      - Screen List
components:
  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.