agentpayments-python 0.1.0__py3-none-any.whl

agentpayments_python/solana.py

@@ -0,0 +1,196 @@
+import json
+import logging
+import re
+import threading
+import time as _time
+from collections import OrderedDict
+from pathlib import Path
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+PAYMENT_CACHE_TTL = 10 * 60      # 10 minutes in seconds
+NEGATIVE_CACHE_TTL = 30          # 30 seconds for negative results
+PAYMENT_CACHE_MAX = 1000
+
+
+class _PaymentCache:
+    """Caches both positive (True) and negative (False) payment results with per-entry TTLs."""
+
+    def __init__(self, max_size: int = PAYMENT_CACHE_MAX):
+        self.max_size = max_size
+        # stores (value: bool, ts: float, ttl: int)
+        self._cache: OrderedDict[str, tuple[bool, float, int]] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def get(self, key: str):
+        """Returns True, False, or None (not cached / expired)."""
+        with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return None
+            value, ts, ttl = entry
+            if _time.time() - ts > ttl:
+                del self._cache[key]
+                return None
+            return value
+
+    def set(self, key: str, value: bool, ttl: int) -> None:
+        with self._lock:
+            if len(self._cache) >= self.max_size:
+                self._cache.popitem(last=False)
+            self._cache[key] = (value, _time.time(), ttl)
+
+
+_payment_cache = _PaymentCache()
+
+BASE58_RE = re.compile(r"^[1-9A-HJ-NP-Za-km-z]{32,44}$")
+
+_constants = json.loads((Path(__file__).resolve().parent / "constants.json").read_text())
+MIN_PAYMENT_MICRO = round(_constants["MIN_PAYMENT"] * 1_000_000)  # integer micro-USDC threshold
+USDC_MINT_DEVNET = _constants["USDC_MINT_DEVNET"]
+USDC_MINT_MAINNET = _constants["USDC_MINT_MAINNET"]
+RPC_DEVNET = _constants["RPC_DEVNET"]
+RPC_MAINNET = _constants["RPC_MAINNET"]
+MEMO_PROGRAM = _constants["MEMO_PROGRAM"]
+MIN_PAYMENT = _constants["MIN_PAYMENT"]
+MAX_TRANSACTIONS_PER_VERIFY = _constants["MAX_TRANSACTIONS_PER_VERIFY"]
+
+
+def _rpc_call(rpc_url: str, method: str, params: list, retries: int = 2, backoff: float = 0.3) -> dict:
+    last_error: Exception = RuntimeError("RPC call failed before any attempt")
+    for attempt in range(retries + 1):
+        if attempt > 0:
+            import time as _sleep_time
+            _sleep_time.sleep(backoff * attempt)
+        try:
+            resp = requests.post(rpc_url, json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params}, timeout=30)
+            # Only retry on 5xx (transient server errors); 4xx are permanent.
+            if resp.status_code >= 500:
+                last_error = requests.HTTPError(f"RPC {method} failed: {resp.status_code}", response=resp)
+                continue
+            resp.raise_for_status()
+            return resp.json()
+        except requests.HTTPError:
+            raise  # permanent 4xx — don't retry
+        except Exception as exc:
+            last_error = exc
+    raise last_error
+
+
+def _rpc_call_with_fallback(rpc_urls: list[str], method: str, params: list, **kwargs) -> dict:
+    """Try each RPC URL in order; move to the next on network/5xx failure."""
+    last_error: Exception = RuntimeError("No RPC URLs provided")
+    for url in rpc_urls:
+        try:
+            return _rpc_call(url, method, params, **kwargs)
+        except Exception as exc:
+            last_error = exc
+            if len(rpc_urls) > 1:
+                logger.warning("[gate] RPC endpoint failed, trying fallback: url=%s error=%s", url, exc)
+    raise last_error
+
+
+def is_valid_solana_address(address: str) -> bool:
+    return bool(address and BASE58_RE.match(address))
+
+
+def verify_payment_on_chain(agent_key: str, wallet_address: str, rpc_url, usdc_mint: str) -> bool:
+    """Verify payment on-chain. rpc_url may be a string or list of strings (fallback URLs)."""
+    # Normalise to list so _rpc_call_with_fallback always gets a list.
+    rpc_urls: list[str] = rpc_url if isinstance(rpc_url, list) else [rpc_url]
+
+    cached = _payment_cache.get(agent_key)
+    if cached is True:
+        return True
+    if cached is False:
+        return False  # negative cached — skip RPC until TTL expires
+    if not is_valid_solana_address(wallet_address):
+        logger.error("[gate] Invalid wallet address: %s", wallet_address)
+        return False
+    try:
+        # commitment: 'finalized' — confirmed blocks can be rolled back (rare but possible).
+        # Finalized adds ~10-20 s latency vs confirmed but guarantees irreversibility.
+        ata_data = _rpc_call_with_fallback(rpc_urls, "getTokenAccountsByOwner", [wallet_address, {"mint": usdc_mint}, {"encoding": "jsonParsed", "commitment": "finalized"}])
+        token_accounts = [a["pubkey"] for a in ata_data.get("result", {}).get("value", [])]
+        # Only transfers landing in one of the vendor's USDC token accounts count as
+        # payment. Token accounts are mint-bound, so membership also guarantees the
+        # token is USDC for plain `transfer` instructions (which carry no mint field).
+        vendor_usdc_accounts = set(token_accounts)
+        if not vendor_usdc_accounts:
+            return False  # vendor has no USDC account yet — no payment possible
+
+        addresses_to_scan = [wallet_address] + token_accounts
+        seen = set()
+        all_signatures = []
+
+        for addr in addresses_to_scan:
+            sigs_data = _rpc_call_with_fallback(rpc_urls, "getSignaturesForAddress", [addr, {"limit": 100, "commitment": "finalized"}])
+            for sig in sigs_data.get("result", []):
+                if sig["signature"] not in seen:
+                    seen.add(sig["signature"])
+                    all_signatures.append(sig)
+
+        tx_call_count = 0
+        for sig_info in all_signatures:
+            if tx_call_count >= MAX_TRANSACTIONS_PER_VERIFY:
+                logger.warning("[gate] getTransaction cap reached (key=%s..., cap=%d)", agent_key[:12], MAX_TRANSACTIONS_PER_VERIFY)
+                break
+            if sig_info.get("err"):
+                continue
+            tx_call_count += 1
+
+            tx_data = _rpc_call_with_fallback(rpc_urls, "getTransaction", [sig_info["signature"], {"encoding": "jsonParsed", "commitment": "finalized", "maxSupportedTransactionVersion": 0}])
+            tx = tx_data.get("result")
+            if not tx:
+                continue
+
+            instructions = tx.get("transaction", {}).get("message", {}).get("instructions", [])
+            inner_instructions = tx.get("meta", {}).get("innerInstructions", [])
+            all_ix = list(instructions)
+            for group in inner_instructions:
+                all_ix.extend(group.get("instructions", []))
+
+            has_memo = False
+            has_payment = False
+
+            for ix in all_ix:
+                program = ix.get("program", "")
+                program_id = ix.get("programId", "")
+                if program == "spl-memo" or program_id == MEMO_PROGRAM:
+                    parsed = ix.get("parsed", "")
+                    memo_text = parsed if isinstance(parsed, str) else str(parsed)
+                    if agent_key in memo_text:
+                        has_memo = True
+
+                if program == "spl-token":
+                    parsed = ix.get("parsed", {})
+                    tx_type = parsed.get("type", "")
+                    if tx_type in ("transfer", "transferChecked"):
+                        info = parsed.get("info", {})
+                        # Payment must be delivered to one of the vendor's USDC token accounts.
+                        if info.get("destination") not in vendor_usdc_accounts:
+                            continue
+                        if tx_type == "transferChecked" and info.get("mint") != usdc_mint:
+                            continue
+                        # Integer base-unit comparison — avoids float precision issues at
+                        # the payment threshold. tokenAmount.amount and amount are both
+                        # integer strings in micro-USDC (base units).
+                        token_amount = info.get("tokenAmount") or {}
+                        amount_str = token_amount.get("amount") or info.get("amount", "0")
+                        try:
+                            amount_micro = int(amount_str)
+                        except (ValueError, TypeError):
+                            amount_micro = 0
+                        if amount_micro >= MIN_PAYMENT_MICRO:
+                            has_payment = True
+
+            if has_memo and has_payment:
+                _payment_cache.set(agent_key, True, PAYMENT_CACHE_TTL)
+                return True
+    except Exception:
+        logger.exception("[gate] Solana RPC error")
+
+    _payment_cache.set(agent_key, False, NEGATIVE_CACHE_TTL)
+    return False

agentpayments_python/x402.py

@@ -0,0 +1,84 @@
+"""
+x402 protocol compatibility helpers.
+
+Builds x402-standard PaymentRequirements objects and the X-PAYMENT-REQUIRED
+header value so that x402-aware AI agent clients can parse the payment
+requirements from our 402 responses.
+
+Spec: https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_svm.md
+"""
+import base64
+import json as _json
+import math
+from pathlib import Path as _Path
+
+_constants = _json.loads((_Path(__file__).resolve().parent / "constants.json").read_text())
+
+USDC_DECIMALS: int = _constants["USDC_DECIMALS"]
+X402_VERSION: int = _constants["X402_VERSION"]
+SOLANA_CHAIN_ID_MAINNET: str = _constants["SOLANA_CHAIN_ID_MAINNET"]
+SOLANA_CHAIN_ID_DEVNET: str = _constants["SOLANA_CHAIN_ID_DEVNET"]
+
+
+def build_payment_requirements(
+    *,
+    wallet_address: str,
+    mint: str,
+    min_payment: float,
+    debug: bool,
+    agent_key: str = "",
+    resource: str = "",
+) -> dict:
+    """
+    Build an x402-standard PaymentRequirements dict for the Solana exact scheme.
+
+    Args:
+        wallet_address: Merchant wallet public key (payTo).
+        mint:           USDC mint address.
+        min_payment:    Human-readable amount (e.g. 0.01 for 0.01 USDC).
+        debug:          True → use devnet chain ID.
+        agent_key:      If set, included as extra.memo so x402 clients know
+                        which key to reference in their transaction memo.
+        resource:       URL path of the gated resource (optional).
+
+    Returns:
+        PaymentRequirements dict per the x402 SVM exact scheme spec.
+    """
+    chain_id = SOLANA_CHAIN_ID_DEVNET if debug else SOLANA_CHAIN_ID_MAINNET
+    base_units = str(math.floor(min_payment * (10 ** USDC_DECIMALS) + 0.5))  # round half-up
+    req: dict = {
+        "scheme": "exact",
+        "network": chain_id,
+        "amount": base_units,
+        "asset": mint,
+        "payTo": wallet_address,
+        "maxTimeoutSeconds": 300,
+        "extra": {
+            "name": "USDC",
+            "decimals": USDC_DECIMALS,
+            **({"memo": agent_key} if agent_key else {}),
+        },
+    }
+    if resource:
+        req["resource"] = resource
+    return req
+
+
+def payment_required_header(payment_requirements: dict) -> str:
+    """
+    Return the value for the X-PAYMENT-REQUIRED response header.
+    The spec requires the PaymentRequirements to be base64-encoded JSON.
+    """
+    return base64.b64encode(_json.dumps(payment_requirements).encode()).decode()
+
+
+def enrich_402_body(body: dict, payment_requirements: dict) -> dict:
+    """
+    Prepend x402Version and accepts[] to a 402 response body dict,
+    keeping all existing fields for backward compatibility.
+    """
+    return {
+        "x402Version": X402_VERSION,
+        "accepts": [payment_requirements],
+        **body,
+    }

agentpayments_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: agentpayments-python
+Version: 0.1.0
+Summary: AgentPayments gate for Python web frameworks — charge AI agents USDC on Solana before they can access your API
+License: MIT
+Project-URL: Homepage, https://github.com/adambrzosko/AgentPayments
+Project-URL: Documentation, https://github.com/adambrzosko/AgentPayments/tree/main/sdk/python
+Project-URL: Repository, https://github.com/adambrzosko/AgentPayments
+Project-URL: Bug Tracker, https://github.com/adambrzosko/AgentPayments/issues
+Keywords: agentpayments,ai-agents,solana,usdc,payments,middleware,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: django
+Requires-Dist: Django>=5.0; extra == "django"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Requires-Dist: starlette>=0.37; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == "flask"
+Provides-Extra: all
+Requires-Dist: Django>=5.0; extra == "all"
+Requires-Dist: fastapi>=0.110; extra == "all"
+Requires-Dist: starlette>=0.37; extra == "all"
+Requires-Dist: flask>=3.0; extra == "all"
+Dynamic: license-file
+
+# agentpayments-python
+
+Python adapters for the AgentPayments gate. Supports Django, FastAPI/Starlette, and Flask.
+
+## Install
+
+```bash
+pip install agentpayments-python
+# or, in this monorepo:
+# pip install -e sdk/python
+```
+
+## Django
+
+```python
+# settings.py
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "agentpayments_python.django_adapter.GateMiddleware",
+    # ... other middleware
+]
+
+# Required settings
+CHALLENGE_SECRET = os.environ["CHALLENGE_SECRET"]
+HOME_WALLET_ADDRESS = os.environ["HOME_WALLET_ADDRESS"]
+
+# Optional settings
+SOLANA_RPC_URL = os.environ.get("SOLANA_RPC_URL")
+USDC_MINT = os.environ.get("USDC_MINT")
+DEBUG = True  # True = devnet, False = mainnet
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from agentpayments_python.fastapi_adapter import (
+    AgentPaymentsASGIMiddleware,
+    challenge_verify_endpoint,
+)
+
+app = FastAPI()
+
+app.add_middleware(
+    AgentPaymentsASGIMiddleware,
+    challenge_secret=os.environ["CHALLENGE_SECRET"],
+    home_wallet_address=os.environ["HOME_WALLET_ADDRESS"],
+    debug=True,
+)
+
+@app.post("/__challenge/verify")
+async def verify(request: Request):
+    return await challenge_verify_endpoint(
+        request,
+        challenge_secret=os.environ["CHALLENGE_SECRET"],
+    )
+```
+
+## Flask
+
+```python
+from flask import Flask
+from agentpayments_python.flask_adapter import register_agentpayments
+
+app = Flask(__name__)
+register_agentpayments(
+    app,
+    challenge_secret=os.environ["CHALLENGE_SECRET"],
+    home_wallet_address=os.environ["HOME_WALLET_ADDRESS"],
+    debug=True,
+)
+```
+
+## Configuration
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `challenge_secret` | Yes (production) | `'default-secret-change-me'` | HMAC secret for signing cookies, nonces, and agent keys. |
+| `home_wallet_address` | Yes | `''` | Solana wallet address to receive USDC payments. |
+| `solana_rpc_url` | No | Auto (devnet/mainnet) | Custom Solana RPC endpoint. |
+| `usdc_mint` | No | Auto (devnet/mainnet) | Custom USDC mint address. |
+| `debug` | No | `True` | `True` = devnet. `False` = mainnet + strict mode. |
+
+Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`). FastAPI and Flask accept them as constructor arguments.
+
+## Security Features
+
+- **Timing-safe HMAC comparison** — uses `hmac.compare_digest()` for all signature checks
+- **Payment verification cache** — 10-minute TTL, 1000-entry max (thread-safe)
+- **Rate limiting** — 20 challenge verifications per minute per IP (thread-safe)
+- **Input size limits** — key (64 chars), nonce (128), return URL (2048), fingerprint (128)
+- **Wallet address validation** — base58 format, 32-44 chars, validated at init
+- **Default secret detection** — warns in debug, raises `RuntimeError` in production
+- **Secure cookies** — Django auto-detects HTTPS via `request.is_secure()`
+
+## Module Structure
+
+```
+agentpayments_python/
+  __init__.py
+  django_adapter.py      Django middleware (GateMiddleware)
+  fastapi_adapter.py     FastAPI/Starlette ASGI middleware
+  flask_adapter.py       Flask integration (before_request hook)
+  challenge.py           Shared challenge HTML generation
+  cookies.py             Cookie creation and validation
+  crypto.py              HMAC signing and agent key management
+  detection.py           Browser detection and public path checks
+  solana.py              On-chain payment verification + caching
+  ratelimit.py           Shared IP-based rate limiter
+```
+
+## Notes
+- Constants loaded from `sdk/constants.json` via `pathlib`.
+- Logging uses Python stdlib `logging` module.
+- All shared modules are framework-agnostic; adapters are thin wiring.

agentpayments_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+agentpayments_python/__init__.py,sha256=-_ZaZGRDrd1kueJ5wvc4A4P_wt6QOchSG9gLK_BKlH4,952
+agentpayments_python/challenge.py,sha256=feWqlTcQ1LMONuwFBUOQBQOw5tsO1f7PirZZN_S3e3A,6386
+agentpayments_python/constants.json,sha256=ZlhvktuiaziGsxedn4PugWi2RXhliK3uCWAIkAeU6Qg,979
+agentpayments_python/cookies.py,sha256=0xO2_e4R4FpOprBcGWqY84E_eJppgJCkMGLCElZOQ90,1244
+agentpayments_python/crawler.py,sha256=G06nF6qFmyA5nDvMW18rfh44JxxJMKc2GCO0DXiZuoY,2514
+agentpayments_python/crypto.py,sha256=81xNcH1E468v26BimEQpK6n42bkqyz4q6eXhLLqQ6QY,1315
+agentpayments_python/detection.py,sha256=8_RqNwF5C3TYnJkB2rO6Bs6vhBvgW4MNS3u7WTw1TCM,1292
+agentpayments_python/django_adapter.py,sha256=aSCnzIAK9P-Ph0djssg1aYPRpGDiOgsRvJTopEJN7WQ,12516
+agentpayments_python/fastapi_adapter.py,sha256=AUdDLEGyk9D_rqpmzAAwTHvAcxVVzawrTyrBpKg7RA0,11779
+agentpayments_python/flask_adapter.py,sha256=r6l94yID5pmCv64mFf7mj25UwmHhtsiLQYcJQvXfkMQ,10116
+agentpayments_python/grant_store.py,sha256=wqRsSdbpzd_TGy6a6LJRtNOMbjVBJQm7H3qpIVHEeuw,2643
+agentpayments_python/platform_client.py,sha256=PgjqriOKxfUM0_hEdwKrWRN34M3QcvSfCsv-APMiwW0,3996
+agentpayments_python/ratelimit.py,sha256=Q6uxFRbYbf7D8qykZ9ieVaSCU8FkXFYPS59XmkrnE_k,1580
+agentpayments_python/solana.py,sha256=TxJndushbLEM3oJtOBl6tzY8NG3pkVsbIU3wYLmw91U,8707
+agentpayments_python/x402.py,sha256=IAqWhjqo7rDX0Bf0_sDi4RlFE7PwwvY3WN39fjT7kjw,2775
+agentpayments_python-0.1.0.dist-info/licenses/LICENSE,sha256=PMKDe4kanHRVI7QQezG4GeluZkMljhVO-tFSFNUiYS4,1069
+agentpayments_python-0.1.0.dist-info/METADATA,sha256=BFzUDa3Jujc5JSM0v9xq7OQqppuEbrUpZO-CaUz_ETI,5327
+agentpayments_python-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentpayments_python-0.1.0.dist-info/top_level.txt,sha256=DxGMGvTYQVdoBQ6pBbbsJXy5BZhbSjNGF_uSO3git4w,21
+agentpayments_python-0.1.0.dist-info/RECORD,,

agentpayments_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentpayments_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Brzosko
+
+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.

agentpayments_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentpayments_python