payagent 0.1.0__py3-none-any.whl

payagent/__init__.py

@@ -0,0 +1,63 @@
+"""payagent — Universal Payment & Monetization Engine for AI Agents."""
+
+from __future__ import annotations
+
+from payagent.client import AgentPayClient
+from payagent.escrow import EscrowRecord, EscrowSession, EscrowState
+from payagent.exceptions import (
+    AgentPayError,
+    BudgetExceededError,
+    EscrowError,
+    EscrowValidationError,
+    HumanApprovalRequiredError,
+    InsufficientFundsError,
+    PaymentError,
+    PaymentVerificationError,
+    PolicyViolationError,
+    ProviderNotFoundError,
+)
+from payagent.guardrails import PolicyEnforcer, SpendingLedger, SpendingPolicy
+from payagent.paywall import PaymentVerifier, paywall
+from payagent.providers import (
+    BaseProvider,
+    FiatProvider,
+    PaymentResult,
+    SolanaProvider,
+    X402Provider,
+)
+from payagent.wallet import AgentWallet
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # core
+    "AgentWallet",
+    "AgentPayClient",
+    "EscrowSession",
+    "EscrowRecord",
+    "EscrowState",
+    "paywall",
+    "PaymentVerifier",
+    # policy
+    "SpendingPolicy",
+    "SpendingLedger",
+    "PolicyEnforcer",
+    # providers
+    "BaseProvider",
+    "PaymentResult",
+    "X402Provider",
+    "SolanaProvider",
+    "FiatProvider",
+    # exceptions
+    "AgentPayError",
+    "InsufficientFundsError",
+    "BudgetExceededError",
+    "PolicyViolationError",
+    "HumanApprovalRequiredError",
+    "PaymentError",
+    "PaymentVerificationError",
+    "ProviderNotFoundError",
+    "EscrowError",
+    "EscrowValidationError",
+    "__version__",
+]

payagent/client.py

@@ -0,0 +1,146 @@
+"""HTTP client with automatic HTTP 402 payment handling."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from payagent.exceptions import PaymentError
+from payagent.providers.x402 import X402Provider
+from payagent.wallet import AgentWallet
+
+
+class AgentPayClient:
+    """``httpx.AsyncClient`` wrapper that settles 402 challenges via a wallet.
+
+    Flow:
+      1. Issue the original request.
+      2. On ``402 Payment Required``, parse payment headers.
+      3. Pay via :class:`AgentWallet`.
+      4. Retry once with ``X-PAYMENT-PROOF`` (and related) headers.
+    """
+
+    def __init__(
+        self,
+        wallet: AgentWallet,
+        *,
+        client: httpx.AsyncClient | None = None,
+        max_payment_retries: int = 1,
+        timeout: float = 30.0,
+        base_url: str = "",
+        default_headers: dict[str, str] | None = None,
+    ) -> None:
+        self.wallet = wallet
+        self.max_payment_retries = max_payment_retries
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(
+            timeout=timeout,
+            base_url=base_url,
+            headers=default_headers or {},
+        )
+        self.last_payment: Any | None = None
+
+    @property
+    def http(self) -> httpx.AsyncClient:
+        return self._client
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        hdrs = dict(headers or {})
+        response = await self._client.request(method, url, headers=hdrs, **kwargs)
+
+        retries = 0
+        while response.status_code == 402 and retries < self.max_payment_retries:
+            payment_info = self._extract_payment_requirement(response)
+            domain = self._domain_for(url)
+            amount = float(payment_info["amount"])
+            currency = payment_info["currency"]
+            recipient = payment_info["address"]
+            network = payment_info.get("network")
+
+            result = await self.wallet.pay(
+                amount=amount,
+                currency=currency,
+                recipient=recipient,
+                domain=domain,
+                network=network,
+                metadata={"url": str(url), "method": method},
+            )
+            self.last_payment = result
+
+            pay_headers = {
+                **hdrs,
+                "X-PAYMENT-PROOF": result.as_proof_header(),
+                "X-PAYMENT-TX": result.tx_hash,
+                "X-PAYMENT-AMOUNT": str(result.amount),
+                "X-PAYMENT-CURRENCY": result.currency,
+                "X-PAYMENT-PROVIDER": result.provider,
+            }
+            response = await self._client.request(method, url, headers=pay_headers, **kwargs)
+            retries += 1
+
+        return response
+
+    async def get(self, url: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("GET", url, **kwargs)
+
+    async def post(self, url: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("POST", url, **kwargs)
+
+    async def put(self, url: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("PUT", url, **kwargs)
+
+    async def delete(self, url: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("DELETE", url, **kwargs)
+
+    async def patch(self, url: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("PATCH", url, **kwargs)
+
+    def _extract_payment_requirement(self, response: httpx.Response) -> dict[str, str]:
+        try:
+            return X402Provider.parse_402_headers(response.headers)
+        except PaymentError:
+            # Fallback: JSON body {amount, address/currency}
+            try:
+                data = response.json()
+            except Exception as exc:  # noqa: BLE001
+                raise PaymentError(
+                    "402 response missing payment headers and JSON body"
+                ) from exc
+            address = data.get("address") or data.get("recipient") or data.get("pay_to")
+            amount = data.get("amount") or data.get("price")
+            currency = (data.get("currency") or "USDC").upper()
+            network = data.get("network") or "base"
+            if address is None or amount is None:
+                raise PaymentError("402 JSON body missing address/amount")
+            return {
+                "address": str(address),
+                "amount": str(amount),
+                "currency": currency,
+                "network": str(network),
+            }
+
+    @staticmethod
+    def _domain_for(url: str) -> str | None:
+        try:
+            return urlparse(str(url)).hostname
+        except Exception:  # noqa: BLE001
+            return None
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AgentPayClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

payagent/escrow.py

@@ -0,0 +1,204 @@
+"""Conditional escrow: lock → execute → validate → release or refund."""
+
+from __future__ import annotations
+
+import enum
+import inspect
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Awaitable, Callable, Generic, TypeVar
+
+from payagent.exceptions import EscrowError, EscrowValidationError
+from payagent.providers.base import PaymentResult
+from payagent.wallet import AgentWallet
+
+T = TypeVar("T")
+
+ValidatorFn = Callable[[T], bool | Awaitable[bool]]
+JobFn = Callable[[], T | Awaitable[T]]
+
+
+class EscrowState(str, enum.Enum):
+    CREATED = "created"
+    LOCKED = "locked"
+    EXECUTED = "executed"
+    RELEASED = "released"
+    REFUNDED = "refunded"
+    FAILED = "failed"
+
+
+@dataclass
+class EscrowRecord:
+    session_id: str
+    amount: float
+    currency: str
+    recipient: str
+    state: EscrowState = EscrowState.CREATED
+    lock_result: PaymentResult | None = None
+    release_result: PaymentResult | None = None
+    refund_result: PaymentResult | None = None
+    job_result: Any = None
+    error: str | None = None
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+async def _maybe_await(value: T | Awaitable[T]) -> T:
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+class EscrowSession(Generic[T]):
+    """Hold funds until ``validator_fn(result)`` succeeds.
+
+    Model (mock-friendly):
+      * **lock** — reserve / debit funds to an escrow address (or internal hold)
+      * **job** — run the paid work
+      * **validate** — user-supplied check (Pydantic model, status code, etc.)
+      * **release** — pay the service provider on success
+      * **refund** — credit back on failure (mock ledger bump / reverse entry)
+    """
+
+    def __init__(
+        self,
+        wallet: AgentWallet,
+        validator_fn: ValidatorFn[T],
+        *,
+        escrow_address: str = "escrow://payagent",
+        refund_address: str = "refund://payagent",
+    ) -> None:
+        self.wallet = wallet
+        self.validator_fn = validator_fn
+        self.escrow_address = escrow_address
+        self.refund_address = refund_address
+        self.record: EscrowRecord | None = None
+
+    async def run(
+        self,
+        job: JobFn[T],
+        *,
+        amount: float,
+        currency: str,
+        recipient: str,
+        domain: str | None = None,
+        network: str | None = None,
+        memo: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> T:
+        session_id = uuid.uuid4().hex
+        self.record = EscrowRecord(
+            session_id=session_id,
+            amount=amount,
+            currency=currency,
+            recipient=recipient,
+            metadata=dict(metadata or {}),
+        )
+
+        # 1) Lock funds (policy-checked payment to escrow address)
+        try:
+            lock = await self.wallet.pay(
+                amount=amount,
+                currency=currency,
+                recipient=self.escrow_address,
+                domain=domain,
+                network=network,
+                memo=memo or f"escrow-lock:{session_id}",
+                metadata={"escrow_session": session_id, "phase": "lock", **(metadata or {})},
+            )
+            self.record.lock_result = lock
+            self.record.state = EscrowState.LOCKED
+        except Exception as exc:
+            self.record.state = EscrowState.FAILED
+            self.record.error = str(exc)
+            raise EscrowError(f"escrow lock failed: {exc}") from exc
+
+        # 2) Execute job
+        try:
+            result = await _maybe_await(job())
+            self.record.job_result = result
+            self.record.state = EscrowState.EXECUTED
+        except Exception as exc:
+            self.record.error = str(exc)
+            await self._refund(session_id, amount, currency, domain, network)
+            raise EscrowError(f"escrow job failed: {exc}") from exc
+
+        # 3) Validate
+        try:
+            ok = await _maybe_await(self.validator_fn(result))
+        except Exception as exc:
+            self.record.error = str(exc)
+            await self._refund(session_id, amount, currency, domain, network)
+            raise EscrowValidationError(f"validator raised: {exc}") from exc
+
+        if not ok:
+            self.record.error = "validator returned False"
+            await self._refund(session_id, amount, currency, domain, network)
+            raise EscrowValidationError("escrow validation failed; funds refunded")
+
+        # 4) Release to provider (do not double-count budget: record_spend=False)
+        try:
+            release = await self.wallet.pay(
+                amount=amount,
+                currency=currency,
+                recipient=recipient,
+                domain=domain,
+                network=network,
+                memo=memo or f"escrow-release:{session_id}",
+                metadata={
+                    "escrow_session": session_id,
+                    "phase": "release",
+                    "lock_tx": lock.tx_hash,
+                    **(metadata or {}),
+                },
+                record_spend=False,
+            )
+            self.record.release_result = release
+            self.record.state = EscrowState.RELEASED
+        except Exception as exc:
+            self.record.error = str(exc)
+            await self._refund(session_id, amount, currency, domain, network)
+            raise EscrowError(f"escrow release failed: {exc}") from exc
+
+        return result
+
+    async def _refund(
+        self,
+        session_id: str,
+        amount: float,
+        currency: str,
+        domain: str | None,
+        network: str | None,
+    ) -> None:
+        assert self.record is not None
+        try:
+            # Mock-friendly: pay back to refund address without re-applying budget
+            # (budget already charged on lock).
+            refund = await self.wallet.pay(
+                amount=amount,
+                currency=currency,
+                recipient=self.refund_address,
+                domain=domain,
+                network=network,
+                memo=f"escrow-refund:{session_id}",
+                metadata={"escrow_session": session_id, "phase": "refund"},
+                record_spend=False,
+            )
+            # Credit mock balances where possible
+            self._credit_mock_providers(amount, currency)
+            self.record.refund_result = refund
+            self.record.state = EscrowState.REFUNDED
+        except Exception as exc:  # noqa: BLE001
+            self.record.state = EscrowState.FAILED
+            self.record.error = f"refund failed: {exc}"
+
+    def _credit_mock_providers(self, amount: float, currency: str) -> None:
+        """Best-effort restore mock balances after refund."""
+        cur = currency.upper()
+        for p in self.wallet.providers:
+            if not p.supports(cur):
+                continue
+            bal = getattr(p, "_mock_balance", None)
+            if isinstance(bal, (int, float)) and getattr(p, "mock", False):
+                setattr(p, "_mock_balance", float(bal) + amount)

payagent/exceptions.py

@@ -0,0 +1,43 @@
+"""Custom exceptions for payagent."""
+
+from __future__ import annotations
+
+
+class AgentPayError(Exception):
+    """Base error for the payagent library."""
+
+
+class InsufficientFundsError(AgentPayError):
+    """Wallet or provider balance is too low for the requested payment."""
+
+
+class BudgetExceededError(AgentPayError):
+    """Spending would exceed a configured budget limit (per-tx, daily, monthly)."""
+
+
+class PolicyViolationError(AgentPayError):
+    """Payment violates a spending policy rule (domain allowlist, etc.)."""
+
+
+class HumanApprovalRequiredError(AgentPayError):
+    """Amount exceeds the human-in-the-loop threshold; approval is required."""
+
+
+class PaymentError(AgentPayError):
+    """Payment execution failed at the provider layer."""
+
+
+class PaymentVerificationError(AgentPayError):
+    """Payment proof / transaction could not be verified."""
+
+
+class ProviderNotFoundError(AgentPayError):
+    """No provider registered for the requested currency or network."""
+
+
+class EscrowError(AgentPayError):
+    """Escrow session failed (lock, release, refund, or validation)."""
+
+
+class EscrowValidationError(EscrowError):
+    """Escrow job result failed validation; funds should be refunded."""

payagent/guardrails.py

@@ -0,0 +1,237 @@
+"""Budget limits, domain allowlists, and HITL policy enforcement."""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, Iterable
+from urllib.parse import urlparse
+
+from payagent.exceptions import (
+    BudgetExceededError,
+    HumanApprovalRequiredError,
+    PolicyViolationError,
+)
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _day_key(dt: datetime | None = None) -> str:
+    d = dt or _utc_now()
+    return d.astimezone(timezone.utc).strftime("%Y-%m-%d")
+
+
+def _month_key(dt: datetime | None = None) -> str:
+    d = dt or _utc_now()
+    return d.astimezone(timezone.utc).strftime("%Y-%m")
+
+
+@dataclass
+class SpendingPolicy:
+    """Declarative spending limits and rules for an agent wallet."""
+
+    max_per_tx: float = 0.50
+    daily_limit: float = 10.0
+    monthly_limit: float = 100.0
+    allowlist_domains: list[str] = field(default_factory=list)
+    require_human_approval_above: float | None = None
+    # If True, empty allowlist means "allow all". If False, empty blocks all hosts.
+    allow_all_when_empty_allowlist: bool = True
+
+    def domain_allowed(self, domain_or_url: str | None) -> bool:
+        if domain_or_url is None:
+            return True
+        host = domain_or_url
+        if "://" in domain_or_url:
+            host = urlparse(domain_or_url).hostname or domain_or_url
+        host = host.lower().strip(".")
+        if not self.allowlist_domains:
+            return self.allow_all_when_empty_allowlist
+        for pattern in self.allowlist_domains:
+            p = pattern.lower().strip(".")
+            if host == p or host.endswith("." + p):
+                return True
+        return False
+
+
+class SpendingLedger:
+    """Thread-safe expenditure tracker (in-memory or lightweight SQLite)."""
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        self._lock = threading.RLock()
+        self._memory: list[tuple[float, float, str | None]] = []  # ts, amount, domain
+        self._db_path = Path(db_path) if db_path else None
+        self._conn: sqlite3.Connection | None = None
+        if self._db_path is not None:
+            self._db_path.parent.mkdir(parents=True, exist_ok=True)
+            self._conn = sqlite3.connect(str(self._db_path), check_same_thread=False)
+            self._conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS spend (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    ts REAL NOT NULL,
+                    amount REAL NOT NULL,
+                    domain TEXT,
+                    day_key TEXT NOT NULL,
+                    month_key TEXT NOT NULL
+                )
+                """
+            )
+            self._conn.commit()
+
+    def record(self, amount: float, domain: str | None = None) -> None:
+        now = time.time()
+        dt = datetime.fromtimestamp(now, tz=timezone.utc)
+        with self._lock:
+            if self._conn is not None:
+                self._conn.execute(
+                    "INSERT INTO spend (ts, amount, domain, day_key, month_key) VALUES (?, ?, ?, ?, ?)",
+                    (now, amount, domain, _day_key(dt), _month_key(dt)),
+                )
+                self._conn.commit()
+            else:
+                self._memory.append((now, amount, domain))
+
+    def spent_today(self) -> float:
+        key = _day_key()
+        with self._lock:
+            if self._conn is not None:
+                cur = self._conn.execute(
+                    "SELECT COALESCE(SUM(amount), 0) FROM spend WHERE day_key = ?",
+                    (key,),
+                )
+                row = cur.fetchone()
+                return float(row[0] if row else 0.0)
+            total = 0.0
+            for ts, amount, _ in self._memory:
+                dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+                if _day_key(dt) == key:
+                    total += amount
+            return total
+
+    def spent_this_month(self) -> float:
+        key = _month_key()
+        with self._lock:
+            if self._conn is not None:
+                cur = self._conn.execute(
+                    "SELECT COALESCE(SUM(amount), 0) FROM spend WHERE month_key = ?",
+                    (key,),
+                )
+                row = cur.fetchone()
+                return float(row[0] if row else 0.0)
+            total = 0.0
+            for ts, amount, _ in self._memory:
+                dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+                if _month_key(dt) == key:
+                    total += amount
+            return total
+
+    def reset(self) -> None:
+        with self._lock:
+            self._memory.clear()
+            if self._conn is not None:
+                self._conn.execute("DELETE FROM spend")
+                self._conn.commit()
+
+    def close(self) -> None:
+        with self._lock:
+            if self._conn is not None:
+                self._conn.close()
+                self._conn = None
+
+
+ApprovalCallback = Callable[[float, str, str | None], bool]
+
+
+class PolicyEnforcer:
+    """Checks a proposed payment against :class:`SpendingPolicy` + ledger."""
+
+    def __init__(
+        self,
+        policy: SpendingPolicy,
+        ledger: SpendingLedger | None = None,
+        *,
+        approval_callback: ApprovalCallback | None = None,
+    ) -> None:
+        self.policy = policy
+        self.ledger = ledger or SpendingLedger()
+        self.approval_callback = approval_callback
+
+    def check(
+        self,
+        amount: float,
+        *,
+        domain: str | None = None,
+        currency: str = "USDC",
+        recipient: str | None = None,
+    ) -> None:
+        """Raise if the payment is not allowed. Does not record spend."""
+        _ = currency, recipient
+        if amount <= 0:
+            raise PolicyViolationError("payment amount must be positive")
+
+        if amount > self.policy.max_per_tx:
+            raise BudgetExceededError(
+                f"amount {amount} exceeds max_per_tx {self.policy.max_per_tx}"
+            )
+
+        daily = self.ledger.spent_today()
+        if daily + amount > self.policy.daily_limit:
+            raise BudgetExceededError(
+                f"daily spend {daily} + {amount} exceeds daily_limit {self.policy.daily_limit}"
+            )
+
+        monthly = self.ledger.spent_this_month()
+        if monthly + amount > self.policy.monthly_limit:
+            raise BudgetExceededError(
+                f"monthly spend {monthly} + {amount} exceeds monthly_limit {self.policy.monthly_limit}"
+            )
+
+        if not self.policy.domain_allowed(domain):
+            raise PolicyViolationError(f"domain not allowlisted: {domain!r}")
+
+        thr = self.policy.require_human_approval_above
+        if thr is not None and amount > thr:
+            approved = False
+            if self.approval_callback is not None:
+                approved = bool(self.approval_callback(amount, currency, domain))
+            if not approved:
+                raise HumanApprovalRequiredError(
+                    f"amount {amount} requires human approval (threshold {thr})"
+                )
+
+    def authorize_and_record(
+        self,
+        amount: float,
+        *,
+        domain: str | None = None,
+        currency: str = "USDC",
+        recipient: str | None = None,
+    ) -> None:
+        """Policy check then record spend (call only after payment succeeds, or before lock)."""
+        self.check(amount, domain=domain, currency=currency, recipient=recipient)
+        self.ledger.record(amount, domain)
+
+    def remaining_daily(self) -> float:
+        return max(0.0, self.policy.daily_limit - self.ledger.spent_today())
+
+    def remaining_monthly(self) -> float:
+        return max(0.0, self.policy.monthly_limit - self.ledger.spent_this_month())
+
+
+def merge_allowlists(*lists: Iterable[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for lst in lists:
+        for item in lst:
+            key = item.lower()
+            if key not in seen:
+                seen.add(key)
+                out.append(item)
+    return out