agentpayments-python 0.1.0__tar.gz → 0.1.1__tar.gz

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpayments-python
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -117,8 +117,14 @@ register_agentpayments(
 | `solana_rpc_url` | No | Auto (devnet/mainnet) | Custom Solana RPC endpoint. |
 | `usdc_mint` | No | Auto (devnet/mainnet) | Custom USDC mint address. |
 | `debug` | No | `True` | `True` = devnet. `False` = mainnet + strict mode. |
+| `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. |
 
-Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`). FastAPI and Flask accept them as constructor arguments.
+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.
 
 ## Security Features
 

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/README.md

@@ -80,8 +80,14 @@ register_agentpayments(
 | `solana_rpc_url` | No | Auto (devnet/mainnet) | Custom Solana RPC endpoint. |
 | `usdc_mint` | No | Auto (devnet/mainnet) | Custom USDC mint address. |
 | `debug` | No | `True` | `True` = devnet. `False` = mainnet + strict mode. |
+| `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. |
 
-Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`). FastAPI and Flask accept them as constructor arguments.
+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.
 
 ## Security Features
 

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/agentpayments_python/constants.json

@@ -22,6 +22,6 @@
   "X402_VERSION": 1,
   "SOLANA_CHAIN_ID_MAINNET": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
   "SOLANA_CHAIN_ID_DEVNET": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
-  "PLATFORM_API_URL": "https://api.agentpayments.dev",
+  "PLATFORM_API_URL": "https://api.agentpayments.cloud",
   "HOSTED_KEY_PREFIX": "agp_"
 }

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/agentpayments_python/django_adapter.py

@@ -12,7 +12,7 @@ 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_requirements, enrich_402_body, payment_required_header
+from .x402 import build_payment_object, build_payment_requirements, enrich_402_body, payment_required_header
 from .platform_client import HOSTED_KEY_PREFIX, PlatformClient, is_valid_hosted_key
 
 import json as _json
@@ -105,6 +105,16 @@ class GateMiddleware:
         }
         if not is_browser_from_headers(headers):
             agent_key = request.META.get("HTTP_X_AGENT_KEY")
+
+            # Resolve the on-chain platform fee requirement once (hosted-platform
+            # mode only — always None for self-hosted vendors with no platform client).
+            fee_info = None
+            if self._platform_client:
+                try:
+                    fee_info = self._platform_client.get_platform_fee_info()
+                except Exception as exc:
+                    logger.warning("Failed to fetch platform fee info, proceeding without fee enforcement: %s", exc)
+
             if not agent_key:
                 # Hosted mode: issue metered platform key (agp_).
                 # Local mode: generate self-signed key (ag_).
@@ -116,20 +126,20 @@ class GateMiddleware:
                         new_key = generate_agent_key(secret)
                 else:
                     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'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.'
                 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": {
-                            "chain": "solana",
-                            "network": network,
-                            "token": "USDC",
-                            "amount": str(MIN_PAYMENT),
-                            "wallet_address": wallet_address,
-                            "memo": new_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.',
-                        },
+                        "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),
                     },
                     wallet_address=wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
                     debug=self.debug, agent_key=new_key, resource=pathname,
@@ -160,7 +170,7 @@ 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)
+            paid = verify_payment_on_chain(agent_key, wallet_address, self.rpc_url, self.usdc_mint, fee_info=fee_info)
             if paid and self.grant_store:
                 self.grant_store.add(agent_key)
             if not paid:
@@ -169,14 +179,7 @@ class GateMiddleware:
                         "error": "payment_required",
                         "message": "Key is valid but payment has not been verified on-chain yet.",
                         "your_key": agent_key,
-                        "payment": {
-                            "chain": "solana",
-                            "network": network,
-                            "token": "USDC",
-                            "amount": str(MIN_PAYMENT),
-                            "wallet_address": wallet_address,
-                            "memo": agent_key,
-                        },
+                        "payment": build_payment_object(network=network, min_payment=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,
                     debug=self.debug, agent_key=agent_key, resource=pathname,

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/agentpayments_python/fastapi_adapter.py

@@ -11,7 +11,7 @@ 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_requirements, enrich_402_body, payment_required_header
+from .x402 import build_payment_object, build_payment_requirements, enrich_402_body, payment_required_header
 from .platform_client import HOSTED_KEY_PREFIX, PlatformClient, is_valid_hosted_key
 
 import json as _json
@@ -88,6 +88,18 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
         if not is_browser_from_headers(dict(request.headers)):
             agent_key = request.headers.get("x-agent-key")
             network = "devnet" if self.debug else "mainnet-beta"
+            loop = asyncio.get_event_loop()
+
+            # Resolve the on-chain platform fee requirement once (hosted-platform
+            # mode only — always None for self-hosted vendors with no platform client).
+            fee_info = None
+            if self._platform_client:
+                try:
+                    fee_info = await loop.run_in_executor(None, self._platform_client.get_platform_fee_info)
+                except Exception as exc:
+                    import logging as _log
+                    _log.getLogger("agentpayments").warning("Failed to fetch platform fee info, proceeding without fee enforcement: %s", exc)
+
             if not agent_key:
                 if self._platform_client:
                     try:
@@ -98,20 +110,20 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
                         new_key = generate_agent_key(self.challenge_secret)
                 else:
                     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'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.'
                 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": {
-                            "chain": "solana",
-                            "network": network,
-                            "token": "USDC",
-                            "amount": str(MIN_PAYMENT),
-                            "wallet_address": self.home_wallet_address,
-                            "memo": new_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.',
-                        },
+                        "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),
                     },
                     wallet_address=self.home_wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
                     debug=self.debug, agent_key=new_key, resource=path,
@@ -143,9 +155,8 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
 
             # verify_payment_on_chain is synchronous (uses requests). Run it in a
             # thread-pool executor so it doesn't block the async event loop.
-            loop = asyncio.get_event_loop()
             paid = await loop.run_in_executor(
-                None, verify_payment_on_chain, agent_key, self.home_wallet_address, self.solana_rpc_url, self.usdc_mint
+                None, lambda: verify_payment_on_chain(agent_key, self.home_wallet_address, self.solana_rpc_url, self.usdc_mint, fee_info=fee_info)
             )
             if paid and self.grant_store:
                 self.grant_store.add(agent_key)
@@ -155,7 +166,7 @@ class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
                         "error": "payment_required",
                         "message": "Key is valid but payment has not been verified on-chain yet.",
                         "your_key": agent_key,
-                        "payment": {"chain": "solana", "network": network, "token": "USDC", "amount": str(MIN_PAYMENT), "wallet_address": self.home_wallet_address, "memo": 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),
                     },
                     wallet_address=self.home_wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
                     debug=self.debug, agent_key=agent_key, resource=path,

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/agentpayments_python/flask_adapter.py

@@ -8,7 +8,7 @@ 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_requirements, enrich_402_body, payment_required_header
+from .x402 import build_payment_object, build_payment_requirements, enrich_402_body, payment_required_header
 from .platform_client import HOSTED_KEY_PREFIX, PlatformClient, is_valid_hosted_key
 
 import json as _json
@@ -71,6 +71,17 @@ def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: s
         if not is_browser_from_headers(request.headers):
             key = request.headers.get("X-Agent-Key")
             network = "devnet" if debug else "mainnet-beta"
+
+            # Resolve the on-chain platform fee requirement once (hosted-platform
+            # mode only — always None for self-hosted vendors with no platform client).
+            fee_info = None
+            if _platform_client:
+                try:
+                    fee_info = _platform_client.get_platform_fee_info()
+                except Exception as exc:
+                    import logging as _log
+                    _log.getLogger("agentpayments").warning("Failed to fetch platform fee info, proceeding without fee enforcement: %s", exc)
+
             if not key:
                 if _platform_client:
                     try:
@@ -81,20 +92,20 @@ def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: s
                         new_key = generate_agent_key(challenge_secret)
                 else:
                     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'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.'
                 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": {
-                            "chain": "solana",
-                            "network": network,
-                            "token": "USDC",
-                            "amount": str(MIN_PAYMENT),
-                            "wallet_address": home_wallet_address,
-                            "memo": new_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.',
-                        },
+                        "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),
                     },
                     wallet_address=home_wallet_address, mint=mint, min_payment=MIN_PAYMENT,
                     debug=debug, agent_key=new_key, resource=path,
@@ -118,7 +129,7 @@ def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: s
                 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)
+            paid = verify_payment_on_chain(key, home_wallet_address, rpc_url, mint, fee_info=fee_info)
             if paid and grant_store:
                 grant_store.add(key)
             if not paid:
@@ -127,7 +138,7 @@ def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: s
                         "error": "payment_required",
                         "message": "Key is valid but payment has not been verified on-chain yet.",
                         "your_key": key,
-                        "payment": {"chain": "solana", "network": network, "token": "USDC", "amount": str(MIN_PAYMENT), "wallet_address": home_wallet_address, "memo": key},
+                        "payment": build_payment_object(network=network, min_payment=MIN_PAYMENT, wallet_address=home_wallet_address, memo=key, fee_info=fee_info),
                     },
                     wallet_address=home_wallet_address, mint=mint, min_payment=MIN_PAYMENT,
                     debug=debug, agent_key=key, resource=path,

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/agentpayments_python/platform_client.py

@@ -63,8 +63,13 @@ class PlatformClient:
 
     def __init__(self, api_key: str, platform_url: str = PLATFORM_API_URL) -> None:
         self.api_key = api_key
-        self.platform_url = platform_url.rstrip("/")
+        # Callers (django/fastapi/flask adapters) often pass platform_url=None
+        # explicitly when no override was configured, which bypasses this
+        # parameter's own default — fall back to PLATFORM_API_URL here too.
+        self.platform_url = (platform_url or PLATFORM_API_URL).rstrip("/")
         self._verification_secret: str | None = None
+        self._platform_fee_info: dict | None = None
+        self._account_fetched = False
         self._lock = threading.Lock()
 
     def _auth_headers(self) -> dict:
@@ -98,19 +103,38 @@ class PlatformClient:
         except urllib.error.HTTPError as exc:
             raise RuntimeError(f"Platform API {path} returned {exc.code}") from exc
 
-    @property
-    def verification_secret(self) -> str:
-        """Fetch + cache verificationSecret from /v1/account (thread-safe)."""
-        if self._verification_secret:
-            return self._verification_secret
+    def _ensure_account_fetched(self) -> None:
+        """Fetch + cache the /v1/account response once (thread-safe, double-checked)."""
+        if self._account_fetched:
+            return
         with self._lock:
-            # Double-checked locking
-            if self._verification_secret:
-                return self._verification_secret
+            if self._account_fetched:
+                return
             data = self._get("/v1/account")
             self._verification_secret = data["verificationSecret"]
+            fee_wallet = data.get("platformFeeWallet")
+            self._platform_fee_info = (
+                {"wallet": fee_wallet, "rate_pct": data.get("platformFeeRatePct")}
+                if fee_wallet
+                else None
+            )
+            self._account_fetched = True
+
+    @property
+    def verification_secret(self) -> str:
+        """Fetch + cache verificationSecret from /v1/account (thread-safe)."""
+        self._ensure_account_fetched()
         return self._verification_secret
 
+    def get_platform_fee_info(self) -> dict | None:
+        """
+        Fetch + cache the on-chain platform fee config from /v1/account (same
+        request as verification_secret — no extra round trip if already fetched).
+        Returns {"wallet": str, "rate_pct": float} or None if no fee is configured.
+        """
+        self._ensure_account_fetched()
+        return self._platform_fee_info
+
     def issue_key(self) -> str:
         """Issue a single platform-signed agent key (agp_...). Metered."""
         data = self._post("/v1/keys/issue")

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/agentpayments_python/solana.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import json
 import logging
 import re
@@ -96,8 +98,15 @@ def is_valid_solana_address(address: str) -> bool:
     return bool(address and BASE58_RE.match(address))
 
 
-def verify_payment_on_chain(agent_key: str, wallet_address: str, rpc_url, usdc_mint: str) -> bool:
-    """Verify payment on-chain. rpc_url may be a string or list of strings (fallback URLs)."""
+def verify_payment_on_chain(agent_key: str, wallet_address: str, rpc_url, usdc_mint: str, fee_info: dict | None = None) -> bool:
+    """
+    Verify payment on-chain. 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.
+    """
     # 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]
 
@@ -121,6 +130,15 @@ def verify_payment_on_chain(agent_key: str, wallet_address: str, rpc_url, usdc_m
         if not vendor_usdc_accounts:
             return False  # 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)
+            if not fee_usdc_accounts:
+                return False  # fee wallet has no USDC account — fee can never be satisfied
+
         addresses_to_scan = [wallet_address] + token_accounts
         seen = set()
         all_signatures = []
@@ -154,6 +172,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
 
             for ix in all_ix:
                 program = ix.get("program", "")
@@ -169,8 +188,12 @@ def verify_payment_on_chain(agent_key: str, wallet_address: str, rpc_url, usdc_m
                     tx_type = parsed.get("type", "")
                     if tx_type in ("transfer", "transferChecked"):
                         info = parsed.get("info", {})
-                        # Payment must be delivered to one of the vendor's USDC token accounts.
-                        if info.get("destination") not in vendor_usdc_accounts:
+                        destination = info.get("destination")
+                        # Payment must be delivered to one of the vendor's or fee
+                        # wallet's USDC token accounts — anything else is irrelevant.
+                        is_vendor_dest = destination in vendor_usdc_accounts
+                        is_fee_dest = fee_usdc_accounts is not None and destination in fee_usdc_accounts
+                        if not is_vendor_dest and not is_fee_dest:
                             continue
                         if tx_type == "transferChecked" and info.get("mint") != usdc_mint:
                             continue
@@ -183,10 +206,12 @@ 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 amount_micro >= MIN_PAYMENT_MICRO:
+                        if is_vendor_dest and amount_micro >= MIN_PAYMENT_MICRO:
                             has_payment = True
+                        elif is_fee_dest and amount_micro >= fee_amount_micro:
+                            has_fee_payment = True
 
-            if has_memo and has_payment:
+            if has_memo and has_payment and has_fee_payment:
                 _payment_cache.set(agent_key, True, PAYMENT_CACHE_TTL)
                 return True
     except Exception:

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/agentpayments_python/x402.py

@@ -7,6 +7,8 @@ requirements from our 402 responses.
 
 Spec: https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_svm.md
 """
+from __future__ import annotations
+
 import base64
 import json as _json
 import math
@@ -64,6 +66,48 @@ def build_payment_requirements(
     return req
 
 
+def build_payment_object(
+    *,
+    network: str,
+    min_payment: float,
+    wallet_address: str,
+    memo: str,
+    fee_info: dict | None = None,
+    instructions: str = "",
+) -> dict:
+    """
+    Build the custom `payment` dict for a 402 body — NOT part of the x402 spec
+    (that's build_payment_requirements above, which stays vendor-leg-only). When
+    fee_info is set (hosted-platform mode with an on-chain fee configured), adds
+    a platform_fee field describing the second required transfer. Deliberately
+    not added as a second x402 accepts[] entry — that would read to a
+    spec-compliant client as an alternative payment method, not an additional
+    requirement.
+
+    fee_info: {"wallet": str, "rate_pct": float} or None.
+    """
+    payment: dict = {
+        "chain": "solana",
+        "network": network,
+        "token": "USDC",
+        "amount": str(min_payment),
+        "wallet_address": wallet_address,
+        "memo": memo,
+    }
+    if fee_info:
+        fee_amount_micro = round(round(min_payment * 1_000_000) * fee_info["rate_pct"] / 100)
+        payment["platform_fee"] = {
+            "wallet_address": fee_info["wallet"],
+            "amount": str(fee_amount_micro / 1_000_000),
+            "token": "USDC",
+            "rate_pct": fee_info["rate_pct"],
+            "note": "Must be a second USDC transfer inside the SAME Solana transaction as the payment above, or access will be denied.",
+        }
+    if instructions:
+        payment["instructions"] = instructions
+    return payment
+
+
 def payment_required_header(payment_requirements: dict) -> str:
     """
     Return the value for the X-PAYMENT-REQUIRED response header.

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/agentpayments_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpayments-python
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -117,8 +117,14 @@ register_agentpayments(
 | `solana_rpc_url` | No | Auto (devnet/mainnet) | Custom Solana RPC endpoint. |
 | `usdc_mint` | No | Auto (devnet/mainnet) | Custom USDC mint address. |
 | `debug` | No | `True` | `True` = devnet. `False` = mainnet + strict mode. |
+| `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. |
 
-Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`). FastAPI and Flask accept them as constructor arguments.
+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.
 
 ## Security Features
 

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/pyproject.toml

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

{agentpayments_python-0.1.0 → agentpayments_python-0.1.1}/tests/test_core.py

@@ -587,8 +587,47 @@ def _rpc_response(result):
     )
 
 
-def _build_tx(memo: str, amount: float, mint: str, destination_owner: str, ok=True):
-    """Build a minimal mock RPC getTransaction response for a transferChecked."""
+def _build_tx(memo: str, amount: float, mint: str, destination_owner: str, ok=True, fee_amount: float = None):
+    """Build a minimal mock RPC getTransaction response for a transferChecked.
+
+    fee_amount, if given, adds a second transferChecked instruction (in the SAME
+    transaction) to a distinct "fee_ata_address" destination — simulating the
+    on-chain platform fee leg.
+    """
+    instructions = [
+        {
+            "program": "spl-token",
+            "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+            "parsed": {
+                "type": "transferChecked",
+                "info": {
+                    "mint": mint,
+                    "tokenAmount": {"uiAmount": amount, "amount": str(round(amount * 1_000_000)), "decimals": 6},
+                    "destination": "dest_ata_address",
+                    "authority": "payer_address",
+                },
+            },
+        },
+    ]
+    if fee_amount is not None:
+        instructions.append({
+            "program": "spl-token",
+            "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+            "parsed": {
+                "type": "transferChecked",
+                "info": {
+                    "mint": mint,
+                    "tokenAmount": {"uiAmount": fee_amount, "amount": str(round(fee_amount * 1_000_000)), "decimals": 6},
+                    "destination": "fee_ata_address",
+                    "authority": "payer_address",
+                },
+            },
+        })
+    instructions.append({
+        "program": "spl-memo",
+        "programId": "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr",
+        "parsed": memo,
+    })
     return {
         "meta": {
             "err": None if ok else {"InstructionError": [0, "Custom"]},
@@ -597,26 +636,7 @@ def _build_tx(memo: str, amount: float, mint: str, destination_owner: str, ok=Tr
         },
         "transaction": {
             "message": {
-                "instructions": [
-                    {
-                        "program": "spl-token",
-                        "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
-                        "parsed": {
-                            "type": "transferChecked",
-                            "info": {
-                                "mint": mint,
-                                "tokenAmount": {"uiAmount": amount, "amount": str(round(amount * 1_000_000)), "decimals": 6},
-                                "destination": "dest_ata_address",
-                                "authority": "payer_address",
-                            },
-                        },
-                    },
-                    {
-                        "program": "spl-memo",
-                        "programId": "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr",
-                        "parsed": memo,
-                    },
-                ],
+                "instructions": instructions,
                 "accountKeys": [],
             }
         },
@@ -625,21 +645,28 @@ def _build_tx(memo: str, amount: float, mint: str, destination_owner: str, ok=Tr
 
 class TestVerifyPaymentOnChain:
     WALLET = "5rXZeAEbg13DQnSFijEno2hKEJLK2p14fAo3AmPtfBft"
+    FEE_WALLET = "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
     MINT = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"  # devnet USDC
     RPC = "https://api.devnet.solana.com"
 
     def _fresh_key(self):
         return generate_agent_key(SECRET)
 
-    def _patch_rpc(self, sigs_result, ata_result, tx_result):
-        """Return a context manager that patches requests.post with ordered responses."""
-        from unittest.mock import call
+    def _patch_rpc(self, sigs_result, ata_result, tx_result, fee_ata_result=None):
+        """Return a context manager that patches requests.post with ordered responses.
 
-        responses = []
+        When fee_ata_result is given, getTokenAccountsByOwner is dispatched by the
+        queried owner (params[0]): self.WALLET -> ata_result, self.FEE_WALLET ->
+        fee_ata_result — mirrors the two separate ATA lookups verify_payment_on_chain
+        makes when fee_info is set.
+        """
 
         def side_effect(url, json=None, timeout=None):
             method = json.get("method", "")
             if method == "getTokenAccountsByOwner":
+                owner = (json.get("params") or [None])[0]
+                if fee_ata_result is not None and owner == self.FEE_WALLET:
+                    return _rpc_response(fee_ata_result)
                 return _rpc_response(ata_result)
             if method == "getSignaturesForAddress":
                 return _rpc_response(sigs_result)
@@ -765,3 +792,107 @@ class TestVerifyPaymentOnChain:
         with patch("requests.post", side_effect=Exception("should not be called")):
             result = verify_payment_on_chain(key, self.WALLET, self.RPC, self.MINT)
         assert result is False
+
+
+class TestVerifyPaymentOnChainFee:
+    """On-chain platform fee leg — hosted-mode vendors only (fee_info set)."""
+
+    WALLET = TestVerifyPaymentOnChain.WALLET
+    FEE_WALLET = TestVerifyPaymentOnChain.FEE_WALLET
+    MINT = TestVerifyPaymentOnChain.MINT
+    RPC = TestVerifyPaymentOnChain.RPC
+    FEE_INFO = {"wallet": FEE_WALLET, "rate_pct": 2}
+    FEE_AMOUNT = 0.01 * 0.02  # 2% of MIN_PAYMENT (0.01)
+
+    def _fresh_key(self):
+        return generate_agent_key(SECRET)
+
+    def _ata(self, pubkey, owner):
+        return {"value": [{"pubkey": pubkey, "account": {"data": {"parsed": {"info": {"mint": self.MINT, "owner": owner}}}}}]}
+
+    def _patch_rpc(self, sigs_result, ata_result, tx_result, fee_ata_result):
+        """getTokenAccountsByOwner is dispatched by the queried owner (params[0])."""
+
+        def side_effect(url, json=None, timeout=None):
+            method = json.get("method", "")
+            if method == "getTokenAccountsByOwner":
+                owner = (json.get("params") or [None])[0]
+                return _rpc_response(fee_ata_result if owner == self.FEE_WALLET else ata_result)
+            if method == "getSignaturesForAddress":
+                return _rpc_response(sigs_result)
+            if method == "getTransaction":
+                return _rpc_response(tx_result)
+            return _rpc_response(None)
+
+        return patch("requests.post", side_effect=side_effect)
+
+    def test_fee_leg_missing_denies_access(self):
+        from agentpayments_python.solana import verify_payment_on_chain
+        key = self._fresh_key()
+        tx = _build_tx(key, 0.01, self.MINT, self.WALLET)  # vendor leg only, no fee leg
+        ata = self._ata("dest_ata_address", self.WALLET)
+        fee_ata = self._ata("fee_ata_address", self.FEE_WALLET)
+        sigs = [{"signature": "fee_sig_missing", "err": None}]
+        with self._patch_rpc(sigs, ata, tx, fee_ata):
+            result = verify_payment_on_chain(key, self.WALLET, self.RPC, self.MINT, fee_info=self.FEE_INFO)
+        assert result is False
+
+    def test_fee_leg_present_grants_access(self):
+        from agentpayments_python.solana import verify_payment_on_chain
+        key = self._fresh_key()
+        tx = _build_tx(key, 0.01, self.MINT, self.WALLET, fee_amount=self.FEE_AMOUNT)
+        ata = self._ata("dest_ata_address", self.WALLET)
+        fee_ata = self._ata("fee_ata_address", self.FEE_WALLET)
+        sigs = [{"signature": "fee_sig_ok", "err": None}]
+        with self._patch_rpc(sigs, ata, tx, fee_ata):
+            result = verify_payment_on_chain(key, self.WALLET, self.RPC, self.MINT, fee_info=self.FEE_INFO)
+        assert result is True
+
+    def test_fee_leg_underpaid_denies_access(self):
+        from agentpayments_python.solana import verify_payment_on_chain
+        key = self._fresh_key()
+        tx = _build_tx(key, 0.01, self.MINT, self.WALLET, fee_amount=self.FEE_AMOUNT / 2)
+        ata = self._ata("dest_ata_address", self.WALLET)
+        fee_ata = self._ata("fee_ata_address", self.FEE_WALLET)
+        sigs = [{"signature": "fee_sig_underpaid", "err": None}]
+        with self._patch_rpc(sigs, ata, tx, fee_ata):
+            result = verify_payment_on_chain(key, self.WALLET, self.RPC, self.MINT, fee_info=self.FEE_INFO)
+        assert result is False
+
+    def test_fee_wallet_with_no_usdc_account_denies_access(self):
+        from agentpayments_python.solana import verify_payment_on_chain
+        key = self._fresh_key()
+        tx = _build_tx(key, 0.01, self.MINT, self.WALLET, fee_amount=self.FEE_AMOUNT)
+        ata = self._ata("dest_ata_address", self.WALLET)
+        fee_ata = {"value": []}  # fee wallet has no USDC ATA yet
+        sigs = [{"signature": "fee_sig_no_ata", "err": None}]
+        with self._patch_rpc(sigs, ata, tx, fee_ata):
+            result = verify_payment_on_chain(key, self.WALLET, self.RPC, self.MINT, fee_info=self.FEE_INFO)
+        assert result is False
+
+    def test_no_fee_info_skips_fee_check_entirely(self):
+        """fee_info=None (self-hosted / no platform fee configured) behaves exactly
+        like today: only one getTokenAccountsByOwner call, vendor leg alone suffices."""
+        from agentpayments_python.solana import verify_payment_on_chain
+        key = self._fresh_key()
+        tx = _build_tx(key, 0.01, self.MINT, self.WALLET)  # vendor leg only
+        ata = self._ata("dest_ata_address", self.WALLET)
+        sigs = [{"signature": "fee_sig_none", "err": None}]
+
+        ata_calls = {"n": 0}
+
+        def side_effect(url, json=None, timeout=None):
+            method = json.get("method", "")
+            if method == "getTokenAccountsByOwner":
+                ata_calls["n"] += 1
+                return _rpc_response(ata)
+            if method == "getSignaturesForAddress":
+                return _rpc_response(sigs)
+            if method == "getTransaction":
+                return _rpc_response(tx)
+            return _rpc_response(None)
+
+        with patch("requests.post", side_effect=side_effect):
+            result = verify_payment_on_chain(key, self.WALLET, self.RPC, self.MINT, fee_info=None)
+        assert result is True
+        assert ata_calls["n"] == 1