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

agentpayments_python/django_adapter.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import logging
+import time as _time
 
 from django.conf import settings
 from django.http import HttpResponse, HttpResponseRedirect, JsonResponse
@@ -11,9 +14,10 @@ from .crypto import generate_agent_key, is_valid_agent_key
 from .detection import is_browser_from_headers, is_public_path
 from .ratelimit import _challenge_limiter, _agent_key_limiter, _challenge_issue_limiter
 from .crawler import is_verified_crawler
-from .solana import MIN_PAYMENT, RPC_DEVNET, RPC_MAINNET, USDC_MINT_DEVNET, USDC_MINT_MAINNET, is_valid_solana_address, verify_payment_on_chain
-from .x402 import build_payment_object, build_payment_requirements, enrich_402_body, payment_required_header
+from .solana import MIN_PAYMENT, RPC_DEVNET, RPC_MAINNET, USDC_MINT_DEVNET, USDC_MINT_MAINNET, is_valid_solana_address, _scan_for_payment
+from .x402 import build_payment_object, build_payment_requirements, enrich_402_body, payment_required_header, tier_x402_opts_list
 from .platform_client import HOSTED_KEY_PREFIX, PlatformClient, is_valid_hosted_key
+from .pricing import normalize_price_config, build_routes_table, resolve_route_config, resolve_tier
 
 import json as _json
 from pathlib import Path as _Path
@@ -26,10 +30,11 @@ MAX_POW_LENGTH = _constants["MAX_POW_LENGTH"]
 logger = logging.getLogger("agentpayments")
 
 
-def _payment_required_response(body: dict, *, wallet_address: str, mint: str, min_payment: float, debug: bool, agent_key: str = "", resource: str = "") -> JsonResponse:
+def _payment_required_response(body: dict, *, wallet_address: str, mint: str, min_payment: float, debug: bool, agent_key: str = "", resource: str = "", extra_tier_opts: list[dict] | None = None) -> JsonResponse:
     """Return a 402 JsonResponse enriched with x402-standard fields and header."""
     pay_req = build_payment_requirements(wallet_address=wallet_address, mint=mint, min_payment=min_payment, debug=debug, agent_key=agent_key, resource=resource)
-    resp = JsonResponse(enrich_402_body(body, pay_req), status=402, json_dumps_params={"indent": 2})
+    extra_reqs = [build_payment_requirements(**opts) for opts in (extra_tier_opts or [])]
+    resp = JsonResponse(enrich_402_body(body, pay_req, extra_reqs), status=402, json_dumps_params={"indent": 2})
     resp["X-PAYMENT-REQUIRED"] = payment_required_header(pay_req)
     return resp
 
@@ -69,11 +74,29 @@ class GateMiddleware:
         self.rpc_url = rpc_url
         self.usdc_mint = usdc_mint
         self.network = "devnet" if debug else "mainnet-beta"
+        # Price/duration/tier resolution is static for this server — precompute
+        # once rather than per-request. Configure via settings.py:
+        #   AGENTPAYMENTS_MIN_PAYMENT, AGENTPAYMENTS_ACCESS_DURATION,
+        #   AGENTPAYMENTS_PRICING_TIERS, AGENTPAYMENTS_ROUTES
+        min_payment = getattr(settings, "AGENTPAYMENTS_MIN_PAYMENT", MIN_PAYMENT)
+        access_duration = getattr(settings, "AGENTPAYMENTS_ACCESS_DURATION", None)
+        pricing_tiers = getattr(settings, "AGENTPAYMENTS_PRICING_TIERS", None)
+        routes = getattr(settings, "AGENTPAYMENTS_ROUTES", None)
+        self.base_price_config = normalize_price_config(min_payment, access_duration, pricing_tiers)
+        self.routes_table = build_routes_table(routes, min_payment, access_duration, pricing_tiers)
         self.pow_difficulty = getattr(settings, "POW_DIFFICULTY", POW_DIFFICULTY)
         self.verify_crawlers = getattr(settings, "AGENTPAYMENTS_VERIFY_CRAWLERS", True)
         # 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
@@ -81,6 +104,7 @@ class GateMiddleware:
         network = self.network
 
         pathname = request.path
+        price_config = resolve_route_config(pathname, self.routes_table, self.base_price_config)
         if is_public_path(pathname):
             return self.get_response(request)
 
@@ -128,21 +152,22 @@ class GateMiddleware:
                     new_key = generate_agent_key(secret)
                 if fee_info:
                     no_key_instructions = (
-                        f'Send {MIN_PAYMENT} USDC on Solana {network} to {wallet_address} with memo "{new_key}", '
+                        f'Send {price_config["min_payment"]} USDC on Solana {network} to {wallet_address} with memo "{new_key}", '
                         f'AND in the SAME transaction send the platform fee (see platform_fee below) to {fee_info["wallet"]}. '
                         f'Then include the header X-Agent-Key: {new_key} on all subsequent requests.'
                     )
                 else:
-                    no_key_instructions = f'Send {MIN_PAYMENT} USDC on Solana {network} to {wallet_address} with memo "{new_key}". Then include the header X-Agent-Key: {new_key} on all subsequent requests.'
+                    no_key_instructions = f'Send {price_config["min_payment"]} USDC on Solana {network} to {wallet_address} with memo "{new_key}". Then include the header X-Agent-Key: {new_key} on all subsequent requests.'
                 return _payment_required_response(
                     {
                         "error": "payment_required",
                         "message": "Access requires a paid API key. A key has been generated for you below. Send a USDC payment on Solana with this key as the memo to activate it, then retry your request with the X-Agent-Key header.",
                         "your_key": new_key,
-                        "payment": build_payment_object(network=network, min_payment=MIN_PAYMENT, wallet_address=wallet_address, memo=new_key, fee_info=fee_info, instructions=no_key_instructions),
+                        "payment": build_payment_object(network=network, min_payment=price_config["min_payment"], wallet_address=wallet_address, memo=new_key, fee_info=fee_info, instructions=no_key_instructions),
                     },
-                    wallet_address=wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
+                    wallet_address=wallet_address, mint=self.usdc_mint, min_payment=price_config["min_payment"],
                     debug=self.debug, agent_key=new_key, resource=pathname,
+                    extra_tier_opts=tier_x402_opts_list(price_config["pricing_tiers"], {"wallet_address": wallet_address, "mint": self.usdc_mint, "debug": self.debug, "agent_key": new_key, "resource": pathname}),
                 )
 
             # Validate the key. Platform-issued (agp_) use verificationSecret;
@@ -160,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:
@@ -170,19 +195,24 @@ class GateMiddleware:
             if self.grant_store and self.grant_store.has(agent_key):
                 return self.get_response(request)
 
-            paid = verify_payment_on_chain(agent_key, wallet_address, self.rpc_url, self.usdc_mint, 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:
-                self.grant_store.add(agent_key)
+                tier = resolve_tier(scan_result["amount_paid"], price_config["pricing_tiers"])
+                duration_seconds = tier["duration_seconds"] if tier else price_config["access_duration"]
+                expires_at = (_time.time() + duration_seconds) if duration_seconds else None
+                self.grant_store.add(agent_key, expires_at=expires_at, tier=(tier["name"] if tier else None))
             if not paid:
                 return _payment_required_response(
                     {
                         "error": "payment_required",
                         "message": "Key is valid but payment has not been verified on-chain yet.",
                         "your_key": agent_key,
-                        "payment": build_payment_object(network=network, min_payment=MIN_PAYMENT, wallet_address=wallet_address, memo=agent_key, fee_info=fee_info),
+                        "payment": build_payment_object(network=network, min_payment=price_config["min_payment"], wallet_address=wallet_address, memo=agent_key, fee_info=fee_info),
                     },
-                    wallet_address=wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
+                    wallet_address=wallet_address, mint=self.usdc_mint, min_payment=price_config["min_payment"],
                     debug=self.debug, agent_key=agent_key, resource=pathname,
+                    extra_tier_opts=tier_x402_opts_list(price_config["pricing_tiers"], {"wallet_address": wallet_address, "mint": self.usdc_mint, "debug": self.debug, "agent_key": agent_key, "resource": pathname}),
                 )
 
             return self.get_response(request)
@@ -193,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)
@@ -208,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

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 
 from starlette.middleware.base import BaseHTTPMiddleware
@@ -10,9 +12,11 @@ from .crypto import generate_agent_key, is_valid_agent_key
 from .detection import is_browser_from_headers, is_public_path
 from .ratelimit import _challenge_limiter, _agent_key_limiter, _challenge_issue_limiter
 from .crawler import is_verified_crawler
-from .solana import MIN_PAYMENT, RPC_DEVNET, RPC_MAINNET, USDC_MINT_DEVNET, USDC_MINT_MAINNET, is_valid_solana_address, verify_payment_on_chain
-from .x402 import build_payment_object, build_payment_requirements, enrich_402_body, payment_required_header
+from .solana import MIN_PAYMENT, RPC_DEVNET, RPC_MAINNET, USDC_MINT_DEVNET, USDC_MINT_MAINNET, is_valid_solana_address, _scan_for_payment
+from .x402 import build_payment_object, build_payment_requirements, enrich_402_body, payment_required_header, tier_x402_opts_list
 from .platform_client import HOSTED_KEY_PREFIX, PlatformClient, is_valid_hosted_key
+from .pricing import normalize_price_config, build_routes_table, resolve_route_config, resolve_tier
+import time as _time
 
 import json as _json
 from pathlib import Path as _Path
@@ -23,11 +27,12 @@ MAX_FP_LENGTH = _constants["MAX_FP_LENGTH"]
 MAX_POW_LENGTH = _constants["MAX_POW_LENGTH"]
 
 
-def _payment_required_response(body: dict, *, wallet_address: str, mint: str, min_payment: float, debug: bool, agent_key: str = "", resource: str = "") -> JSONResponse:
+def _payment_required_response(body: dict, *, wallet_address: str, mint: str, min_payment: float, debug: bool, agent_key: str = "", resource: str = "", extra_tier_opts: list[dict] | None = None) -> JSONResponse:
     """Return a Starlette JSONResponse (402) enriched with x402-standard fields and header."""
     pay_req = build_payment_requirements(wallet_address=wallet_address, mint=mint, min_payment=min_payment, debug=debug, agent_key=agent_key, resource=resource)
+    extra_reqs = [build_payment_requirements(**opts) for opts in (extra_tier_opts or [])]
     return JSONResponse(
-        content=enrich_402_body(body, pay_req),
+        content=enrich_402_body(body, pay_req, extra_reqs),
         status_code=402,
         headers={"X-PAYMENT-REQUIRED": payment_required_header(pay_req)},
     )
@@ -41,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 = "", 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
@@ -58,14 +63,27 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
         raw_rpc = solana_rpc_url or (RPC_DEVNET if debug else RPC_MAINNET)
         self.solana_rpc_url = raw_rpc if isinstance(raw_rpc, list) else [raw_rpc]
         self.usdc_mint = usdc_mint or (USDC_MINT_DEVNET if debug else USDC_MINT_MAINNET)
+        # Price/duration/tier resolution is static for this middleware instance —
+        # precompute once rather than per-request.
+        self.base_price_config = normalize_price_config(min_payment, access_duration, pricing_tiers)
+        self.routes_table = build_routes_table(routes, min_payment, access_duration, pricing_tiers)
         self.pow_difficulty = pow_difficulty
         self.verify_crawlers = verify_crawlers
         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
+        price_config = resolve_route_config(path, self.routes_table, self.base_price_config)
         if is_public_path(path):
             return await call_next(request)
 
@@ -112,21 +130,22 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
                     new_key = generate_agent_key(self.challenge_secret)
                 if fee_info:
                     no_key_instructions = (
-                        f'Send {MIN_PAYMENT} USDC on Solana {network} to {self.home_wallet_address} with memo "{new_key}", '
+                        f'Send {price_config["min_payment"]} USDC on Solana {network} to {self.home_wallet_address} with memo "{new_key}", '
                         f'AND in the SAME transaction send the platform fee (see platform_fee below) to {fee_info["wallet"]}. '
                         f'Then include the header X-Agent-Key: {new_key} on all subsequent requests.'
                     )
                 else:
-                    no_key_instructions = f'Send {MIN_PAYMENT} USDC on Solana {network} to {self.home_wallet_address} with memo "{new_key}". Then include the header X-Agent-Key: {new_key} on all subsequent requests.'
+                    no_key_instructions = f'Send {price_config["min_payment"]} USDC on Solana {network} to {self.home_wallet_address} with memo "{new_key}". Then include the header X-Agent-Key: {new_key} on all subsequent requests.'
                 return _payment_required_response(
                     {
                         "error": "payment_required",
                         "message": "Access requires a paid API key. A key has been generated for you below. Send a USDC payment on Solana with this key as the memo to activate it, then retry your request with the X-Agent-Key header.",
                         "your_key": new_key,
-                        "payment": build_payment_object(network=network, min_payment=MIN_PAYMENT, wallet_address=self.home_wallet_address, memo=new_key, fee_info=fee_info, instructions=no_key_instructions),
+                        "payment": build_payment_object(network=network, min_payment=price_config["min_payment"], wallet_address=self.home_wallet_address, memo=new_key, fee_info=fee_info, instructions=no_key_instructions),
                     },
-                    wallet_address=self.home_wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
+                    wallet_address=self.home_wallet_address, mint=self.usdc_mint, min_payment=price_config["min_payment"],
                     debug=self.debug, agent_key=new_key, resource=path,
+                    extra_tier_opts=tier_x402_opts_list(price_config["pricing_tiers"], {"wallet_address": self.home_wallet_address, "mint": self.usdc_mint, "debug": self.debug, "agent_key": new_key, "resource": path}),
                 )
 
             if agent_key.startswith(HOSTED_KEY_PREFIX):
@@ -143,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:
@@ -153,23 +172,28 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
             if self.grant_store and self.grant_store.has(agent_key):
                 return await call_next(request)
 
-            # verify_payment_on_chain is synchronous (uses requests). Run it in a
+            # _scan_for_payment is synchronous (uses requests). Run it in a
             # thread-pool executor so it doesn't block the async event loop.
-            paid = await loop.run_in_executor(
-                None, lambda: verify_payment_on_chain(agent_key, self.home_wallet_address, self.solana_rpc_url, self.usdc_mint, fee_info=fee_info)
+            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, payment_cache=self.payment_cache)
             )
+            paid = scan_result["paid"]
             if paid and self.grant_store:
-                self.grant_store.add(agent_key)
+                tier = resolve_tier(scan_result["amount_paid"], price_config["pricing_tiers"])
+                duration_seconds = tier["duration_seconds"] if tier else price_config["access_duration"]
+                expires_at = (_time.time() + duration_seconds) if duration_seconds else None
+                self.grant_store.add(agent_key, expires_at=expires_at, tier=(tier["name"] if tier else None))
             if not paid:
                 return _payment_required_response(
                     {
                         "error": "payment_required",
                         "message": "Key is valid but payment has not been verified on-chain yet.",
                         "your_key": agent_key,
-                        "payment": build_payment_object(network=network, min_payment=MIN_PAYMENT, wallet_address=self.home_wallet_address, memo=agent_key, fee_info=fee_info),
+                        "payment": build_payment_object(network=network, min_payment=price_config["min_payment"], wallet_address=self.home_wallet_address, memo=agent_key, fee_info=fee_info),
                     },
-                    wallet_address=self.home_wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
+                    wallet_address=self.home_wallet_address, mint=self.usdc_mint, min_payment=price_config["min_payment"],
                     debug=self.debug, agent_key=agent_key, resource=path,
+                    extra_tier_opts=tier_x402_opts_list(price_config["pricing_tiers"], {"wallet_address": self.home_wallet_address, "mint": self.usdc_mint, "debug": self.debug, "agent_key": agent_key, "resource": path}),
                 )
 
             return await call_next(request)
@@ -179,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)
@@ -190,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

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 from flask import jsonify, make_response, redirect, request, Response as FlaskResponse
 import json as _flask_json
+import time as _time
 
 from .challenge import POW_DIFFICULTY, challenge_html, make_nonce, validate_challenge_submission
 from .cookies import COOKIE_MAX_AGE, COOKIE_NAME, is_valid_cookie_value, make_cookie
@@ -7,9 +10,10 @@ from .crypto import generate_agent_key, is_valid_agent_key
 from .detection import is_browser_from_headers, is_public_path
 from .ratelimit import _challenge_limiter, _agent_key_limiter, _challenge_issue_limiter
 from .crawler import is_verified_crawler
-from .solana import MIN_PAYMENT, RPC_DEVNET, RPC_MAINNET, USDC_MINT_DEVNET, USDC_MINT_MAINNET, is_valid_solana_address, verify_payment_on_chain
-from .x402 import build_payment_object, build_payment_requirements, enrich_402_body, payment_required_header
+from .solana import MIN_PAYMENT, RPC_DEVNET, RPC_MAINNET, USDC_MINT_DEVNET, USDC_MINT_MAINNET, is_valid_solana_address, _scan_for_payment
+from .x402 import build_payment_object, build_payment_requirements, enrich_402_body, payment_required_header, tier_x402_opts_list
 from .platform_client import HOSTED_KEY_PREFIX, PlatformClient, is_valid_hosted_key
+from .pricing import normalize_price_config, build_routes_table, resolve_route_config, resolve_tier
 
 import json as _json
 from pathlib import Path as _Path
@@ -20,10 +24,11 @@ MAX_FP_LENGTH = _constants["MAX_FP_LENGTH"]
 MAX_POW_LENGTH = _constants["MAX_POW_LENGTH"]
 
 
-def _payment_required_flask(body: dict, *, wallet_address: str, mint: str, min_payment: float, debug: bool, agent_key: str = "", resource: str = ""):
+def _payment_required_flask(body: dict, *, wallet_address: str, mint: str, min_payment: float, debug: bool, agent_key: str = "", resource: str = "", extra_tier_opts: list[dict] | None = None):
     """Return a Flask 402 response enriched with x402-standard fields and header."""
     pay_req = build_payment_requirements(wallet_address=wallet_address, mint=mint, min_payment=min_payment, debug=debug, agent_key=agent_key, resource=resource)
-    enriched = enrich_402_body(body, pay_req)
+    extra_reqs = [build_payment_requirements(**opts) for opts in (extra_tier_opts or [])]
+    enriched = enrich_402_body(body, pay_req, extra_reqs)
     resp = make_response(_flask_json.dumps(enriched, indent=2), 402)
     resp.headers["Content-Type"] = "application/json"
     resp.headers["X-PAYMENT-REQUIRED"] = payment_required_header(pay_req)
@@ -34,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 = "", 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")
@@ -49,10 +62,14 @@ def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: s
     mint = usdc_mint or (USDC_MINT_DEVNET if debug else USDC_MINT_MAINNET)
     _require_https = (not debug) if require_https is None else require_https
     _platform_client = PlatformClient(api_key, platform_url) if api_key else None
+    # Price/duration/tier resolution is static for this app — precompute once.
+    base_price_config = normalize_price_config(min_payment, access_duration, pricing_tiers)
+    routes_table = build_routes_table(routes, min_payment, access_duration, pricing_tiers)
 
     @app.before_request
     def _gate():
         path = request.path
+        price_config = resolve_route_config(path, routes_table, base_price_config)
         if is_public_path(path):
             return None
         if path == "/__challenge/verify" and request.method == "POST":
@@ -94,21 +111,22 @@ def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: s
                     new_key = generate_agent_key(challenge_secret)
                 if fee_info:
                     no_key_instructions = (
-                        f'Send {MIN_PAYMENT} USDC on Solana {network} to {home_wallet_address} with memo "{new_key}", '
+                        f'Send {price_config["min_payment"]} USDC on Solana {network} to {home_wallet_address} with memo "{new_key}", '
                         f'AND in the SAME transaction send the platform fee (see platform_fee below) to {fee_info["wallet"]}. '
                         f'Then include the header X-Agent-Key: {new_key} on all subsequent requests.'
                     )
                 else:
-                    no_key_instructions = f'Send {MIN_PAYMENT} USDC on Solana {network} to {home_wallet_address} with memo "{new_key}". Then include the header X-Agent-Key: {new_key} on all subsequent requests.'
+                    no_key_instructions = f'Send {price_config["min_payment"]} USDC on Solana {network} to {home_wallet_address} with memo "{new_key}". Then include the header X-Agent-Key: {new_key} on all subsequent requests.'
                 return _payment_required_flask(
                     {
                         "error": "payment_required",
                         "message": "Access requires a paid API key. A key has been generated for you below. Send a USDC payment on Solana with this key as the memo to activate it, then retry your request with the X-Agent-Key header.",
                         "your_key": new_key,
-                        "payment": build_payment_object(network=network, min_payment=MIN_PAYMENT, wallet_address=home_wallet_address, memo=new_key, fee_info=fee_info, instructions=no_key_instructions),
+                        "payment": build_payment_object(network=network, min_payment=price_config["min_payment"], wallet_address=home_wallet_address, memo=new_key, fee_info=fee_info, instructions=no_key_instructions),
                     },
-                    wallet_address=home_wallet_address, mint=mint, min_payment=MIN_PAYMENT,
+                    wallet_address=home_wallet_address, mint=mint, min_payment=price_config["min_payment"],
                     debug=debug, agent_key=new_key, resource=path,
+                    extra_tier_opts=tier_x402_opts_list(price_config["pricing_tiers"], {"wallet_address": home_wallet_address, "mint": mint, "debug": debug, "agent_key": new_key, "resource": path}),
                 )
             if key.startswith(HOSTED_KEY_PREFIX):
                 if not _platform_client:
@@ -123,25 +141,30 @@ 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
-            paid = verify_payment_on_chain(key, home_wallet_address, rpc_url, mint, 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:
-                grant_store.add(key)
+                tier = resolve_tier(scan_result["amount_paid"], price_config["pricing_tiers"])
+                duration_seconds = tier["duration_seconds"] if tier else price_config["access_duration"]
+                expires_at = (_time.time() + duration_seconds) if duration_seconds else None
+                grant_store.add(key, expires_at=expires_at, tier=(tier["name"] if tier else None))
             if not paid:
                 return _payment_required_flask(
                     {
                         "error": "payment_required",
                         "message": "Key is valid but payment has not been verified on-chain yet.",
                         "your_key": key,
-                        "payment": build_payment_object(network=network, min_payment=MIN_PAYMENT, wallet_address=home_wallet_address, memo=key, fee_info=fee_info),
+                        "payment": build_payment_object(network=network, min_payment=price_config["min_payment"], wallet_address=home_wallet_address, memo=key, fee_info=fee_info),
                     },
-                    wallet_address=home_wallet_address, mint=mint, min_payment=MIN_PAYMENT,
+                    wallet_address=home_wallet_address, mint=mint, min_payment=price_config["min_payment"],
                     debug=debug, agent_key=key, resource=path,
+                    extra_tier_opts=tier_x402_opts_list(price_config["pricing_tiers"], {"wallet_address": home_wallet_address, "mint": mint, "debug": debug, "agent_key": key, "resource": path}),
                 )
             return None
 
@@ -150,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)
@@ -164,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/grant_store.py

@@ -19,7 +19,16 @@ Grant store interface (implement your own for Redis, Postgres, etc.):
 
     class GrantStore(Protocol):
         def has(self, agent_key: str) -> bool: ...
-        def add(self, agent_key: str) -> None: ...
+        def add(self, agent_key: str, expires_at: float | None = None, tier: str | None = None) -> None: ...
+        def revoke(self, agent_key: str) -> None: ...
+
+``add``'s ``expires_at``/``tier`` arguments are optional — a custom store
+whose ``add`` only accepts ``agent_key`` will break if a caller passes them
+as keywords; this is the one Python-side interface change to be aware of
+when upgrading a custom store (see CHANGELOG). ``revoke`` is called by the
+vendor's own code (e.g. an admin route) to cut off a specific key early; the
+adapters never call it — ``has()`` on the built-in stores already returns
+False for a revoked or expired grant.
 """
 
 from __future__ import annotations
@@ -27,23 +36,37 @@ from __future__ import annotations
 import json
 import os
 import threading
+import time
 from pathlib import Path
 
 
+def _is_expired(grant: dict) -> bool:
+    expires_at = grant.get("expires_at")
+    return expires_at is not None and time.time() > expires_at
+
+
 class MemoryGrantStore:
     """In-memory grant store. Does not survive restarts."""
 
     def __init__(self) -> None:
-        self._grants: set[str] = set()
+        self._grants: dict[str, dict] = {}
         self._lock = threading.Lock()
 
     def has(self, agent_key: str) -> bool:
         with self._lock:
-            return agent_key in self._grants
+            grant = self._grants.get(agent_key)
+            if not grant or grant.get("revoked") or _is_expired(grant):
+                return False
+            return True
+
+    def add(self, agent_key: str, expires_at: float | None = None, tier: str | None = None) -> None:
+        with self._lock:
+            self._grants[agent_key] = {"expires_at": expires_at, "tier": tier, "revoked": False}
 
-    def add(self, agent_key: str) -> None:
+    def revoke(self, agent_key: str) -> None:
         with self._lock:
-            self._grants.add(agent_key)
+            existing = self._grants.get(agent_key, {"expires_at": None, "tier": None})
+            self._grants[agent_key] = {**existing, "revoked": True}
 
 
 class FileGrantStore:
@@ -51,36 +74,57 @@ class FileGrantStore:
     File-backed grant store. Persists grants to a JSON file so they survive
     process restarts. Writes are atomic (write to temp file, os.replace).
 
+    Reads the legacy on-disk format (a plain JSON array of key strings) as
+    pre-existing permanent grants, so upgrading does not invalidate a
+    vendor's existing grants file. Writes the newer object-map format going
+    forward.
+
     Not suitable for multi-process deployments — use a database or Redis there.
     """
 
     def __init__(self, path: str | Path) -> None:
         self._path = Path(path).resolve()
-        self._grants: set[str] = set()
+        self._grants: dict[str, dict] = {}
         self._lock = threading.Lock()
         self._load()
 
     def _load(self) -> None:
         try:
-            keys = json.loads(self._path.read_text())
-            if isinstance(keys, list):
-                self._grants.update(keys)
+            parsed = json.loads(self._path.read_text())
+            if isinstance(parsed, list):
+                # Legacy format: array of key strings, each a permanent grant.
+                for key in parsed:
+                    self._grants[key] = {"expires_at": None, "tier": None, "revoked": False}
+            elif isinstance(parsed, dict):
+                for key, grant in parsed.items():
+                    self._grants[key] = {
+                        "expires_at": grant.get("expires_at"),
+                        "tier": grant.get("tier"),
+                        "revoked": bool(grant.get("revoked")),
+                    }
         except FileNotFoundError:
             pass  # will be created on first write
 
     def _save(self) -> None:
         self._path.parent.mkdir(parents=True, exist_ok=True)
         tmp = self._path.with_suffix(".tmp")
-        tmp.write_text(json.dumps(sorted(self._grants), indent=2))
+        tmp.write_text(json.dumps(self._grants, indent=2, sort_keys=True))
         os.replace(tmp, self._path)
 
     def has(self, agent_key: str) -> bool:
         with self._lock:
-            return agent_key in self._grants
+            grant = self._grants.get(agent_key)
+            if not grant or grant.get("revoked") or _is_expired(grant):
+                return False
+            return True
+
+    def add(self, agent_key: str, expires_at: float | None = None, tier: str | None = None) -> None:
+        with self._lock:
+            self._grants[agent_key] = {"expires_at": expires_at, "tier": tier, "revoked": False}
+            self._save()
 
-    def add(self, agent_key: str) -> None:
+    def revoke(self, agent_key: str) -> None:
         with self._lock:
-            if agent_key in self._grants:
-                return
-            self._grants.add(agent_key)
+            existing = self._grants.get(agent_key, {"expires_at": None, "tier": None})
+            self._grants[agent_key] = {**existing, "revoked": True}
             self._save()

agentpayments_python/pricing.py

@@ -0,0 +1,70 @@
+"""
+Pricing/access-model resolution shared by all three adapters (Django,
+FastAPI, Flask): payment-amount -> access-duration tiers, and per-route
+price/duration/tier overrides for a single middleware instance.
+
+Config shapes (plain dicts, so they're trivial to declare in settings.py or
+pass as constructor kwargs):
+
+    pricing_tier = {"min_amount": 0.01, "duration_seconds": 3600, "name": "hourly"}
+    route_config = {"path_prefix": "/premium", "min_payment": 0.05,
+                     "access_duration": None, "pricing_tiers": None}
+"""
+
+from __future__ import annotations
+
+
+def sort_tiers(tiers: list[dict]) -> list[dict]:
+    return sorted(tiers, key=lambda t: t["min_amount"])
+
+
+def resolve_tier(amount_paid: float | None, pricing_tiers: list[dict] | None) -> dict | None:
+    """Highest tier whose min_amount the actual paid amount satisfies, or None."""
+    if not pricing_tiers or amount_paid is None:
+        return None
+    matched = None
+    for tier in sort_tiers(pricing_tiers):
+        if amount_paid >= tier["min_amount"]:
+            matched = tier
+        else:
+            break
+    return matched
+
+
+def normalize_price_config(min_payment: float, access_duration: float | None, pricing_tiers: list[dict] | None) -> dict:
+    """Collapses a (min_payment, access_duration, pricing_tiers) config into
+    its effective floor price (lowest tier's min_amount when tiers are set)."""
+    if pricing_tiers:
+        sorted_tiers = sort_tiers(pricing_tiers)
+        return {"min_payment": sorted_tiers[0]["min_amount"], "access_duration": None, "pricing_tiers": sorted_tiers}
+    return {"min_payment": min_payment, "access_duration": access_duration, "pricing_tiers": None}
+
+
+def path_matches_prefix(pathname: str, prefix: str) -> bool:
+    if pathname == prefix:
+        return True
+    boundary = prefix if prefix.endswith("/") else prefix + "/"
+    return pathname.startswith(boundary)
+
+
+def build_routes_table(routes: list[dict] | None, min_payment: float, access_duration: float | None, pricing_tiers: list[dict] | None) -> list[dict]:
+    """Precomputes normalized route entries once at middleware-construction time."""
+    table = []
+    for r in routes or []:
+        normalized = normalize_price_config(
+            r.get("min_payment", min_payment),
+            r.get("access_duration", access_duration),
+            r.get("pricing_tiers", pricing_tiers),
+        )
+        table.append({"path_prefix": r["path_prefix"], **normalized})
+    return table
+
+
+def resolve_route_config(pathname: str, routes_table: list[dict], base_config: dict) -> dict:
+    """Longest-prefix match against routes_table, falling back to base_config."""
+    best = None
+    for route in routes_table:
+        if path_matches_prefix(pathname, route["path_prefix"]):
+            if best is None or len(route["path_prefix"]) > len(best["path_prefix"]):
+                best = route
+    return best or base_config

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,26 +98,48 @@ 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, 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. rpc_url may be a string or list of strings (fallback URLs).
+    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, 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, 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
+    resolve pricing tiers. rpc_url may be a string or list of strings
+    (fallback URLs).
 
     fee_info, when set (hosted-platform mode with an on-chain fee configured), is
     {"wallet": str, "rate_pct": float}. When set, the SAME transaction that carries
     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.
+    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 True
+        return {"paid": True, "amount_paid": None}  # cache doesn't retain the amount
     if cached is False:
-        return False  # negative cached — skip RPC until TTL expires
+        return not_paid  # 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
+        return not_paid
     try:
         # commitment: 'finalized' — confirmed blocks can be rolled back (rare but possible).
         # Finalized adds ~10-20 s latency vs confirmed but guarantees irreversibility.
@@ -128,16 +150,16 @@ def verify_payment_on_chain(agent_key: str, wallet_address: str, rpc_url, usdc_m
         # 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
+            return not_paid  # vendor has no USDC account yet — no payment possible
 
         fee_usdc_accounts = None
         fee_amount_micro = 0
         if fee_info:
             fee_ata_data = _rpc_call_with_fallback(rpc_urls, "getTokenAccountsByOwner", [fee_info["wallet"], {"mint": usdc_mint}, {"encoding": "jsonParsed", "commitment": "finalized"}])
             fee_usdc_accounts = {a["pubkey"] for a in fee_ata_data.get("result", {}).get("value", [])}
-            fee_amount_micro = round(MIN_PAYMENT_MICRO * fee_info["rate_pct"] / 100)
+            fee_amount_micro = round(min_payment_micro * fee_info["rate_pct"] / 100)
             if not fee_usdc_accounts:
-                return False  # fee wallet has no USDC account — fee can never be satisfied
+                return not_paid  # fee wallet has no USDC account — fee can never be satisfied
 
         addresses_to_scan = [wallet_address] + token_accounts
         seen = set()
@@ -173,6 +195,7 @@ def verify_payment_on_chain(agent_key: str, wallet_address: str, rpc_url, usdc_m
             has_memo = False
             has_payment = False
             has_fee_payment = fee_info is None  # vacuously satisfied when no fee is required
+            matched_amount_micro = None
 
             for ix in all_ix:
                 program = ix.get("program", "")
@@ -206,16 +229,17 @@ def verify_payment_on_chain(agent_key: str, wallet_address: str, rpc_url, usdc_m
                             amount_micro = int(amount_str)
                         except (ValueError, TypeError):
                             amount_micro = 0
-                        if is_vendor_dest and amount_micro >= MIN_PAYMENT_MICRO:
+                        if is_vendor_dest and amount_micro >= min_payment_micro:
                             has_payment = True
+                            matched_amount_micro = amount_micro
                         elif is_fee_dest and amount_micro >= fee_amount_micro:
                             has_fee_payment = True
 
             if has_memo and has_payment and has_fee_payment:
-                _payment_cache.set(agent_key, True, PAYMENT_CACHE_TTL)
-                return True
+                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)
-    return False
+    cache.set(agent_key, False, NEGATIVE_CACHE_TTL)
+    return not_paid

agentpayments_python/x402.py

@@ -30,6 +30,7 @@ def build_payment_requirements(
     debug: bool,
     agent_key: str = "",
     resource: str = "",
+    tier: dict | None = None,
 ) -> dict:
     """
     Build an x402-standard PaymentRequirements dict for the Solana exact scheme.
@@ -42,6 +43,9 @@ def build_payment_requirements(
         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).
+        tier:           Optional {"name": str, "duration_seconds": int|None} —
+                        non-standard x402 extension surfacing pricing-tier
+                        duration so an agent can compare tiers upfront.
 
     Returns:
         PaymentRequirements dict per the x402 SVM exact scheme spec.
@@ -59,6 +63,7 @@ def build_payment_requirements(
             "name": "USDC",
             "decimals": USDC_DECIMALS,
             **({"memo": agent_key} if agent_key else {}),
+            **({"tier": tier.get("name"), "durationSeconds": tier.get("duration_seconds")} if tier else {}),
         },
     }
     if resource:
@@ -66,6 +71,23 @@ def build_payment_requirements(
     return req
 
 
+def tier_x402_opts_list(pricing_tiers: list[dict] | None, base_opts: dict) -> list[dict]:
+    """
+    Builds one build_payment_requirements()-kwargs dict per non-floor pricing
+    tier, so the 402 response's accepts[] array lets an agent compare
+    price/duration tradeoffs upfront. The floor tier is already covered by
+    the primary entry built from the resolved base min_payment.
+    """
+    if not pricing_tiers or len(pricing_tiers) < 2:
+        return []
+    from .pricing import sort_tiers
+    sorted_tiers = sort_tiers(pricing_tiers)
+    return [
+        {**base_opts, "min_payment": t["min_amount"], "tier": {"name": t.get("name"), "duration_seconds": t.get("duration_seconds")}}
+        for t in sorted_tiers[1:]
+    ]
+
+
 def build_payment_object(
     *,
     network: str,
@@ -116,13 +138,13 @@ def payment_required_header(payment_requirements: dict) -> str:
     return base64.b64encode(_json.dumps(payment_requirements).encode()).decode()
 
 
-def enrich_402_body(body: dict, payment_requirements: dict) -> dict:
+def enrich_402_body(body: dict, payment_requirements: dict, extra_payment_requirements: list[dict] | None = None) -> 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],
+        "accepts": [payment_requirements, *(extra_payment_requirements or [])],
         **body,
     }

{agentpayments_python-0.1.2.dist-info → agentpayments_python-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpayments-python
-Version: 0.1.2
+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
@@ -116,9 +116,16 @@ register_agentpayments(
 | `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. |
+| `min_payment` | No | `0.01` | Minimum USDC payment required. Ignored when `pricing_tiers` is set (the lowest tier's `min_amount` becomes the floor). |
+| `access_duration` | No | `None` (forever) | Seconds a successful payment grants access for. Requires `grant_store` to actually persist. |
+| `pricing_tiers` | No | `None` | Payment-amount → access mapping: `[{"min_amount": ..., "duration_seconds": ..., "name": ...}]`. Overrides `min_payment`/`access_duration`. |
+| `routes` | No | `None` | Per-route overrides for a single middleware instance: `[{"path_prefix": ..., "min_payment": ..., "access_duration": ..., "pricing_tiers": ...}]`, matched by longest `path_prefix`. |
 | `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.
 
@@ -126,6 +133,72 @@ Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`, `settin
 
 Setting `api_key` switches agent-key issuance from local (`ag_...`) to platform-issued (`agp_...`), and — when the platform account has an on-chain fee configured — every 402 response's `payment` dict gains a `platform_fee` field describing a second required USDC transfer, to be sent in the **same Solana transaction** as the vendor payment. Missing that second transfer is treated as an unpaid request, same as any other invalid payment. This is opt-in per vendor account and has no effect on self-hosted deployments (no `api_key`). The standards-compliant `accepts[]`/`X-PAYMENT-REQUIRED` x402 fields are untouched — they still describe only the vendor leg.
 
+## Pricing & Access Model
+
+By default one `min_payment` buys indefinite access. Three parameters layer on top, identical across Django/FastAPI/Flask (Django via `settings.AGENTPAYMENTS_*`, the others as constructor kwargs):
+
+```python
+# FastAPI / Flask
+register_agentpayments(  # or AgentPaymentsASGIMiddleware(...)
+    app, ...,
+    grant_store=FileGrantStore("./data/grants.json"),  # required for duration/tiers to persist
+    access_duration=86400,  # seconds; a paid key is only good for 24h, then re-verifies
+    pricing_tiers=[
+        {"min_amount": 0.01, "duration_seconds": 3600,  "name": "hourly"},
+        {"min_amount": 0.05, "duration_seconds": 86400, "name": "daily"},
+        {"min_amount": 0.50, "duration_seconds": None,  "name": "lifetime"},
+    ],
+    routes=[
+        {"path_prefix": "/api/premium", "min_payment": 0.05},
+        {"path_prefix": "/api/basic",   "min_payment": 0.01},
+    ],
+)
+```
+
+```python
+# Django settings.py
+AGENTPAYMENTS_GRANT_STORE = FileGrantStore("/var/data/agp_grants.json")
+AGENTPAYMENTS_ACCESS_DURATION = 86400
+AGENTPAYMENTS_PRICING_TIERS = [...]  # same shape as above
+AGENTPAYMENTS_ROUTES = [...]
+```
+
+`pricing_tiers` overrides `min_payment`/`access_duration` when set — the gate finds the highest tier the actual on-chain payment clears and grants that tier's duration; the lowest tier's `min_amount` becomes the floor price for any access at all. Every non-floor tier also appears as its own entry in the 402 response's x402 `accepts[]` array. `routes` is matched by longest `path_prefix` on a path-segment boundary; unmatched requests fall back to the top-level `min_payment`/`access_duration`/`pricing_tiers`.
+
+**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
@@ -150,6 +223,9 @@ agentpayments_python/
   detection.py           Browser detection and public path checks
   solana.py              On-chain payment verification + caching
   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.3.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+agentpayments_python/__init__.py,sha256=-_ZaZGRDrd1kueJ5wvc4A4P_wt6QOchSG9gLK_BKlH4,952
+agentpayments_python/challenge.py,sha256=feWqlTcQ1LMONuwFBUOQBQOw5tsO1f7PirZZN_S3e3A,6386
+agentpayments_python/constants.json,sha256=GbrHSYfHwCGq8kgdNAiOdyqhc3-s-oX2qWvjRsbhjVo,981
+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=5KRaVdlMjOUaE167WTQyDXWIwF6sRFZ1DGZ2eqtoBAQ,1938
+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/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.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,,

agentpayments_python-0.1.2.dist-info/RECORD

@@ -1,20 +0,0 @@
-agentpayments_python/__init__.py,sha256=-_ZaZGRDrd1kueJ5wvc4A4P_wt6QOchSG9gLK_BKlH4,952
-agentpayments_python/challenge.py,sha256=feWqlTcQ1LMONuwFBUOQBQOw5tsO1f7PirZZN_S3e3A,6386
-agentpayments_python/constants.json,sha256=GbrHSYfHwCGq8kgdNAiOdyqhc3-s-oX2qWvjRsbhjVo,981
-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=5KRaVdlMjOUaE167WTQyDXWIwF6sRFZ1DGZ2eqtoBAQ,1938
-agentpayments_python/django_adapter.py,sha256=vmFLt0d-IliHsIi7zpGxSegS2dmSAapaIg9chfXvlgY,13138
-agentpayments_python/fastapi_adapter.py,sha256=3rhe-uGoJ9vNMcyAr5M0rloZQFTDZ18-45BpWYTnxfs,12714
-agentpayments_python/flask_adapter.py,sha256=ns2dgoOWrrvNgJ4oZDVV68vBwxzGcIINOBY6Sk0ht6A,10996
-agentpayments_python/grant_store.py,sha256=wqRsSdbpzd_TGy6a6LJRtNOMbjVBJQm7H3qpIVHEeuw,2643
-agentpayments_python/platform_client.py,sha256=T-fSzxsABXVJ9nfrqL370GboV2-hdJaA-ploOw0uOd8,5108
-agentpayments_python/ratelimit.py,sha256=Q6uxFRbYbf7D8qykZ9ieVaSCU8FkXFYPS59XmkrnE_k,1580
-agentpayments_python/solana.py,sha256=Mlc0Ig4fGJCyuN-cClsSqIgTqXBgArTDix3jAnyCieg,10272
-agentpayments_python/x402.py,sha256=8UUG7dpYXOiLjhXfAbbBSyBuoiMuO6oVobqFk17hIM8,4336
-agentpayments_python-0.1.2.dist-info/licenses/LICENSE,sha256=PMKDe4kanHRVI7QQezG4GeluZkMljhVO-tFSFNUiYS4,1069
-agentpayments_python-0.1.2.dist-info/METADATA,sha256=h2z4XBoxpw6lzG2ljHdBbQlyyHeY9Lrhq2Zs3SkyCVM,6362
-agentpayments_python-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-agentpayments_python-0.1.2.dist-info/top_level.txt,sha256=DxGMGvTYQVdoBQ6pBbbsJXy5BZhbSjNGF_uSO3git4w,21
-agentpayments_python-0.1.2.dist-info/RECORD,,