agentpayments-python 0.1.0__py3-none-any.whl

agentpayments_python/__init__.py

@@ -0,0 +1,30 @@
+# Adapters are optional: each import succeeds only if its framework is
+# installed. ImportError (missing framework) is expected; any other exception
+# is a real bug and should propagate.
+
+# x402 helpers are always available (no framework dependency).
+from .x402 import build_payment_requirements, enrich_402_body, payment_required_header
+
+__all__ = [
+    "build_payment_requirements",
+    "enrich_402_body",
+    "payment_required_header",
+]
+
+try:
+    from .django_adapter import GateMiddleware, challenge_verify
+    __all__ += ["GateMiddleware", "challenge_verify"]
+except ImportError:
+    pass
+
+try:
+    from .fastapi_adapter import AgentPaymentsASGIMiddleware, challenge_verify_endpoint as fastapi_challenge_verify
+    __all__ += ["AgentPaymentsASGIMiddleware", "fastapi_challenge_verify"]
+except ImportError:
+    pass
+
+try:
+    from .flask_adapter import register_agentpayments
+    __all__ += ["register_agentpayments"]
+except ImportError:
+    pass

agentpayments_python/challenge.py

@@ -0,0 +1,151 @@
+import hmac
+import json
+import re
+import secrets as _secrets
+import threading
+import time
+from pathlib import Path
+
+from .crypto import client_id_for_ip, hmac_sign, sha256_hex
+
+_constants = json.loads((Path(__file__).resolve().parent / "constants.json").read_text())
+POW_DIFFICULTY = _constants["POW_DIFFICULTY"]
+MAX_POW_LENGTH = _constants["MAX_POW_LENGTH"]
+NONCE_TTL_MS = _constants["NONCE_TTL_MS"]
+
+# Canvas fingerprints are a base64 slice of a data URL. Reject anything that
+# isn't base64 or is degenerate (e.g. a single repeated character).
+_FP_RE = re.compile(r"^[A-Za-z0-9+/]{10,}$")
+_POW_RE = re.compile(r"^\d{1,20}$")
+
+
+def make_nonce(secret: str, client_ip: str) -> str:
+    """Nonce format: <ts>.<rand>.<sig>, signature bound to the client IP."""
+    ts = str(int(time.time() * 1000))
+    rand = _secrets.token_hex(8)
+    client_id = client_id_for_ip(client_ip, secret)
+    sig = hmac_sign(f"nonce:{ts}:{rand}:{client_id}", secret)
+    return f"{ts}.{rand}.{sig}"
+
+
+def _is_plausible_fingerprint(fp: str) -> bool:
+    return bool(_FP_RE.match(fp)) and len(set(fp)) >= 4
+
+
+def _verify_pow(nonce: str, pow_value: str, difficulty: int) -> bool:
+    """Proof-of-work: sha256(f"{nonce}:{pow}") must start with `difficulty`
+    zero hex chars. Verification is one hash; solving costs ~16^difficulty."""
+    if not _POW_RE.match(pow_value):
+        return False
+    return sha256_hex(f"{nonce}:{pow_value}").startswith("0" * difficulty)
+
+
+class _ConsumedNonces:
+    """Single-use nonce tracking (best-effort, in-memory, thread-safe)."""
+
+    def __init__(self, ttl_ms: int = NONCE_TTL_MS, max_size: int = 10000):
+        self.ttl = ttl_ms / 1000.0
+        self.max_size = max_size
+        self._seen: dict[str, float] = {}
+        self._lock = threading.Lock()
+
+    def consume(self, sig: str) -> bool:
+        """Returns True if the nonce was fresh (and marks it consumed)."""
+        now = time.time()
+        with self._lock:
+            exp = self._seen.get(sig)
+            if exp is not None and exp > now:
+                return False
+            if len(self._seen) >= self.max_size:
+                expired = [k for k, v in self._seen.items() if v <= now]
+                for k in expired:
+                    del self._seen[k]
+                if len(self._seen) >= self.max_size:
+                    del self._seen[next(iter(self._seen))]
+            self._seen[sig] = now + self.ttl
+            return True
+
+
+_consumed_nonces = _ConsumedNonces()
+
+
+def validate_challenge_submission(
+    nonce: str,
+    fp: str,
+    pow_value: str,
+    secret: str,
+    client_ip: str,
+    difficulty: int = POW_DIFFICULTY,
+) -> bool:
+    """Full server-side validation of a challenge form submission.
+
+    Checks: nonce structure and expiry, IP-bound HMAC signature, plausible
+    fingerprint, proof-of-work, and single use.
+    """
+    parts = nonce.split(".")
+    if len(parts) != 3 or not _is_plausible_fingerprint(fp):
+        return False
+    nonce_ts, nonce_rand, nonce_sig = parts
+    try:
+        ts = int(nonce_ts)
+    except ValueError:
+        return False
+    if int(time.time() * 1000) - ts > NONCE_TTL_MS:
+        return False
+    client_id = client_id_for_ip(client_ip, secret)
+    expected = hmac_sign(f"nonce:{nonce_ts}:{nonce_rand}:{client_id}", secret)
+    if not hmac.compare_digest(nonce_sig, expected):
+        return False
+    if not _verify_pow(nonce, pow_value, difficulty):
+        return False
+    return _consumed_nonces.consume(nonce_sig)
+
+
+def challenge_html(return_to: str, nonce: str, pow_difficulty: int = POW_DIFFICULTY) -> str:
+    # Reject protocol-relative URLs (e.g. //attacker.com) which start with '/'
+    # but are treated as external by browsers.
+    safe_path = return_to if (return_to.startswith("/") and not return_to.startswith("//")) else "/"
+    nonce_json = json.dumps(nonce)
+    safe_path_json = json.dumps(safe_path)
+    target_json = json.dumps("0" * pow_difficulty)
+    return (
+        "<!DOCTYPE html><html lang='en'><head><meta charset='UTF-8'>"
+        "<meta name='viewport' content='width=device-width, initial-scale=1.0'>"
+        "<title>Verifying your access...</title>"
+        "<style>body{font-family:system-ui,sans-serif;display:flex;justify-content:center;"
+        "align-items:center;min-height:100vh;margin:0;background:#fafafa;color:#333}"
+        "main{text-align:center;padding:2rem}"
+        ".spinner{width:40px;height:40px;border:4px solid #e0e0e0;border-top-color:#333;"
+        "border-radius:50%;animation:spin .8s linear infinite;margin:1rem auto}"
+        "@keyframes spin{to{transform:rotate(360deg)}}</style>"
+        "</head><body>"
+        "<main role='status' aria-live='polite'>"
+        "<div class='spinner' aria-hidden='true'></div>"
+        "<p>Verifying your access&hellip;</p>"
+        "<noscript><p><strong>JavaScript is required to verify your access. "
+        "Please enable JavaScript and reload this page.</strong></p></noscript>"
+        "</main>"
+        "<script>(function(){"
+        "if(navigator.webdriver)return;"
+        "if(!window.crypto||!window.crypto.subtle)return;"
+        "var c=document.createElement('canvas');c.width=200;c.height=50;"
+        "var ctx=c.getContext('2d');if(!ctx)return;"
+        "ctx.font='18px Arial';ctx.fillStyle='#1a1a2e';ctx.fillText('verify',10,30);"
+        "var data=c.toDataURL();if(!data||data.length<100)return;"
+        "if(typeof window.innerWidth==='undefined'||window.innerWidth===0)return;"
+        f"var nonce={nonce_json};var target={target_json};"
+        "var enc=new TextEncoder();var i=0;"
+        "function submit(pow){"
+        "var form=document.createElement('form');form.method='POST';form.action='/__challenge/verify';"
+        f"var fields={{nonce:nonce,return_to:{safe_path_json},fp:data.slice(22,86),pow:pow}};"
+        "for(var k in fields){var input=document.createElement('input');"
+        "input.type='hidden';input.name=k;input.value=fields[k];form.appendChild(input);}"
+        "document.body.appendChild(form);form.submit();}"
+        "function mine(){window.crypto.subtle.digest('SHA-256',enc.encode(nonce+':'+i)).then(function(buf){"
+        "var b=new Uint8Array(buf);var h='';"
+        "for(var j=0;j<4;j++)h+=(b[j]<16?'0':'')+b[j].toString(16);"
+        "if(h.slice(0,target.length)===target)return submit(String(i));"
+        "i++;mine();});}"
+        "mine();})();</script>"
+        "</body></html>"
+    )

agentpayments_python/constants.json

@@ -0,0 +1,27 @@
+{
+  "USDC_MINT_DEVNET": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+  "USDC_MINT_MAINNET": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  "RPC_DEVNET": "https://api.devnet.solana.com",
+  "RPC_MAINNET": "https://api.mainnet-beta.solana.com",
+  "MEMO_PROGRAM": "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr",
+  "MIN_PAYMENT": 0.01,
+  "COOKIE_NAME": "__agp_verified",
+  "COOKIE_MAX_AGE": 86400,
+  "KEY_PREFIX": "ag_",
+  "POW_DIFFICULTY": 4,
+  "MAX_POW_LENGTH": 20,
+  "NONCE_TTL_MS": 300000,
+  "MAX_KEY_LENGTH": 64,
+  "MAX_NONCE_LENGTH": 128,
+  "MAX_RETURN_TO_LENGTH": 2048,
+  "MAX_FP_LENGTH": 128,
+  "NEGATIVE_CACHE_TTL_MS": 30000,
+  "MAX_TRANSACTIONS_PER_VERIFY": 20,
+  "AGENT_KEY_RATE_LIMIT_MAX": 10,
+  "USDC_DECIMALS": 6,
+  "X402_VERSION": 1,
+  "SOLANA_CHAIN_ID_MAINNET": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  "SOLANA_CHAIN_ID_DEVNET": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+  "PLATFORM_API_URL": "https://api.agentpayments.dev",
+  "HOSTED_KEY_PREFIX": "agp_"
+}

agentpayments_python/cookies.py

@@ -0,0 +1,37 @@
+import hmac
+import json
+import time
+from pathlib import Path
+
+from .crypto import client_id_for_ip, hmac_sign
+
+_constants = json.loads((Path(__file__).resolve().parent / "constants.json").read_text())
+COOKIE_NAME = _constants["COOKIE_NAME"]
+COOKIE_MAX_AGE = _constants["COOKIE_MAX_AGE"]
+
+
+def make_cookie(secret: str, client_ip: str) -> str:
+    """Cookie format: <ts>.<sig>, signature bound to the client IP that
+    solved the challenge, so a captured cookie is useless from another IP."""
+    now_ms = str(int(time.time() * 1000))
+    client_id = client_id_for_ip(client_ip, secret)
+    return f"{now_ms}.{hmac_sign(f'cookie:{now_ms}:{client_id}', secret)}"
+
+
+def is_valid_cookie_value(cookie_value: str, secret: str, client_ip: str) -> bool:
+    if not cookie_value:
+        return False
+    i = cookie_value.find(".")
+    if i == -1:
+        return False
+    ts_str = cookie_value[:i]
+    sig = cookie_value[i + 1:]
+    try:
+        ts = int(ts_str)
+    except ValueError:
+        return False
+    if int(time.time() * 1000) - ts > COOKIE_MAX_AGE * 1000:
+        return False
+    client_id = client_id_for_ip(client_ip, secret)
+    expected = hmac_sign(f"cookie:{ts_str}:{client_id}", secret)
+    return hmac.compare_digest(sig, expected)

agentpayments_python/crawler.py

@@ -0,0 +1,74 @@
+"""
+Verified search crawler detection.
+
+UA heuristic + reverse/forward DNS (Google's documented method).
+Results are cached for 1 hour to avoid repeated DNS lookups.
+"""
+import re
+import socket
+import time
+import threading
+from typing import Optional
+
+# (ua_pattern, expected_ptr_suffix)
+# suffix=None means UA match only — not recommended, included for completeness.
+CRAWLERS = [
+    (re.compile(r'googlebot', re.I),             '.googlebot.com'),
+    (re.compile(r'google-inspectiontool', re.I), '.google.com'),
+    (re.compile(r'bingbot', re.I),               '.search.msn.com'),
+    (re.compile(r'slurp', re.I),                 '.crawl.yahoo.net'),
+    (re.compile(r'duckduckbot', re.I),           '.duckduckgo.com'),
+    (re.compile(r'baiduspider', re.I),           '.crawl.baidu.com'),
+    (re.compile(r'yandexbot', re.I),             '.yandex.com'),
+    (re.compile(r'applebot', re.I),              '.applebot.apple.com'),
+]
+
+CRAWLER_CACHE_TTL = 3600  # 1 hour
+_cache: dict[str, tuple[bool, float]] = {}  # ip -> (verified, expiry)
+_cache_lock = threading.Lock()
+
+
+def is_verified_crawler(ip: str, user_agent: str) -> bool:
+    """
+    Return True if the request is from a verified search crawler.
+
+    Verification is: UA matches a known crawler pattern AND the IP's reverse-DNS
+    hostname ends with the crawler's published suffix AND a forward DNS lookup of
+    that hostname resolves back to the same IP.
+
+    Results are cached for 1 hour to limit DNS round-trips. Blocking I/O — for
+    FastAPI/async use, call this in a thread-pool executor.
+    """
+    if not user_agent or not ip or ip == 'unknown':
+        return False
+
+    match = next((c for c in CRAWLERS if c[0].search(user_agent)), None)
+    if match is None:
+        return False
+
+    suffix = match[1]
+
+    with _cache_lock:
+        entry = _cache.get(ip)
+        if entry is not None and entry[1] > time.time():
+            return entry[0]
+
+    verified = _verify_dns(ip, suffix)
+
+    with _cache_lock:
+        _cache[ip] = (verified, time.time() + CRAWLER_CACHE_TTL)
+
+    return verified
+
+
+def _verify_dns(ip: str, suffix: str) -> bool:
+    try:
+        hostname, _, _ = socket.gethostbyaddr(ip)
+        if not hostname.endswith(suffix):
+            return False
+        # Forward verify: resolve hostname back and confirm it includes the original IP.
+        results = socket.getaddrinfo(hostname, None)
+        resolved_ips = {r[4][0] for r in results}
+        return ip in resolved_ips
+    except Exception:
+        return False

agentpayments_python/crypto.py

@@ -0,0 +1,43 @@
+import hashlib
+import hmac
+import json
+import uuid
+from pathlib import Path
+
+_constants = json.loads((Path(__file__).resolve().parent / "constants.json").read_text())
+KEY_PREFIX = _constants["KEY_PREFIX"]
+MAX_KEY_LENGTH = _constants["MAX_KEY_LENGTH"]
+
+
+def hmac_sign(data: str, secret: str) -> str:
+    return hmac.new(secret.encode(), data.encode(), hashlib.sha256).hexdigest()
+
+
+def sha256_hex(data: str) -> str:
+    return hashlib.sha256(data.encode()).hexdigest()
+
+
+def client_id_for_ip(ip: str, secret: str) -> str:
+    """Short HMAC of the client IP. Used to bind nonces and cookies to the
+    client that solved the challenge, so a captured cookie is useless from
+    another IP."""
+    return hmac_sign(f"client:{ip}", secret)[:16]
+
+
+def generate_agent_key(secret: str) -> str:
+    random_part = uuid.uuid4().hex[:16]
+    sig = hmac_sign(random_part, secret)
+    return f"{KEY_PREFIX}{random_part}_{sig[:16]}"
+
+
+def is_valid_agent_key(key: str, secret: str) -> bool:
+    if not key or len(key) > MAX_KEY_LENGTH or not key.startswith(KEY_PREFIX):
+        return False
+    rest = key[len(KEY_PREFIX):]
+    i = rest.find("_")
+    if i == -1:
+        return False
+    random_part = rest[:i]
+    sig = rest[i + 1:]
+    expected = hmac_sign(random_part, secret)
+    return hmac.compare_digest(sig, expected[:16])

agentpayments_python/detection.py

@@ -0,0 +1,28 @@
+import re as _re
+
+def is_public_path(pathname: str) -> bool:
+    return pathname == "/robots.txt" or pathname.startswith("/.well-known/")
+
+
+# Sec-Fetch-* headers were introduced in Chrome 76 (2019) and Firefox 90 (2021).
+# Older browsers, some mobile WebViews, and certain proxies strip them.
+# This UA pattern matches common desktop/mobile browsers as a fallback so they
+# get a challenge rather than a 402.
+_BROWSER_UA_RE = _re.compile(
+    r"(Chrome|Chromium|Firefox|Safari|Edg|OPR|Opera|SamsungBrowser|UCBrowser|Mobile Safari)"
+    r"(?!/.*bot)",  # exclude UA strings that contain the browser name followed by /.*bot
+    _re.IGNORECASE,
+)
+# Explicit bot/crawler suffixes that should NOT match even if they spoof a browser UA.
+_BOT_UA_RE = _re.compile(r"bot|crawl|spider|slurp|mediapartners|adsbot", _re.IGNORECASE)
+
+
+def is_browser_from_headers(headers: dict) -> bool:
+    # Primary signal: Fetch metadata headers (Chrome 76+, Firefox 90+).
+    if headers.get("sec-fetch-mode") or headers.get("sec-fetch-dest"):
+        return True
+    # Fallback: UA heuristic for older browsers that don't send Sec-Fetch-*.
+    ua = headers.get("user-agent") or headers.get("User-Agent") or ""
+    if ua and not _BOT_UA_RE.search(ua) and _BROWSER_UA_RE.search(ua):
+        return True
+    return False

agentpayments_python/django_adapter.py

@@ -0,0 +1,232 @@
+import logging
+
+from django.conf import settings
+from django.http import HttpResponse, HttpResponseRedirect, JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+
+from .challenge import POW_DIFFICULTY, challenge_html, make_nonce, validate_challenge_submission
+from .cookies import COOKIE_MAX_AGE, COOKIE_NAME, is_valid_cookie_value, make_cookie
+from .crypto import generate_agent_key, is_valid_agent_key
+from .detection import is_browser_from_headers, is_public_path
+from .ratelimit import _challenge_limiter, _agent_key_limiter, _challenge_issue_limiter
+from .crawler import is_verified_crawler
+from .solana import MIN_PAYMENT, RPC_DEVNET, RPC_MAINNET, USDC_MINT_DEVNET, USDC_MINT_MAINNET, is_valid_solana_address, verify_payment_on_chain
+from .x402 import build_payment_requirements, enrich_402_body, payment_required_header
+from .platform_client import HOSTED_KEY_PREFIX, PlatformClient, is_valid_hosted_key
+
+import json as _json
+from pathlib import Path as _Path
+_constants = _json.loads((_Path(__file__).resolve().parent / "constants.json").read_text())
+MAX_NONCE_LENGTH = _constants["MAX_NONCE_LENGTH"]
+MAX_RETURN_TO_LENGTH = _constants["MAX_RETURN_TO_LENGTH"]
+MAX_FP_LENGTH = _constants["MAX_FP_LENGTH"]
+MAX_POW_LENGTH = _constants["MAX_POW_LENGTH"]
+
+logger = logging.getLogger("agentpayments")
+
+
+def _payment_required_response(body: dict, *, wallet_address: str, mint: str, min_payment: float, debug: bool, agent_key: str = "", resource: str = "") -> JsonResponse:
+    """Return a 402 JsonResponse enriched with x402-standard fields and header."""
+    pay_req = build_payment_requirements(wallet_address=wallet_address, mint=mint, min_payment=min_payment, debug=debug, agent_key=agent_key, resource=resource)
+    resp = JsonResponse(enrich_402_body(body, pay_req), status=402, json_dumps_params={"indent": 2})
+    resp["X-PAYMENT-REQUIRED"] = payment_required_header(pay_req)
+    return resp
+
+
+def _client_ip(request):
+    return request.META.get("HTTP_X_FORWARDED_FOR", "").split(",")[0].strip() or request.META.get("REMOTE_ADDR", "unknown")
+
+
+class GateMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+        # Resolve and validate config once at startup, not per-request.
+        secret = settings.CHALLENGE_SECRET
+        if secret == "default-secret-change-me":
+            if settings.DEBUG:
+                logger.warning("Using default CHALLENGE_SECRET. Set a strong secret before deploying to production.")
+            else:
+                raise RuntimeError("CHALLENGE_SECRET is set to the insecure default. Set a strong, unique secret for production.")
+        wallet_address = getattr(settings, "HOME_WALLET_ADDRESS", None)
+        if wallet_address and not is_valid_solana_address(wallet_address):
+            raise ValueError(f"HOME_WALLET_ADDRESS '{wallet_address}' is not a valid Solana public key (expected 32-44 base58 characters).")
+        debug = settings.DEBUG
+        raw_rpc = getattr(settings, "SOLANA_RPC_URL", None) or (RPC_DEVNET if debug else RPC_MAINNET)
+        rpc_url = raw_rpc if isinstance(raw_rpc, list) else [raw_rpc]
+        self.require_https = getattr(settings, "AGENTPAYMENTS_REQUIRE_HTTPS", not debug)
+        # Hosted key-issuance mode. Set AGENTPAYMENTS_API_KEY in settings.py.
+        # When set, keys are issued via the platform (metered) and carry the agp_ prefix.
+        api_key = getattr(settings, "AGENTPAYMENTS_API_KEY", None)
+        platform_url = getattr(settings, "AGENTPAYMENTS_PLATFORM_URL", None)
+        self._platform_client = PlatformClient(api_key, platform_url) if api_key else None
+        usdc_mint = getattr(settings, "USDC_MINT", None) or (USDC_MINT_DEVNET if debug else USDC_MINT_MAINNET)
+
+        self.secret = secret
+        self.wallet_address = wallet_address
+        self.debug = debug
+        self.rpc_url = rpc_url
+        self.usdc_mint = usdc_mint
+        self.network = "devnet" if debug else "mainnet-beta"
+        self.pow_difficulty = getattr(settings, "POW_DIFFICULTY", POW_DIFFICULTY)
+        self.verify_crawlers = getattr(settings, "AGENTPAYMENTS_VERIFY_CRAWLERS", True)
+        # Optional grant store for durable paid-key persistence. Set
+        # AGENTPAYMENTS_GRANT_STORE to a GrantStore instance in settings.py.
+        self.grant_store = getattr(settings, "AGENTPAYMENTS_GRANT_STORE", None)
+
+    def __call__(self, request):
+        secret = self.secret
+        wallet_address = self.wallet_address
+        network = self.network
+
+        pathname = request.path
+        if is_public_path(pathname):
+            return self.get_response(request)
+
+        if pathname == "/__challenge/verify" and request.method == "POST":
+            return self.get_response(request)
+
+        # Reject plaintext HTTP in production. Behind a reverse proxy, Django
+        # uses X-Forwarded-Proto via SECURE_PROXY_SSL_HEADER in settings.
+        if self.require_https and not request.is_secure():
+            return JsonResponse({"error": "https_required", "message": "This service requires a secure HTTPS connection."}, status=400)
+
+        # Verified search crawlers bypass the gate entirely.
+        if self.verify_crawlers:
+            client_ip_early = _client_ip(request)
+            ua = request.META.get("HTTP_USER_AGENT", "")
+            if is_verified_crawler(client_ip_early, ua):
+                return self.get_response(request)
+
+        headers = {
+            "sec-fetch-mode": request.META.get("HTTP_SEC_FETCH_MODE"),
+            "sec-fetch-dest": request.META.get("HTTP_SEC_FETCH_DEST"),
+        }
+        if not is_browser_from_headers(headers):
+            agent_key = request.META.get("HTTP_X_AGENT_KEY")
+            if not agent_key:
+                # Hosted mode: issue metered platform key (agp_).
+                # Local mode: generate self-signed key (ag_).
+                if self._platform_client:
+                    try:
+                        new_key = self._platform_client.issue_key()
+                    except Exception as exc:
+                        logger.warning("Platform key issuance failed, falling back to local key: %s", exc)
+                        new_key = generate_agent_key(secret)
+                else:
+                    new_key = generate_agent_key(secret)
+                return _payment_required_response(
+                    {
+                        "error": "payment_required",
+                        "message": "Access requires a paid API key. A key has been generated for you below. Send a USDC payment on Solana with this key as the memo to activate it, then retry your request with the X-Agent-Key header.",
+                        "your_key": new_key,
+                        "payment": {
+                            "chain": "solana",
+                            "network": network,
+                            "token": "USDC",
+                            "amount": str(MIN_PAYMENT),
+                            "wallet_address": wallet_address,
+                            "memo": new_key,
+                            "instructions": f'Send {MIN_PAYMENT} USDC on Solana {network} to {wallet_address} with memo "{new_key}". Then include the header X-Agent-Key: {new_key} on all subsequent requests.',
+                        },
+                    },
+                    wallet_address=wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
+                    debug=self.debug, agent_key=new_key, resource=pathname,
+                )
+
+            # Validate the key. Platform-issued (agp_) use verificationSecret;
+            # local keys (ag_) use challengeSecret.
+            if agent_key.startswith(HOSTED_KEY_PREFIX):
+                if not self._platform_client:
+                    return JsonResponse({"error": "forbidden", "message": "Platform-issued keys (agp_) require AGENTPAYMENTS_API_KEY to be configured."}, status=403)
+                try:
+                    ver_sec = self._platform_client.verification_secret
+                except Exception as exc:
+                    logger.error("Failed to fetch verificationSecret from platform: %s", exc)
+                    return JsonResponse({"error": "service_unavailable", "message": "Key verification temporarily unavailable."}, status=503)
+                if not is_valid_hosted_key(agent_key, ver_sec):
+                    return JsonResponse({"error": "forbidden", "message": "Invalid API key."}, status=403)
+            elif not is_valid_agent_key(agent_key, secret):
+                return JsonResponse({"error": "forbidden", "message": "Invalid API key. Keys must be issued by this server."}, status=403)
+
+            if not _agent_key_limiter.check(_client_ip(request)):
+                return JsonResponse({"error": "rate_limited", "message": "Too many payment verification requests. Please wait and try again."}, status=429)
+
+            if not wallet_address:
+                return JsonResponse({"error": "server_error", "message": "Payment verification unavailable."}, status=500)
+
+            # Durable grant check — bypasses RPC scan entirely for known-paid keys.
+            if self.grant_store and self.grant_store.has(agent_key):
+                return self.get_response(request)
+
+            paid = verify_payment_on_chain(agent_key, wallet_address, self.rpc_url, self.usdc_mint)
+            if paid and self.grant_store:
+                self.grant_store.add(agent_key)
+            if not paid:
+                return _payment_required_response(
+                    {
+                        "error": "payment_required",
+                        "message": "Key is valid but payment has not been verified on-chain yet.",
+                        "your_key": agent_key,
+                        "payment": {
+                            "chain": "solana",
+                            "network": network,
+                            "token": "USDC",
+                            "amount": str(MIN_PAYMENT),
+                            "wallet_address": wallet_address,
+                            "memo": agent_key,
+                        },
+                    },
+                    wallet_address=wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
+                    debug=self.debug, agent_key=agent_key, resource=pathname,
+                )
+
+            return self.get_response(request)
+
+        client_ip = _client_ip(request)
+        cookie_val = request.COOKIES.get(COOKIE_NAME, "")
+        if is_valid_cookie_value(cookie_val, secret, client_ip):
+            return self.get_response(request)
+
+        # Rate-limit challenge page issuance to prevent unlimited nonce harvesting.
+        if not _challenge_issue_limiter.check(client_ip):
+            return JsonResponse({"error": "rate_limited", "message": "Too many requests. Please try again later."}, status=429)
+
+        nonce = make_nonce(secret, client_ip)
+        resp = HttpResponse(challenge_html(request.get_full_path(), nonce, self.pow_difficulty), content_type="text/html")
+        resp["Cache-Control"] = "no-store"
+        resp["X-Frame-Options"] = "DENY"
+        resp["Content-Security-Policy"] = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; form-action 'self'"
+        return resp
+
+
+@csrf_exempt
+@require_POST
+def challenge_verify(request):
+    client_ip = _client_ip(request)
+    if not _challenge_limiter.check(client_ip):
+        return JsonResponse({"error": "rate_limited", "message": "Too many verification attempts. Please wait and try again."}, status=429)
+    secret = settings.CHALLENGE_SECRET
+    nonce = request.POST.get("nonce", "")[:MAX_NONCE_LENGTH]
+    return_to = request.POST.get("return_to", "/")[:MAX_RETURN_TO_LENGTH]
+    fp = request.POST.get("fp", "")[:MAX_FP_LENGTH]
+    pow_value = request.POST.get("pow", "")[:MAX_POW_LENGTH]
+
+    difficulty = getattr(settings, "POW_DIFFICULTY", POW_DIFFICULTY)
+    if not validate_challenge_submission(nonce, fp, pow_value, secret, client_ip, difficulty):
+        return JsonResponse({"error": "forbidden", "message": "Challenge verification failed."}, status=403)
+
+    safe_path = return_to if (return_to.startswith("/") and not return_to.startswith("//")) else "/"
+    response = HttpResponseRedirect(safe_path)
+    secure_cookie = request.is_secure()
+    response.set_cookie(
+        COOKIE_NAME,
+        make_cookie(secret, client_ip),
+        max_age=COOKIE_MAX_AGE,
+        path="/",
+        httponly=True,
+        secure=secure_cookie,
+        samesite="Lax",
+    )
+    return response