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

@@ -47,6 +47,16 @@ class AgentCorePaymentsPluginConfig:
             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
@@ -63,6 +73,7 @@ class AgentCorePaymentsPluginConfig:
     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."""
@@ -99,6 +110,18 @@ def __post_init__(self) -> None:
         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

@@ -2,6 +2,7 @@
 
 import json
 import logging
+import time
 import uuid
 from typing import Any, Dict, Optional, Union
 
@@ -251,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)

tests/bedrock_agentcore/payments/integrations/strands/test_plugin.py

@@ -1800,3 +1800,168 @@ def test_allowlist_none_allows_all_tools(self):
 
             mock_handler.extract_status_code.assert_called_once()
             mock_pm_instance.generate_payment_header.assert_called_once()
+
+
+class TestPostPaymentRetryDelay:
+    """Tests for post_payment_retry_delay_seconds backoff before tool retry.
+
+    The x402 EIP-3009 transferWithAuthorization contract requires
+    block.timestamp > validAfter (strict greater-than). When the signing
+    service sets validAfter near the current time, fast facilitators submit
+    in the same second the signature was minted and hit a deterministic
+    revert. The plugin sleeps post_payment_retry_delay_seconds between
+    signing and re-invoking the tool to let the chain advance.
+    """
+
+    @patch("bedrock_agentcore.payments.integrations.strands.plugin.time.sleep")
+    @patch("bedrock_agentcore.payments.integrations.strands.plugin.PaymentManager")
+    def test_default_delay_is_three_seconds(self, mock_payment_manager_class, mock_sleep):
+        """Default post_payment_retry_delay_seconds is 3.0 — sleep is called with 3.0."""
+        config = AgentCorePaymentsPluginConfig(
+            payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/test",
+            user_id="test-user",
+            payment_instrument_id="payment-instrument-123",
+            payment_session_id="payment-session-456",
+        )
+        assert config.post_payment_retry_delay_seconds == 3.0
+
+        mock_pm_instance = MagicMock()
+        mock_pm_instance.generate_payment_header.return_value = {"X-PAYMENT": "base64"}
+        plugin = AgentCorePaymentsPlugin(config=config)
+        plugin.payment_manager = mock_pm_instance
+
+        event, agent = _create_event_with_agent(
+            {
+                "result": [{"text": f"PAYMENT_REQUIRED: {json.dumps({'statusCode': 402, 'headers': {}, 'body': {}})}"}],
+                "tool_use": {"name": "http_request", "toolUseId": "tool-123", "input": {"headers": {}}},
+                "invocation_state": {},
+                "retry": False,
+            }
+        )
+        plugin.after_tool_call(event)
+
+        assert event.retry is True
+        mock_sleep.assert_called_once_with(3.0)
+
+    @patch("bedrock_agentcore.payments.integrations.strands.plugin.time.sleep")
+    @patch("bedrock_agentcore.payments.integrations.strands.plugin.PaymentManager")
+    def test_custom_delay_value(self, mock_payment_manager_class, mock_sleep):
+        """A custom positive delay is honored verbatim."""
+        config = AgentCorePaymentsPluginConfig(
+            payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/test",
+            user_id="test-user",
+            payment_instrument_id="payment-instrument-123",
+            payment_session_id="payment-session-456",
+            post_payment_retry_delay_seconds=1.5,
+        )
+
+        mock_pm_instance = MagicMock()
+        mock_pm_instance.generate_payment_header.return_value = {"X-PAYMENT": "base64"}
+        plugin = AgentCorePaymentsPlugin(config=config)
+        plugin.payment_manager = mock_pm_instance
+
+        event, agent = _create_event_with_agent(
+            {
+                "result": [{"text": f"PAYMENT_REQUIRED: {json.dumps({'statusCode': 402, 'headers': {}, 'body': {}})}"}],
+                "tool_use": {"name": "http_request", "toolUseId": "tool-123", "input": {"headers": {}}},
+                "invocation_state": {},
+                "retry": False,
+            }
+        )
+        plugin.after_tool_call(event)
+
+        mock_sleep.assert_called_once_with(1.5)
+
+    @patch("bedrock_agentcore.payments.integrations.strands.plugin.time.sleep")
+    @patch("bedrock_agentcore.payments.integrations.strands.plugin.PaymentManager")
+    def test_zero_delay_skips_sleep(self, mock_payment_manager_class, mock_sleep):
+        """post_payment_retry_delay_seconds=0 skips the sleep entirely."""
+        config = AgentCorePaymentsPluginConfig(
+            payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/test",
+            user_id="test-user",
+            payment_instrument_id="payment-instrument-123",
+            payment_session_id="payment-session-456",
+            post_payment_retry_delay_seconds=0,
+        )
+
+        mock_pm_instance = MagicMock()
+        mock_pm_instance.generate_payment_header.return_value = {"X-PAYMENT": "base64"}
+        plugin = AgentCorePaymentsPlugin(config=config)
+        plugin.payment_manager = mock_pm_instance
+
+        event, agent = _create_event_with_agent(
+            {
+                "result": [{"text": f"PAYMENT_REQUIRED: {json.dumps({'statusCode': 402, 'headers': {}, 'body': {}})}"}],
+                "tool_use": {"name": "http_request", "toolUseId": "tool-123", "input": {"headers": {}}},
+                "invocation_state": {},
+                "retry": False,
+            }
+        )
+        plugin.after_tool_call(event)
+
+        # Tool should still be set to retry — sleep is the only thing skipped.
+        assert event.retry is True
+        mock_sleep.assert_not_called()
+
+    @patch("bedrock_agentcore.payments.integrations.strands.plugin.time.sleep")
+    @patch("bedrock_agentcore.payments.integrations.strands.plugin.PaymentManager")
+    def test_sleep_does_not_fire_when_payment_fails(self, mock_payment_manager_class, mock_sleep):
+        """If signing fails, no sleep should run — we never reach the retry path."""
+        from bedrock_agentcore.payments.manager import PaymentInstrumentNotFound
+
+        config = AgentCorePaymentsPluginConfig(
+            payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/test",
+            user_id="test-user",
+            payment_instrument_id="payment-instrument-123",
+            payment_session_id="payment-session-456",
+        )
+
+        mock_pm_instance = MagicMock()
+        mock_pm_instance.generate_payment_header.side_effect = PaymentInstrumentNotFound("missing")
+        plugin = AgentCorePaymentsPlugin(config=config)
+        plugin.payment_manager = mock_pm_instance
+
+        event, agent = _create_event_with_agent(
+            {
+                "result": [{"text": f"PAYMENT_REQUIRED: {json.dumps({'statusCode': 402, 'headers': {}, 'body': {}})}"}],
+                "tool_use": {"name": "http_request", "toolUseId": "tool-123", "input": {"headers": {}}},
+                "invocation_state": {},
+                "retry": False,
+            }
+        )
+        plugin.after_tool_call(event)
+
+        mock_sleep.assert_not_called()
+
+    def test_validator_rejects_negative_delay(self):
+        """post_payment_retry_delay_seconds cannot be negative."""
+        import pytest
+
+        with pytest.raises(ValueError, match="post_payment_retry_delay_seconds must be >= 0"):
+            AgentCorePaymentsPluginConfig(
+                payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/test",
+                user_id="test-user",
+                post_payment_retry_delay_seconds=-1.0,
+            )
+
+    def test_validator_rejects_non_numeric_delay(self):
+        """post_payment_retry_delay_seconds must be int/float, not bool/str."""
+        import pytest
+
+        with pytest.raises(ValueError, match="post_payment_retry_delay_seconds must be a number"):
+            AgentCorePaymentsPluginConfig(
+                payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/test",
+                user_id="test-user",
+                post_payment_retry_delay_seconds="3",  # type: ignore[arg-type]
+            )
+
+    def test_validator_rejects_bool_delay(self):
+        """bool sneaks through isinstance(int) — explicitly reject."""
+        import pytest
+
+        with pytest.raises(ValueError, match="post_payment_retry_delay_seconds must be a number"):
+            AgentCorePaymentsPluginConfig(
+                payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/test",
+                user_id="test-user",
+                post_payment_retry_delay_seconds=True,  # type: ignore[arg-type]
+            )