agentpayments-python 0.2.0__tar.gz → 0.3.0__tar.gz

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpayments-python
-Version: 0.2.0
+Version: 0.3.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
@@ -123,6 +123,9 @@ register_agentpayments(
 | `debug` | No | `True` | `True` = devnet. `False` = mainnet + strict mode. |
 | `api_key` | No | `None` | AgentPayments hosted-platform API key (`ap_live_...`). When set, agent keys are issued and metered via the platform instead of self-signed locally. See **Hosted Platform Mode** below. |
 | `platform_url` | No | AgentPayments-hosted URL | Override for a self-hosted platform API. |
+| `agent_key_rate_limiter` | No | Built-in in-memory (10/min/IP) | Pluggable rate limiter for the agent-key payment-verification path. Pass a Redis-backed one for multi-process deployments — see **Multi-Process Deployments** below. |
+| `challenge_issue_rate_limiter` | No | Built-in in-memory (30/min/IP) | Pluggable rate limiter for browser challenge-page issuance. |
+| `payment_cache` | No | Module-level in-memory singleton | Pluggable payment-verification cache (10-min positive / 30s negative TTL by default). |
 
 Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`, `settings.AGENTPAYMENTS_API_KEY`). FastAPI and Flask accept them as constructor arguments.
 
@@ -164,6 +167,38 @@ AGENTPAYMENTS_ROUTES = [...]
 
 **Revocation**: `MemoryGrantStore`/`FileGrantStore` (`agentpayments_python.grant_store`) both gained a `revoke(agent_key)` method — call it from your own admin view to cut off a specific paid key early. The adapters need no changes to respect this: `has()` already returns `False` for a revoked (or expired) grant. A grants file written by an older SDK version (a plain JSON array of key strings) is still read correctly as a set of permanent grants.
 
+## Multi-Process Deployments (Redis)
+
+The built-in rate limiters and payment cache are in-memory and **per-process** — with `gunicorn -w 4`, each of the 4 workers enforces its own independent 10-req/min agent-key limit (40/min in aggregate) and caches payment results separately, so a payment verified by one worker isn't recognized by another until its own cache/rate-limit state catches up. For any multi-process deployment, plug in a Redis-backed store instead:
+
+```python
+import redis
+from agentpayments_python.redis_store import create_redis_store
+
+r = redis.Redis.from_url(os.environ["REDIS_URL"])
+store = create_redis_store(r)
+
+# FastAPI / Flask
+register_agentpayments(app, ...,  # or AgentPaymentsASGIMiddleware(...)
+    agent_key_rate_limiter=store["agent_key_rate_limiter"],
+    challenge_issue_rate_limiter=store["challenge_issue_rate_limiter"],
+    payment_cache=store["payment_cache"],
+)
+
+# Django settings.py
+AGENTPAYMENTS_AGENT_KEY_RATE_LIMITER = store["agent_key_rate_limiter"]
+AGENTPAYMENTS_CHALLENGE_ISSUE_RATE_LIMITER = store["challenge_issue_rate_limiter"]
+AGENTPAYMENTS_PAYMENT_CACHE = store["payment_cache"]
+
+# The /__challenge/verify endpoint has its own rate limiter, passed separately
+# since it's a standalone route/view rather than the main middleware:
+#   FastAPI: challenge_verify_endpoint(request, challenge_secret=..., rate_limiter=store["challenge_verify_rate_limiter"])
+#   Django:  AGENTPAYMENTS_CHALLENGE_VERIFY_RATE_LIMITER = store["challenge_verify_rate_limiter"]
+#   Flask:   register_agentpayments(app, ..., challenge_verify_rate_limiter=store["challenge_verify_rate_limiter"])
+```
+
+`redis_store.py` has no hard dependency on the `redis` package — it's duck-typed against any client exposing `eval(script, numkeys, *args)`, `get(key)`, and `set(key, value, ex=ttl)` (redis-py's `Redis` client satisfies this directly), mirroring `sdk/node/redis-store.js`. Rate limiting fails open on a Redis error (never blocks legitimate traffic); the payment cache fails to a miss (falls through to a normal chain scan). All four are optional — anything left unset keeps using the default in-memory implementation.
+
 ## Security Features
 
 - **Timing-safe HMAC comparison** — uses `hmac.compare_digest()` for all signature checks
@@ -190,6 +225,7 @@ agentpayments_python/
   ratelimit.py           Shared IP-based rate limiter
   grant_store.py         Durable paid-key persistence (expiry, revocation)
   pricing.py             Pricing-tier / access-duration / per-route resolution
+  redis_store.py         Redis-backed rate limiter + payment cache (multi-process)
 ```
 
 ## Notes

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/README.md

@@ -86,6 +86,9 @@ register_agentpayments(
 | `debug` | No | `True` | `True` = devnet. `False` = mainnet + strict mode. |
 | `api_key` | No | `None` | AgentPayments hosted-platform API key (`ap_live_...`). When set, agent keys are issued and metered via the platform instead of self-signed locally. See **Hosted Platform Mode** below. |
 | `platform_url` | No | AgentPayments-hosted URL | Override for a self-hosted platform API. |
+| `agent_key_rate_limiter` | No | Built-in in-memory (10/min/IP) | Pluggable rate limiter for the agent-key payment-verification path. Pass a Redis-backed one for multi-process deployments — see **Multi-Process Deployments** below. |
+| `challenge_issue_rate_limiter` | No | Built-in in-memory (30/min/IP) | Pluggable rate limiter for browser challenge-page issuance. |
+| `payment_cache` | No | Module-level in-memory singleton | Pluggable payment-verification cache (10-min positive / 30s negative TTL by default). |
 
 Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`, `settings.AGENTPAYMENTS_API_KEY`). FastAPI and Flask accept them as constructor arguments.
 
@@ -127,6 +130,38 @@ AGENTPAYMENTS_ROUTES = [...]
 
 **Revocation**: `MemoryGrantStore`/`FileGrantStore` (`agentpayments_python.grant_store`) both gained a `revoke(agent_key)` method — call it from your own admin view to cut off a specific paid key early. The adapters need no changes to respect this: `has()` already returns `False` for a revoked (or expired) grant. A grants file written by an older SDK version (a plain JSON array of key strings) is still read correctly as a set of permanent grants.
 
+## Multi-Process Deployments (Redis)
+
+The built-in rate limiters and payment cache are in-memory and **per-process** — with `gunicorn -w 4`, each of the 4 workers enforces its own independent 10-req/min agent-key limit (40/min in aggregate) and caches payment results separately, so a payment verified by one worker isn't recognized by another until its own cache/rate-limit state catches up. For any multi-process deployment, plug in a Redis-backed store instead:
+
+```python
+import redis
+from agentpayments_python.redis_store import create_redis_store
+
+r = redis.Redis.from_url(os.environ["REDIS_URL"])
+store = create_redis_store(r)
+
+# FastAPI / Flask
+register_agentpayments(app, ...,  # or AgentPaymentsASGIMiddleware(...)
+    agent_key_rate_limiter=store["agent_key_rate_limiter"],
+    challenge_issue_rate_limiter=store["challenge_issue_rate_limiter"],
+    payment_cache=store["payment_cache"],
+)
+
+# Django settings.py
+AGENTPAYMENTS_AGENT_KEY_RATE_LIMITER = store["agent_key_rate_limiter"]
+AGENTPAYMENTS_CHALLENGE_ISSUE_RATE_LIMITER = store["challenge_issue_rate_limiter"]
+AGENTPAYMENTS_PAYMENT_CACHE = store["payment_cache"]
+
+# The /__challenge/verify endpoint has its own rate limiter, passed separately
+# since it's a standalone route/view rather than the main middleware:
+#   FastAPI: challenge_verify_endpoint(request, challenge_secret=..., rate_limiter=store["challenge_verify_rate_limiter"])
+#   Django:  AGENTPAYMENTS_CHALLENGE_VERIFY_RATE_LIMITER = store["challenge_verify_rate_limiter"]
+#   Flask:   register_agentpayments(app, ..., challenge_verify_rate_limiter=store["challenge_verify_rate_limiter"])
+```
+
+`redis_store.py` has no hard dependency on the `redis` package — it's duck-typed against any client exposing `eval(script, numkeys, *args)`, `get(key)`, and `set(key, value, ex=ttl)` (redis-py's `Redis` client satisfies this directly), mirroring `sdk/node/redis-store.js`. Rate limiting fails open on a Redis error (never blocks legitimate traffic); the payment cache fails to a miss (falls through to a normal chain scan). All four are optional — anything left unset keeps using the default in-memory implementation.
+
 ## Security Features
 
 - **Timing-safe HMAC comparison** — uses `hmac.compare_digest()` for all signature checks
@@ -153,6 +188,7 @@ agentpayments_python/
   ratelimit.py           Shared IP-based rate limiter
   grant_store.py         Durable paid-key persistence (expiry, revocation)
   pricing.py             Pricing-tier / access-duration / per-route resolution
+  redis_store.py         Redis-backed rate limiter + payment cache (multi-process)
 ```
 
 ## Notes

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/agentpayments_python/django_adapter.py

@@ -89,6 +89,14 @@ class GateMiddleware:
         # Optional grant store for durable paid-key persistence. Set
         # AGENTPAYMENTS_GRANT_STORE to a GrantStore instance in settings.py.
         self.grant_store = getattr(settings, "AGENTPAYMENTS_GRANT_STORE", None)
+        # Pluggable rate limiters / payment cache — default to the built-in
+        # in-memory singletons (fine for single-process deployments). For
+        # multi-process (e.g. gunicorn -w 4), set these to Redis-backed
+        # instances from agentpayments_python.redis_store so state is shared
+        # across workers instead of each worker enforcing its own limit.
+        self.agent_key_rate_limiter = getattr(settings, "AGENTPAYMENTS_AGENT_KEY_RATE_LIMITER", None) or _agent_key_limiter
+        self.challenge_issue_rate_limiter = getattr(settings, "AGENTPAYMENTS_CHALLENGE_ISSUE_RATE_LIMITER", None) or _challenge_issue_limiter
+        self.payment_cache = getattr(settings, "AGENTPAYMENTS_PAYMENT_CACHE", None)
 
     def __call__(self, request):
         secret = self.secret
@@ -177,7 +185,7 @@ class GateMiddleware:
             elif not is_valid_agent_key(agent_key, secret):
                 return JsonResponse({"error": "forbidden", "message": "Invalid API key. Keys must be issued by this server."}, status=403)
 
-            if not _agent_key_limiter.check(_client_ip(request)):
+            if not self.agent_key_rate_limiter.check(_client_ip(request)):
                 return JsonResponse({"error": "rate_limited", "message": "Too many payment verification requests. Please wait and try again."}, status=429)
 
             if not wallet_address:
@@ -187,7 +195,7 @@ class GateMiddleware:
             if self.grant_store and self.grant_store.has(agent_key):
                 return self.get_response(request)
 
-            scan_result = _scan_for_payment(agent_key, wallet_address, self.rpc_url, self.usdc_mint, min_payment=price_config["min_payment"], fee_info=fee_info)
+            scan_result = _scan_for_payment(agent_key, wallet_address, self.rpc_url, self.usdc_mint, min_payment=price_config["min_payment"], fee_info=fee_info, payment_cache=self.payment_cache)
             paid = scan_result["paid"]
             if paid and self.grant_store:
                 tier = resolve_tier(scan_result["amount_paid"], price_config["pricing_tiers"])
@@ -215,7 +223,7 @@ class GateMiddleware:
             return self.get_response(request)
 
         # Rate-limit challenge page issuance to prevent unlimited nonce harvesting.
-        if not _challenge_issue_limiter.check(client_ip):
+        if not self.challenge_issue_rate_limiter.check(client_ip):
             return JsonResponse({"error": "rate_limited", "message": "Too many requests. Please try again later."}, status=429)
 
         nonce = make_nonce(secret, client_ip)
@@ -230,7 +238,10 @@ class GateMiddleware:
 @require_POST
 def challenge_verify(request):
     client_ip = _client_ip(request)
-    if not _challenge_limiter.check(client_ip):
+    # Optional: set AGENTPAYMENTS_CHALLENGE_VERIFY_RATE_LIMITER in settings.py
+    # to a Redis-backed limiter for multi-process deployments.
+    limiter = getattr(settings, "AGENTPAYMENTS_CHALLENGE_VERIFY_RATE_LIMITER", None) or _challenge_limiter
+    if not limiter.check(client_ip):
         return JsonResponse({"error": "rate_limited", "message": "Too many verification attempts. Please wait and try again."}, status=429)
     secret = settings.CHALLENGE_SECRET
     nonce = request.POST.get("nonce", "")[:MAX_NONCE_LENGTH]

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/agentpayments_python/fastapi_adapter.py

@@ -46,7 +46,7 @@ def _client_ip(request: Request) -> str:
 
 
 class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
-    def __init__(self, app, *, challenge_secret: str, home_wallet_address: str, debug: bool = True, solana_rpc_url=None, usdc_mint: str = "", min_payment: float = MIN_PAYMENT, access_duration: float | None = None, pricing_tiers: list[dict] | None = None, routes: list[dict] | None = None, pow_difficulty: int = POW_DIFFICULTY, verify_crawlers: bool = True, grant_store=None, require_https: bool = None, api_key: str = None, platform_url: str = None):
+    def __init__(self, app, *, challenge_secret: str, home_wallet_address: str, debug: bool = True, solana_rpc_url=None, usdc_mint: str = "", min_payment: float = MIN_PAYMENT, access_duration: float | None = None, pricing_tiers: list[dict] | None = None, routes: list[dict] | None = None, pow_difficulty: int = POW_DIFFICULTY, verify_crawlers: bool = True, grant_store=None, require_https: bool = None, api_key: str = None, platform_url: str = None, agent_key_rate_limiter=None, challenge_issue_rate_limiter=None, payment_cache=None):
         super().__init__(app)
         if challenge_secret == "default-secret-change-me":
             import logging
@@ -72,6 +72,14 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
         self.grant_store = grant_store
         self.require_https = (not debug) if require_https is None else require_https
         self._platform_client = PlatformClient(api_key, platform_url) if api_key else None
+        # Pluggable rate limiter / payment cache — default to the built-in
+        # in-memory singletons (fine for single-process deployments). For
+        # multi-process (e.g. gunicorn -w 4), pass Redis-backed instances
+        # from agentpayments_python.redis_store so state is shared across
+        # workers instead of each worker enforcing its own independent limit.
+        self.agent_key_rate_limiter = agent_key_rate_limiter or _agent_key_limiter
+        self.challenge_issue_rate_limiter = challenge_issue_rate_limiter or _challenge_issue_limiter
+        self.payment_cache = payment_cache
 
     async def dispatch(self, request: Request, call_next):
         path = request.url.path
@@ -154,7 +162,7 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
             elif not is_valid_agent_key(agent_key, self.challenge_secret):
                 return JSONResponse({"error": "forbidden", "message": "Invalid API key."}, status_code=403)
 
-            if not _agent_key_limiter.check(_client_ip(request)):
+            if not self.agent_key_rate_limiter.check(_client_ip(request)):
                 return JSONResponse({"error": "rate_limited", "message": "Too many payment verification requests. Please wait and try again."}, status_code=429)
 
             if not self.home_wallet_address:
@@ -167,7 +175,7 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
             # _scan_for_payment is synchronous (uses requests). Run it in a
             # thread-pool executor so it doesn't block the async event loop.
             scan_result = await loop.run_in_executor(
-                None, lambda: _scan_for_payment(agent_key, self.home_wallet_address, self.solana_rpc_url, self.usdc_mint, min_payment=price_config["min_payment"], fee_info=fee_info)
+                None, lambda: _scan_for_payment(agent_key, self.home_wallet_address, self.solana_rpc_url, self.usdc_mint, min_payment=price_config["min_payment"], fee_info=fee_info, payment_cache=self.payment_cache)
             )
             paid = scan_result["paid"]
             if paid and self.grant_store:
@@ -195,7 +203,7 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
         if is_valid_cookie_value(cookie_val, self.challenge_secret, client_ip):
             return await call_next(request)
 
-        if not _challenge_issue_limiter.check(client_ip):
+        if not self.challenge_issue_rate_limiter.check(client_ip):
             return JSONResponse({"error": "rate_limited", "message": "Too many requests. Please try again later."}, status_code=429)
 
         nonce = make_nonce(self.challenge_secret, client_ip)
@@ -206,9 +214,10 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
         })
 
 
-async def challenge_verify_endpoint(request: Request, challenge_secret: str, pow_difficulty: int = POW_DIFFICULTY):
+async def challenge_verify_endpoint(request: Request, challenge_secret: str, pow_difficulty: int = POW_DIFFICULTY, rate_limiter=None):
     client_ip = _client_ip(request)
-    if not _challenge_limiter.check(client_ip):
+    limiter = rate_limiter or _challenge_limiter
+    if not limiter.check(client_ip):
         return JSONResponse({"error": "rate_limited", "message": "Too many verification attempts. Please wait and try again."}, status_code=429)
     form = await request.form()
     nonce = str(form.get("nonce", ""))[:MAX_NONCE_LENGTH]

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/agentpayments_python/flask_adapter.py

@@ -39,7 +39,15 @@ def _client_ip() -> str:
     return request.headers.get("X-Forwarded-For", "").split(",")[0].strip() or request.remote_addr or "unknown"
 
 
-def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: str, debug: bool = True, solana_rpc_url=None, usdc_mint: str = "", min_payment: float = MIN_PAYMENT, access_duration: float | None = None, pricing_tiers: list[dict] | None = None, routes: list[dict] | None = None, pow_difficulty: int = POW_DIFFICULTY, verify_crawlers: bool = True, grant_store=None, require_https: bool = None, api_key: str = None, platform_url: str = None):
+def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: str, debug: bool = True, solana_rpc_url=None, usdc_mint: str = "", min_payment: float = MIN_PAYMENT, access_duration: float | None = None, pricing_tiers: list[dict] | None = None, routes: list[dict] | None = None, pow_difficulty: int = POW_DIFFICULTY, verify_crawlers: bool = True, grant_store=None, require_https: bool = None, api_key: str = None, platform_url: str = None, challenge_verify_rate_limiter=None, agent_key_rate_limiter=None, challenge_issue_rate_limiter=None, payment_cache=None):
+    # Pluggable rate limiters / payment cache — default to the built-in
+    # in-memory singletons (fine for single-process deployments). For
+    # multi-process (e.g. gunicorn -w 4), pass Redis-backed instances from
+    # agentpayments_python.redis_store so state is shared across workers
+    # instead of each worker enforcing its own independent limit.
+    _challenge_verify_limiter = challenge_verify_rate_limiter or _challenge_limiter
+    _agent_key_rate_limiter = agent_key_rate_limiter or _agent_key_limiter
+    _challenge_issue_rate_limiter = challenge_issue_rate_limiter or _challenge_issue_limiter
     if challenge_secret == "default-secret-change-me":
         import logging
         logger = logging.getLogger("agentpayments")
@@ -133,13 +141,13 @@ def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: s
                     return jsonify({"error": "forbidden", "message": "Invalid API key."}), 403
             elif not is_valid_agent_key(key, challenge_secret):
                 return jsonify({"error": "forbidden", "message": "Invalid API key."}), 403
-            if not _agent_key_limiter.check(_client_ip()):
+            if not _agent_key_rate_limiter.check(_client_ip()):
                 return jsonify({"error": "rate_limited", "message": "Too many payment verification requests. Please wait and try again."}), 429
             if not home_wallet_address:
                 return jsonify({"error": "server_error", "message": "Payment verification unavailable."}), 500
             if grant_store and grant_store.has(key):
                 return None
-            scan_result = _scan_for_payment(key, home_wallet_address, rpc_url, mint, min_payment=price_config["min_payment"], fee_info=fee_info)
+            scan_result = _scan_for_payment(key, home_wallet_address, rpc_url, mint, min_payment=price_config["min_payment"], fee_info=fee_info, payment_cache=payment_cache)
             paid = scan_result["paid"]
             if paid and grant_store:
                 tier = resolve_tier(scan_result["amount_paid"], price_config["pricing_tiers"])
@@ -165,7 +173,7 @@ def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: s
         if is_valid_cookie_value(cookie_val, challenge_secret, client_ip):
             return None
 
-        if not _challenge_issue_limiter.check(client_ip):
+        if not _challenge_issue_rate_limiter.check(client_ip):
             return make_response(_flask_json.dumps({"error": "rate_limited", "message": "Too many requests. Please try again later."}, indent=2), 429, {"Content-Type": "application/json"})
 
         nonce = make_nonce(challenge_secret, client_ip)
@@ -179,7 +187,7 @@ def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: s
     @app.post("/__challenge/verify")
     def _verify():
         client_ip = _client_ip()
-        if not _challenge_limiter.check(client_ip):
+        if not _challenge_verify_limiter.check(client_ip):
             return jsonify({"error": "rate_limited", "message": "Too many verification attempts. Please wait and try again."}), 429
         nonce = request.form.get("nonce", "")[:MAX_NONCE_LENGTH]
         return_to = request.form.get("return_to", "/")[:MAX_RETURN_TO_LENGTH]

agentpayments_python-0.3.0/agentpayments_python/redis_store.py

@@ -0,0 +1,128 @@
+"""
+RedisStore -- pluggable state backend for the Python SDK using Redis.
+
+Designed for multi-process Django/FastAPI/Flask deployments (e.g.
+`gunicorn -w 4`) where the built-in in-memory rate limiters and payment
+cache are per-process and therefore far less effective than intended: a
+paid key's positive/negative cache result, and each IP's rate-limit
+count, only apply within the one worker process that happened to handle
+that request.
+
+Usage:
+
+    import redis
+    from agentpayments_python.redis_store import create_redis_store
+
+    r = redis.Redis.from_url(os.environ["REDIS_URL"])
+    store = create_redis_store(r)
+
+    # FastAPI / Flask constructor kwargs
+    register_agentpayments(app, ...,
+        agent_key_rate_limiter=store["agent_key_rate_limiter"],
+        challenge_verify_rate_limiter=store["challenge_verify_rate_limiter"],
+        challenge_issue_rate_limiter=store["challenge_issue_rate_limiter"],
+        payment_cache=store["payment_cache"],
+    )
+
+    # Django settings.py
+    AGENTPAYMENTS_AGENT_KEY_RATE_LIMITER = store["agent_key_rate_limiter"]
+    AGENTPAYMENTS_CHALLENGE_VERIFY_RATE_LIMITER = store["challenge_verify_rate_limiter"]
+    AGENTPAYMENTS_CHALLENGE_ISSUE_RATE_LIMITER = store["challenge_issue_rate_limiter"]
+    AGENTPAYMENTS_PAYMENT_CACHE = store["payment_cache"]
+
+Duck-typed against any client exposing `eval(script, numkeys, *keys_and_args)`,
+`get(key)`, and `set(key, value, ex=ttl_seconds)` -- redis-py's `Redis`
+client satisfies this directly. This module has no hard dependency on the
+`redis` package itself (mirrors sdk/node/redis-store.js) -- bring your own
+client.
+
+Atomicity: RateLimiter uses a Lua INCR+EXPIRE script executed atomically
+server-side, so there is no read-modify-write race under concurrent
+requests. PaymentCache uses plain SET EX.
+
+Fails open on Redis errors -- a Redis outage must not block legitimate
+traffic (rate limiter allows the request through) or brick payment
+verification (a cache error just falls through to a normal chain scan).
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("agentpayments")
+
+RATE_LIMIT_WINDOW = 60  # seconds
+RATE_LIMIT_MAX = 20
+AGENT_KEY_RATE_LIMIT_MAX = 10
+CHALLENGE_ISSUE_RATE_LIMIT_MAX = 30
+
+# Atomically increment and set a TTL only on the first hit in the window.
+# Returns the current count after increment.
+_INCR_SCRIPT = """
+local current = redis.call('INCR', KEYS[1])
+if current == 1 then
+  redis.call('EXPIRE', KEYS[1], ARGV[1])
+end
+return current
+"""
+
+
+class RateLimiter:
+    """Drop-in replacement for agentpayments_python.ratelimit.RateLimiter."""
+
+    def __init__(self, redis_client, window: int = RATE_LIMIT_WINDOW, max_hits: int = RATE_LIMIT_MAX, key_prefix: str = "agp:rl:"):
+        self._redis = redis_client
+        self._window = window
+        self._max = max_hits
+        self._prefix = key_prefix
+
+    def check(self, key: str) -> bool:
+        """Returns True if the request should be allowed, False if rate-limited."""
+        try:
+            count = self._redis.eval(_INCR_SCRIPT, 1, f"{self._prefix}{key}", self._window)
+            return int(count) <= self._max
+        except Exception as exc:
+            logger.error("[agentpayments] RedisStore.RateLimiter error: %s", exc)
+            return True  # fail open — don't block legitimate traffic
+
+
+class PaymentCache:
+    """Drop-in replacement for the module-level _payment_cache in solana.py."""
+
+    def __init__(self, redis_client, key_prefix: str = "agp:pay:"):
+        self._redis = redis_client
+        self._prefix = key_prefix
+
+    def get(self, agent_key: str):
+        """Returns True, False, or None (not cached / expired / error)."""
+        try:
+            val = self._redis.get(f"{self._prefix}{agent_key}")
+            if val is None:
+                return None
+            if isinstance(val, bytes):
+                val = val.decode()
+            return val == "1"
+        except Exception as exc:
+            logger.error("[agentpayments] RedisStore.PaymentCache.get error: %s", exc)
+            return None
+
+    def set(self, agent_key: str, value: bool, ttl: int) -> None:
+        """ttl is in seconds, matching solana.py's _PaymentCache.set signature."""
+        try:
+            self._redis.set(f"{self._prefix}{agent_key}", "1" if value else "0", ex=max(1, int(ttl)))
+        except Exception as exc:
+            logger.error("[agentpayments] RedisStore.PaymentCache.set error: %s", exc)
+
+
+def create_redis_store(redis_client) -> dict:
+    """
+    Convenience factory: create pre-configured rate limiters matching the
+    built-in defaults (challenge verify 20/min, agent-key 10/min, challenge
+    issuance 30/min), plus a shared payment cache.
+    """
+    return {
+        "challenge_verify_rate_limiter": RateLimiter(redis_client, max_hits=RATE_LIMIT_MAX, key_prefix="agp:rl:cv:"),
+        "agent_key_rate_limiter": RateLimiter(redis_client, max_hits=AGENT_KEY_RATE_LIMIT_MAX, key_prefix="agp:rl:ak:"),
+        "challenge_issue_rate_limiter": RateLimiter(redis_client, max_hits=CHALLENGE_ISSUE_RATE_LIMIT_MAX, key_prefix="agp:rl:ci:"),
+        "payment_cache": PaymentCache(redis_client),
+    }

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/agentpayments_python/solana.py

@@ -98,17 +98,23 @@ 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, min_payment: float = MIN_PAYMENT, fee_info: dict | None = None) -> bool:
+def verify_payment_on_chain(agent_key: str, wallet_address: str, rpc_url, usdc_mint: str, min_payment: float = MIN_PAYMENT, fee_info: dict | None = None, payment_cache=None) -> bool:
     """
     Verify payment on-chain. Returns true/false only — the stable, tested
     public API. See _scan_for_payment below for the amount-returning variant
     used internally for pricing-tier resolution.
+
+    payment_cache: optional cache object with the same interface as the
+    module-level default (get(key) -> True/False/None, set(key, value, ttl)).
+    Pass a agentpayments_python.redis_store.PaymentCache for multi-process
+    deployments where the default in-memory cache (per-process) is
+    ineffective. Defaults to the module-level singleton.
     """
-    result = _scan_for_payment(agent_key, wallet_address, rpc_url, usdc_mint, min_payment=min_payment, fee_info=fee_info)
+    result = _scan_for_payment(agent_key, wallet_address, rpc_url, usdc_mint, min_payment=min_payment, fee_info=fee_info, payment_cache=payment_cache)
     return result["paid"]
 
 
-def _scan_for_payment(agent_key: str, wallet_address: str, rpc_url, usdc_mint: str, min_payment: float = MIN_PAYMENT, fee_info: dict | None = None) -> dict:
+def _scan_for_payment(agent_key: str, wallet_address: str, rpc_url, usdc_mint: str, min_payment: float = MIN_PAYMENT, fee_info: dict | None = None, payment_cache=None) -> dict:
     """
     Scans the chain for a matching payment, same as verify_payment_on_chain,
     but also returns the actual amount paid (decimal USDC) so callers can
@@ -120,12 +126,13 @@ def _scan_for_payment(agent_key: str, wallet_address: str, rpc_url, usdc_mint: s
     the vendor payment must also carry a USDC transfer to fee_info["wallet"] of at
     least min_payment * rate_pct / 100, or the payment is treated as unverified.
     """
+    cache = payment_cache if payment_cache is not None else _payment_cache
     # 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]
     min_payment_micro = round(min_payment * 1_000_000)
     not_paid = {"paid": False, "amount_paid": None}
 
-    cached = _payment_cache.get(agent_key)
+    cached = cache.get(agent_key)
     if cached is True:
         return {"paid": True, "amount_paid": None}  # cache doesn't retain the amount
     if cached is False:
@@ -229,10 +236,10 @@ def _scan_for_payment(agent_key: str, wallet_address: str, rpc_url, usdc_mint: s
                             has_fee_payment = True
 
             if has_memo and has_payment and has_fee_payment:
-                _payment_cache.set(agent_key, True, PAYMENT_CACHE_TTL)
+                cache.set(agent_key, True, PAYMENT_CACHE_TTL)
                 return {"paid": True, "amount_paid": matched_amount_micro / 1_000_000}
     except Exception:
         logger.exception("[gate] Solana RPC error")
 
-    _payment_cache.set(agent_key, False, NEGATIVE_CACHE_TTL)
+    cache.set(agent_key, False, NEGATIVE_CACHE_TTL)
     return not_paid

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/agentpayments_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpayments-python
-Version: 0.2.0
+Version: 0.3.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
@@ -123,6 +123,9 @@ register_agentpayments(
 | `debug` | No | `True` | `True` = devnet. `False` = mainnet + strict mode. |
 | `api_key` | No | `None` | AgentPayments hosted-platform API key (`ap_live_...`). When set, agent keys are issued and metered via the platform instead of self-signed locally. See **Hosted Platform Mode** below. |
 | `platform_url` | No | AgentPayments-hosted URL | Override for a self-hosted platform API. |
+| `agent_key_rate_limiter` | No | Built-in in-memory (10/min/IP) | Pluggable rate limiter for the agent-key payment-verification path. Pass a Redis-backed one for multi-process deployments — see **Multi-Process Deployments** below. |
+| `challenge_issue_rate_limiter` | No | Built-in in-memory (30/min/IP) | Pluggable rate limiter for browser challenge-page issuance. |
+| `payment_cache` | No | Module-level in-memory singleton | Pluggable payment-verification cache (10-min positive / 30s negative TTL by default). |
 
 Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`, `settings.AGENTPAYMENTS_API_KEY`). FastAPI and Flask accept them as constructor arguments.
 
@@ -164,6 +167,38 @@ AGENTPAYMENTS_ROUTES = [...]
 
 **Revocation**: `MemoryGrantStore`/`FileGrantStore` (`agentpayments_python.grant_store`) both gained a `revoke(agent_key)` method — call it from your own admin view to cut off a specific paid key early. The adapters need no changes to respect this: `has()` already returns `False` for a revoked (or expired) grant. A grants file written by an older SDK version (a plain JSON array of key strings) is still read correctly as a set of permanent grants.
 
+## Multi-Process Deployments (Redis)
+
+The built-in rate limiters and payment cache are in-memory and **per-process** — with `gunicorn -w 4`, each of the 4 workers enforces its own independent 10-req/min agent-key limit (40/min in aggregate) and caches payment results separately, so a payment verified by one worker isn't recognized by another until its own cache/rate-limit state catches up. For any multi-process deployment, plug in a Redis-backed store instead:
+
+```python
+import redis
+from agentpayments_python.redis_store import create_redis_store
+
+r = redis.Redis.from_url(os.environ["REDIS_URL"])
+store = create_redis_store(r)
+
+# FastAPI / Flask
+register_agentpayments(app, ...,  # or AgentPaymentsASGIMiddleware(...)
+    agent_key_rate_limiter=store["agent_key_rate_limiter"],
+    challenge_issue_rate_limiter=store["challenge_issue_rate_limiter"],
+    payment_cache=store["payment_cache"],
+)
+
+# Django settings.py
+AGENTPAYMENTS_AGENT_KEY_RATE_LIMITER = store["agent_key_rate_limiter"]
+AGENTPAYMENTS_CHALLENGE_ISSUE_RATE_LIMITER = store["challenge_issue_rate_limiter"]
+AGENTPAYMENTS_PAYMENT_CACHE = store["payment_cache"]
+
+# The /__challenge/verify endpoint has its own rate limiter, passed separately
+# since it's a standalone route/view rather than the main middleware:
+#   FastAPI: challenge_verify_endpoint(request, challenge_secret=..., rate_limiter=store["challenge_verify_rate_limiter"])
+#   Django:  AGENTPAYMENTS_CHALLENGE_VERIFY_RATE_LIMITER = store["challenge_verify_rate_limiter"]
+#   Flask:   register_agentpayments(app, ..., challenge_verify_rate_limiter=store["challenge_verify_rate_limiter"])
+```
+
+`redis_store.py` has no hard dependency on the `redis` package — it's duck-typed against any client exposing `eval(script, numkeys, *args)`, `get(key)`, and `set(key, value, ex=ttl)` (redis-py's `Redis` client satisfies this directly), mirroring `sdk/node/redis-store.js`. Rate limiting fails open on a Redis error (never blocks legitimate traffic); the payment cache fails to a miss (falls through to a normal chain scan). All four are optional — anything left unset keeps using the default in-memory implementation.
+
 ## Security Features
 
 - **Timing-safe HMAC comparison** — uses `hmac.compare_digest()` for all signature checks
@@ -190,6 +225,7 @@ agentpayments_python/
   ratelimit.py           Shared IP-based rate limiter
   grant_store.py         Durable paid-key persistence (expiry, revocation)
   pricing.py             Pricing-tier / access-duration / per-route resolution
+  redis_store.py         Redis-backed rate limiter + payment cache (multi-process)
 ```
 
 ## Notes

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/agentpayments_python.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ agentpayments_python/grant_store.py
 agentpayments_python/platform_client.py
 agentpayments_python/pricing.py
 agentpayments_python/ratelimit.py
+agentpayments_python/redis_store.py
 agentpayments_python/solana.py
 agentpayments_python/x402.py
 agentpayments_python.egg-info/PKG-INFO

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentpayments-python"
-version = "0.2.0"
+version = "0.3.0"
 description = "AgentPayments gate for Python web frameworks — charge AI agents USDC on Solana before they can access your API"
 readme = "README.md"
 license = { text = "MIT" }

{agentpayments_python-0.2.0 → agentpayments_python-0.3.0}/tests/test_core.py

@@ -38,6 +38,11 @@ from agentpayments_python.challenge import (
 from agentpayments_python.detection import is_browser_from_headers, is_public_path
 from agentpayments_python.ratelimit import RateLimiter
 from agentpayments_python.grant_store import FileGrantStore, MemoryGrantStore
+from agentpayments_python.redis_store import (
+    RateLimiter as RedisRateLimiter,
+    PaymentCache as RedisPaymentCache,
+    create_redis_store,
+)
 from agentpayments_python.solana import (
     NEGATIVE_CACHE_TTL,
     PAYMENT_CACHE_TTL,
@@ -474,6 +479,108 @@ class TestPaymentCache:
         assert cache.get("d") is True
 
 
+# ─── redis_store: pluggable state backend for multi-process deployments ────
+
+class FakeRedis:
+    """Minimal fake standing in for a redis-py client: eval/get/set only."""
+
+    def __init__(self):
+        self._counters = {}
+        self._values = {}
+        self.fail = False
+
+    def eval(self, script, numkeys, key, ttl):
+        if self.fail:
+            raise ConnectionError("redis unavailable")
+        self._counters[key] = self._counters.get(key, 0) + 1
+        return self._counters[key]
+
+    def get(self, key):
+        if self.fail:
+            raise ConnectionError("redis unavailable")
+        return self._values.get(key)
+
+    def set(self, key, value, ex=None):
+        if self.fail:
+            raise ConnectionError("redis unavailable")
+        self._values[key] = value.encode() if isinstance(value, str) else value
+
+
+class TestRedisRateLimiter:
+    def test_allows_under_the_limit(self):
+        limiter = RedisRateLimiter(FakeRedis(), max_hits=3)
+        assert limiter.check("1.2.3.4")
+        assert limiter.check("1.2.3.4")
+        assert limiter.check("1.2.3.4")
+
+    def test_denies_over_the_limit(self):
+        limiter = RedisRateLimiter(FakeRedis(), max_hits=3)
+        for _ in range(3):
+            assert limiter.check("1.2.3.4")
+        assert not limiter.check("1.2.3.4")
+
+    def test_different_keys_independent(self):
+        redis = FakeRedis()
+        limiter = RedisRateLimiter(redis, max_hits=1)
+        assert limiter.check("a")
+        assert not limiter.check("a")
+        assert limiter.check("b")  # separate key, separate budget
+
+    def test_fails_open_on_redis_error(self):
+        redis = FakeRedis()
+        redis.fail = True
+        limiter = RedisRateLimiter(redis, max_hits=1)
+        assert limiter.check("1.2.3.4"), "a Redis outage must not block legitimate traffic"
+
+
+class TestRedisPaymentCache:
+    def test_miss_returns_none(self):
+        cache = RedisPaymentCache(FakeRedis())
+        assert cache.get("ag_unknown") is None
+
+    def test_positive_and_negative_roundtrip(self):
+        redis = FakeRedis()
+        cache = RedisPaymentCache(redis)
+        cache.set("ag_paid", True, 600)
+        cache.set("ag_unpaid", False, 30)
+        assert cache.get("ag_paid") is True
+        assert cache.get("ag_unpaid") is False
+
+    def test_fails_open_on_redis_error(self):
+        redis = FakeRedis()
+        redis.fail = True
+        cache = RedisPaymentCache(redis)
+        assert cache.get("ag_key") is None  # treated as a cache miss, not a crash
+        cache.set("ag_key", True, 600)  # must not raise
+
+
+class TestCreateRedisStore:
+    def test_returns_expected_keys(self):
+        store = create_redis_store(FakeRedis())
+        assert set(store.keys()) == {
+            "challenge_verify_rate_limiter",
+            "agent_key_rate_limiter",
+            "challenge_issue_rate_limiter",
+            "payment_cache",
+        }
+
+    def test_limiters_use_distinct_keyspaces(self):
+        # Same IP hitting two different limiters from the same store must not
+        # share a rate-limit budget with each other.
+        redis = FakeRedis()
+        store = create_redis_store(redis)
+        for _ in range(10):
+            store["agent_key_rate_limiter"].check("1.2.3.4")
+        assert store["challenge_verify_rate_limiter"].check("1.2.3.4")
+
+    def test_default_max_hits_match_built_in_limiters(self):
+        store = create_redis_store(FakeRedis())
+        # agent_key: 10/min, challenge_verify: 20/min, challenge_issue: 30/min
+        for _ in range(10):
+            assert store["agent_key_rate_limiter"].check("k")
+        assert not store["agent_key_rate_limiter"].check("k")
+
+
 # ─── grant stores ────────────────────────────────────────────────────────────
 
 class TestMemoryGrantStore:
@@ -1168,6 +1275,115 @@ class TestAdapterPricingWiring:
         assert len(store.grants) == 1
         assert store.grants[0]["expires_at"] > before + 86000  # ~24h out, allowing test slack
 
+    class _AlwaysDenyLimiter:
+        def check(self, key):
+            return False
+
+    class _PreSeededPaymentCache:
+        """Reports the given key as already paid, no matter what — used to
+        prove the gate consults the injected cache instead of a hardcoded
+        singleton, without needing a real chain scan."""
+        def __init__(self, key):
+            self._key = key
+
+        def get(self, key):
+            return True if key == self._key else None
+
+        def set(self, key, value, ttl):
+            pass
+
+    def test_fastapi_custom_agent_key_rate_limiter_is_used(self):
+        pytest.importorskip("fastapi")
+        import asyncio
+        from starlette.requests import Request
+        from starlette.responses import Response
+        from agentpayments_python.fastapi_adapter import AgentPaymentsASGIMiddleware
+        from agentpayments_python.crypto import generate_agent_key
+
+        key = generate_agent_key(self.SECRET)
+        mw = AgentPaymentsASGIMiddleware(
+            app=None,
+            challenge_secret=self.SECRET,
+            home_wallet_address=self.WALLET,
+            debug=True,
+            usdc_mint=self.MINT,
+            agent_key_rate_limiter=self._AlwaysDenyLimiter(),
+        )
+
+        async def call_next(_req):
+            return Response("ok", status_code=200)
+
+        async def run():
+            req = Request({
+                "type": "http", "method": "GET", "path": "/data",
+                "headers": [(b"x-agent-key", key.encode())],
+                "query_string": b"", "scheme": "https", "client": ("127.0.0.1", 1234),
+            })
+            return await mw.dispatch(req, call_next)
+
+        resp = asyncio.run(run())
+        assert resp.status_code == 429
+
+    def test_flask_custom_payment_cache_short_circuits_chain_scan(self):
+        pytest.importorskip("flask")
+        from flask import Flask
+        from agentpayments_python.flask_adapter import register_agentpayments
+        from agentpayments_python.crypto import generate_agent_key
+
+        key = generate_agent_key(self.SECRET)
+        app = Flask(__name__)
+        register_agentpayments(
+            app,
+            challenge_secret=self.SECRET,
+            home_wallet_address=self.WALLET,
+            debug=True,
+            usdc_mint=self.MINT,
+            payment_cache=self._PreSeededPaymentCache(key),
+        )
+
+        @app.route("/data")
+        def data():
+            return "ok"
+
+        client = app.test_client()
+        # No RPC mock at all -- if the gate ignored the injected cache and
+        # fell through to a real chain scan, this would hit the live network
+        # (and almost certainly fail/timeout in CI) instead of the assertion below.
+        with patch("requests.post", side_effect=AssertionError("should not hit the network — payment_cache should have short-circuited this")):
+            resp = client.get("/data", headers={"X-Agent-Key": key})
+        assert resp.status_code == 200
+
+    def test_django_custom_challenge_issue_rate_limiter_is_used(self):
+        pytest.importorskip("django")
+        import django
+        from django.conf import settings
+
+        if not settings.configured:
+            settings.configure(
+                DEBUG=True,
+                CHALLENGE_SECRET=self.SECRET,
+                HOME_WALLET_ADDRESS=self.WALLET,
+                USDC_MINT=self.MINT,
+                ALLOWED_HOSTS=["*"],
+            )
+            django.setup()
+
+        from django.test import RequestFactory
+        from django.http import HttpResponse
+        from agentpayments_python.django_adapter import GateMiddleware
+
+        with patch.object(settings, "AGENTPAYMENTS_CHALLENGE_ISSUE_RATE_LIMITER", self._AlwaysDenyLimiter(), create=True):
+            mw = GateMiddleware(lambda req: HttpResponse("ok"))
+            rf = RequestFactory()
+            # A plain browser-shaped request (no agent key, no Sec-Fetch/UA —
+            # still non-browser per is_browser_from_headers) won't reach the
+            # challenge-issuance path; use a UA that resolves to "browser" so
+            # the request falls through to the rate-limited challenge page.
+            req = rf.get("/", HTTP_SEC_FETCH_MODE="navigate", HTTP_SEC_FETCH_DEST="document")
+            resp = mw(req)
+
+        assert resp.status_code == 429
+
 
 # ─── pricing.py: pure helper unit tests ──────────────────────────────────────