paynode-sdk-python 2.2.0__tar.gz → 2.5.0__tar.gz

{paynode_sdk_python-2.2.0/paynode_sdk_python.egg-info → paynode_sdk_python-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paynode-sdk-python
-Version: 2.2.0
+Version: 2.5.0
 Summary: PayNode Protocol Python SDK for AI Agents
 Author-email: PayNodeLabs <contact@paynode.dev>
 License: MIT
@@ -25,7 +25,7 @@ Dynamic: license-file
 [![Official Documentation](https://img.shields.io/badge/Docs-docs.paynode.dev-00ff88?style=for-the-badge&logo=readthedocs)](https://docs.paynode.dev)
 [![PyPI Version](https://img.shields.io/pypi/v/paynode-sdk-python.svg?style=for-the-badge)](https://pypi.org/project/paynode-sdk-python/)
 
-The official Python SDK for the **PayNode Protocol (v2.2.0)**. PayNode allows autonomous AI Agents to seamlessly pay for APIs and computational resources using USDC on Base L2, utilizing the standardized HTTP 402 protocol with support for both on-chain receipts and off-chain signatures (EIP-3009).
+The official Python SDK for the **PayNode Protocol (v2.2.1)**. PayNode allows autonomous AI Agents to seamlessly pay for APIs and computational resources using USDC on Base L2, utilizing the standardized HTTP 402 protocol with support for both on-chain receipts and off-chain signatures (EIP-3009).
 
 ## 📖 Read the Docs
 
@@ -56,7 +56,7 @@ response = agent.request_gate("https://api.merchant.com/premium-data", method="P
 print(response.json())
 ```
 
-### Key Features (v2.2.0)
+### Key Features (v2.2.1)
 - **EIP-3009 Support**: Sign payments off-chain using `TransferWithAuthorization`, allowing for gasless or relayer-mediated settlement.
 - **X402 V2 Protocol**: JSON-based handshake for more structured and machine-readable payment instructions.
 - **Dual Flow**: Automatic fallback to V1 (on-chain receipts) for legacy merchant support.

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0}/README.md

@@ -3,7 +3,7 @@
 [![Official Documentation](https://img.shields.io/badge/Docs-docs.paynode.dev-00ff88?style=for-the-badge&logo=readthedocs)](https://docs.paynode.dev)
 [![PyPI Version](https://img.shields.io/pypi/v/paynode-sdk-python.svg?style=for-the-badge)](https://pypi.org/project/paynode-sdk-python/)
 
-The official Python SDK for the **PayNode Protocol (v2.2.0)**. PayNode allows autonomous AI Agents to seamlessly pay for APIs and computational resources using USDC on Base L2, utilizing the standardized HTTP 402 protocol with support for both on-chain receipts and off-chain signatures (EIP-3009).
+The official Python SDK for the **PayNode Protocol (v2.2.1)**. PayNode allows autonomous AI Agents to seamlessly pay for APIs and computational resources using USDC on Base L2, utilizing the standardized HTTP 402 protocol with support for both on-chain receipts and off-chain signatures (EIP-3009).
 
 ## 📖 Read the Docs
 
@@ -34,7 +34,7 @@ response = agent.request_gate("https://api.merchant.com/premium-data", method="P
 print(response.json())
 ```
 
-### Key Features (v2.2.0)
+### Key Features (v2.2.1)
 - **EIP-3009 Support**: Sign payments off-chain using `TransferWithAuthorization`, allowing for gasless or relayer-mediated settlement.
 - **X402 V2 Protocol**: JSON-based handshake for more structured and machine-readable payment instructions.
 - **Dual Flow**: Automatic fallback to V1 (on-chain receipts) for legacy merchant support.

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0}/paynode_sdk/__init__.py

@@ -5,27 +5,33 @@ import logging
 # to ensure a clean experience for PayNode SDK users.
 warnings.filterwarnings("ignore", category=DeprecationWarning, module="websockets.legacy")
 
-from .middleware import PayNodeMiddleware, x402_gate
+from .middleware import PayNodeMiddleware, x402_gate, PayNodeMerchantMiddleware
+from .merchant import PayNodeMerchant
 from .verifier import PayNodeVerifier
 from .errors import ErrorCode, PayNodeException
 from .idempotency import IdempotencyStore, MemoryIdempotencyStore, RedisIdempotencyStore
 from .webhook import PayNodeWebhookNotifier, PaymentEvent
 from .client import PayNodeAgentClient
+from .utils.payload import PayNodePayloadHelper
 from .constants import (
     PAYNODE_ROUTER_ADDRESS,
     PAYNODE_ROUTER_ADDRESS_SANDBOX,
     BASE_USDC_ADDRESS,
     BASE_USDC_ADDRESS_SANDBOX,
     ACCEPTED_TOKENS,
-    MIN_PAYMENT_AMOUNT
+    MIN_PAYMENT_AMOUNT,
+    PROTOCOL_VERSION,
+    SDK_VERSION
 )
 
 __all__ = [
-    "PayNodeMiddleware", "x402_gate", "PayNodeVerifier", "ErrorCode", "PayNodeException",
+    "PayNodeMiddleware", "x402_gate", "PayNodeMerchantMiddleware",
+    "PayNodeMerchant", "PayNodeVerifier", "ErrorCode", "PayNodeException",
     "IdempotencyStore", "MemoryIdempotencyStore", "RedisIdempotencyStore",
     "PayNodeWebhookNotifier", "PaymentEvent",
     "PayNodeAgentClient",
     "PAYNODE_ROUTER_ADDRESS", "PAYNODE_ROUTER_ADDRESS_SANDBOX",
     "BASE_USDC_ADDRESS", "BASE_USDC_ADDRESS_SANDBOX",
-    "ACCEPTED_TOKENS", "MIN_PAYMENT_AMOUNT"
+    "ACCEPTED_TOKENS", "MIN_PAYMENT_AMOUNT", "PROTOCOL_VERSION", "SDK_VERSION",
+    "PayNodePayloadHelper"
 ]

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0}/paynode_sdk/client.py

@@ -10,14 +10,14 @@ from eth_account.messages import encode_typed_data
 from web3 import Web3
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
-from .constants import PAYNODE_ROUTER_ADDRESS, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, BASE_RPC_URLS, ACCEPTED_TOKENS, MIN_PAYMENT_AMOUNT, PAYNODE_ROUTER_ABI
+from .constants import PAYNODE_ROUTER_ADDRESS, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, BASE_RPC_URLS, ACCEPTED_TOKENS, MIN_PAYMENT_AMOUNT, PAYNODE_ROUTER_ABI, SDK_VERSION
 from .errors import PayNodeException, ErrorCode
 
 logger = logging.getLogger("paynode_sdk.client")
 
 class PayNodeAgentClient:
     """
-    The main PayNode Client for AI Agents (v2.2.0).
+    The main PayNode Client for AI Agents (v2.5.0).
     Automatically handles the x402 'Payment Required' handshake.
     Supports RPC redundancy, EIP-2612 Permit, and EIP-3009 Authorization.
     """
@@ -84,6 +84,12 @@ class PayNodeAgentClient:
 
     def request_gate(self, url: str, method: str = "GET", **kwargs):
         """The high-level autonomous method handling 402 loop."""
+        # Inject X-PayNode-Network header (mirrors JS SDK behavior)
+        chain_id = self.w3.eth.chain_id
+        paynode_network = 'mainnet' if chain_id == 8453 else 'testnet'
+        headers = kwargs.get('headers', {}).copy()
+        headers.setdefault('X-PayNode-Network', paynode_network)
+        kwargs['headers'] = headers
         return self._request_with_402_retry(method.upper(), url, **kwargs)
 
     def get(self, url, **kwargs):
@@ -111,12 +117,19 @@ class PayNodeAgentClient:
                     except Exception as e:
                         logger.debug(f"⚠️ [PayNode-PY] Failed to parse 402 JSON body: {e}")
                 
-                if not body and b64_required:
+                header_body = None
+                if b64_required:
                     try:
-                        body = json.loads(base64.b64decode(b64_required).decode())
+                        header_body = json.loads(base64.b64decode(b64_required).decode())
                     except Exception as e:
                         logger.warning(f"❌ [PayNode-PY] Failed to decode PAYMENT-REQUIRED header: {e}")
 
+                if not body and header_body:
+                    body = header_body
+                elif body and header_body and not body.get('x402Version'):
+                    # Robustness: Merge header info into body if body is missing critical bits
+                    body.update({k: v for k, v in header_body.items() if k not in body})
+
                 if body and body.get('x402Version') == 2:
                     logger.info("🚀 [PayNode-PY] x402 v2 detected. Handling autonomous payment...")
                     if order_id and not body.get('orderId'): body['orderId'] = order_id
@@ -152,6 +165,7 @@ class PayNodeAgentClient:
             raise PayNodeException(ErrorCode.token_not_accepted, message=f"Token {requirement['asset']} is not in the whitelist for chain {chain_id}")
 
         logger.info(f"💡 [PayNode-PY] Payment request (v2): {requirement['amount']} atomic units of {requirement['asset']} to {requirement['payTo']}")
+        logger.info(f"💡 [PayNode-PY] Selected payment method: {requirement.get('type', 'onchain')} on {requirement.get('network')}")
         
         # Dust limit check
         if int(requirement['amount']) < MIN_PAYMENT_AMOUNT:
@@ -208,6 +222,7 @@ class PayNodeAgentClient:
             "resource": requirements.get('resource'),
             "accepted": {
                 "scheme": requirement.get('scheme'),
+                "type": ptype,
                 "network": requirement.get('network'),
                 "amount": requirement.get('amount'),
                 "asset": requirement.get('asset'),
@@ -217,7 +232,7 @@ class PayNodeAgentClient:
             },
             "payload": payload_data,
             "_paynode": {
-                "version": "2.2.0",
+                "sdkVersion": SDK_VERSION,
                 "type": ptype,
                 "orderId": order_id
             }
@@ -231,12 +246,16 @@ class PayNodeAgentClient:
         
         b64_payload = base64.b64encode(json.dumps(payment_payload).encode()).decode()
 
+        chain_id = self.w3.eth.chain_id
+        paynode_network = 'mainnet' if chain_id == 8453 else 'testnet'
+
         retry_headers = kwargs.get('headers', {}).copy()
         retry_headers.update({
             'Content-Type': 'application/json',
             'PAYMENT-SIGNATURE': b64_payload,
             'X-402-Payload': b64_payload, # Backward compatibility
-            'X-402-Order-Id': order_id
+            'X-402-Order-Id': order_id,
+            'X-PayNode-Network': paynode_network
         })
         kwargs['headers'] = retry_headers
         return kwargs
@@ -248,7 +267,12 @@ class PayNodeAgentClient:
         settle_header = response.headers.get('PAYMENT-RESPONSE') or response.headers.get('X-PAYMENT-RESPONSE')
         if settle_header:
             try:
-                settle_data = json.loads(base64.b64decode(settle_header).decode())
+                settle_header_str = settle_header.strip()
+                if settle_header_str.startswith('{'):
+                    decoded = settle_header_str
+                else:
+                    decoded = base64.b64decode(settle_header).decode()
+                settle_data = json.loads(decoded)
                 if settle_data.get('success'):
                     logger.info(f"✅ [PayNode-PY] Settlement confirmed: {settle_data.get('transaction')}")
                 else:
@@ -370,7 +394,7 @@ class PayNodeAgentClient:
         sig = self.sign_permit(token_addr, router_addr, amount, version=version)
         router = self.w3.eth.contract(address=Web3.to_checksum_address(router_addr), abi=PAYNODE_ROUTER_ABI)
         order_id_bytes = self.w3.keccak(text=order_id)
-        current_gas_price = int(self.w3.eth.gas_price * 1.2)
+        current_gas_price = self.w3.eth.gas_price * 120 // 100
         with self.nonce_lock:
             nonce = self.w3.eth.get_transaction_count(self.account.address, 'pending')
             tx = router.functions.payWithPermit(self.account.address, Web3.to_checksum_address(token_addr), Web3.to_checksum_address(merchant_addr), amount, order_id_bytes, sig["deadline"], sig["v"], sig["r"], sig["s"]).build_transaction({'from': self.account.address, 'nonce': nonce, 'gas': 300000, 'gasPrice': current_gas_price})
@@ -385,7 +409,7 @@ class PayNodeAgentClient:
     def __pay_raw(self, router_addr, token_addr, merchant_addr, amount, order_id):
         router = self.w3.eth.contract(address=Web3.to_checksum_address(router_addr), abi=PAYNODE_ROUTER_ABI)
         order_id_bytes = self.w3.keccak(text=order_id)
-        current_gas_price = int(self.w3.eth.gas_price * 1.2)
+        current_gas_price = self.w3.eth.gas_price * 120 // 100
         with self.nonce_lock:
             nonce = self.w3.eth.get_transaction_count(self.account.address, 'pending')
             tx = router.functions.pay(Web3.to_checksum_address(token_addr), Web3.to_checksum_address(merchant_addr), amount, order_id_bytes).build_transaction({'from': self.account.address, 'nonce': nonce, 'gas': 200000, 'gasPrice': current_gas_price})

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0}/paynode_sdk/constants.py

@@ -1,10 +1,12 @@
-# Generated by scripts/sync-config.py
+# Generated by meta/scripts/sync-config.py
 PAYNODE_ROUTER_ADDRESS = "0x4A73696ccF76E7381b044cB95127B3784369Ed63"
 PAYNODE_ROUTER_ADDRESS_SANDBOX = "0x24cD8b68aaC209217ff5a6ef1Bf55a59f2c8Ca6F"
 BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 BASE_USDC_ADDRESS_SANDBOX = "0x65c088EfBDB0E03185Dbe8e258Ad0cf4Ab7946b0"
 BASE_USDC_DECIMALS = 6
 
+PROTOCOL_VERSION = 2
+SDK_VERSION = "2.5.0"
 PROTOCOL_TREASURY = "0x598bF63F5449876efafa7b36b77Deb2070621C0E"
 PROTOCOL_FEE_BPS = 100
 MIN_PAYMENT_AMOUNT = 1000

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0}/paynode_sdk/errors.py

@@ -1,4 +1,4 @@
-# Generated by scripts/sync-config.py
+# Generated by meta/scripts/sync-config.py
 from enum import Enum
 from typing import Any, Optional
 

paynode_sdk_python-2.5.0/paynode_sdk/merchant.py

@@ -0,0 +1,137 @@
+import logging
+import requests
+import time
+from typing import Optional, Dict, Any, Union
+from .utils.signature import verify_market_signature
+from .middleware import PayNodeMiddleware
+from .constants import PROTOCOL_VERSION
+
+logger = logging.getLogger("paynode_sdk.merchant")
+
+class PayNodeMerchant:
+    """
+    PayNodeMerchant: The high-level SDK class for Merchant Integration.
+    Mirrors JS PayNodeMerchant v2.5.0 baseline.
+    """
+    def __init__(
+        self,
+        shared_secret: str,
+        market_url: str = "https://mk.paynode.dev",
+        quiet: bool = False
+    ):
+        self.shared_secret = shared_secret
+        self.market_url = market_url
+        self.quiet = quiet
+
+    def sync(self, manifest: Dict[str, Any]) -> bool:
+        """
+        Registers or syncs the API manifest with the PayNode Market.
+        This ensures the market shows the correct price and input schema.
+        """
+        if not self.quiet:
+            logger.info(f"[PayNode-SDK] Syncing API manifest for {manifest.get('slug')} to {self.market_url}")
+
+        try:
+            payload = {**manifest, "gateway_url": manifest.get("slug")}
+            response = requests.post(
+                f"{self.market_url}/api/v1/merchant/apis",
+                json=payload,
+                timeout=10
+            )
+            
+            result = response.json()
+            if response.status_code == 200 and result.get("success"):
+                if not self.quiet:
+                    logger.info(f"[PayNode-SDK] Successfully synced {manifest.get('slug')}. ID: {result.get('api_id')}")
+                return True
+            else:
+                error_msg = result.get("error") or response.reason
+                if not self.quiet:
+                    logger.warning(f"[PayNode-SDK] Sync failed for {manifest.get('slug')}: {error_msg}")
+                return False
+        except Exception as e:
+            if not self.quiet:
+                logger.error(f"[PayNode-SDK] Network error during sync for {manifest.get('slug')}: {e}")
+            return False
+
+    async def verify(self, request: Any) -> Dict[str, Any]:
+        """
+        Manual verification for FastAPI or other environments.
+        Extracts headers and verifies signature. Returns the unwrapped body and context.
+        """
+        # Adapt for FastAPI/Starlette request or dict-like object
+        if hasattr(request, "headers"):
+            headers = request.headers
+        else:
+            headers = getattr(request, "headers", {})
+
+        signature = headers.get("X-PayNode-Signature")
+        timestamp = headers.get("X-PayNode-Timestamp")
+        # Try fallbacks matching JS logic
+        request_id = (
+            headers.get("X-PayNode-Request-Id") or 
+            headers.get("X-402-Order-Id") or 
+            headers.get("PAYMENT-SIGNATURE")
+        )
+
+        is_valid = verify_market_signature(
+            signature=signature,
+            order_id=request_id,
+            timestamp=timestamp,
+            shared_secret=self.shared_secret
+        )
+
+        if not is_valid:
+            return {"isValid": False, "error": "Invalid PayNode Market Signature"}
+
+        # Handle Body Unwrap
+        body = {}
+        try:
+            if hasattr(request, "json") and callable(request.json):
+                body = await request.json()
+            else:
+                body = getattr(request, "body", {})
+                if isinstance(body, bytes):
+                    import json
+                    body = json.loads(body)
+        except Exception:
+            pass
+
+        paynode_context = {"orderId": request_id}
+
+        if isinstance(body, dict) and body.get("payload") and isinstance(body.get("payload"), dict):
+            # Enrich context with proxy details
+            paynode_context.update({
+                "txHash": headers.get("X-PayNode-Transaction-Hash") or body.get("tx_hash"),
+                "amount": headers.get("X-PayNode-Amount") or body.get("amount"),
+                "network": headers.get("X-PayNode-Network") or body.get("network"),
+                "chainId": headers.get("X-PayNode-Chain-Id") or (str(body.get("chain_id")) if body.get("chain_id") else None),
+            })
+            # Transparently Unwrap Body
+            body = body.get("payload")
+
+        return {
+            "isValid": True,
+            "body": body,
+            "paynodeContext": paynode_context
+        }
+
+    def middleware(self, merchant_address: str, price: str, manifest: Optional[Dict[str, Any]] = None, **kwargs):
+        """
+        Creates a unified middleware that handles:
+        1. Market Proxy (Strict Signature Check + Body Unwrap)
+        2. Auto-Discovery (Market Sync Probe)
+        
+        Usage for FastAPI:
+        merchant = PayNodeMerchant(shared_secret="...")
+        app.add_middleware(merchant.middleware, merchant_address="0x...", price="0.01")
+        """
+        from .middleware import PayNodeMerchantMiddleware
+        return lambda app: PayNodeMerchantMiddleware(
+            app=app,
+            merchant=self,
+            merchant_address=merchant_address,
+            price=price,
+            manifest=manifest,
+            **kwargs
+        )

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0}/paynode_sdk/middleware.py

@@ -12,8 +12,13 @@ from .constants import (
     BASE_RPC_URLS, 
     PAYNODE_ROUTER_ADDRESS, 
     BASE_USDC_ADDRESS, 
-    BASE_USDC_DECIMALS
+    BASE_USDC_DECIMALS,
+    PROTOCOL_VERSION,
+    SDK_VERSION
 )
+from datetime import datetime, timezone
+from typing import Optional, Callable, Any, Dict
+from .utils.payload import PayNodePayloadHelper
 
 from starlette.middleware.base import BaseHTTPMiddleware
 
@@ -69,39 +74,8 @@ class PayNodeMiddleware(BaseHTTPMiddleware):
         unified_payload = None
         if v2_payload_header:
             try:
-                parsed = json.loads(base64.b64decode(v2_payload_header.encode()).decode())
-                
-                if parsed.get('x402Version') == 2 and parsed.get('accepted'):
-                    # Official X402 V2 format - convert to internal format
-                    internal_order_id = parsed.get('_paynode', {}).get('orderId') \
-                                     or order_id \
-                                     or f"auto_{int(time.time() * 1000)}"
-                    
-                    # Infer type from payload content if missing
-                    payload_content = parsed.get('payload', {})
-                    inferred_type = 'onchain'
-                    if payload_content.get('signature') or payload_content.get('authorization'):
-                        inferred_type = 'eip3009'
-                    elif payload_content.get('txHash'):
-                        inferred_type = 'onchain'
-                    
-                    p_type = parsed.get('_paynode', {}).get('type') or inferred_type
-                    
-                    unified_payload = {
-                        "version": "2.2.0",
-                        "type": p_type,
-                        "orderId": internal_order_id,
-                        "router": parsed.get('accepted', {}).get('router'),
-                        "payload": parsed.get('payload')
-                    }
-                    order_id = internal_order_id
-                elif parsed.get('version') == "2.2.0":
-                    # Legacy PayNode format
-                    unified_payload = parsed
-                    if 'orderId' in unified_payload:
-                        order_id = unified_payload['orderId']
-                    elif 'order_id' in unified_payload:
-                        order_id = unified_payload['order_id']
+                unified_payload = PayNodePayloadHelper.normalize(v2_payload_header, order_id)
+                order_id = unified_payload.get("orderId") or order_id
             except Exception as e:
                 logger.error(f"❌ [PayNode-Middleware] Failed to decode payment payload header: {e}")
 
@@ -170,6 +144,7 @@ class PayNodeMiddleware(BaseHTTPMiddleware):
         v2_response = {
             "x402Version": 2,
             "error": "Payment Required by PayNode",
+            "orderId": order_id,
             "resource": {
                 "url": str(request.url),
                 "description": self.description,
@@ -211,6 +186,119 @@ class PayNodeMiddleware(BaseHTTPMiddleware):
         }
         return JSONResponse(status_code=402, headers=headers, content=v2_response)
 
+
+class PayNodeMerchantMiddleware(BaseHTTPMiddleware):
+    """
+    Unified PayNode Merchant Middleware
+    Handles: 
+    1. Market Proxy (Strict HMAC Signature + Body Unwrapping)
+    2. Discovery Probes (Auto-respond with API Manifest)
+    
+    Note: Standalone direct X402 payment flow should be handled 
+    via x402_gate.
+    """
+    def __init__(
+        self,
+        app: Any,
+        merchant: Any,  # PayNodeMerchant instance
+        merchant_address: str,
+        price: str,
+        manifest: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ):
+        super().__init__(app)
+        self.merchant = merchant
+        self.merchant_address = merchant_address
+        self.price = price
+        self.manifest = manifest or {}
+        self.quiet = getattr(merchant, "quiet", False)
+
+    async def dispatch(self, request: Request, call_next):
+        # 1. Check for Market Proxy Headers
+        headers = request.headers
+        signature = headers.get("X-PayNode-Signature")
+        timestamp = headers.get("X-PayNode-Timestamp")
+        request_id = headers.get("X-PayNode-Request-Id") or headers.get("X-402-Order-Id")
+        is_discovery = headers.get("X-PayNode-Discovery") == "true"
+
+        if signature and request_id and timestamp:
+            # ✅ Verify Signature from PayNode Market
+            from .utils.signature import verify_market_signature
+            is_valid = verify_market_signature(
+                signature=signature,
+                order_id=request_id,
+                timestamp=timestamp,
+                shared_secret=self.merchant.shared_secret
+            )
+
+            if not is_valid:
+                if not self.quiet:
+                    logger.error(f"[PayNode-SDK] Invalid Market Proxy Signature for request {request_id}")
+                return JSONResponse(
+                    status_code=401,
+                    content={"error": "unauthorized", "message": "PayNode Market Signature verification failed."}
+                )
+
+            # --- Scene A: Discovery Probe ---
+            if is_discovery:
+                return JSONResponse(
+                    status_code=200,
+                    content={
+                        "status": "DISCOVERED",
+                        "x402Version": PROTOCOL_VERSION,
+                        "manifest": self.manifest,
+                        "last_synced": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+                    }
+                )
+
+            # --- Scene B: Proxy Flow - Context Enrichment ---
+            # In FastAPI, we store the unwrapped data in request.state
+            # Transparently unwrapping req.body is complex in BaseHTTPMiddleware, 
+            # so we provide the unwrapped body in request.state.paynode_body
+            
+            paynode_context = {"orderId": request_id}
+            
+            # Simple body check (may consume stream, so we use request.state to cache if needed)
+            # For now, we mirror JS context enrichment
+            try:
+                # We assume the Market Proxy always sends JSON
+                body = await request.json()
+                if isinstance(body, dict) and body.get("payload"):
+                    metadata = {k: v for k, v in body.items() if k != "payload"}
+                    
+                    request.state.paynode = {
+                        "orderId": request_id,
+                        "txHash": headers.get("X-PayNode-Transaction-Hash") or body.get("tx_hash"),
+                        "amount": headers.get("X-PayNode-Amount") or body.get("amount"),
+                        "network": headers.get("X-PayNode-Network") or body.get("network"),
+                        "chainId": headers.get("X-PayNode-Chain-Id") or (str(body.get("chain_id")) if body.get("chain_id") else None),
+                        "proxyMetadata": metadata
+                    }
+                    # Store the unwrapped body for the handler
+                    request.state.paynode_body = body.get("payload")
+                    
+                    # NOTE: To truly "unwrap" req.body for downstream handlers (so request.json() works),
+                    # we would need to override the request.receive channel. 
+                    # For this SDK, we recommend handlers check request.state.paynode_body if accessed via Proxy.
+                else:
+                    request.state.paynode = {"orderId": request_id}
+                    request.state.paynode_body = body
+            except Exception:
+                request.state.paynode = {"orderId": request_id}
+                request.state.paynode_body = None
+
+            return await call_next(request)
+
+        # 2. Scene C: Direct Agent Call (Rejected)
+        # PayNodeMerchant requires Market Proxy for verification.
+        return JSONResponse(
+            status_code=403,
+            content={
+                "error": "forbidden",
+                "message": "PayNode Market Auth required. This API must be accessed via PayNode Market Proxy for verification."
+            }
+        )
+
 def x402_gate(
     merchant_address: str, 
     price: str,

paynode_sdk_python-2.5.0/paynode_sdk/utils/payload.py

@@ -0,0 +1,64 @@
+import base64
+import json
+import logging
+from typing import Optional, Dict, Any
+from ..constants import SDK_VERSION
+
+logger = logging.getLogger("paynode_sdk.payload")
+
+class PayNodePayloadHelper:
+    """
+    Normalizes raw payment payloads into the Unified format.
+    Mirrors JS X402PayloadHelper.
+    """
+    
+    @staticmethod
+    def normalize(auth_header: str, fallback_order_id: str = "") -> Dict[str, Any]:
+        """
+        Normalizes a raw payment payload (from PAYMENT-SIGNATURE or X-402-Payload headers).
+        """
+        try:
+            decoded = base64.b64decode(auth_header).decode('utf-8')
+            parsed = json.loads(decoded)
+
+            # 1. Handle Official X402 V2 Standard Format
+            if parsed.get('x402Version') == 2 and parsed.get('accepted'):
+                inferred_type = "onchain"
+                payload_content = parsed.get('payload', {})
+                
+                if payload_content.get('signature') or payload_content.get('authorization'):
+                    inferred_type = "eip3009"
+                elif payload_content.get('txHash'):
+                    inferred_type = "onchain"
+
+                return {
+                    "x402Version": 2,
+                    "type": parsed.get('_paynode', {}).get('type') or inferred_type,
+                    "orderId": parsed.get('_paynode', {}).get('orderId') or fallback_order_id,
+                    "router": parsed.get('accepted', {}).get('router') or parsed.get('router'),
+                    "payload": parsed.get('payload'),
+                    "_paynode": {
+                        "sdkVersion": SDK_VERSION
+                    }
+                }
+
+            # 2. Handle Legacy or already Unified Format
+            version = parsed.get('version')
+            if isinstance(version, str) and (version.startswith("2.2") or version.startswith("2.3") or version.startswith("2.4")):
+                return {
+                    "x402Version": parsed.get('x402Version', 2),
+                    "type": parsed.get('type'),
+                    "orderId": parsed.get('orderId') or parsed.get('order_id') or fallback_order_id,
+                    "router": parsed.get('router'),
+                    "payload": parsed.get('payload'),
+                    "_paynode": parsed.get('_paynode') or {
+                        "sdkVersion": version
+                    }
+                }
+
+            # 3. Fallback
+            return parsed
+            
+        except Exception as e:
+            logger.error(f"Failed to normalize PayNode payload: {e}")
+            raise ValueError(f"Failed to normalize PayNode payload: {e}")

paynode_sdk_python-2.5.0/paynode_sdk/utils/signature.py

@@ -0,0 +1,67 @@
+import hmac
+import hashlib
+import time
+from datetime import datetime
+import logging
+
+logger = logging.getLogger("paynode_sdk.signature")
+
+def verify_market_signature(
+    signature: str,
+    order_id: str,
+    timestamp: str,
+    shared_secret: str,
+    now: float = None,
+    drift_window: int = 300  # 5 minutes in seconds
+) -> bool:
+    """
+    Verifies the HMAC-SHA256 signature from PayNode Market Proxy.
+    
+    Args:
+        signature: Received hex signature
+        order_id: The order ID or request ID
+        timestamp: ISO string or millisecond timestamp
+        shared_secret: Merchant-specific shared secret
+        now: Current time in seconds (for testing)
+        drift_window: Allowed drift in seconds
+        
+    Returns:
+        bool: True if signature is valid and within drift window
+    """
+    if not all([signature, order_id, timestamp, shared_secret]):
+        return False
+
+    try:
+        # 1. Parse timestamp
+        check_time = now or time.time()
+        
+        try:
+            # Try ISO format (matching JS new Date(timestamp))
+            ts_dt = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+            ts_seconds = ts_dt.timestamp()
+        except ValueError:
+            # Try milliseconds (JS numeric timestamp)
+            try:
+                ts_seconds = int(timestamp) / 1000.0
+            except ValueError:
+                return False
+
+        # 2. Check for timestamp drift
+        drift = abs(check_time - ts_seconds)
+        if drift > drift_window:
+            logger.warning(f"[PayNode-SDK] Signature timestamp drift too high: {int(drift * 1000)}ms")
+            return False
+
+        # 3. Calculate expected signature
+        # Formula: orderId + ":" + timestamp
+        msg = f"{order_id}:{timestamp}".encode("utf-8")
+        key = shared_secret.encode("utf-8")
+        
+        expected_sig = hmac.new(key, msg, hashlib.sha256).hexdigest()
+        
+        # 4. Constant-time comparison
+        return hmac.compare_digest(signature.lower(), expected_sig.lower())
+
+    except Exception as e:
+        logger.error(f"[PayNode-SDK] Error verifying market signature: {e}")
+        return False

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0}/paynode_sdk/verifier.py

@@ -1,6 +1,7 @@
 import asyncio
 import time
 import logging
+import hmac
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from .errors import ErrorCode, PayNodeException
 from .constants import ACCEPTED_TOKENS, MIN_PAYMENT_AMOUNT, PAYNODE_ROUTER_ABI
@@ -47,7 +48,13 @@ class PayNodeVerifier:
             token_list = ACCEPTED_TOKENS.get(self.chain_id)
         else:
             token_list = None
-        self.accepted_tokens = set(t.lower() for t in token_list) if token_list else None
+
+        if not token_list:
+            raise PayNodeException(
+                ErrorCode.internal_error,
+                message="Verifier requires either a valid chain_id or accepted_tokens to initialize its whitelist"
+            )
+        self.accepted_tokens = set(t.lower() for t in token_list)
 
     async def verify(self, unified_payload: dict, expected: dict, extra: dict = None) -> dict:
         """
@@ -61,7 +68,7 @@ class PayNodeVerifier:
                  return {"isValid": False, "error": PayNodeException(ErrorCode.amount_too_low)}
 
             # 2. Security: Token Whitelist Check
-            if self.accepted_tokens and expected.get("tokenAddress", "").lower() not in self.accepted_tokens:
+            if expected.get("tokenAddress", "").lower() not in self.accepted_tokens:
                 return {"isValid": False, "error": PayNodeException(ErrorCode.token_not_accepted, message=f"Token {expected.get('tokenAddress')} not allowed")}
 
             payload_type = unified_payload.get("type")
@@ -140,10 +147,10 @@ class PayNodeVerifier:
         order_id_mismatch_found = False
         for log in processed_logs:
             args = log.args
-            is_merchant_match = args.get("merchant", "").lower() == merchant
-            is_token_match = args.get("token", "").lower() == token
+            is_merchant_match = hmac.compare_digest(args.get("merchant", "").lower(), merchant)
+            is_token_match = hmac.compare_digest(args.get("token", "").lower(), token)
             is_amount_match = args.get("amount", 0) >= amount
-            is_order_match = args.get("orderId") == order_id_bytes
+            is_order_match = hmac.compare_digest(args.get("orderId"), order_id_bytes)
 
             if is_merchant_match and is_token_match and is_amount_match:
                 if is_order_match:
@@ -185,7 +192,7 @@ class PayNodeVerifier:
             auth = payload["authorization"]
             
             # 1. Basic validation
-            if auth["to"].lower() != expected["to"].lower():
+            if not hmac.compare_digest(auth["to"].lower(), expected["to"].lower()):
                 return {"isValid": False, "error": PayNodeException(ErrorCode.invalid_receipt, message="Recipient mismatch")}
             
             payload_value = int(auth["value"])
@@ -246,7 +253,7 @@ class PayNodeVerifier:
             signable_msg = encode_typed_data(full_message=structured_data)
             recovered_address = Account.recover_message(signable_msg, signature=signature)
 
-            if recovered_address.lower() != auth["from"].lower():
+            if not hmac.compare_digest(recovered_address.lower(), auth["from"].lower()):
                 return {"isValid": False, "error": PayNodeException(ErrorCode.invalid_receipt, message="Invalid signature")}
 
             # 4. Idempotency (Nonce local check)

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0/paynode_sdk_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paynode-sdk-python
-Version: 2.2.0
+Version: 2.5.0
 Summary: PayNode Protocol Python SDK for AI Agents
 Author-email: PayNodeLabs <contact@paynode.dev>
 License: MIT
@@ -25,7 +25,7 @@ Dynamic: license-file
 [![Official Documentation](https://img.shields.io/badge/Docs-docs.paynode.dev-00ff88?style=for-the-badge&logo=readthedocs)](https://docs.paynode.dev)
 [![PyPI Version](https://img.shields.io/pypi/v/paynode-sdk-python.svg?style=for-the-badge)](https://pypi.org/project/paynode-sdk-python/)
 
-The official Python SDK for the **PayNode Protocol (v2.2.0)**. PayNode allows autonomous AI Agents to seamlessly pay for APIs and computational resources using USDC on Base L2, utilizing the standardized HTTP 402 protocol with support for both on-chain receipts and off-chain signatures (EIP-3009).
+The official Python SDK for the **PayNode Protocol (v2.2.1)**. PayNode allows autonomous AI Agents to seamlessly pay for APIs and computational resources using USDC on Base L2, utilizing the standardized HTTP 402 protocol with support for both on-chain receipts and off-chain signatures (EIP-3009).
 
 ## 📖 Read the Docs
 
@@ -56,7 +56,7 @@ response = agent.request_gate("https://api.merchant.com/premium-data", method="P
 print(response.json())
 ```
 
-### Key Features (v2.2.0)
+### Key Features (v2.2.1)
 - **EIP-3009 Support**: Sign payments off-chain using `TransferWithAuthorization`, allowing for gasless or relayer-mediated settlement.
 - **X402 V2 Protocol**: JSON-based handshake for more structured and machine-readable payment instructions.
 - **Dual Flow**: Automatic fallback to V1 (on-chain receipts) for legacy merchant support.

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0}/paynode_sdk_python.egg-info/SOURCES.txt

@@ -6,9 +6,13 @@ paynode_sdk/client.py
 paynode_sdk/constants.py
 paynode_sdk/errors.py
 paynode_sdk/idempotency.py
+paynode_sdk/merchant.py
 paynode_sdk/middleware.py
 paynode_sdk/verifier.py
 paynode_sdk/webhook.py
+paynode_sdk/utils/__init__.py
+paynode_sdk/utils/payload.py
+paynode_sdk/utils/signature.py
 paynode_sdk_python.egg-info/PKG-INFO
 paynode_sdk_python.egg-info/SOURCES.txt
 paynode_sdk_python.egg-info/dependency_links.txt
@@ -17,4 +21,5 @@ paynode_sdk_python.egg-info/top_level.txt
 tests/test_client.py
 tests/test_concurrency.py
 tests/test_internals.py
+tests/test_v2_5_alignment.py
 tests/test_verifier_logic.py

{paynode_sdk_python-2.2.0 → paynode_sdk_python-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "paynode-sdk-python"
-version = "2.2.0"
+version = "2.5.0"
 description = "PayNode Protocol Python SDK for AI Agents"
 readme = "README.md"
 authors = [{ name = "PayNodeLabs", email = "contact@paynode.dev" }]

paynode_sdk_python-2.5.0/tests/test_v2_5_alignment.py

@@ -0,0 +1,189 @@
+import unittest
+import json
+import base64
+import hmac
+import hashlib
+from datetime import datetime, timezone, timedelta
+from fastapi import FastAPI, Request
+from fastapi.testclient import TestClient
+from paynode_sdk import (
+    PayNodeAgentClient, 
+    PayNodeMiddleware, 
+    PayNodeMerchant, 
+    PayNodeMerchantMiddleware,
+    PayNodePayloadHelper,
+    SDK_VERSION
+)
+
+class TestSDKAlignment(unittest.IsolatedAsyncioTestCase):
+    def setUp(self):
+        self.merchant_addr = "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
+        self.shared_secret = "test_secret_123"
+        self.api_key = "test_key"
+        
+    def test_version_alignment(self):
+        """Ensure SDK_VERSION is 2.5.0 and globally consistent."""
+        self.assertEqual(SDK_VERSION, "2.5.0")
+
+    def test_payload_normalization(self):
+        """Test PayNodePayloadHelper.normalize against X402 V2 standard format."""
+        v2_payload = {
+            "x402Version": 2,
+            "accepted": {"scheme": "exact", "type": "onchain", "router": "0x123"},
+            "payload": {"txHash": "0xabc"},
+            "_paynode": {
+                "sdkVersion": "2.5.0",
+                "type": "onchain",
+                "orderId": "req_123"
+            }
+        }
+        b64_payload = base64.b64encode(json.dumps(v2_payload).encode()).decode()
+        
+        normalized = PayNodePayloadHelper.normalize(b64_payload, fallback_order_id="fallback")
+        
+        self.assertEqual(normalized["orderId"], "req_123")
+        self.assertEqual(normalized["type"], "onchain")
+        self.assertEqual(normalized["_paynode"]["sdkVersion"], "2.5.0")
+
+    async def test_402_challenge_format(self):
+        """Verify middleware includes orderId in JSON response body (v2.5.0 feature)."""
+        app = FastAPI()
+        app.add_middleware(
+            PayNodeMiddleware, 
+            merchant_address=self.merchant_addr, 
+            price="0.01"
+        )
+
+        @app.get("/premium")
+        async def premium():
+            return {"data": "secret"}
+
+        client = TestClient(app)
+        response = client.get("/premium")
+        
+        self.assertEqual(response.status_code, 402)
+        body = response.json()
+        self.assertEqual(body["x402Version"], 2)
+        self.assertIn("orderId", body)
+        self.assertTrue(body["orderId"].startswith("agent_py_"))
+
+    async def test_market_proxy_hmac(self):
+        """Verify PayNodeMerchant HMAC verification (aligned with JS)."""
+        merchant = PayNodeMerchant(shared_secret=self.shared_secret)
+        import time
+        order_id = "test_order_999"
+        timestamp = str(int(time.time() * 1000))
+        msg = f"{order_id}:{timestamp}".encode("utf-8")
+        expected_sig = hmac.new(self.shared_secret.encode(), msg, hashlib.sha256).hexdigest()
+        
+        # Use TestClient for consistent header behavior
+        app = FastAPI()
+        @app.get("/verify")
+        async def verify_endpoint(request: Request):
+            return await merchant.verify(request)
+        
+        client = TestClient(app)
+        
+        headers = {
+            "X-PayNode-Signature": expected_sig,
+            "X-PayNode-Request-Id": order_id,
+            "X-PayNode-Timestamp": timestamp
+        }
+        
+        response = client.get("/verify", headers=headers)
+        self.assertEqual(response.status_code, 200)
+        result = response.json()
+        self.assertTrue(result["isValid"], result.get("error"))
+        
+        # Verify invalid
+        response_invalid = client.get("/verify", headers={"X-PayNode-Signature": "wrong"})
+        self.assertFalse(response_invalid.json()["isValid"])
+        
+        # Verify drift
+        old_ts = (datetime.now(timezone.utc) - timedelta(minutes=10)).strftime("%Y-%m-%dT%H:%M:%SZ")
+        headers_old = {**headers, "X-PayNode-Timestamp": old_ts}
+        response_old = client.get("/verify", headers=headers_old)
+        self.assertFalse(response_old.json()["isValid"])
+
+    async def test_merchant_middleware_discovery(self):
+        """Test PayNodeMerchantMiddleware discovery probe."""
+        merchant = PayNodeMerchant(shared_secret=self.shared_secret)
+        app = FastAPI()
+        manifest = {"name": "Test Tool", "price": "0.1"}
+        app.add_middleware(
+            PayNodeMerchantMiddleware,
+            merchant=merchant,
+            merchant_address=self.merchant_addr,
+            price="0.1",
+            manifest=manifest
+        )
+
+        @app.post("/tool")
+        async def tool():
+            return {"ok": True}
+
+        client = TestClient(app)
+        
+        # Signed Discovery Probe
+        order_id = "probe_1"
+        import time
+        timestamp = str(int(time.time() * 1000))
+        msg = f"{order_id}:{timestamp}".encode("utf-8")
+        sig = hmac.new(self.shared_secret.encode(), msg, hashlib.sha256).hexdigest()
+        
+        headers = {
+            "X-PayNode-Signature": sig,
+            "X-PayNode-Timestamp": timestamp,
+            "X-PayNode-Request-Id": order_id,
+            "X-PayNode-Discovery": "true"
+        }
+        
+        response = client.post("/tool", headers=headers)
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertEqual(data["status"], "DISCOVERED")
+        self.assertEqual(data["manifest"]["name"], "Test Tool")
+
+    async def test_merchant_middleware_unwrap(self):
+        """Test PayNodeMerchantMiddleware body unwrapping."""
+        merchant = PayNodeMerchant(shared_secret=self.shared_secret)
+        app = FastAPI()
+        app.add_middleware(
+            PayNodeMerchantMiddleware,
+            merchant=merchant,
+            merchant_address=self.merchant_addr,
+            price="0.1"
+        )
+
+        from fastapi import Request
+        @app.post("/tool")
+        async def tool(request: Request):
+            # Access unwrapped body from state
+            return {"echo": request.state.paynode_body}
+
+        client = TestClient(app)
+        
+        order_id = "req_unwrap"
+        import time
+        timestamp = str(int(time.time() * 1000))
+        sig = hmac.new(self.shared_secret.encode(), f"{order_id}:{timestamp}".encode(), hashlib.sha256).hexdigest()
+        
+        # Wrapped payload
+        wrapped_body = {
+            "payload": {"query": "hello world"},
+            "tx_hash": "0x123",
+            "amount": "100000"
+        }
+        
+        headers = {
+            "X-PayNode-Signature": sig,
+            "X-PayNode-Timestamp": timestamp,
+            "X-PayNode-Request-Id": order_id
+        }
+        
+        response = client.post("/tool", headers=headers, json=wrapped_body)
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["echo"]["query"], "hello world")
+
+if __name__ == "__main__":
+    unittest.main()