Kerberus APIkerberus.com ↗

"""
Kerberus Domain Safety Scanner API Client

Scan Web3 domains for scam, phishing, and fraud detection.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional


class ParseClient:
    """Client for interacting with the Kerberus Domain Safety Scanner API."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.

        Args:
            api_key: Optional API key. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "e190f387-aef2-46e6-9d62-1464e9b69c9c"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")

    def _call(self, endpoint: str, method: str = "POST", **params) -> dict:
        """
        Make a request to the Parse API.

        Args:
            endpoint: The endpoint name (e.g., 'scan_domain')
            method: HTTP method ('GET' or 'POST')
            **params: Query parameters or JSON payload

        Returns:
            Response JSON as dictionary

        Raises:
            requests.RequestException: If the API request fails
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def scan_domain(self, domain: str) -> dict:
        """
        Scan a Web3 domain for safety classification.

        Checks if a domain is flagged as a scam, phishing site, or whitelisted as safe.

        Args:
            domain: The domain to scan (e.g., 'uniswap.org', 'opensea.io')

        Returns:
            Dictionary containing:
                - domain: The scanned domain
                - is_blocked: Whether the domain is actively blocked
                - is_blacklisted: Whether the domain is on the blacklist
                - is_whitelisted: Whether the domain is on the whitelist
                - status: Overall safety classification ('green' or 'red')
                - request_id: Unique identifier for this scan
                - processed_time: Time taken to process the scan

        Raises:
            requests.RequestException: If the API request fails
        """
        return self._call("scan_domain", method="POST", domain=domain)


def print_scan_result(result: dict) -> None:
    """Pretty print a domain scan result."""
    status_emoji = "✅" if result["status"] == "green" else "🚨"
    print(f"\n{status_emoji} Domain: {result['domain']}")
    print(f"   Status: {result['status'].upper()}")
    print(f"   Blocked: {result['is_blocked']}")
    print(f"   Blacklisted: {result['is_blacklisted']}")
    print(f"   Whitelisted: {result['is_whitelisted']}")
    print(f"   Request ID: {result['request_id']}")
    print(f"   Processed in: {result['processed_time']}")


if __name__ == "__main__":
    # Initialize the client
    client = ParseClient()

    # Practical workflow: scan multiple Web3 domains and categorize results
    domains_to_scan = [
        "uniswap.org",
        "opensea.io",
        "etherscan.io",
        "suspicious-defi-site.xyz",
        "pancakeswap.finance"
    ]

    safe_domains = []
    blocked_domains = []

    print("🔍 Scanning Web3 domains for safety...\n")
    print("=" * 60)

    # Scan each domain and collect results
    for domain in domains_to_scan:
        try:
            result = client.scan_domain(domain)
            print_scan_result(result)

            # Categorize results for summary
            if result["status"] == "green":
                safe_domains.append({
                    "domain": result["domain"],
                    "whitelisted": result["is_whitelisted"]
                })
            else:
                blocked_domains.append({
                    "domain": result["domain"],
                    "blacklisted": result["is_blacklisted"]
                })

        except requests.RequestException as e:
            print(f"\n❌ Error scanning {domain}: {e}")
        except Exception as e:
            print(f"\n⚠️  Unexpected error scanning {domain}: {e}")

    # Print summary report
    print("\n" + "=" * 60)
    print("\n📊 SCAN SUMMARY REPORT")
    print(f"Total domains scanned: {len(domains_to_scan)}")
    print(f"Safe domains: {len(safe_domains)}")
    print(f"Blocked domains: {len(blocked_domains)}")

    if safe_domains:
        print("\n✅ Safe domains:")
        for item in safe_domains:
            whitelist_status = "(whitelisted)" if item["whitelisted"] else "(verified safe)"
            print(f"   • {item['domain']} {whitelist_status}")

    if blocked_domains:
        print("\n🚨 Blocked domains:")
        for item in blocked_domains:
            blacklist_status = "(blacklisted)" if item["blacklisted"] else "(blocked)"
            print(f"   • {item['domain']} {blacklist_status}")

    print("\n" + "=" * 60)