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

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

@@ -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/README.md

@@ -0,0 +1,197 @@
+# agentpayments-python
+
+Python adapters for the AgentPayments gate. Supports Django, FastAPI/Starlette, and Flask.
+
+## Install
+
+```bash
+pip install agentpayments-python
+# or, in this monorepo:
+# pip install -e sdk/python
+```
+
+## Django
+
+```python
+# settings.py
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "agentpayments_python.django_adapter.GateMiddleware",
+    # ... other middleware
+]
+
+# Required settings
+CHALLENGE_SECRET = os.environ["CHALLENGE_SECRET"]
+HOME_WALLET_ADDRESS = os.environ["HOME_WALLET_ADDRESS"]
+
+# Optional settings
+SOLANA_RPC_URL = os.environ.get("SOLANA_RPC_URL")
+USDC_MINT = os.environ.get("USDC_MINT")
+DEBUG = True  # True = devnet, False = mainnet
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from agentpayments_python.fastapi_adapter import (
+    AgentPaymentsASGIMiddleware,
+    challenge_verify_endpoint,
+)
+
+app = FastAPI()
+
+app.add_middleware(
+    AgentPaymentsASGIMiddleware,
+    challenge_secret=os.environ["CHALLENGE_SECRET"],
+    home_wallet_address=os.environ["HOME_WALLET_ADDRESS"],
+    debug=True,
+)
+
+@app.post("/__challenge/verify")
+async def verify(request: Request):
+    return await challenge_verify_endpoint(
+        request,
+        challenge_secret=os.environ["CHALLENGE_SECRET"],
+    )
+```
+
+## Flask
+
+```python
+from flask import Flask
+from agentpayments_python.flask_adapter import register_agentpayments
+
+app = Flask(__name__)
+register_agentpayments(
+    app,
+    challenge_secret=os.environ["CHALLENGE_SECRET"],
+    home_wallet_address=os.environ["HOME_WALLET_ADDRESS"],
+    debug=True,
+)
+```
+
+## Configuration
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `challenge_secret` | Yes (production) | `'default-secret-change-me'` | HMAC secret for signing cookies, nonces, and agent keys. |
+| `home_wallet_address` | Yes | `''` | Solana wallet address to receive USDC payments. |
+| `solana_rpc_url` | No | Auto (devnet/mainnet) | Custom Solana RPC endpoint. |
+| `usdc_mint` | No | Auto (devnet/mainnet) | Custom USDC mint address. |
+| `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.
+
+## Hosted Platform Mode
+
+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
+- **Payment verification cache** — 10-minute TTL, 1000-entry max (thread-safe)
+- **Rate limiting** — 20 challenge verifications per minute per IP (thread-safe)
+- **Input size limits** — key (64 chars), nonce (128), return URL (2048), fingerprint (128)
+- **Wallet address validation** — base58 format, 32-44 chars, validated at init
+- **Default secret detection** — warns in debug, raises `RuntimeError` in production
+- **Secure cookies** — Django auto-detects HTTPS via `request.is_secure()`
+
+## Module Structure
+
+```
+agentpayments_python/
+  __init__.py
+  django_adapter.py      Django middleware (GateMiddleware)
+  fastapi_adapter.py     FastAPI/Starlette ASGI middleware
+  flask_adapter.py       Flask integration (before_request hook)
+  challenge.py           Shared challenge HTML generation
+  cookies.py             Cookie creation and validation
+  crypto.py              HMAC signing and agent key management
+  detection.py           Browser detection and public path checks
+  solana.py              On-chain payment verification + caching
+  ratelimit.py           Shared IP-based rate limiter
+  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
+- Constants loaded from `sdk/constants.json` via `pathlib`.
+- Logging uses Python stdlib `logging` module.
+- All shared modules are framework-agnostic; adapters are thin wiring.

{agentpayments_python-0.1.2 → agentpayments_python-0.3.0}/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-0.1.2 → agentpayments_python-0.3.0}/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]