agentpayments-python 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

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/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/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/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/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.dist-info → agentpayments_python-0.3.0.dist-info}/METADATA

@@ -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.dist-info → agentpayments_python-0.3.0.dist-info}/RECORD

@@ -5,17 +5,18 @@ agentpayments_python/cookies.py,sha256=0xO2_e4R4FpOprBcGWqY84E_eJppgJCkMGLCElZOQ
 agentpayments_python/crawler.py,sha256=G06nF6qFmyA5nDvMW18rfh44JxxJMKc2GCO0DXiZuoY,2514
 agentpayments_python/crypto.py,sha256=81xNcH1E468v26BimEQpK6n42bkqyz4q6eXhLLqQ6QY,1315
 agentpayments_python/detection.py,sha256=5KRaVdlMjOUaE167WTQyDXWIwF6sRFZ1DGZ2eqtoBAQ,1938
-agentpayments_python/django_adapter.py,sha256=D8dq0TUoZUN4u5g9VCEkqDzFYnwIHM_FRYzM9QholFI,15303
-agentpayments_python/fastapi_adapter.py,sha256=0L4PBqFb2A4UbNp7tLLQ3AEJC_tJAC9nAxM_sdhBboc,14573
-agentpayments_python/flask_adapter.py,sha256=i2hbB8Jf5qLmv_uLR7tGoNRR7Rls8xBnrIHzPqnJnYI,12733
+agentpayments_python/django_adapter.py,sha256=pZIq62sC_MYcfP_fgKvg5Fs_F4ismTct5I7HmfWxZVQ,16317
+agentpayments_python/fastapi_adapter.py,sha256=3dvPg_btZCxAws5xBIJ_hgbXFYuef8H2PGo5aXtCRwg,15370
+agentpayments_python/flask_adapter.py,sha256=s6IOKE5gldgPXIlRwvT2fN_etPZr43NpGaSSZtDBOMg,13509
 agentpayments_python/grant_store.py,sha256=ewYAxKocgfJE_txZp1SDnML066QP4BBB6V9vXIo47eE,5057
 agentpayments_python/platform_client.py,sha256=T-fSzxsABXVJ9nfrqL370GboV2-hdJaA-ploOw0uOd8,5108
 agentpayments_python/pricing.py,sha256=3AujxsDlP5pMBals4FnoPdfOYBe1VPLREo_IJtJVxwg,2910
 agentpayments_python/ratelimit.py,sha256=Q6uxFRbYbf7D8qykZ9ieVaSCU8FkXFYPS59XmkrnE_k,1580
-agentpayments_python/solana.py,sha256=hRJ6V_rcxLgcw68XdNTqE_ShCIwpBXljjptj2IylPtw,11335
+agentpayments_python/redis_store.py,sha256=2WSPBJYi8qp7B_yhqYX1bemfjbYn8OrH_ww9qpRw7Bc,5145
+agentpayments_python/solana.py,sha256=SE6psJlveTZJEsY6I2Q1Dttp1cqdzuzsqM_yeer5toU,11802
 agentpayments_python/x402.py,sha256=PS5U_dWX1CyRMTxxAYnyuzb-q4mRWvXe1Pys3y-CvEg,5527
-agentpayments_python-0.2.0.dist-info/licenses/LICENSE,sha256=PMKDe4kanHRVI7QQezG4GeluZkMljhVO-tFSFNUiYS4,1069
-agentpayments_python-0.2.0.dist-info/METADATA,sha256=0uSQF-ytcrOf96T2kdg2tz3TmfXxcxBIUNS6mPPj_UY,9317
-agentpayments_python-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-agentpayments_python-0.2.0.dist-info/top_level.txt,sha256=DxGMGvTYQVdoBQ6pBbbsJXy5BZhbSjNGF_uSO3git4w,21
-agentpayments_python-0.2.0.dist-info/RECORD,,
+agentpayments_python-0.3.0.dist-info/licenses/LICENSE,sha256=PMKDe4kanHRVI7QQezG4GeluZkMljhVO-tFSFNUiYS4,1069
+agentpayments_python-0.3.0.dist-info/METADATA,sha256=OXACM_sGdSQctXJuB-0hqhQziHG5TsA7jBQvE_zJTvc,12066
+agentpayments_python-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentpayments_python-0.3.0.dist-info/top_level.txt,sha256=DxGMGvTYQVdoBQ6pBbbsJXy5BZhbSjNGF_uSO3git4w,21
+agentpayments_python-0.3.0.dist-info/RECORD,,