Cabal-Hunter Watch API

openapi: 3.2.0
info:
  title: Cabal-Hunter Watch 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: Watch
paths:
  /api/watch:
    get:
      operationId: listWatches
      summary: List the dump watches registered by your key
      description: Returns only YOUR watches. Requires X-API-Key. The response carries used and limit so a client can see its remaining headroom without guessing.
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Your watches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchList'
        '401':
          description: Missing or unknown API key
      tags:
      - Watch
    post:
      operationId: watchDump
      summary: Watch a token you hold and get a webhook the moment it starts dumping
      description: 'A scan answers whether a token is safe to BUY. This answers whether it is still safe to HOLD. We poll the token continuously and POST your webhook_url the instant a coordinated dump or a liquidity drain begins — with the on-chain transactions that prove it, not just a verdict. Requires a key so that only you can see or remove your own watches. Any key gets the alert by email (omit webhook_url and it goes to the address on your key); webhook_url delivery is part of the Pro plan. On the $9 plan (newest watch) and Pro (every watch) the same destination also receives insider_* events for 7 days (insider_dev_sold, insider_dev_sent, insider_exit, insiders_selling, insiders_buying, insiders_digest), each with the wallet, its role, the share of supply and the transaction. webhook_url must resolve to a PUBLIC address: loopback, private, link-local and cloud-metadata targets are refused. Re-posting the same mint and url is idempotent and does not consume a slot.'
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mint
              properties:
                mint:
                  type: string
                  description: Base58 Solana token mint address
                webhook_url:
                  type: string
                  description: 'Pro plan: public http(s) URL we POST the alert to. Omit it for an email alert to the address on your key.'
      responses:
        '200':
          description: Watch registered
        '400':
          description: Invalid mint, or a webhook_url that is not a public http(s) address
        '401':
          description: Missing or unknown API key
        '402':
          description: 'pro_required: webhook, Discord or Slack delivery needs the Pro plan'
        '429':
          description: Your plan's active-watch limit is reached. The body carries plan, limit and used.
      tags:
      - Watch
    delete:
      operationId: unwatchDump
      summary: Remove one of your own watches
      description: Deletes a watch belonging to your key. Omit webhook_url to remove every watch you hold on that mint. Never affects another key's watches.
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mint
              properties:
                mint:
                  type: string
                webhook_url:
                  type: string
                  description: Optional — narrows the delete to one destination
      responses:
        '200':
          description: Removed
        '401':
          description: Missing or unknown API key
        '404':
          description: You have no watch registered on that mint
      tags:
      - Watch
components:
  schemas:
    WatchList:
      type: object
      properties:
        watches:
          type: array
          items:
            type: object
            properties:
              mint:
                type: string
              webhook_url:
                type: string
              created_ts:
                type: integer
        used:
          type: integer
          description: Active watches on this key
        limit:
          type: integer
          description: How many this plan allows
        plan:
          type: string
  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.