paynode-sdk-python 1.0.1__py3-none-any.whl → 1.1.1__py3-none-any.whl

paynode_sdk/__init__.py

@@ -1,6 +1,21 @@
+import warnings
+import logging
+
+# Silence upstream library deprecation warnings from web3's websocket dependency
+# to ensure a clean experience for PayNode SDK users.
+warnings.filterwarnings("ignore", category=DeprecationWarning, module="websockets.legacy")
+
 from .middleware import PayNodeMiddleware
 from .verifier import PayNodeVerifier
 from .errors import ErrorCode, PayNodeException
 from .idempotency import IdempotencyStore, MemoryIdempotencyStore
+from .webhook import PayNodeWebhookNotifier, PaymentEvent
+from .client import PayNodeAgentClient
+from .constants import ACCEPTED_TOKENS
 
-__all__ = ["PayNodeMiddleware", "PayNodeVerifier", "ErrorCode", "PayNodeException", "IdempotencyStore", "MemoryIdempotencyStore"]
+__all__ = [
+    "PayNodeMiddleware", "PayNodeVerifier", "ErrorCode", "PayNodeException",
+    "IdempotencyStore", "MemoryIdempotencyStore",
+    "PayNodeWebhookNotifier", "PaymentEvent",
+    "PayNodeAgentClient", "ACCEPTED_TOKENS"
+]

paynode_sdk/client.py

@@ -1,99 +1,216 @@
-import requests
 import time
+import logging
+import threading
+import requests
+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
+from .errors import PayNodeException, ErrorCode
+
+logger = logging.getLogger("paynode_sdk.client")
 
 class PayNodeAgentClient:
-    def __init__(self, rpc_urls: list, private_key: str):
-        self.w3 = Web3(Web3.HTTPProvider(rpc_urls[0]))
+    """
+    The main PayNode Client for AI Agents (v1.1.1).
+    Automatically handles the x402 'Payment Required' handshake.
+    Supports RPC redundancy and EIP-2612 Permit-First payments.
+    """
+    def __init__(self, private_key: str, rpc_urls: list | str = "https://mainnet.base.org"):
+        self.rpc_urls = rpc_urls if isinstance(rpc_urls, list) else [rpc_urls]
+        self.w3 = self._init_w3()
+        
+        # Initialize account and discard private key string
         self.account = self.w3.eth.account.from_key(private_key)
-        self.private_key = private_key
+        self.nonce_lock = threading.Lock()
+        
+        # Setup session
+        self.session = requests.Session()
+        retry_strategy = Retry(
+            total=3,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["HEAD", "GET", "POST", "PUT", "DELETE", "OPTIONS", "TRACE"]
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("https://", adapter)
+        self.session.mount("http://", adapter)
+
+    def _init_w3(self):
+        """Finds a working RPC from the list."""
+        for rpc in self.rpc_urls:
+            try:
+                w3 = Web3(Web3.HTTPProvider(rpc, request_kwargs={'timeout': 5}))
+                if w3.is_connected():
+                    return w3
+            except Exception as e:
+                logger.warning(f"⚠️ [PayNode-PY] RPC {rpc} failed: {str(e)}")
+                continue
+        raise PayNodeException("Failed to connect to any provided RPC nodes.", ErrorCode.RPC_ERROR)
+
+    def request_gate(self, url: str, method: str = "GET", **kwargs):
+        """The high-level autonomous method handling 402 loop."""
+        return self._request_with_402_retry(method.upper(), url, **kwargs)
 
     def get(self, url, **kwargs):
-        response = requests.get(url, **kwargs)
-        if response.status_code == 402:
-            print("💡 [PayNode-PY] 402 Detected. Handling payment...")
-            return self._handle_402(url, "GET", response.headers, **kwargs)
-        return response
+        return self.request_gate(url, "GET", **kwargs)
 
     def post(self, url, **kwargs):
-        response = requests.post(url, **kwargs)
-        if response.status_code == 402:
-            print("💡 [PayNode-PY] 402 Detected. Handling payment...")
-            return self._handle_402(url, "POST", response.headers, **kwargs)
+        return self.request_gate(url, "POST", **kwargs)
+
+    def _request_with_402_retry(self, method, url, max_retries=3, **kwargs):
+        for _ in range(max_retries):
+            response = self.session.request(method, url, **kwargs)
+            if response.status_code == 402:
+                logger.info("💡 [PayNode-PY] 402 Detected. Handling payment...")
+                try:
+                    kwargs = self._handle_402(response.headers, **kwargs)
+                except Exception as e:
+                    if isinstance(e, PayNodeException): raise
+                    raise PayNodeException(f"An unexpected error occurred: {str(e)}", ErrorCode.INTERNAL_ERROR)
+                continue
+            return response
         return response
 
-    def _handle_402(self, url, method, headers, **kwargs):
+    def _handle_402(self, headers, **kwargs):
         router_addr = headers.get('x-paynode-contract')
         merchant_addr = headers.get('x-paynode-merchant')
         amount_raw = int(headers.get('x-paynode-amount', 0))
         token_addr = headers.get('x-paynode-token-address')
         order_id = headers.get('x-paynode-order-id')
 
-        # 1. Handle Approval
-        self._ensure_allowance(token_addr, router_addr, amount_raw)
+        if not all([router_addr, merchant_addr, amount_raw, token_addr, order_id]):
+            raise PayNodeException("Malformed 402 headers: missing metadata", ErrorCode.INTERNAL_ERROR)
+
+        # v1.3 Constraint: Min payment protection
+        if amount_raw < 1000:
+            raise PayNodeException("Payment amount is below the protocol minimum (1000).", ErrorCode.AMOUNT_TOO_LOW)
 
-        # 2. Execute Payment
-        tx_hash = self._execute_pay(router_addr, token_addr, merchant_addr, amount_raw, order_id)
-        print(f"✅ [PayNode-PY] Payment successful: {tx_hash}")
+        # Protocol v1.3: Permit-First Execution
+        try:
+            # Check allowance first to decide if we need Permit
+            allowance = self._get_allowance(token_addr, router_addr)
+            if allowance >= amount_raw:
+                tx_hash = self._execute_pay(router_addr, token_addr, merchant_addr, amount_raw, order_id)
+            else:
+                logger.info("⚡ [PayNode-PY] Insufficient allowance. Attempting Permit-First payment...")
+                tx_hash = self.pay_with_permit_auto(router_addr, token_addr, merchant_addr, amount_raw, order_id)
+            
+            logger.info(f"✅ [PayNode-PY] Payment successful: {tx_hash}")
+        except Exception as e:
+            if isinstance(e, PayNodeException): raise
+            raise PayNodeException(f"On-chain transaction reverted or failed: {str(e)}", ErrorCode.TRANSACTION_FAILED)
 
-        # 3. Retry
         retry_headers = kwargs.get('headers', {}).copy()
-        retry_headers.update({
-            'x-paynode-receipt': tx_hash,
-            'x-paynode-order-id': order_id
-        })
+        retry_headers.update({'x-paynode-receipt': tx_hash, 'x-paynode-order-id': order_id})
         kwargs['headers'] = retry_headers
+        return kwargs
+
+    def _get_allowance(self, token_addr, spender_addr):
+        abi = [{"constant": True, "inputs": [{"name": "o", "type": "address"}, {"name": "s", "type": "address"}], "name": "allowance", "outputs": [{"name": "", "type": "uint256"}], "type": "function"}]
+        token = self.w3.eth.contract(address=Web3.to_checksum_address(token_addr), abi=abi)
+        return token.functions.allowance(self.account.address, Web3.to_checksum_address(spender_addr)).call()
+
+    def sign_permit(self, token_addr, spender_addr, amount, deadline=None):
+        """Signs EIP-2612 Permit data."""
+        if deadline is None:
+            deadline = int(time.time()) + 3600
+        
+        token_addr = Web3.to_checksum_address(token_addr)
+        spender_addr = Web3.to_checksum_address(spender_addr)
         
-        if method == "GET":
-            return requests.get(url, **kwargs)
-        return requests.post(url, **kwargs)
-
-    def _ensure_allowance(self, token_addr, spender_addr, amount):
-        token_abi = [
-            {"constant": True, "inputs": [{"name": "o", "type": "address"}, {"name": "s", "type": "address"}], "name": "allowance", "outputs": [{"name": "", "type": "uint256"}], "type": "function"},
-            {"constant": False, "inputs": [{"name": "s", "type": "address"}, {"name": "a", "type": "uint256"}], "name": "approve", "outputs": [{"name": "", "type": "bool"}], "type": "function"}
+        # Get nonce and domain separator
+        abi = [
+            {"inputs": [{"name": "o", "type": "address"}], "name": "nonces", "outputs": [{"name": "", "type": "uint256"}], "stateMutability": "view", "type": "function"},
+            {"inputs": [], "name": "name", "outputs": [{"name": "", "type": "string"}], "stateMutability": "view", "type": "function"}
         ]
-        token = self.w3.eth.contract(address=Web3.to_checksum_address(token_addr), abi=token_abi)
-        allowance = token.functions.allowance(self.account.address, Web3.to_checksum_address(spender_addr)).call()
+        token = self.w3.eth.contract(address=token_addr, abi=abi)
+        nonce = token.functions.nonces(self.account.address).call()
+        name = token.functions.name().call()
+        chain_id = self.w3.eth.chain_id
+
+        domain = {
+            "name": name,
+            "version": "1",
+            "chainId": chain_id,
+            "verifyingContract": token_addr,
+        }
+        message = {
+            "owner": self.account.address,
+            "spender": spender_addr,
+            "value": amount,
+            "nonce": nonce,
+            "deadline": deadline,
+        }
+        types = {
+            "EIP712Domain": [
+                {"name": "name", "type": "string"},
+                {"name": "version", "type": "string"},
+                {"name": "chainId", "type": "uint256"},
+                {"name": "verifyingContract", "type": "address"},
+            ],
+            "Permit": [
+                {"name": "owner", "type": "address"},
+                {"name": "spender", "type": "address"},
+                {"name": "value", "type": "uint256"},
+                {"name": "nonce", "type": "uint256"},
+                {"name": "deadline", "type": "uint256"},
+            ],
+        }
         
-        if allowance < amount:
-            print(f"🔐 [PayNode-PY] Allowance too low. Granting Infinite Approval...")
-            # Use 20% higher gas price for better reliability
-            current_gas_price = int(self.w3.eth.gas_price * 1.2)
-            
-            tx = token.functions.approve(Web3.to_checksum_address(spender_addr), 2**256 - 1).build_transaction({
+        structured_data = {
+            "types": types,
+            "domain": domain,
+            "primaryType": "Permit",
+            "message": message,
+        }
+        
+        signed = self.account.sign_typed_data(full_message=structured_data)
+        return {"v": signed.v, "r": signed.r, "s": signed.s, "deadline": deadline}
+
+    def pay_with_permit_auto(self, router_addr, token_addr, merchant_addr, amount, order_id):
+        """Combines sign_permit and on-chain submission."""
+        sig = self.sign_permit(token_addr, router_addr, amount)
+        router_abi = [{"inputs": [{"name": "p", "type": "address"}, {"name": "t", "type": "address"}, {"name": "m", "type": "address"}, {"name": "a", "type": "uint256"}, {"name": "o", "type": "bytes32"}, {"name": "d", "type": "uint256"}, {"name": "v", "type": "uint8"}, {"name": "r", "type": "bytes32"}, {"name": "s", "type": "bytes32"}], "name": "payWithPermit", "outputs": [], "stateMutability": "nonpayable", "type": "function"}]
+        router = self.w3.eth.contract(address=Web3.to_checksum_address(router_addr), abi=router_abi)
+        order_id_bytes = self.w3.keccak(text=order_id)
+        
+        current_gas_price = int(self.w3.eth.gas_price * 1.2)
+        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': self.w3.eth.get_transaction_count(self.account.address, 'pending'),
-                'gas': 100000,
+                'nonce': nonce,
+                'gas': 300000,
                 'gasPrice': current_gas_price
             })
-            signed_tx = self.w3.eth.account.sign_transaction(tx, self.private_key)
+            signed_tx = self.account.sign_transaction(tx)
             tx_h = self.w3.eth.send_raw_transaction(signed_tx.raw_transaction)
-            print(f"⏳ Waiting for approval confirmation: {self.w3.to_hex(tx_h)}...")
-            self.w3.eth.wait_for_transaction_receipt(tx_h)
-            time.sleep(1) # Extra buffer for indexers
+        
+        self.w3.eth.wait_for_transaction_receipt(tx_h, timeout=60)
+        return self.w3.to_hex(tx_h)
 
     def _execute_pay(self, router_addr, token_addr, merchant_addr, amount, order_id):
+        """Standard pay method (fallback)."""
         router_abi = [{"inputs": [{"name": "t", "type": "address"}, {"name": "m", "type": "address"}, {"name": "a", "type": "uint256"}, {"name": "o", "type": "bytes32"}], "name": "pay", "outputs": [], "stateMutability": "nonpayable", "type": "function"}]
         router = self.w3.eth.contract(address=Web3.to_checksum_address(router_addr), abi=router_abi)
         order_id_bytes = self.w3.keccak(text=order_id)
-
-        # Use 20% higher gas price
         current_gas_price = int(self.w3.eth.gas_price * 1.2)
-
-        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': self.w3.eth.get_transaction_count(self.account.address, 'pending'),
-            'gas': 200000,
-            'gasPrice': current_gas_price
-        })
-        signed_tx = self.w3.eth.account.sign_transaction(tx, self.private_key)
-        tx_h = self.w3.eth.send_raw_transaction(signed_tx.raw_transaction)
-        self.w3.eth.wait_for_transaction_receipt(tx_h)
+        
+        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
+            })
+            signed_tx = self.account.sign_transaction(tx)
+            tx_h = self.w3.eth.send_raw_transaction(signed_tx.raw_transaction)
+        
+        self.w3.eth.wait_for_transaction_receipt(tx_h, timeout=60)
         return self.w3.to_hex(tx_h)

paynode_sdk/constants.py

@@ -1,5 +1,35 @@
-PAYNODE_ROUTER_ADDRESS = "0xA88B5eaD188De39c015AC51F45E1B41D3d95f2bb"
-PAYNODE_ROUTER_ADDRESS_SANDBOX = "0x1E12700393D3222BC451fb0aEe7351E4eB6779b1"
+# Generated by scripts/sync-config.py
+PAYNODE_ROUTER_ADDRESS = "0x92e20164FC457a2aC35f53D06268168e6352b200"
+PAYNODE_ROUTER_ADDRESS_SANDBOX = "0xB587Bc36aaCf65962eCd6Ba59e2DA76f2f575408"
 BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 BASE_USDC_ADDRESS_SANDBOX = "0xeAC1f2C7099CdaFfB91Aa3b8Ffd653Ef16935798"
 BASE_USDC_DECIMALS = 6
+
+PROTOCOL_TREASURY = "0x598bF63F5449876efafa7b36b77Deb2070621C0E"
+PROTOCOL_FEE_BPS = 100
+MIN_PAYMENT_AMOUNT = 1000
+
+BASE_RPC_URLS = ["https://mainnet.base.org", "https://base.meowrpc.com", "https://1rpc.io/base"]
+BASE_RPC_URLS_SANDBOX = ["https://sepolia.base.org", "https://base-sepolia-rpc.publicnode.com"]
+
+ACCEPTED_TOKENS = {
+    8453: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
+    84532: ["0xeAC1f2C7099CdaFfB91Aa3b8Ffd653Ef16935798"]
+}
+
+PAYNODE_ROUTER_ABI = [
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "orderId", "type": "bytes32"},
+            {"indexed": True, "name": "merchant", "type": "address"},
+            {"indexed": True, "name": "payer", "type": "address"},
+            {"indexed": False, "name": "token", "type": "address"},
+            {"indexed": False, "name": "amount", "type": "uint256"},
+            {"indexed": False, "name": "fee", "type": "uint256"},
+            {"indexed": False, "name": "chainId", "type": "uint256"}
+        ],
+        "name": "PaymentReceived",
+        "type": "event"
+    }
+]

paynode_sdk/errors.py

@@ -13,8 +13,11 @@ class ErrorCode(str, Enum):
     WRONG_CONTRACT = 'PAYNODE_WRONG_CONTRACT'
     WRONG_MERCHANT = 'PAYNODE_WRONG_MERCHANT'
     WRONG_TOKEN = 'PAYNODE_WRONG_TOKEN'
+    TOKEN_NOT_ACCEPTED = 'PAYNODE_TOKEN_NOT_ACCEPTED'
+    AMOUNT_TOO_LOW = 'PAYNODE_AMOUNT_TOO_LOW'
     INSUFFICIENT_FUNDS = 'PAYNODE_INSUFFICIENT_FUNDS'
     ORDER_MISMATCH = 'PAYNODE_ORDER_MISMATCH'
+    PERMIT_FAILED = 'PAYNODE_PERMIT_FAILED'
     
     # System
     RPC_ERROR = 'PAYNODE_RPC_ERROR'

paynode_sdk/middleware.py

@@ -6,9 +6,12 @@ from .verifier import PayNodeVerifier
 from .errors import ErrorCode
 from .idempotency import IdempotencyStore
 
-class PayNodeMiddleware:
+from starlette.middleware.base import BaseHTTPMiddleware
+
+class PayNodeMiddleware(BaseHTTPMiddleware):
     def __init__(
         self,
+        app: Any,
         rpc_url: str,
         contract_address: str,
         merchant_address: str,
@@ -20,6 +23,7 @@ class PayNodeMiddleware:
         store: Optional[IdempotencyStore] = None,
         generate_order_id: Optional[Callable[[Request], str]] = None
     ):
+        super().__init__(app)
         # The Verifier holds the state of the idempotency store
         self.verifier = PayNodeVerifier(rpc_url, contract_address, chain_id, store=store)
         self.merchant_address = merchant_address
@@ -34,7 +38,7 @@ class PayNodeMiddleware:
         # Calculate raw amount (integer)
         self.amount_int = int(float(price) * (10 ** decimals))
 
-    async def __call__(self, request: Request, call_next):
+    async def dispatch(self, request: Request, call_next):
         receipt_hash = request.headers.get('x-paynode-receipt')
         order_id = request.headers.get('x-paynode-order-id')
 
@@ -78,6 +82,7 @@ class PayNodeMiddleware:
         else:
             # Validation Failed
             err = result.get("error")
+            print(f"❌ [PayNode-PY] Verification Failed for Order: {order_id}. Reason: {str(err)}")
             return JSONResponse(
                 status_code=403,
                 content={

paynode_sdk/verifier.py

@@ -1,36 +1,108 @@
-from .errors import ErrorCode
-from unittest.mock import MagicMock
+from .errors import ErrorCode, PayNodeException
+from .constants import PAYNODE_ROUTER_ABI, ACCEPTED_TOKENS, MIN_PAYMENT_AMOUNT
+from .idempotency import MemoryIdempotencyStore
+from web3 import Web3
 
 class PayNodeVerifier:
-    def __init__(self, rpc_url=None, contract_address=None, chain_id=None, w3=None):
-        self.w3 = w3 or MagicMock()
+    def __init__(self, rpc_url=None, contract_address=None, chain_id=None, w3=None, store=None, accepted_tokens=None):
+        self.w3 = w3
+        if not self.w3 and rpc_url:
+            self.w3 = Web3(Web3.HTTPProvider(rpc_url))
         self.contract_address = contract_address
-        self.used_receipts = set()
+        self.chain_id = int(chain_id) if chain_id else None
+        self.store = store or MemoryIdempotencyStore()
+
+        # Build accepted token set: user-provided or chain-default
+        # accepted_tokens=None → use chain default; accepted_tokens=[] → explicitly disable whitelist
+        if accepted_tokens is not None:
+            token_list = accepted_tokens
+        elif self.chain_id:
+            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
 
     async def verify_payment(self, tx_hash, expected):
-        if tx_hash in self.used_receipts:
-            return {"isValid": False, "error": MagicError(ErrorCode.TRANSACTION_NOT_FOUND if "Used" not in str(tx_hash) else ErrorCode.RECEIPT_ALREADY_USED)}
-        
-        # 兼容性修复：根据枚举实际名称调整
+        if not self.w3:
+            return {"isValid": False, "error": PayNodeException("Verifier Provider Missing", ErrorCode.RPC_ERROR)}
+
+        # 0. Dust Exploit Check (Minimum Payment)
+        amount = int(expected.get("amount", 0))
+        if amount < MIN_PAYMENT_AMOUNT:
+             return {"isValid": False, "error": PayNodeException(
+                f"Payment amount {amount} is below the minimum threshold of {MIN_PAYMENT_AMOUNT}.",
+                ErrorCode.AMOUNT_TOO_LOW
+            )}
+
+        # 1. Token Whitelist Check (Anti-FakeToken)
+        expected_token = expected.get("tokenAddress", "").lower()
+        if self.accepted_tokens and expected_token not in self.accepted_tokens:
+            return {"isValid": False, "error": PayNodeException(
+                f"Token {expected.get('tokenAddress')} is not in the accepted whitelist.",
+                ErrorCode.TOKEN_NOT_ACCEPTED
+            )}
+
         try:
-            err_code = ErrorCode.RECEIPT_ALREADY_USED
-        except AttributeError:
-            err_code = ErrorCode.PAYNODE_RECEIPT_ALREADY_USED
+            is_new = await self.store.check_and_set(tx_hash, 86400) # 24 hour TTL
+            if not is_new:
+                return {"isValid": False, "error": PayNodeException("Receipt already used", ErrorCode.RECEIPT_ALREADY_USED)}
+        except Exception as e:
+            return {"isValid": False, "error": PayNodeException("Store Error", ErrorCode.INTERNAL_ERROR, details=str(e))}
+
+        try:
+            receipt = self.w3.eth.get_transaction_receipt(tx_hash)
+        except Exception:
+            return {"isValid": False, "error": PayNodeException("Transaction not found", ErrorCode.TRANSACTION_NOT_FOUND)}
 
-        if tx_hash == "0xUsedHash":
-             return {"isValid": False, "error": MagicError(err_code)}
-        
-        receipt = self.w3.eth.get_transaction_receipt(tx_hash)
         if not receipt:
-            try: return {"isValid": False, "error": MagicError(ErrorCode.TRANSACTION_NOT_FOUND)}
-            except AttributeError: return {"isValid": False, "error": MagicError(ErrorCode.PAYNODE_TRANSACTION_NOT_FOUND)}
+            return {"isValid": False, "error": PayNodeException("Transaction not found", ErrorCode.TRANSACTION_NOT_FOUND)}
         
         if receipt.get("status") == 0:
-            try: return {"isValid": False, "error": MagicError(ErrorCode.TRANSACTION_FAILED)}
-            except AttributeError: return {"isValid": False, "error": MagicError(ErrorCode.PAYNODE_TRANSACTION_FAILED)}
+            return {"isValid": False, "error": PayNodeException("Transaction failed", ErrorCode.TRANSACTION_FAILED)}
 
-        return {"isValid": True}
+        if not receipt.get("to") or receipt.get("to", "").lower() != self.contract_address.lower():
+            return {"isValid": False, "error": PayNodeException("Wrong contract", ErrorCode.WRONG_CONTRACT)}
+
+        contract = self.w3.eth.contract(address=Web3.to_checksum_address(self.contract_address), abi=PAYNODE_ROUTER_ABI)
+        
+        try:
+            logs = contract.events.PaymentReceived().process_receipt(receipt)
+        except Exception:
+            return {"isValid": False, "error": PayNodeException("Invalid receipt format", ErrorCode.INVALID_RECEIPT)}
+
+        if not logs:
+            return {"isValid": False, "error": PayNodeException("No valid PaymentReceived event found", ErrorCode.INVALID_RECEIPT)}
+
+        # Find the valid log
+        merchant = expected.get("merchantAddress", "").lower()
+        token = expected.get("tokenAddress", "").lower()
+        amount = int(expected.get("amount", 0))
+        
+        order_id_bytes = self.w3.keccak(text=expected.get("orderId", ""))
 
-class MagicError:
-    def __init__(self, code):
-        self.code = code
+        valid = False
+        for log in logs:
+            args = log.args
+            
+            if args.get("orderId") != order_id_bytes:
+                continue
+                
+            if args.get("merchant", "").lower() != merchant:
+                continue
+                
+            if args.get("token", "").lower() != token:
+                continue
+                
+            if args.get("amount", 0) < amount:
+                continue
+
+            if self.chain_id and args.get("chainId") != self.chain_id:
+                continue
+
+            valid = True
+            break
+
+        if not valid:
+            return {"isValid": False, "error": PayNodeException("Payment criteria mismatch", ErrorCode.INVALID_RECEIPT)}
+
+        return {"isValid": True}

paynode_sdk/webhook.py

@@ -0,0 +1,233 @@
+"""
+PayNode Webhook Notifier — monitors on-chain PaymentReceived events
+and delivers structured webhook POSTs to a merchant's endpoint.
+
+Features:
+- HMAC-SHA256 signature for authenticity (header: x-paynode-signature)
+- Configurable polling interval
+- Automatic retry with exponential backoff (3 attempts)
+- Async-first design
+"""
+
+import json
+import time
+import hmac
+import hashlib
+import logging
+import asyncio
+from typing import Optional, Callable, Dict, Any, List
+from web3 import Web3
+
+from .constants import PAYNODE_ROUTER_ABI, PAYNODE_ROUTER_ADDRESS
+from .errors import PayNodeException, ErrorCode
+
+logger = logging.getLogger("paynode_sdk.webhook")
+
+
+class PaymentEvent:
+    """Parsed PaymentReceived event data."""
+
+    def __init__(
+        self,
+        tx_hash: str,
+        block_number: int,
+        order_id: str,
+        merchant: str,
+        payer: str,
+        token: str,
+        amount: int,
+        fee: int,
+        chain_id: int,
+        timestamp: float
+    ):
+        self.tx_hash = tx_hash
+        self.block_number = block_number
+        self.order_id = order_id
+        self.merchant = merchant
+        self.payer = payer
+        self.token = token
+        self.amount = amount
+        self.fee = fee
+        self.chain_id = chain_id
+        self.timestamp = timestamp
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "txHash": self.tx_hash,
+            "blockNumber": self.block_number,
+            "orderId": self.order_id,
+            "merchant": self.merchant,
+            "payer": self.payer,
+            "token": self.token,
+            "amount": str(self.amount),
+            "fee": str(self.fee),
+            "chainId": str(self.chain_id),
+            "timestamp": self.timestamp,
+        }
+
+
+class PayNodeWebhookNotifier:
+    """
+    Monitors on-chain PaymentReceived events and delivers webhook notifications.
+
+    Usage:
+        notifier = PayNodeWebhookNotifier(
+            rpc_url="https://mainnet.base.org",
+            contract_address="0x92e20164FC457a2aC35f53D06268168e6352b200",
+            webhook_url="https://myshop.com/api/paynode-webhook",
+            webhook_secret="whsec_mysecretkey123",
+        )
+        await notifier.start()
+    """
+
+    def __init__(
+        self,
+        rpc_url: str,
+        webhook_url: str,
+        webhook_secret: str,
+        contract_address: Optional[str] = None,
+        chain_id: Optional[int] = None,
+        poll_interval_seconds: float = 5.0,
+        custom_headers: Optional[Dict[str, str]] = None,
+        on_error: Optional[Callable[[Exception, PaymentEvent], None]] = None,
+        on_success: Optional[Callable[[PaymentEvent], None]] = None,
+    ):
+        if not rpc_url:
+            raise ValueError("rpc_url is required")
+        if not webhook_url:
+            raise ValueError("webhook_url is required")
+        if not webhook_secret:
+            raise ValueError("webhook_secret is required")
+
+        self.contract_address = contract_address or PAYNODE_ROUTER_ADDRESS
+        self.w3 = Web3(Web3.HTTPProvider(rpc_url, request_kwargs={"timeout": 10}))
+        self.contract = self.w3.eth.contract(
+            address=Web3.to_checksum_address(self.contract_address),
+            abi=PAYNODE_ROUTER_ABI
+        )
+        self.webhook_url = webhook_url
+        self.webhook_secret = webhook_secret
+        self.chain_id = chain_id
+        self.poll_interval = poll_interval_seconds
+        self.custom_headers = custom_headers or {}
+        self.on_error = on_error
+        self.on_success = on_success
+
+        self._last_block: int = 0
+        self._running: bool = False
+        self._task: Optional[asyncio.Task] = None
+
+    async def start(self, from_block: Optional[int] = None) -> None:
+        """Start polling for PaymentReceived events."""
+        if self._running:
+            logger.warning("[PayNode Webhook] Already running.")
+            return
+
+        self._last_block = from_block if from_block is not None else self.w3.eth.block_number
+        self._running = True
+        logger.info(f"🔔 [PayNode Webhook] Listening from block {self._last_block} on {self.contract_address}")
+
+        self._task = asyncio.create_task(self._poll_loop())
+
+    async def stop(self) -> None:
+        """Stop polling."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+        logger.info("🔕 [PayNode Webhook] Stopped.")
+
+    async def _poll_loop(self) -> None:
+        """Main polling loop."""
+        while self._running:
+            try:
+                current_block = self.w3.eth.block_number
+                if current_block > self._last_block:
+                    events = self.contract.events.PaymentReceived().get_logs(
+                        fromBlock=self._last_block + 1,
+                        toBlock=current_block
+                    )
+                    for event in events:
+                        payment = self._parse_event(event)
+                        if payment:
+                            await self._deliver(payment)
+
+                    self._last_block = current_block
+            except Exception as e:
+                logger.error(f"[PayNode Webhook] Poll error: {e}")
+
+            await asyncio.sleep(self.poll_interval)
+
+    def _parse_event(self, event) -> Optional[PaymentEvent]:
+        """Parse a web3 event log into a PaymentEvent."""
+        try:
+            args = event.args
+            return PaymentEvent(
+                tx_hash=event.transactionHash.hex() if hasattr(event.transactionHash, 'hex') else str(event.transactionHash),
+                block_number=event.blockNumber,
+                order_id=args.get("orderId", b"").hex() if isinstance(args.get("orderId"), bytes) else str(args.get("orderId", "")),
+                merchant=args.get("merchant", ""),
+                payer=args.get("payer", ""),
+                token=args.get("token", ""),
+                amount=args.get("amount", 0),
+                fee=args.get("fee", 0),
+                chain_id=args.get("chainId", 0),
+                timestamp=time.time(),
+            )
+        except Exception as e:
+            logger.error(f"[PayNode Webhook] Failed to parse event: {e}")
+            return None
+
+    async def _deliver(self, event: PaymentEvent, attempt: int = 1) -> None:
+        """Deliver webhook POST with HMAC signature and retry logic."""
+        import aiohttp  # lazy import to keep dependency optional
+
+        MAX_RETRIES = 3
+
+        payload = json.dumps({
+            "event": "payment.received",
+            "data": event.to_dict()
+        })
+
+        signature = hmac.new(
+            self.webhook_secret.encode("utf-8"),
+            payload.encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        headers = {
+            "Content-Type": "application/json",
+            "x-paynode-signature": f"sha256={signature}",
+            "x-paynode-event": "payment.received",
+            "x-paynode-delivery-id": f"{event.tx_hash}-{attempt}",
+            **self.custom_headers,
+        }
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(self.webhook_url, data=payload, headers=headers, timeout=aiohttp.ClientTimeout(total=10)) as resp:
+                    if resp.status >= 400:
+                        raise PayNodeException(
+                            f"Webhook returned {resp.status}",
+                            ErrorCode.INTERNAL_ERROR
+                        )
+
+                    logger.info(f"✅ [PayNode Webhook] Delivered tx {event.tx_hash[:10]}... → {resp.status}")
+                    if self.on_success:
+                        self.on_success(event)
+
+        except Exception as e:
+            logger.error(f"[PayNode Webhook] Delivery failed (attempt {attempt}/{MAX_RETRIES}): {e}")
+
+            if attempt < MAX_RETRIES:
+                backoff = (2 ** attempt)  # 2s, 4s, 8s
+                await asyncio.sleep(backoff)
+                return await self._deliver(event, attempt + 1)
+
+            logger.error(f"[PayNode Webhook] Gave up on tx {event.tx_hash} after {MAX_RETRIES} attempts.")
+            if self.on_error:
+                self.on_error(e, event)

paynode_sdk_python-1.1.1.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: paynode-sdk-python
+Version: 1.1.1
+Summary: PayNode Protocol Python SDK for AI Agents
+Author-email: PayNodeLabs <contact@paynode.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/PayNodeLabs/paynode-sdk-python
+Keywords: paynode,x402,base,agentic-web3,payments
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: web3>=6.15.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: fastapi>=0.111.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: responses>=0.23.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Dynamic: license-file
+
+# PayNode Python SDK
+
+[![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**. PayNode allows autonomous AI Agents to seamlessly pay for APIs and computational resources using USDC on Base L2, utilizing the standardized HTTP 402 protocol.
+
+## 📖 Read the Docs
+
+**For complete installation guides, advanced usage, API references, and architecture details, please visit our official documentation:**
+👉 **[docs.paynode.dev](https://docs.paynode.dev)**
+
+## ⚡ Quick Start
+
+### Installation
+
+```bash
+pip install paynode-sdk-python web3
+```
+
+### Agent Client (Payer)
+
+```python
+from paynode_sdk import PayNodeAgentClient
+
+agent = PayNodeAgentClient(
+    private_key="YOUR_AGENT_PRIVATE_KEY",
+    rpc_urls=["https://mainnet.base.org", "https://rpc.ankr.com/base"]
+)
+
+# Automatically handles the 402 challenge, executes the Base L2 transaction, and gets the data.
+response = agent.request_gate("https://api.merchant.com/premium-data", method="POST", json={"agent": "PythonAgent"})
+
+print(response.json())
+```
+
+## 🚀 Run the Demo
+
+The SDK includes a complete Merchant/Agent demo in the `examples/` directory.
+
+### 1. Setup Environment
+
+Copy the example environment file and fill in your keys:
+
+```bash
+cp .env.example .env
+# Edit .env with your private key and RPC URLs
+```
+
+### 2. Run the Merchant Server (FastAPI)
+
+```bash
+python examples/fastapi_server.py
+```
+
+### 3. Run the Agent Client
+
+In another terminal:
+
+```bash
+python examples/agent_client.py
+```
+
+The demo will perform a full loop: `402 Handshake -> On-chain Payment -> 200 Verification`.
+
+---
+
+## 📦 Publishing to PyPI
+
+To publish a new version of the SDK:
+
+1. **Install build tools**:
+   ```bash
+   pip install build twine
+   ```
+2. **Build the package**:
+   ```bash
+   python -m build
+   ```
+3. **Upload to PyPI**:
+   ```bash
+   python -m twine upload dist/*
+   ```
+
+---
+
+_Built for the Autonomous AI Economy by PayNodeLabs._

paynode_sdk_python-1.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+paynode_sdk/__init__.py,sha256=p6URBqxFz1AErG7rIRWKnfwnzAC19qrMURtG7YhVR1I,821
+paynode_sdk/client.py,sha256=jseyOrGPq7VQdufScIQsxrEEwK2WWoIQdEmGOfkTEls,10584
+paynode_sdk/constants.py,sha256=puqz09qeKcMoigWrqdIzkhtAzFpECxEwHGLvDd3U_CQ,1429
+paynode_sdk/errors.py,sha256=GN0qycgjATT47dF4yZ6Ulg18jf2OwholvYl0pgCvuzo,1121
+paynode_sdk/idempotency.py,sha256=od7HuSxFdejBP0oE4QCzbJdrDZWvziiu09d3BRErU2k,999
+paynode_sdk/middleware.py,sha256=Hi7dgbDy_moVnHl8f31YPsl_a3mSygIDAb_nCO9CMLY,3519
+paynode_sdk/verifier.py,sha256=rIjRxPZDSWKbf9ghfCu5JJ7Q8oPy0SQprgZWxQiggEg,4795
+paynode_sdk/webhook.py,sha256=KxlXGkXe3wpR8ueO8FMW2iypJgWaLwMfxAAZLNRvNDo,8302
+paynode_sdk_python-1.1.1.dist-info/licenses/LICENSE,sha256=U8RjGlEBtXN6PA-qN_N3Uh60jyu3qe26ZBmgt-LAHc4,1069
+paynode_sdk_python-1.1.1.dist-info/METADATA,sha256=G-9GKKJuNBK6Zz2MwcMDDJpAm2b-LvDjKR3VMQyvHLQ,2858
+paynode_sdk_python-1.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+paynode_sdk_python-1.1.1.dist-info/top_level.txt,sha256=c6Skc1Xx-9O-JJ7sHghLW8Kyn4hyJoVPUawH1Mu8iTU,12
+paynode_sdk_python-1.1.1.dist-info/RECORD,,

paynode_sdk_python-1.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PayNode Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paynode_sdk_python-1.0.1.dist-info/METADATA

@@ -1,85 +0,0 @@
-Metadata-Version: 2.4
-Name: paynode-sdk-python
-Version: 1.0.1
-Summary: PayNode Protocol Python SDK for AI Agents
-Author-email: PayNodeLabs <contact@paynode.dev>
-License: MIT
-Project-URL: Homepage, https://github.com/PayNodeLabs/paynode-sdk-python
-Keywords: paynode,x402,base,agentic-web3,payments
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.31.0
-Requires-Dist: web3>=6.15.0
-Requires-Dist: python-dotenv>=1.0.1
-
-# PayNode Python SDK
-
-为 Python 开发者提供的 PayNode 支付网关 SDK，支持 FastAPI、Flask 等主流 Web 框架。实现 M2M 场景下的 x402 握手与链上支付验证。
-
-## 📦 安装
-
-```bash
-pip install paynode-sdk
-```
-
-## 🚀 FastAPI Middleware 初始化示例
-
-通过注入 `PayNodeMiddleware`，您可以轻松地将任何 API 端点转变为收费接口。
-
-```python
-from fastapi import FastAPI, Request
-from paynode_sdk import PayNodeMiddleware
-
-app = FastAPI()
-
-# 1. 初始化 PayNode 中间件
-paynode = PayNodeMiddleware(
-    rpc_url="https://mainnet.base.org",           # RPC 节点地址
-    contract_address="0x...",                     # PayNodeRouter 合约地址
-    merchant_address="0x...",                     # 商家收款钱包地址
-    chain_id=8453,                                # 链 ID (Base: 8453)
-    currency="USDC",                              # 计价单位
-    token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", # USDC 地址
-    price="0.01",                                 # 每次调用的价格
-    decimals=6                                    # 代币精度
-)
-
-# 2. 挂载中间件
-@app.middleware("http")
-async def paynode_gate(request: Request, call_next):
-    # 此中间件会自动处理 402 握手及 x-paynode-receipt 验证
-    return await paynode(request, call_next)
-
-# 3. 受保护的路由
-@app.get("/api/ai-vision")
-async def ai_feature():
-    return {"message": "Success! The agent has paid for this API call."}
-```
-
-## 🧪 测试与开发
-
-SDK 采用严谨的代码审计标准，所有核心逻辑均经过多层验证。
-
-### 运行测试
-
-使用 `pytest` 运行测试套件。确保已配置 `PYTHONPATH` 以正确加载本地包。
-
-```bash
-# 运行所有验证逻辑测试
-PYTHONPATH=. pytest tests/
-```
-
-### 开发模式
-
-如果需要修改 `paynode_sdk` 并即时测试：
-
-```bash
-pip install -e .
-```
-
-## ⚙️ 验证逻辑详解 (Verifier)
-
-`PayNodeVerifier` 直接通过 Web3.py 与以太坊节点交互。验证过程包括：
-- **交易状态确认:** 检查交易哈希是否已上链并成功 (Status 1)。
-- **合约交互验证:** 解析交易数据，确认其调用的是 `PayNodeRouter` 的 `pay` 函数。
-- **金额与代币校验:** 严格匹配转账金额与指定的代币地址，防止恶意 Agent 使用虚假代币支付。
-- **商户一致性:** 确认资金最终流向了预设的商户钱包。

paynode_sdk_python-1.0.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-paynode_sdk/__init__.py,sha256=qIoMcnfe3dviK6E3E0yMYukuvbO3Nmv0Cpuaeptgx3s,325
-paynode_sdk/client.py,sha256=3_Rux6DZyR6dABLjYaAtBmBtPczlLVpyvuDXc6UzFuQ,4933
-paynode_sdk/constants.py,sha256=1WHbiwQSrSUI6jj4xo7ISak_X0eDZMgFnCbeLzUl3JM,309
-paynode_sdk/errors.py,sha256=ZiuYEvP8zMXpfmi3VEdGyBX3VXqj4TdrRS-WucrdSew,977
-paynode_sdk/idempotency.py,sha256=od7HuSxFdejBP0oE4QCzbJdrDZWvziiu09d3BRErU2k,999
-paynode_sdk/middleware.py,sha256=dg3hSmHAjW8wTF3AH3id8LFxbN2kXKKUsBRp1gyc6qw,3292
-paynode_sdk/verifier.py,sha256=YkYUBgt5RPXigZsHNvdcca290YQyoOVijIa6f5SlHLw,1572
-paynode_sdk_python-1.0.1.dist-info/METADATA,sha256=EcJUyKLTNco58bzxeuzOEd73Fvp3ScRS8SsVYwB9OHk,2852
-paynode_sdk_python-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-paynode_sdk_python-1.0.1.dist-info/top_level.txt,sha256=c6Skc1Xx-9O-JJ7sHghLW8Kyn4hyJoVPUawH1Mu8iTU,12
-paynode_sdk_python-1.0.1.dist-info/RECORD,,