agentspend 0.1.0__tar.gz

agentspend-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.tgz
+bun.lock

agentspend-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: agentspend
+Version: 0.1.0
+Summary: Python SDK for AgentSpend — card & crypto paywalls for AI agents
+Project-URL: Homepage, https://agentspend.co
+Project-URL: Repository, https://github.com/agentspend/agentspend
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Provides-Extra: django
+Requires-Dist: django>=4.0; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Requires-Dist: uvicorn>=0.20; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# agentspend
+
+Python SDK for AgentSpend — card & crypto paywalls for AI agents.

agentspend-0.1.0/README.md

@@ -0,0 +1,3 @@
+# agentspend
+
+Python SDK for AgentSpend — card & crypto paywalls for AI agents.

agentspend-0.1.0/agentspend/__init__.py

@@ -0,0 +1,23 @@
+from agentspend.core import AgentSpendClient
+from agentspend.types import (
+    AgentSpendOptions,
+    ChargeOptions,
+    ChargeResponse,
+    PaywallOptions,
+    PaywallPaymentContext,
+    PaywallRequest,
+    PaywallResult,
+    AgentSpendChargeError,
+)
+
+__all__ = [
+    "AgentSpendClient",
+    "AgentSpendOptions",
+    "ChargeOptions",
+    "ChargeResponse",
+    "PaywallOptions",
+    "PaywallPaymentContext",
+    "PaywallRequest",
+    "PaywallResult",
+    "AgentSpendChargeError",
+]

agentspend-0.1.0/agentspend/core.py

@@ -0,0 +1,416 @@
+"""Core AgentSpend client — framework-agnostic."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import uuid
+import time
+import random
+from typing import Any, Optional
+
+import httpx
+
+from agentspend.types import (
+    AgentSpendChargeError,
+    AgentSpendOptions,
+    ChargeOptions,
+    ChargeResponse,
+    PaywallOptions,
+    PaywallPaymentContext,
+    PaywallRequest,
+    PaywallResult,
+)
+
+DEFAULT_PLATFORM_API_BASE_URL = "https://api.agentspend.co"
+
+USDC_BASE_ASSET = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+
+
+def _resolve_platform_url(explicit: Optional[str]) -> str:
+    if explicit and explicit.strip():
+        return explicit.strip()
+    env = os.environ.get("AGENTSPEND_API_URL", "")
+    if env.strip():
+        return env.strip()
+    return DEFAULT_PLATFORM_API_BASE_URL
+
+
+def _join_url(base: str, path: str) -> str:
+    base = base.rstrip("/")
+    path = path if path.startswith("/") else f"/{path}"
+    return f"{base}{path}"
+
+
+def _best_effort_idempotency_key() -> str:
+    try:
+        return str(uuid.uuid4())
+    except Exception:
+        return f"auto_{int(time.time())}_{random.randint(0, 0xFFFFFFFF):08x}"
+
+
+def _to_card_id(value: Any) -> Optional[str]:
+    if not isinstance(value, str):
+        return None
+    trimmed = value.strip()
+    return trimmed if trimmed.startswith("card_") else None
+
+
+def _to_string_metadata(data: Any) -> dict[str, str]:
+    if not isinstance(data, dict):
+        return {}
+    result: dict[str, str] = {}
+    for key, value in data.items():
+        if isinstance(value, str):
+            result[key] = value
+        elif isinstance(value, (int, float)):
+            result[key] = str(value)
+        elif isinstance(value, bool):
+            result[key] = "true" if value else "false"
+    return result
+
+
+def _resolve_amount(amount: int | str | Any, body: Any) -> int:
+    if isinstance(amount, int):
+        return amount
+    if isinstance(amount, str):
+        if isinstance(body, dict):
+            raw = body.get(amount)
+            return raw if isinstance(raw, int) else 0
+        return 0
+    # callable
+    return amount(body)
+
+
+def _extract_card_id(headers: dict[str, Optional[str]], body: Any) -> Optional[str]:
+    card_id = _to_card_id(headers.get("x-card-id"))
+    if not card_id and isinstance(body, dict):
+        card_id = _to_card_id(body.get("card_id"))
+    return card_id
+
+
+def _extract_payment_header(headers: dict[str, Optional[str]]) -> Optional[str]:
+    return headers.get("payment-signature") or headers.get("x-payment") or None
+
+
+class AgentSpendClient:
+    """Framework-agnostic AgentSpend client.
+
+    Usage::
+
+        client = AgentSpendClient(AgentSpendOptions(service_api_key="sk_..."))
+        result = client.charge("card_...", ChargeOptions(amount_cents=500))
+    """
+
+    def __init__(self, options: AgentSpendOptions):
+        if not options.service_api_key and not options.crypto:
+            raise AgentSpendChargeError(
+                "At least one of service_api_key or crypto config must be provided",
+                500,
+            )
+        self._options = options
+        self._base_url = _resolve_platform_url(options.platform_api_base_url)
+        self._cached_service_id: Optional[str] = None
+        self._network = options.crypto.network if options.crypto else "eip155:8453"
+        self._http = httpx.Client(timeout=30)
+
+    # -----------------------------------------------------------------
+    # charge()
+    # -----------------------------------------------------------------
+
+    def charge(self, card_id_input: str, opts: ChargeOptions) -> ChargeResponse:
+        if not self._options.service_api_key:
+            raise AgentSpendChargeError("charge() requires service_api_key", 500)
+
+        card_id = _to_card_id(card_id_input)
+        if not card_id:
+            raise AgentSpendChargeError("card_id must start with card_", 400)
+        if not isinstance(opts.amount_cents, int) or opts.amount_cents <= 0:
+            raise AgentSpendChargeError("amount_cents must be a positive integer", 400)
+
+        payload: dict[str, Any] = {
+            "card_id": card_id,
+            "amount_cents": opts.amount_cents,
+            "currency": opts.currency,
+            "idempotency_key": opts.idempotency_key or _best_effort_idempotency_key(),
+        }
+        if opts.description:
+            payload["description"] = opts.description
+        if opts.metadata:
+            payload["metadata"] = opts.metadata
+
+        resp = self._http.post(
+            _join_url(self._base_url, "/v1/charge"),
+            json=payload,
+            headers={
+                "authorization": f"Bearer {self._options.service_api_key}",
+                "content-type": "application/json",
+            },
+        )
+
+        body = resp.json()
+        if resp.status_code >= 400:
+            msg = body.get("error", "AgentSpend charge failed") if isinstance(body, dict) else "AgentSpend charge failed"
+            raise AgentSpendChargeError(msg, resp.status_code, body)
+
+        return ChargeResponse(
+            charged=body.get("charged", True),
+            card_id=body.get("card_id", card_id),
+            amount_cents=body.get("amount_cents", opts.amount_cents),
+            currency=body.get("currency", opts.currency),
+            remaining_limit_cents=body.get("remaining_limit_cents", 0),
+            stripe_payment_intent_id=body.get("stripe_payment_intent_id", ""),
+            stripe_charge_id=body.get("stripe_charge_id", ""),
+            charge_attempt_id=body.get("charge_attempt_id", ""),
+        )
+
+    # -----------------------------------------------------------------
+    # process_paywall()
+    # -----------------------------------------------------------------
+
+    def process_paywall(self, opts: PaywallOptions, request: PaywallRequest) -> PaywallResult:
+        if isinstance(opts.amount, int):
+            if opts.amount <= 0:
+                raise AgentSpendChargeError("amount must be a positive integer", 500)
+
+        body = request.body
+        effective_amount = _resolve_amount(opts.amount, body)
+
+        if not isinstance(effective_amount, int) or effective_amount <= 0:
+            return PaywallResult(
+                outcome="error",
+                status_code=400,
+                body={"error": "Could not determine payment amount from request"},
+            )
+
+        currency = opts.currency
+
+        # Crypto payment
+        payment_header = _extract_payment_header(request.headers)
+        if payment_header:
+            return self._handle_crypto_payment(payment_header, effective_amount, currency)
+
+        # Card payment
+        card_id = _extract_card_id(request.headers, body)
+        if card_id:
+            return self._handle_card_payment(request, card_id, effective_amount, currency, body, opts)
+
+        # 402
+        return self._build_402_result(request.url, effective_amount, currency)
+
+    # -----------------------------------------------------------------
+    # Internal
+    # -----------------------------------------------------------------
+
+    def _get_service_id(self) -> Optional[str]:
+        if self._cached_service_id:
+            return self._cached_service_id
+        if not self._options.service_api_key:
+            return None
+        try:
+            resp = self._http.get(
+                _join_url(self._base_url, "/v1/service/me"),
+                headers={"authorization": f"Bearer {self._options.service_api_key}"},
+            )
+            if resp.status_code < 400:
+                data = resp.json()
+                self._cached_service_id = data.get("id")
+        except Exception:
+            pass
+        return self._cached_service_id
+
+    def _resolve_pay_to_address(self) -> str:
+        if self._options.crypto and self._options.crypto.receiver_address:
+            return self._options.crypto.receiver_address
+
+        if self._options.service_api_key:
+            resp = self._http.post(
+                _join_url(self._base_url, "/v1/crypto/deposit-address"),
+                json={"amount_cents": 0, "currency": "usd"},
+                headers={
+                    "authorization": f"Bearer {self._options.service_api_key}",
+                    "content-type": "application/json",
+                },
+            )
+            if resp.status_code >= 400:
+                raise AgentSpendChargeError("Failed to resolve crypto deposit address", 502)
+            data = resp.json()
+            addr = data.get("deposit_address")
+            if not addr:
+                raise AgentSpendChargeError("No deposit address returned", 502)
+            return addr
+
+        raise AgentSpendChargeError("No crypto payTo address available", 500)
+
+    def _build_402_result(self, request_url: str, amount_cents: int, currency: str) -> PaywallResult:
+        service_id = self._get_service_id()
+
+        agentspend_block: dict[str, Any] = {}
+        if service_id:
+            agentspend_block = {"agentspend": {"service_id": service_id, "amount_cents": amount_cents}}
+
+        try:
+            pay_to = self._resolve_pay_to_address()
+            payment_requirements = {
+                "scheme": "exact",
+                "network": self._network,
+                "amount": str(amount_cents),
+                "asset": USDC_BASE_ASSET,
+                "payTo": pay_to,
+                "maxTimeoutSeconds": 300,
+                "extra": {"name": "USD Coin", "version": "2"},
+            }
+            payment_required = {
+                "x402Version": 2,
+                "error": "Payment required",
+                "resource": {
+                    "url": request_url,
+                    "description": f"Payment of {amount_cents} cents",
+                    "mimeType": "application/json",
+                },
+                "accepts": [payment_requirements],
+            }
+            header_value = base64.b64encode(json.dumps(payment_required).encode()).decode()
+
+            return PaywallResult(
+                outcome="payment_required",
+                status_code=402,
+                body={"error": "Payment required", "amount_cents": amount_cents, "currency": currency, **agentspend_block},
+                headers={"Payment-Required": header_value},
+            )
+        except Exception as exc:
+            print(f"[agentspend] Failed to resolve crypto payTo address — returning card-only 402: {exc}")
+            return PaywallResult(
+                outcome="payment_required",
+                status_code=402,
+                body={"error": "Payment required", "amount_cents": amount_cents, "currency": currency, **agentspend_block},
+                headers={},
+            )
+
+    def _handle_card_payment(
+        self,
+        request: PaywallRequest,
+        card_id: str,
+        amount_cents: int,
+        currency: str,
+        body: Any,
+        opts: PaywallOptions,
+    ) -> PaywallResult:
+        if not self._options.service_api_key:
+            return PaywallResult(outcome="error", status_code=500, body={"error": "Card payments require service_api_key"})
+
+        try:
+            charge_result = self.charge(
+                card_id,
+                ChargeOptions(
+                    amount_cents=amount_cents,
+                    currency=currency,
+                    description=opts.description,
+                    metadata=_to_string_metadata(opts.metadata(body)) if opts.metadata else None,
+                    idempotency_key=request.headers.get("x-request-id") or request.headers.get("idempotency-key"),
+                ),
+            )
+            return PaywallResult(
+                outcome="charged",
+                payment_context=PaywallPaymentContext(
+                    method="card",
+                    amount_cents=amount_cents,
+                    currency=currency,
+                    card_id=card_id,
+                    remaining_limit_cents=charge_result.remaining_limit_cents,
+                ),
+            )
+        except AgentSpendChargeError as exc:
+            if exc.status_code == 403:
+                return self._build_402_result(request.url, amount_cents, currency)
+            if exc.status_code == 402:
+                return PaywallResult(outcome="error", status_code=402, body={"error": "Payment required", "details": exc.details})
+            return PaywallResult(outcome="error", status_code=exc.status_code, body={"error": str(exc), "details": exc.details})
+        except Exception:
+            return PaywallResult(outcome="error", status_code=500, body={"error": "Unexpected paywall failure"})
+
+    def _handle_crypto_payment(
+        self,
+        payment_header: str,
+        amount_cents: int,
+        currency: str,
+    ) -> PaywallResult:
+        try:
+            payload_json = base64.b64decode(payment_header).decode("utf-8")
+            payment_payload = json.loads(payload_json)
+        except Exception:
+            return PaywallResult(outcome="error", status_code=400, body={"error": "Invalid payment payload encoding"})
+
+        accepted_pay_to = None
+        if isinstance(payment_payload, dict):
+            accepted = payment_payload.get("accepted", {})
+            if isinstance(accepted, dict):
+                accepted_pay_to = accepted.get("payTo")
+
+        try:
+            pay_to = accepted_pay_to or self._resolve_pay_to_address()
+        except AgentSpendChargeError as exc:
+            return PaywallResult(outcome="error", status_code=exc.status_code, body={"error": exc.args[0], "details": exc.details})
+
+        # Note: Full x402 verification requires the @x402 libraries.
+        # For Python, crypto verification should be implemented via HTTP calls
+        # to the facilitator endpoint. This is a placeholder that demonstrates
+        # the protocol flow — production use requires facilitator integration.
+        payment_requirements = {
+            "scheme": "exact",
+            "network": self._network,
+            "amount": str(amount_cents),
+            "asset": USDC_BASE_ASSET,
+            "payTo": pay_to,
+            "maxTimeoutSeconds": 300,
+            "extra": {"name": "USD Coin", "version": "2"},
+        }
+
+        facilitator_url = "https://facilitator.openx402.ai"
+        if self._options.crypto and self._options.crypto.facilitator_url:
+            facilitator_url = self._options.crypto.facilitator_url
+
+        # Verify via facilitator
+        try:
+            verify_resp = self._http.post(
+                f"{facilitator_url.rstrip('/')}/verify",
+                json={"payload": payment_payload, "requirements": payment_requirements},
+            )
+            verify_data = verify_resp.json() if verify_resp.status_code < 500 else {}
+            if not verify_data.get("isValid"):
+                return PaywallResult(
+                    outcome="error",
+                    status_code=402,
+                    body={"error": "Payment verification failed", "details": verify_data.get("invalidReason")},
+                )
+        except Exception as exc:
+            return PaywallResult(outcome="error", status_code=500, body={"error": "Crypto payment processing failed", "details": str(exc)})
+
+        # Settle via facilitator
+        try:
+            settle_resp = self._http.post(
+                f"{facilitator_url.rstrip('/')}/settle",
+                json={"payload": payment_payload, "requirements": payment_requirements},
+            )
+            settle_data = settle_resp.json() if settle_resp.status_code < 500 else {}
+            if not settle_data.get("success"):
+                return PaywallResult(
+                    outcome="error",
+                    status_code=402,
+                    body={"error": "Payment settlement failed", "details": settle_data.get("errorReason")},
+                )
+        except Exception as exc:
+            return PaywallResult(outcome="error", status_code=500, body={"error": "Crypto payment processing failed", "details": str(exc)})
+
+        return PaywallResult(
+            outcome="crypto_paid",
+            payment_context=PaywallPaymentContext(
+                method="crypto",
+                amount_cents=amount_cents,
+                currency=currency,
+                transaction_hash=settle_data.get("transaction"),
+                payer_address=verify_data.get("payer"),
+                network=self._network,
+            ),
+        )

agentspend-0.1.0/agentspend/django.py

@@ -0,0 +1,153 @@
+"""Django integration for AgentSpend."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Optional
+
+from django.http import HttpRequest, JsonResponse
+
+from agentspend.core import AgentSpendClient
+from agentspend.types import (
+    AgentSpendOptions,
+    ChargeOptions,
+    ChargeResponse,
+    PaywallOptions,
+    PaywallPaymentContext,
+    PaywallRequest,
+)
+
+_PAYMENT_CONTEXT_ATTR = "_agentspend_payment_context"
+
+
+def get_payment_context(request: HttpRequest) -> PaywallPaymentContext | None:
+    """Retrieve the payment context set by the paywall middleware."""
+    return getattr(request, _PAYMENT_CONTEXT_ATTR, None)
+
+
+class AgentSpendMiddleware:
+    """Django middleware for AgentSpend paywalls.
+
+    Configure in settings.py::
+
+        AGENTSPEND_OPTIONS = AgentSpendOptions(service_api_key="sk_...")
+        AGENTSPEND_PAYWALL_ROUTES = {
+            "/paid/": PaywallOptions(amount=500),
+        }
+
+    Then use the ``agentspend_paywall`` decorator for per-view control,
+    or this middleware for route-based configuration.
+    """
+
+    def __init__(self, get_response: Callable[[HttpRequest], Any]):
+        self.get_response = get_response
+        # Import from Django settings
+        from django.conf import settings
+
+        options: AgentSpendOptions = getattr(settings, "AGENTSPEND_OPTIONS", None)
+        if options is None:
+            raise ValueError("AGENTSPEND_OPTIONS must be set in Django settings")
+
+        self._client = AgentSpendClient(options)
+        self._routes: dict[str, PaywallOptions] = getattr(settings, "AGENTSPEND_PAYWALL_ROUTES", {})
+
+    def __call__(self, request: HttpRequest) -> Any:
+        opts = self._routes.get(request.path)
+        if opts is None:
+            return self.get_response(request)
+
+        result = self._process(request, opts)
+        if result is not None:
+            return result
+
+        return self.get_response(request)
+
+    def _process(self, request: HttpRequest, opts: PaywallOptions) -> Optional[JsonResponse]:
+        try:
+            body = json.loads(request.body) if request.body else {}
+        except (json.JSONDecodeError, ValueError):
+            body = {}
+
+        headers = {
+            "x-card-id": request.headers.get("x-card-id"),
+            "payment-signature": request.headers.get("payment-signature"),
+            "x-payment": request.headers.get("x-payment"),
+            "x-request-id": request.headers.get("x-request-id"),
+            "idempotency-key": request.headers.get("idempotency-key"),
+        }
+
+        paywall_req = PaywallRequest(
+            url=request.build_absolute_uri(),
+            method=request.method,
+            headers=headers,
+            body=body,
+        )
+
+        result = self._client.process_paywall(opts, paywall_req)
+
+        if result.outcome in ("charged", "crypto_paid"):
+            setattr(request, _PAYMENT_CONTEXT_ATTR, result.payment_context)
+            return None
+
+        if result.outcome == "payment_required":
+            resp = JsonResponse(result.body, status=result.status_code or 402)
+            for key, value in result.headers.items():
+                resp[key] = value
+            return resp
+
+        return JsonResponse(result.body, status=result.status_code or 500)
+
+
+def agentspend_paywall(options: AgentSpendOptions, paywall_opts: PaywallOptions) -> Callable[..., Any]:
+    """Decorator for individual Django views.
+
+    Usage::
+
+        from agentspend.django import agentspend_paywall, get_payment_context
+
+        @agentspend_paywall(AgentSpendOptions(service_api_key="sk_..."), PaywallOptions(amount=500))
+        def paid_view(request):
+            ctx = get_payment_context(request)
+            return JsonResponse({"paid": True, "method": ctx.method})
+    """
+    client = AgentSpendClient(options)
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        def wrapper(request: HttpRequest, *args: Any, **kwargs: Any) -> Any:
+            try:
+                body = json.loads(request.body) if request.body else {}
+            except (json.JSONDecodeError, ValueError):
+                body = {}
+
+            headers = {
+                "x-card-id": request.headers.get("x-card-id"),
+                "payment-signature": request.headers.get("payment-signature"),
+                "x-payment": request.headers.get("x-payment"),
+                "x-request-id": request.headers.get("x-request-id"),
+                "idempotency-key": request.headers.get("idempotency-key"),
+            }
+
+            paywall_req = PaywallRequest(
+                url=request.build_absolute_uri(),
+                method=request.method,
+                headers=headers,
+                body=body,
+            )
+
+            result = client.process_paywall(paywall_opts, paywall_req)
+
+            if result.outcome in ("charged", "crypto_paid"):
+                setattr(request, _PAYMENT_CONTEXT_ATTR, result.payment_context)
+                return fn(request, *args, **kwargs)
+
+            if result.outcome == "payment_required":
+                resp = JsonResponse(result.body, status=result.status_code or 402)
+                for key, value in result.headers.items():
+                    resp[key] = value
+                return resp
+
+            return JsonResponse(result.body, status=result.status_code or 500)
+
+        return wrapper
+
+    return decorator

agentspend-0.1.0/agentspend/fastapi.py

@@ -0,0 +1,121 @@
+"""FastAPI integration for AgentSpend."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fastapi import Depends, Request
+from fastapi.responses import JSONResponse
+
+from agentspend.core import AgentSpendClient
+from agentspend.types import (
+    AgentSpendOptions,
+    ChargeOptions,
+    ChargeResponse,
+    PaywallOptions,
+    PaywallPaymentContext,
+    PaywallRequest,
+    PaywallResult,
+)
+
+_PAYMENT_CONTEXT_ATTR = "_agentspend_payment_context"
+
+
+def get_payment_context(request: Request) -> PaywallPaymentContext | None:
+    """Retrieve the payment context set by the paywall dependency."""
+    return getattr(request.state, _PAYMENT_CONTEXT_ATTR, None)
+
+
+class AgentSpend:
+    """FastAPI AgentSpend integration.
+
+    Usage::
+
+        from agentspend.fastapi import AgentSpend, get_payment_context
+
+        spend = AgentSpend(AgentSpendOptions(service_api_key="sk_..."))
+
+        @app.post("/paid", dependencies=[Depends(spend.paywall(PaywallOptions(amount=500)))])
+        async def paid_endpoint(request: Request):
+            ctx = get_payment_context(request)
+            return {"paid": True, "method": ctx.method}
+    """
+
+    def __init__(self, options: AgentSpendOptions):
+        self._client = AgentSpendClient(options)
+
+    def charge(self, card_id: str, opts: ChargeOptions) -> ChargeResponse:
+        return self._client.charge(card_id, opts)
+
+    def paywall(self, opts: PaywallOptions):
+        """Return a FastAPI dependency that gates a route behind a paywall."""
+        client = self._client
+
+        async def paywall_dependency(request: Request) -> Optional[PaywallPaymentContext]:
+            body: Any
+            try:
+                body = await request.json()
+            except Exception:
+                body = {}
+
+            headers = {
+                "x-card-id": request.headers.get("x-card-id"),
+                "payment-signature": request.headers.get("payment-signature"),
+                "x-payment": request.headers.get("x-payment"),
+                "x-request-id": request.headers.get("x-request-id"),
+                "idempotency-key": request.headers.get("idempotency-key"),
+            }
+
+            paywall_req = PaywallRequest(
+                url=str(request.url),
+                method=request.method,
+                headers=headers,
+                body=body,
+            )
+
+            result = client.process_paywall(opts, paywall_req)
+
+            if result.outcome in ("charged", "crypto_paid"):
+                setattr(request.state, _PAYMENT_CONTEXT_ATTR, result.payment_context)
+                return result.payment_context
+
+            if result.outcome == "payment_required":
+                raise _PaywallResponseException(
+                    status_code=result.status_code or 402,
+                    body=result.body or {},
+                    headers=result.headers,
+                )
+
+            raise _PaywallResponseException(
+                status_code=result.status_code or 500,
+                body=result.body or {},
+            )
+
+        return paywall_dependency
+
+
+class _PaywallResponseException(Exception):
+    """Internal exception to short-circuit FastAPI request processing."""
+
+    def __init__(self, status_code: int, body: dict[str, Any], headers: dict[str, str] | None = None):
+        self.status_code = status_code
+        self.body = body
+        self.headers = headers or {}
+
+
+def install_exception_handler(app: Any) -> None:
+    """Install the AgentSpend exception handler on a FastAPI app.
+
+    Call this once during app startup::
+
+        from agentspend.fastapi import install_exception_handler
+        install_exception_handler(app)
+    """
+
+    @app.exception_handler(_PaywallResponseException)
+    async def _handle_paywall_exception(request: Request, exc: _PaywallResponseException) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=exc.body,
+            headers=exc.headers,
+        )

agentspend-0.1.0/agentspend/flask.py

@@ -0,0 +1,90 @@
+"""Flask integration for AgentSpend."""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import Any, Callable
+
+from flask import Response as FlaskResponse, g, jsonify, request
+
+from agentspend.core import AgentSpendClient
+from agentspend.types import (
+    AgentSpendOptions,
+    ChargeOptions,
+    ChargeResponse,
+    PaywallOptions,
+    PaywallPaymentContext,
+    PaywallRequest,
+    PaywallResult,
+)
+
+
+def get_payment_context() -> PaywallPaymentContext | None:
+    """Retrieve the payment context set by the paywall decorator."""
+    return getattr(g, "payment_context", None)
+
+
+class AgentSpend:
+    """Flask AgentSpend integration.
+
+    Usage::
+
+        from agentspend.flask import AgentSpend
+
+        spend = AgentSpend(AgentSpendOptions(service_api_key="sk_..."))
+
+        @app.route("/paid", methods=["POST"])
+        @spend.paywall(PaywallOptions(amount=500))
+        def paid_endpoint():
+            ctx = get_payment_context()
+            return jsonify({"paid": True, "method": ctx.method})
+    """
+
+    def __init__(self, options: AgentSpendOptions):
+        self._client = AgentSpendClient(options)
+
+    def charge(self, card_id: str, opts: ChargeOptions) -> ChargeResponse:
+        return self._client.charge(card_id, opts)
+
+    def paywall(self, opts: PaywallOptions) -> Callable[..., Any]:
+        """Decorator that gates a Flask route behind a paywall."""
+
+        def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+            @wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                headers = {
+                    "x-card-id": request.headers.get("x-card-id"),
+                    "payment-signature": request.headers.get("payment-signature"),
+                    "x-payment": request.headers.get("x-payment"),
+                    "x-request-id": request.headers.get("x-request-id"),
+                    "idempotency-key": request.headers.get("idempotency-key"),
+                }
+
+                body = request.get_json(silent=True) or {}
+
+                paywall_req = PaywallRequest(
+                    url=request.url,
+                    method=request.method,
+                    headers=headers,
+                    body=body,
+                )
+
+                result = self._client.process_paywall(opts, paywall_req)
+
+                if result.outcome in ("charged", "crypto_paid"):
+                    g.payment_context = result.payment_context
+                    return fn(*args, **kwargs)
+                elif result.outcome == "payment_required":
+                    resp = jsonify(result.body)
+                    resp.status_code = result.status_code or 402
+                    for key, value in result.headers.items():
+                        resp.headers[key] = value
+                    return resp
+                else:
+                    resp = jsonify(result.body)
+                    resp.status_code = result.status_code or 500
+                    return resp
+
+            return wrapper
+
+        return decorator

agentspend-0.1.0/agentspend/types.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Union
+
+
+class AgentSpendChargeError(Exception):
+    """Raised when a charge or paywall operation fails."""
+
+    def __init__(self, message: str, status_code: int, details: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.details = details
+
+
+@dataclass
+class AgentSpendOptions:
+    """Configuration for the AgentSpend client."""
+
+    platform_api_base_url: Optional[str] = None
+    service_api_key: Optional[str] = None
+    crypto: Optional[CryptoConfig] = None
+
+
+@dataclass
+class CryptoConfig:
+    """Crypto / x402 configuration."""
+
+    receiver_address: Optional[str] = None
+    network: str = "eip155:8453"
+    facilitator_url: str = "https://facilitator.openx402.ai"
+
+
+@dataclass
+class ChargeOptions:
+    amount_cents: int
+    currency: str = "usd"
+    description: Optional[str] = None
+    metadata: Optional[dict[str, str]] = None
+    idempotency_key: Optional[str] = None
+
+
+@dataclass
+class ChargeResponse:
+    charged: bool
+    card_id: str
+    amount_cents: int
+    currency: str
+    remaining_limit_cents: int
+    stripe_payment_intent_id: str
+    stripe_charge_id: str
+    charge_attempt_id: str
+
+
+@dataclass
+class PaywallOptions:
+    """Paywall configuration.
+
+    amount can be:
+    - int: fixed price in cents (e.g. 500 = $5.00)
+    - str: body field name to read amount from (e.g. "amount_cents")
+    - callable: custom dynamic pricing ``(body) -> int``
+    """
+
+    amount: Union[int, str, Callable[[Any], int]]
+    currency: str = "usd"
+    description: Optional[str] = None
+    metadata: Optional[Callable[[Any], dict[str, Any]]] = None
+
+
+@dataclass
+class PaywallPaymentContext:
+    method: str  # "card" | "crypto"
+    amount_cents: int
+    currency: str
+    card_id: Optional[str] = None
+    remaining_limit_cents: Optional[int] = None
+    transaction_hash: Optional[str] = None
+    payer_address: Optional[str] = None
+    network: Optional[str] = None
+
+
+@dataclass
+class PaywallRequest:
+    url: str
+    method: str
+    headers: dict[str, Optional[str]]
+    body: Any
+
+
+@dataclass
+class PaywallResult:
+    """Result from processPaywall.
+
+    outcome is one of: "charged", "crypto_paid", "payment_required", "error"
+    """
+
+    outcome: str
+    payment_context: Optional[PaywallPaymentContext] = None
+    status_code: Optional[int] = None
+    body: Optional[dict[str, Any]] = None
+    headers: dict[str, str] = field(default_factory=dict)

agentspend-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentspend"
+version = "0.1.0"
+description = "Python SDK for AgentSpend — card & crypto paywalls for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.25",
+]
+
+[project.optional-dependencies]
+flask = ["flask>=2.0"]
+fastapi = ["fastapi>=0.100", "uvicorn>=0.20"]
+django = ["django>=4.0"]
+
+[project.urls]
+Homepage = "https://agentspend.co"
+Repository = "https://github.com/agentspend/agentspend"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agentspend"]