fix(payments): drop unsupported paymentConnectorId + add http_request plugin tool + EIP-3009 timing fix (#493)

* fix(payments): drop unsupported paymentConnectorId from ProcessPayment call

ProcessPayment's public API contract (bedrock-agentcore Data Plane) does
not accept a paymentConnectorId field — the connector is resolved server
side from the payment instrument. The SDK was forwarding the param,
causing every real ProcessPayment call to fail at the boto3 layer with:

  Parameter validation failed:
  Unknown parameter in input: "paymentConnectorId", must be one of:
  userId, agentName, paymentManagerArn, paymentSessionId,
  paymentInstrumentId, paymentType, paymentInput, clientToken

The bug surfaced end-to-end when AgentCorePaymentsPlugin auto-paid a
402 response: get_payment_instrument succeeded, then generate_payment_header
forwarded payment_connector_id into process_payment, which appended it to
the API call and was rejected. Unit tests passed because they mock the
boto3 client and don't validate the param schema.

Fix: stop including paymentConnectorId in the ProcessPayment request body,
and stop forwarding it from generate_payment_header. The kwarg is kept on
both function signatures for backward compatibility, with docstrings
updated to note that it is accepted but no longer forwarded.

Adds a regression test asserting paymentConnectorId is absent from the
ProcessPayment kwargs even when callers pass it explicitly.

* feat(payments): add http_request tool to AgentCorePaymentsPlugin

Ships a Strands @tool method on AgentCorePaymentsPlugin that performs HTTP
requests and emits Strands ToolResult content blocks the SDK's payment
handlers can parse. When the endpoint returns 402 Payment Required, the
tool prefixes the content block with the spec-compliant PAYMENT_REQUIRED:
marker, so the plugin's existing after_tool_call hook intercepts the
result, generates an x402 payment header via PaymentManager, and Strands
re-invokes the tool with the payment header injected.

Why on the plugin: aligns with how get_payment_instrument /
list_payment_instruments / get_payment_session are already exposed —
adding the plugin to a Strands agent now produces a turnkey paid-HTTP
experience without requiring strands-agents-tools or hand-written httpx
code in customer agents.

httpx is already a hard SDK dep; no new dependencies are introduced.
The 402 envelope (statusCode + headers + body) matches what
GenericPaymentHandler / HttpRequestPaymentHandler already parse, so the
existing handler dispatch lights up automatically.

Tests cover:
- 200 envelope shape (Strands ToolResult dict, not a raw list)
- 402 wrapped with PAYMENT_REQUIRED: marker
- End-to-end contract: tool output -> get_payment_handler -> 402
- GET ignores body, POST sends dict as JSON, str body sent verbatim
- Caller header dict isolated (mutations don't bleed back)
- Non-JSON body falls back to {"text": ...}
- httpx.RequestError returned as status='error' (not raised)
- Method casing normalization
- Default headers when caller omits

All 490 payments tests pass.

* style(payments): apply ruff format to plugin + tests

* feat(payments): provide_http_request opt-out flag for AgentCorePaymentsPlugin

Strands' tool registry raises ValueError on duplicate tool names, so a
caller who wants to ship their own http_request currently can't — the
plugin's auto-discovered http_request crashes Agent construction first.

Add provide_http_request: bool = True to AgentCorePaymentsPluginConfig.
When True (default), behavior is unchanged: the plugin's http_request
@tool is auto-registered. When False, the plugin filters its own
http_request out of self._tools right after super().__init__() so the
caller can pass their own without a name collision.

Auto-payment of 402 responses still works against any tool whose output
emits the PAYMENT_REQUIRED: content marker — the after_tool_call hook
is independent of the tool registration, so disabling the flag does
not disable interception.

Adds 5 tests:
- default registers http_request
- opt-out drops only http_request (other plugin tools intact)
- opt-out preserves the after_tool_call/before_tool_call hooks
- config validator rejects non-bool values for the flag
- init_agent still works with the flag off

All 495 payments tests pass.

* feat(payments): add post_payment_retry_delay_seconds to fix EIP-3009 timing race

The x402 EIP-3009 transferWithAuthorization contract requires
block.timestamp > validAfter — a strict greater-than check, not
greater-or-equal. When the signing service mints a signature with
validAfter set to ~current Unix time, fast merchant facilitators submit
the transaction within the same second the signature was minted, hitting
the contract's strict check before block.timestamp advances. The seller
returns a misleading 402 with reason "invalid_payload" or
"invalid_exact_evm_transaction_simulation_failed" — but the signature
is structurally valid; it's a race between minting and submission.

Verified empirically: same signed payload reverts via eth_call within
the validAfter second, then succeeds 5+ seconds later. Once the chain
advances one block past validAfter, the seller's facilitator submits and
the on-chain transferWithAuthorization settles. Real Base Sepolia
transaction proving the round-trip:
0x0e542e2d5c3c97521bd47231d299c6d56841fe0865f63ebfaa92d6f47e28b6b6

Add post_payment_retry_delay_seconds: float = 3.0 to
AgentCorePaymentsPluginConfig. Sleeps that many seconds in
after_tool_call right before setting event.retry = True, so by the time
Strands re-invokes the tool with the PAYMENT-SIGNATURE header, the
chain has advanced one block past validAfter.

3.0s default chosen as ~one Base Sepolia block (~2s) plus margin. Set
to 0 to disable for tests or chains with sub-second blocks.

Adds 7 tests:
- default delay is 3.0
- custom positive delay is honored
- zero delay skips the sleep entirely (event.retry still set)
- no sleep when signing fails (we never reach the retry path)
- validator rejects negative values
- validator rejects non-numeric values (str)
- validator rejects bool (which would otherwise sneak through isinstance(int))

All 502 payments tests pass.

Author: aidandaly24

src/bedrock_agentcore/payments/integrations/config.py

@@ -39,6 +39,24 @@ class AgentCorePaymentsPluginConfig:
             eligible (preserving existing behavior). When set, only tool calls whose
             name appears in this list will trigger payment processing; all others are
             skipped.
+        provide_http_request: Whether the plugin should register its built-in
+            ``http_request`` ``@tool`` on the agent. Defaults to True so adding the
+            plugin gives a turnkey paid-HTTP experience. Set to False if you want
+            to ship your own ``http_request`` tool — Strands raises a ValueError
+            on duplicate tool names, so you must opt out of the plugin's version
+            before passing your own. Auto-payment of 402 responses still works
+            against any tool whose output carries the ``PAYMENT_REQUIRED:``
+            content marker, so disabling this flag does not disable interception.
+        post_payment_retry_delay_seconds: Seconds to wait after generating a
+            payment header before allowing the tool to be retried. The x402
+            EIP-3009 ``transferWithAuthorization`` contract requires
+            ``block.timestamp > validAfter`` (strict greater-than). Some signing
+            services set ``validAfter`` close to the current time, which can
+            cause the merchant facilitator to submit before ``validAfter``
+            elapses, producing a misleading "invalid_payload" response. A small
+            delay between signing and retry lets the chain advance one block so
+            the authorization is valid by the time the seller submits. Defaults
+            to 3.0 seconds (about one Base Sepolia block). Set to 0 to disable.
     """
 
     payment_manager_arn: str
@@ -54,6 +72,8 @@ class AgentCorePaymentsPluginConfig:
     bearer_token: Optional[str] = None
     token_provider: Optional[Callable[[], str]] = None
     payment_tool_allowlist: Optional[List[str]] = None
+    provide_http_request: bool = True
+    post_payment_retry_delay_seconds: float = 3.0
 
     def __post_init__(self) -> None:
         """Validate configuration after initialization."""
@@ -87,6 +107,21 @@ def __post_init__(self) -> None:
             if not all(isinstance(t, str) for t in self.payment_tool_allowlist):
                 raise ValueError("All entries in payment_tool_allowlist must be strings")
 
+        if not isinstance(self.provide_http_request, bool):
+            raise ValueError(f"provide_http_request must be a boolean, got {type(self.provide_http_request).__name__}")
+
+        if not isinstance(self.post_payment_retry_delay_seconds, (int, float)) or isinstance(
+            self.post_payment_retry_delay_seconds, bool
+        ):
+            raise ValueError(
+                "post_payment_retry_delay_seconds must be a number, got "
+                f"{type(self.post_payment_retry_delay_seconds).__name__}"
+            )
+        if self.post_payment_retry_delay_seconds < 0:
+            raise ValueError(
+                f"post_payment_retry_delay_seconds must be >= 0, got {self.post_payment_retry_delay_seconds}"
+            )
+
     def update_payment_session_id(self, payment_session_id: str) -> None:
         """Update the payment session ID.
 

src/bedrock_agentcore/payments/integrations/strands/plugin.py

@@ -1,9 +1,12 @@
 """AgentCorePaymentsPlugin for Strands Agents framework."""
 
+import json
 import logging
+import time
 import uuid
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Union
 
+import httpx
 from strands.hooks import AfterToolCallEvent, BeforeToolCallEvent
 from strands.plugins import Plugin, hook
 from strands.tools import tool
@@ -25,7 +28,8 @@
 class AgentCorePaymentsPlugin(Plugin):
     """Plugin for handling X402 payment requirements and providing payment tools in Strands Agents.
 
-    This plugin provides three tools for querying payment information:
+    This plugin provides tools for querying payment information and making paid HTTP calls:
+    - http_request: Call a (paid) HTTP endpoint; 402 responses are settled automatically
     - getPaymentInstrument: Retrieve details about a specific payment instrument
     - listPaymentInstruments: List all payment instruments for a user
     - getPaymentSession: Retrieve details about a specific payment session
@@ -55,6 +59,18 @@ def __init__(self, config: AgentCorePaymentsPluginConfig):
         super().__init__()
         self.config = config
         self.payment_manager: Optional[PaymentManager] = None
+
+        # Honor the provide_http_request opt-out: Strands' Plugin base auto-discovers
+        # every @tool method into self._tools at super().__init__(). If the caller
+        # wants to ship their own http_request, drop ours so Strands' tool registry
+        # doesn't raise ValueError on duplicate tool name.
+        if not self.config.provide_http_request:
+            self._tools = [t for t in self._tools if t.tool_name != "http_request"]
+            logger.info(
+                "provide_http_request=False — plugin's http_request tool will not be registered. "
+                "Auto-payment still triggers on any tool emitting a PAYMENT_REQUIRED: marker."
+            )
+
         logger.info("Initialized AgentCorePaymentsPlugin")
 
     def init_agent(self, agent) -> None:
@@ -236,6 +252,20 @@ def after_tool_call(self, event: AfterToolCallEvent) -> None:
             # after this retry, we know it's a server-side rejection, not a signing failure.
             self._mark_successful_signing(event)
 
+            # Wait one chain-block before letting the tool retry, so the merchant's
+            # facilitator has time to see block.timestamp > validAfter when it submits
+            # transferWithAuthorization to USDC. Without this delay, fast facilitators
+            # can submit in the same second the signature was minted, hitting the
+            # contract's strict ``block.timestamp > validAfter`` check and producing
+            # a misleading "invalid_payload" 402 from the seller.
+            delay = self.config.post_payment_retry_delay_seconds
+            if delay > 0:
+                logger.info(
+                    "Waiting %.1fs before retry to allow chain to advance past validAfter",
+                    delay,
+                )
+                time.sleep(delay)
+
             # Set retry flag to re-execute the tool with payment credentials.
             event.retry = True
             self._reset_interrupt_retry_count(event)
@@ -726,3 +756,87 @@ def get_payment_session(
                 str(e),
             )
             raise
+
+    @tool
+    def http_request(
+        self,
+        url: str,
+        method: str = "GET",
+        headers: Optional[Dict[str, str]] = None,
+        body: Optional[Union[Dict[str, Any], str]] = None,
+    ) -> Dict[str, Any]:
+        """Call an HTTP endpoint. 402 Payment Required responses are settled automatically.
+
+        When the endpoint responds with HTTP 402, this plugin's after_tool_call hook
+        intercepts the result, generates an x402 payment header via the configured
+        PaymentManager, mutates ``headers`` with the X-PAYMENT (v1) or
+        PAYMENT-SIGNATURE (v2) header, and Strands re-invokes this tool — yielding
+        the final 200 response and (when applicable) a settle hash in the
+        PAYMENT-RESPONSE header.
+
+        Returns a Strands ToolResult dict: ``status`` is always ``success`` (HTTP
+        errors are returned in the body, not raised), and ``content`` is a single
+        text block. On 402 the text is prefixed with ``PAYMENT_REQUIRED:`` so the
+        SDK's payment handlers can extract the x402 payload.
+
+        Args:
+            url: The full URL to request.
+            method: HTTP method. Defaults to ``GET``.
+            headers: Optional request headers. The plugin mutates this dict to add
+                the payment header on retry.
+            body: Optional request body. ``dict`` is sent as JSON; ``str`` is sent
+                as-is. Ignored for ``GET``/``HEAD``.
+
+        Returns:
+            Strands ToolResult dict with ``status`` and ``content``.
+        """
+        request_headers = dict(headers) if headers else {}
+        method_upper = method.upper()
+
+        try:
+            with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+                if body is None or method_upper in ("GET", "HEAD"):
+                    resp = client.request(method_upper, url, headers=request_headers)
+                elif isinstance(body, str):
+                    resp = client.request(method_upper, url, headers=request_headers, content=body)
+                else:
+                    resp = client.request(method_upper, url, headers=request_headers, json=body)
+        except httpx.RequestError as exc:
+            logger.error("http_request failed for %s: %s", url, exc)
+            return {
+                "status": "error",
+                "content": [
+                    {
+                        "text": json.dumps(
+                            {
+                                "statusCode": 0,
+                                "error": f"Request failed: {exc}",
+                                "url": url,
+                            }
+                        )
+                    }
+                ],
+            }
+
+        response_headers = dict(resp.headers)
+        try:
+            response_body: Any = resp.json()
+        except Exception:
+            response_body = {"text": resp.text}
+
+        payload = {
+            "statusCode": resp.status_code,
+            "headers": response_headers,
+            "body": response_body,
+        }
+
+        if resp.status_code == 402:
+            return {
+                "status": "success",
+                "content": [{"text": f"PAYMENT_REQUIRED: {json.dumps(payload)}"}],
+            }
+
+        return {
+            "status": "success",
+            "content": [{"text": json.dumps(payload)}],
+        }

src/bedrock_agentcore/payments/manager.py

@@ -844,7 +844,10 @@ def process_payment(
             payment_input: Payment input details specific to the payment type
             user_id: Unique identifier for the user (optional, omitted for bearer auth)
             client_token: Optional idempotency token for request uniqueness
-            payment_connector_id: Optional payment connector ID to route the payment
+            payment_connector_id: Accepted for backward compatibility but no longer
+                forwarded to the service. ProcessPayment derives the connector from
+                the payment instrument; sending paymentConnectorId on this call was
+                rejected by the API as an unknown parameter.
 
         Returns:
             Dictionary containing processPaymentId and transaction details
@@ -873,8 +876,9 @@ def process_payment(
                 "paymentInput": payment_input,
                 "clientToken": client_token,
             }
-            if payment_connector_id is not None:
-                params["paymentConnectorId"] = payment_connector_id
+            # paymentConnectorId is intentionally NOT included — the ProcessPayment
+            # API does not accept it and rejects requests that contain it. The
+            # connector is resolved server-side from the payment instrument.
 
             result = self._payment_client.process_payment(**params)
             logger.info("Successfully processed payment for user %s", user_id)
@@ -935,7 +939,10 @@ def generate_payment_header(
             network_preferences: Optional list of network identifiers in order of preference.
                 If not provided, defaults to NETWORK_PREFERENCES from constants.
             client_token: Optional unique token for idempotency. If not provided, a new one is generated.
-            payment_connector_id: Optional payment connector ID to pass to process_payment.
+            payment_connector_id: Accepted for backward compatibility but no longer
+                forwarded to process_payment. ProcessPayment derives the connector
+                from the payment instrument; sending paymentConnectorId on that call
+                was rejected by the API as an unknown parameter.
 
         Returns:
             Dictionary with header name and value (e.g., {"X-PAYMENT": "base64..."} or
@@ -1045,18 +1052,18 @@ def generate_payment_header(
                 }
             }
 
-            process_payment_params = {
-                "user_id": user_id,
-                "payment_session_id": payment_session_id,
-                "payment_instrument_id": payment_instrument_id,
-                "payment_type": "CRYPTO_X402",
-                "payment_input": payment_input,
-                "client_token": client_token,
-            }
-            if payment_connector_id is not None:
-                process_payment_params["payment_connector_id"] = payment_connector_id
-
-            payment_result = self.process_payment(**process_payment_params)
+            # ProcessPayment does not accept paymentConnectorId — the connector is
+            # resolved server-side from the payment instrument. The argument is
+            # intentionally not forwarded, even when callers (e.g. plugins) supply
+            # it via plugin config.
+            payment_result = self.process_payment(
+                user_id=user_id,
+                payment_session_id=payment_session_id,
+                payment_instrument_id=payment_instrument_id,
+                payment_type="CRYPTO_X402",
+                payment_input=payment_input,
+                client_token=client_token,
+            )
             logger.debug("Payment processed successfully")
 
             # Extract cryptoX402 proof from payment result