traia-iatp 0.1.2__py3-none-any.whl → 0.1.67__py3-none-any.whl

traia_iatp/d402/client.py

@@ -0,0 +1,150 @@
+"""D402 client for IATP agent-to-agent payments."""
+
+import logging
+from typing import Optional, Dict, Any
+from eth_account import Account
+from .clients.base import d402Client
+from .types import PaymentRequirements
+
+logger = logging.getLogger(__name__)
+
+
+class D402IATPClient:
+    """Client for making d402 payments in IATP protocol.
+    
+    This wraps the Coinbase d402 client and provides IATP-specific functionality,
+    including integration with utility agent smart contracts.
+    """
+    
+    def __init__(
+        self,
+        account: Account,
+        max_value: Optional[int] = None,
+        agent_contract_address: Optional[str] = None,
+        operator_private_key: Optional[str] = None
+    ):
+        """Initialize the d402 IATP client.
+        
+        Args:
+            account: eth_account.Account instance for signing payments
+            max_value: Optional maximum allowed payment amount in base units
+            agent_contract_address: Optional address of the client agent's smart contract
+            operator_private_key: Optional operator private key for signing service requests
+        """
+        self.account = account
+        self.max_value = max_value
+        self.agent_contract_address = agent_contract_address
+        self.operator_private_key = operator_private_key
+        
+        # Initialize the underlying d402 client
+        self.d402_client = d402Client(
+            operator_account=account,
+            max_value=max_value
+        )
+    
+    def create_payment_header(
+        self,
+        payment_requirements: PaymentRequirements,
+        d402_version: int = 1
+    ) -> str:
+        """Create a payment header for the given requirements.
+        
+        This creates an EIP-3009 signed payment authorization that the facilitator
+        can use to pull funds from the client agent's wallet.
+        
+        Args:
+            payment_requirements: Selected payment requirements from server
+            d402_version: d402 protocol version
+            
+        Returns:
+            Base64-encoded signed payment header for X-PAYMENT header
+        """
+        return self.d402_client.create_payment_header(
+            payment_requirements=payment_requirements,
+            d402_version=d402_version
+        )
+    
+    def select_payment_requirements(
+        self,
+        accepts: list[PaymentRequirements],
+        network_filter: Optional[str] = None,
+        scheme_filter: Optional[str] = "exact"
+    ) -> PaymentRequirements:
+        """Select payment requirements from available options.
+        
+        Args:
+            accepts: List of accepted payment requirements from server
+            network_filter: Optional network to filter by
+            scheme_filter: Optional scheme to filter by (default: "exact")
+            
+        Returns:
+            Selected payment requirements
+            
+        Raises:
+            UnsupportedSchemeException: If no supported scheme found
+            PaymentAmountExceededError: If amount exceeds max_value
+        """
+        return self.d402_client.select_payment_requirements(
+            accepts=accepts,
+            network_filter=network_filter,
+            scheme_filter=scheme_filter
+        )
+    
+    def get_payment_info_for_agent_card(self, agent_card: dict) -> Optional[Dict[str, Any]]:
+        """Extract d402 payment information from an agent card.
+        
+        Args:
+            agent_card: Agent card dictionary
+            
+        Returns:
+            Payment information if available, None otherwise
+        """
+        metadata = agent_card.get("metadata", {})
+        return metadata.get("d402")
+
+
+def create_iatp_payment_client(
+    private_key: str,
+    max_value_usd: Optional[float] = None,
+    agent_contract_address: Optional[str] = None
+) -> D402IATPClient:
+    """Convenience function to create an IATP payment client.
+    
+    Args:
+        private_key: Hex-encoded private key (with or without 0x prefix)
+        max_value_usd: Optional maximum payment in USD
+        agent_contract_address: Optional agent contract address
+        
+    Returns:
+        Configured D402IATPClient
+        
+    Example:
+        client = create_iatp_payment_client(
+            private_key="0x...",
+            max_value_usd=10.0  # Max $10 per request
+        )
+        
+        # Use with httpx
+        from .clients.httpx import Httpd402Client
+        http_client = Httpd402Client(client)
+        response = await http_client.get("https://agent.example.com/api")
+    """
+    # Remove 0x prefix if present
+    if private_key.startswith("0x"):
+        private_key = private_key[2:]
+    
+    # Create eth_account.Account
+    account = Account.from_key(private_key)
+    
+    # Convert USD to atomic units (assuming USDC with 6 decimals)
+    max_value = None
+    if max_value_usd is not None:
+        max_value = int(max_value_usd * 1_000_000)  # USDC has 6 decimals
+    
+    return D402IATPClient(
+        account=account,
+        max_value=max_value,
+        agent_contract_address=agent_contract_address,
+        operator_private_key=private_key
+    )
+

traia_iatp/d402/clients/__init__.py

@@ -0,0 +1,7 @@
+"""D402 client implementations."""
+
+from .base import d402Client, decode_x_payment_response
+from .httpx import d402_payment_hooks, d402HttpxClient
+
+__all__ = ["d402Client", "decode_x_payment_response", "d402_payment_hooks", "d402HttpxClient"]
+

traia_iatp/d402/clients/base.py

@@ -0,0 +1,218 @@
+import time
+from typing import Optional, Callable, Dict, Any, List
+from eth_account import Account
+from ..payment_signing import sign_payment_header
+from ..types import (
+    PaymentRequirements,
+    UnsupportedSchemeException,
+)
+from ..common import d402_VERSION
+import secrets
+from ..encoding import safe_base64_decode
+import json
+
+# Define type for the payment requirements selector
+PaymentSelectorCallable = Callable[
+    [List[PaymentRequirements], Optional[str], Optional[str], Optional[int]],
+    PaymentRequirements,
+]
+
+
+def decode_x_payment_response(header: str) -> Dict[str, Any]:
+    """Decode the X-PAYMENT-RESPONSE header.
+
+    Args:
+        header: The X-PAYMENT-RESPONSE header to decode
+
+    Returns:
+        The decoded payment response containing:
+        - success: bool
+        - transaction: str (hex)
+        - network: str
+        - payer: str (address)
+    """
+    decoded = safe_base64_decode(header)
+    result = json.loads(decoded)
+    return result
+
+
+class PaymentError(Exception):
+    """Base class for payment-related errors."""
+
+    pass
+
+
+class PaymentAmountExceededError(PaymentError):
+    """Raised when payment amount exceeds maximum allowed value."""
+
+    pass
+
+
+class MissingRequestConfigError(PaymentError):
+    """Raised when request configuration is missing."""
+
+    pass
+
+
+class PaymentAlreadyAttemptedError(PaymentError):
+    """Raised when payment has already been attempted."""
+
+    pass
+
+
+class d402Client:
+    """Base client for handling d402 payments."""
+
+    def __init__(
+        self,
+        operator_account: Account,
+        wallet_address: str = None,
+        max_value: Optional[int] = None,
+        payment_requirements_selector: Optional[PaymentSelectorCallable] = None,
+    ):
+        """Initialize the d402 client.
+
+        Args:
+            operator_account: Operator account with private key for signing payments (EOA)
+            wallet_address: Consumer's IATPWallet contract address (if None, uses operator_account.address for testing)
+            max_value: Optional safety limit for maximum payment amount per request in base units.
+                      This is a global safety check that prevents paying more than intended.
+                      WARNING: This is a simple numeric comparison and does NOT account for:
+                      - Different tokens (USDC vs TRAIA vs others) - amounts are compared directly
+                      - Token decimals - ensure max_value uses the same decimals as expected tokens
+                      - Exchange rates - this is not a USD limit, it's a token amount limit
+                      Each endpoint can have different payment requirements (amount and token),
+                      but this limit applies to all requests. Set it based on your most expensive
+                      expected payment in the token's base units.
+                      If None, no limit is enforced (not recommended for production).
+            payment_requirements_selector: Optional custom selector for payment requirements
+        """
+        self.operator_account = operator_account  # Operator EOA for signing
+        self.wallet_address = wallet_address or operator_account.address  # IATPWallet contract or EOA for testing
+        self.max_value = max_value
+        self._payment_requirements_selector = (
+            payment_requirements_selector or self.default_payment_requirements_selector
+        )
+
+    @staticmethod
+    def default_payment_requirements_selector(
+        accepts: List[PaymentRequirements],
+        network_filter: Optional[str] = None,
+        scheme_filter: Optional[str] = None,
+        max_value: Optional[int] = None,
+    ) -> PaymentRequirements:
+        """Select payment requirements from the list of accepted requirements.
+
+        Args:
+            accepts: List of accepted payment requirements
+            network_filter: Optional network to filter by
+            scheme_filter: Optional scheme to filter by
+            max_value: Optional maximum allowed payment amount
+
+        Returns:
+            Selected payment requirements (PaymentRequirements instance from ..types)
+
+        Raises:
+            UnsupportedSchemeException: If no supported scheme is found
+            PaymentAmountExceededError: If payment amount exceeds max_value
+        """
+        for paymentRequirements in accepts:
+            scheme = paymentRequirements.scheme
+            network = paymentRequirements.network
+
+            # Check scheme filter
+            if scheme_filter and scheme != scheme_filter:
+                continue
+
+            # Check network filter
+            if network_filter and network != network_filter:
+                continue
+
+            if scheme == "exact":
+                # Check max value if set
+                # NOTE: This is a simple numeric comparison. It does NOT account for:
+                # - Different tokens (USDC vs TRAIA vs others)
+                # - Token decimals differences
+                # - Exchange rates between tokens
+                # This is a safety limit to prevent accidentally paying too much.
+                # The comparison is done on the raw amount values in base units.
+                if max_value is not None:
+                    max_amount = int(paymentRequirements.max_amount_required)
+                    if max_amount > max_value:
+                        raise PaymentAmountExceededError(
+                            f"Payment amount {max_amount} (token: {paymentRequirements.asset}) "
+                            f"exceeds maximum allowed value {max_value} base units. "
+                            f"Note: This comparison does not account for token differences or decimals."
+                        )
+
+                return paymentRequirements
+
+        raise UnsupportedSchemeException("No supported payment scheme found")
+
+    def select_payment_requirements(
+        self,
+        accepts: List[PaymentRequirements],
+        network_filter: Optional[str] = None,
+        scheme_filter: Optional[str] = None,
+    ) -> PaymentRequirements:
+        """Select payment requirements using the configured selector.
+
+        Args:
+            accepts: List of accepted payment requirements (PaymentRequirements models)
+            network_filter: Optional network to filter by
+            scheme_filter: Optional scheme to filter by
+
+        Returns:
+            Selected payment requirements (PaymentRequirements instance from ..types)
+
+        Raises:
+            UnsupportedSchemeException: If no supported scheme is found
+            PaymentAmountExceededError: If payment amount exceeds max_value
+        """
+        return self._payment_requirements_selector(
+            accepts, network_filter, scheme_filter, self.max_value
+        )
+
+   
+    def create_payment_header(
+        self,
+        payment_requirements: PaymentRequirements,
+        d402_version: int = d402_VERSION,
+        request_path: str = None,
+    ) -> str:
+        """Create a payment header for the given requirements.
+
+        Args:
+            payment_requirements: Selected payment requirements
+            d402_version: d402 protocol version
+            request_path: Optional API request path (if None, uses payment_requirements.resource)
+
+        Returns:
+            Signed payment header with PullFundsForSettlement signature
+        """
+        unsigned_header = {
+            "d402Version": d402_version,
+            "scheme": payment_requirements.scheme,
+            "network": payment_requirements.network,
+            "payload": {
+                "signature": None,
+                "authorization": {
+                    "from": self.wallet_address,  # IATPWallet contract address
+                    "to": payment_requirements.pay_to,  # Provider's IATPWallet
+                    "value": payment_requirements.max_amount_required,
+                    "validAfter": str(int(time.time()) - 60),  # 60 seconds before
+                    "validBefore": str(
+                        int(time.time()) + payment_requirements.max_timeout_seconds
+                    ),
+                },
+            },
+        }
+
+        signed_header = sign_payment_header(
+            self.operator_account,
+            payment_requirements,
+            unsigned_header,
+            wallet_address=self.wallet_address,
+            request_path=request_path or payment_requirements.resource
+        )
+        return signed_header

traia_iatp/d402/clients/httpx.py

@@ -0,0 +1,266 @@
+"""HTTPX client integration for d402 payments."""
+
+import logging
+from typing import Optional, Dict, List
+from httpx import Request, Response, AsyncClient
+from eth_account import Account
+from functools import wraps
+
+from .base import (
+    d402Client,
+    MissingRequestConfigError,
+    PaymentError,
+    PaymentSelectorCallable,
+    decode_x_payment_response,
+)
+from ..types import d402PaymentRequiredResponse
+
+logger = logging.getLogger(__name__)
+
+
+class HttpxHooks:
+    """Event hooks for httpx client to handle d402 payments."""
+
+    def __init__(self, client: d402Client, httpx_client: AsyncClient = None):
+        self.client = client
+        self.httpx_client = httpx_client  # Reference to the httpx client for retries
+        self._is_retry = False
+
+    async def on_request(self, request: Request):
+        """Handle request before it is sent."""
+        #TODO: (TBD) if mongodb had endpoints data for each mcp server then the client herre could apriori get the payment details and construct the payment payload.
+        pass
+
+    async def on_response(self, response: Response) -> Response:
+        """Handle response after it is received.
+
+        When a 402 Payment Required response is received:
+        1. Parse payment requirements from the response
+        2. Select appropriate payment option (token/network)
+        3. Create EIP-3009 signed payment authorization
+        4. Retry the original request with X-Payment header
+        """
+
+        # Log every response for debugging
+        logger.debug(f"d402 hook: on_response called - status={response.status_code}, url={response.url}")
+
+        # If this is not a 402, just return the response
+        if response.status_code != 402:
+            return response
+
+        # If this is a retry response, just return it (avoid infinite loop)
+        if self._is_retry:
+            logger.debug(f"d402 hook: This is a retry response, returning as-is")
+            return response
+        
+        logger.info(f"🔔 d402 hook: Intercepted HTTP 402 - creating payment...")
+
+        try:
+            if not response.request:
+                raise MissingRequestConfigError("Missing request configuration")
+
+            # Read the response content before parsing
+            await response.aread()
+
+            # Parse payment requirements from 402 response
+            data = response.json()
+            payment_response = d402PaymentRequiredResponse(**data)
+
+            # Select payment requirements (matches token/network, checks max_value)
+            selected_requirements = self.client.select_payment_requirements(
+                payment_response.accepts
+            )
+
+            # The server sets the resource field in payment_requirements
+            # This is the authoritative requestPath for the signature
+            # The server knows what endpoint is being called and sets it correctly
+            print(f"📍 DEBUG: Request path from server resource field: '{selected_requirements.resource}'")
+            logger.info(f"💳 Creating payment header for retry...")
+
+            # Create signed payment header using CLIENT's account
+            # Use payment_requirements.resource (don't override)
+            payment_header = self.client.create_payment_header(
+                selected_requirements, 
+                payment_response.d402_version
+                # No request_path parameter - uses payment_requirements.resource
+            )
+
+            # Mark as retry to avoid infinite loop
+            self._is_retry = True
+            logger.info(f"💳 Payment header created, preparing retry...")
+            
+            # Get the original request and add payment header
+            request = response.request
+            request.headers["X-Payment"] = payment_header
+            request.headers["Access-Control-Expose-Headers"] = "X-Payment-Response"
+            logger.info(f"💳 Added X-Payment header to request")
+
+            # Retry the request using the httpx client
+            # Priority:
+            # 1. self.httpx_client (if set by d402HttpxClient)
+            # 2. response.request.extensions.get("client") (if available)
+            # 3. Fallback: create new client (may lose hooks)
+            
+            retry_client = None
+            if self.httpx_client:
+                logger.info(f"💳 Using self.httpx_client for retry (d402HttpxClient)")
+                print(f"💳 Using d402HttpxClient instance for retry")
+                retry_client = self.httpx_client
+            else:
+                original_client = response.request.extensions.get("client")
+                logger.info(f"💳 original_client from extensions: {original_client is not None}")
+                
+                if original_client and isinstance(original_client, AsyncClient):
+                    logger.info(f"💳 Using original client from extensions...")
+                    retry_client = original_client
+            
+            if retry_client:
+                logger.info(f"💳 Retrying with client that has hooks...")
+                retry_response = await retry_client.send(request)
+            else:
+                # No client with hooks available - can't retry safely
+                # Just return the 402 response as-is
+                logger.error(f"❌ No client available for retry, cannot handle payment")
+                print(f"❌ Cannot retry payment - no httpx client with hooks available")
+                self._is_retry = False
+                return response
+
+            logger.info(f"💳 Retry response received: HTTP {retry_response.status_code}")
+            print(f"💳 RETRY RESPONSE: HTTP {retry_response.status_code}")
+
+            # Copy the retry response data to the original response object
+            response.status_code = retry_response.status_code
+            response.headers = retry_response.headers
+            response._content = retry_response._content
+            
+            logger.info(f"✅ Payment handling complete, returning response")
+            print(f"✅ Payment retry complete, returning HTTP {response.status_code}")
+            return response
+
+        except PaymentError as e:
+            self._is_retry = False
+            print(f"❌ PaymentError in hook: {e}")
+            raise e
+        except Exception as e:
+            self._is_retry = False
+            print(f"❌ Exception in payment hook: {e}")
+            import traceback
+            traceback.print_exc()
+            raise PaymentError(f"Failed to handle payment: {str(e)}") from e
+
+
+def d402_payment_hooks(
+    operator_account: Account,
+    wallet_address: str = None,
+    max_value: Optional[int] = None,
+    payment_requirements_selector: Optional[PaymentSelectorCallable] = None,
+    httpx_client: AsyncClient = None,
+) -> Dict[str, List]:
+    """Create httpx event hooks dictionary for handling 402 Payment Required responses.
+
+    Args:
+        operator_account: Operator account with private key for signing payments (EOA)
+        wallet_address: Consumer's IATPWallet contract address (if None, uses operator_account.address for testing)
+        max_value: Optional maximum allowed payment amount in base units
+        payment_requirements_selector: Optional custom selector for payment requirements.
+            Should be a callable that takes (accepts, network_filter, scheme_filter, max_value)
+            and returns a PaymentRequirements object.
+
+    Returns:
+        Dictionary of event hooks that can be directly assigned to client.event_hooks
+
+    Example:
+        ```python
+        from eth_account import Account
+        from traia_iatp.d402.clients.httpx import d402_payment_hooks
+        import httpx
+
+        # For testing (uses EOA as wallet)
+        operator_account = Account.from_key("0x...")
+        client.event_hooks = d402_payment_hooks(operator_account)
+        
+        # For production (with IATPWallet contract)
+        operator_account = Account.from_key("0x...")  # Operator key
+        wallet = "0x..."  # IATPWallet contract address
+        client.event_hooks = d402_payment_hooks(operator_account, wallet_address=wallet)
+        ```
+    """
+    # Create d402Client
+    client = d402Client(
+        operator_account,
+        wallet_address=wallet_address,
+        max_value=max_value,
+        payment_requirements_selector=payment_requirements_selector,
+    )
+
+    # Create hooks with optional httpx_client reference
+    hooks = HttpxHooks(client, httpx_client=httpx_client)
+
+    # Return event hooks dictionary
+    return {
+        "request": [hooks.on_request],
+        "response": [hooks.on_response],
+    }
+
+
+class d402HttpxClient(AsyncClient):
+    """AsyncClient with built-in d402 payment handling."""
+
+    def __init__(
+        self,
+        operator_account: Account,
+        wallet_address: str = None,
+        max_value: Optional[int] = None,
+        payment_requirements_selector: Optional[PaymentSelectorCallable] = None,
+        **kwargs,
+    ):
+        """Initialize an AsyncClient with d402 payment handling.
+
+        Args:
+            operator_account: Operator account with private key for signing payments (EOA)
+            wallet_address: Consumer's IATPWallet contract address (if None, uses operator_account.address for testing)
+            max_value: Optional maximum allowed payment amount in base units
+            payment_requirements_selector: Optional custom selector for payment requirements.
+                Should be a callable that takes (accepts, network_filter, scheme_filter, max_value)
+                and returns a PaymentRequirements object.
+            **kwargs: Additional arguments to pass to AsyncClient
+
+        Example:
+            ```python
+            from eth_account import Account
+            from traia_iatp.d402.clients.httpx import d402HttpxClient
+
+            # For testing (uses EOA as wallet)
+            operator_account = Account.from_key("0x...")
+            async with d402HttpxClient(operator_account, base_url="https://api.example.com") as client:
+                response = await client.get("/protected-endpoint")
+                
+            # For production (with IATPWallet contract)
+            operator_account = Account.from_key("0x...")  # Operator key
+            wallet = "0x..."  # IATPWallet contract
+            async with d402HttpxClient(operator_account, wallet_address=wallet, base_url="https://api.example.com") as client:
+                response = await client.get("/protected-endpoint")
+            ```
+        """
+        super().__init__(**kwargs)
+        
+        # Create d402Client
+        payment_client = d402Client(
+            operator_account,
+            wallet_address=wallet_address,
+            max_value=max_value,
+            payment_requirements_selector=payment_requirements_selector,
+        )
+        
+        # Create hooks with reference to this httpx client
+        hooks = HttpxHooks(payment_client, httpx_client=self)
+        
+        # Set event hooks
+        self.event_hooks = {
+            "request": [hooks.on_request],
+            "response": [hooks.on_response],
+        }
+
+
+__all__ = ["d402_payment_hooks", "d402HttpxClient", "HttpxHooks"]
+