@agentlayer.tech/wallet 0.1.27 → 0.1.28

package/.openclaw/extensions/agent-wallet/dist/index.js

@@ -956,7 +956,7 @@ const walletSessionToolDefinitions = [
   {
     name: "x402_pay_request",
     description:
-      `Prepare or execute an x402 paid request using the active wallet backend. This milestone executes the Solana exact buyer flow and keeps EVM as prepare-only. ${OPENCLAW_EXECUTE_APPROVAL_GUIDANCE}`,
+      "Pay for and call an x402 endpoint using the active wallet backend. The tool probes the endpoint, validates compatibility, signs the payment, and returns the service response in one call.",
     parameters: {
       type: "object",
       properties: {
@@ -966,18 +966,9 @@ const walletSessionToolDefinitions = [
         query: { type: "object", additionalProperties: true },
         json_body: {},
         text_body: { type: "string" },
-        mode: {
-          type: "string",
-          enum: ["prepare", "execute"],
-          description: "prepare validates the payment plan; execute sends the paid retry.",
-        },
         purpose: { type: "string" },
-        user_intent: {
-          type: "boolean",
-          description: "Must be true for prepare mode.",
-        },
       },
-      required: ["url", "mode", "purpose"],
+      required: ["url", "purpose"],
       additionalProperties: false,
     },
   },

package/.openclaw/extensions/agent-wallet/index.ts

@@ -956,7 +956,7 @@ const walletSessionToolDefinitions = [
   {
     name: "x402_pay_request",
     description:
-      `Prepare or execute an x402 paid request using the active wallet backend. This milestone executes the Solana exact buyer flow and keeps EVM as prepare-only. ${OPENCLAW_EXECUTE_APPROVAL_GUIDANCE}`,
+      "Pay for and call an x402 endpoint using the active wallet backend. The tool probes the endpoint, validates compatibility, signs the payment, and returns the service response in one call.",
     parameters: {
       type: "object",
       properties: {
@@ -966,18 +966,9 @@ const walletSessionToolDefinitions = [
         query: { type: "object", additionalProperties: true },
         json_body: {},
         text_body: { type: "string" },
-        mode: {
-          type: "string",
-          enum: ["prepare", "execute"],
-          description: "prepare validates the payment plan; execute sends the paid retry.",
-        },
         purpose: { type: "string" },
-        user_intent: {
-          type: "boolean",
-          description: "Must be true for prepare mode.",
-        },
       },
-      required: ["url", "mode", "purpose"],
+      required: ["url", "purpose"],
       additionalProperties: false,
     },
   },

package/.openclaw/extensions/agent-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayertech/agent-wallet-plugin",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "OpenClaw plugin bridge for the AgentLayer wallet runtime.",
   "type": "module",
   "license": "SEE LICENSE IN ../../../LICENSE",

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## v0.1.28 - 2026-05-28
+
+- Simplified `x402_pay_request` into a single-shot paid execution flow while
+  keeping `x402_preview_request` as an optional research tool.
+- Hardened x402 execution with explicit payment requirement validation, longer
+  paid-request timeouts, structured settlement logging, and safer settlement
+  header parsing.
+- Fixed Base x402 EVM signing by normalizing typed-data byte fields before
+  sending them through the local WDK signer bridge.
+- Reduced x402 preview confusion in OpenClaw by exposing a payment summary
+  without approval-token style confirmation semantics.
+- Added an early safety guard for `x402.alchemy.com` so unsupported wallet-auth
+  flows fail before spending funds.
+
 ## v0.1.27 - 2026-05-27
 
 - Improved Solana swap fallback landing by enabling Jupiter dynamic slippage

package/agent-wallet/agent_wallet/openclaw_adapter.py

@@ -245,8 +245,9 @@ class OpenClawWalletAdapter:
             AgentToolSpec(
                 name="x402_pay_request",
                 description=(
-                    "Prepare or execute an x402 paid request using the active wallet backend. "
-                    "This milestone executes the Solana exact buyer flow and keeps EVM as prepare-only."
+                    "Pay for and call an x402 endpoint using the active wallet backend. "
+                    "The tool probes the endpoint, validates compatibility, signs the payment, "
+                    "and returns the service response in one call."
                 ),
                 input_schema={
                     "type": "object",
@@ -257,26 +258,13 @@ class OpenClawWalletAdapter:
                         "query": {"type": "object", "additionalProperties": True},
                         "json_body": {},
                         "text_body": {"type": "string"},
-                        "mode": {
-                            "type": "string",
-                            "enum": ["prepare", "execute"],
-                            "description": "prepare validates the payment plan; execute sends the paid retry.",
-                        },
                         "purpose": {"type": "string"},
-                        "user_intent": {
-                            "type": "boolean",
-                            "description": "Must be true for prepare mode.",
-                        },
-                        "approval_token": {
-                            "type": "string",
-                            "description": "Required for execute mode and must be issued against the exact x402 payment summary.",
-                        },
                     },
-                    "required": ["url", "mode", "purpose"],
+                    "required": ["url", "purpose"],
                     "additionalProperties": False,
                 },
                 read_only=False,
-                requires_explicit_user_intent=True,
+                requires_explicit_user_intent=False,
                 risk_level="high",
             ),
         ]
@@ -872,6 +860,42 @@ class OpenClawWalletAdapter:
             )
         return annotated
 
+    def _annotate_x402_payload(
+        self,
+        payload: dict[str, Any],
+        *,
+        mode: str,
+    ) -> dict[str, Any]:
+        if not payload.get("payment_required"):
+            return dict(payload)
+        annotated = self._annotate_sensitive_payload(
+            payload,
+            action_label="x402 paid request",
+            mode=mode,
+        )
+        summary = dict(annotated.get("confirmation_summary") or {})
+        if summary:
+            annotated["payment_summary"] = summary
+        requirements = dict(annotated.get("confirmation_requirements") or {})
+        requirements["prepare_requires_user_intent"] = False
+        requirements["execute_requires_approval_token"] = False
+        requirements["execute_requires_mainnet_confirmed_in_token"] = False
+        annotated.pop("approval_hint", None)
+        if mode == "preview":
+            annotated.pop("confirmation_summary", None)
+            annotated.pop("confirmation_requirements", None)
+            if annotated.get("is_mainnet"):
+                annotated["preview_note"] = (
+                    "This is a paid mainnet endpoint preview only. Review the service URL, network, asset, amount, and payment destination before calling x402_pay_request."
+                )
+            return annotated
+        annotated["confirmation_requirements"] = requirements
+        if annotated.get("is_mainnet"):
+            annotated["mainnet_warning"] = (
+                "Mainnet x402 payment. Confirm the service URL, network, asset, amount, and payment destination before paying."
+            )
+        return annotated
+
     def list_tools(self) -> list[AgentToolSpec]:
         """Return wallet tools suitable for agent registration."""
         capabilities = self.backend.get_capabilities()
@@ -3309,14 +3333,7 @@ class OpenClawWalletAdapter:
                     text_body=text_body,
                 )
                 if data.get("payment_required"):
-                    data = self._annotate_sensitive_payload(
-                        data,
-                        action_label="x402 paid request",
-                        mode="preview",
-                    )
-                    approval_hint = dict(data.get("approval_hint") or {})
-                    approval_hint["tool_name"] = "x402_pay_request"
-                    data["approval_hint"] = approval_hint
+                    data = self._annotate_x402_payload(data, mode="preview")
                 return AgentToolResult(tool=tool_name, ok=True, data=data)
 
             if tool_name == "x402_pay_request":
@@ -3326,10 +3343,7 @@ class OpenClawWalletAdapter:
                 query = args.get("query")
                 json_body = args.get("json_body")
                 text_body = args.get("text_body")
-                mode = str(args.get("mode") or "").strip().lower()
                 purpose = args.get("purpose")
-                user_intent = args.get("user_intent")
-                approval_token = args.get("approval_token")
                 if not isinstance(url, str) or not url.strip():
                     raise WalletBackendError("url is required.")
                 if method is not None and not isinstance(method, str):
@@ -3340,51 +3354,9 @@ class OpenClawWalletAdapter:
                     raise WalletBackendError("query must be an object when provided.")
                 if text_body is not None and not isinstance(text_body, str):
                     raise WalletBackendError("text_body must be a string when provided.")
-                if mode not in {"prepare", "execute"}:
-                    raise WalletBackendError("mode must be 'prepare' or 'execute'.")
                 if not isinstance(purpose, str) or not purpose.strip():
                     raise WalletBackendError("purpose is required.")
-                if mode == "prepare":
-                    self._require_prepare_intent(user_intent)
-                    data = await x402.prepare_request(
-                        backend=active_backend,
-                        url=url.strip(),
-                        method=method,
-                        headers=headers,
-                        query=query,
-                        json_body=json_body,
-                        text_body=text_body,
-                    )
-                    data["purpose"] = purpose.strip()
-                    data = self._annotate_sensitive_payload(
-                        data,
-                        action_label="x402 paid request",
-                        mode="prepare",
-                    )
-                    return AgentToolResult(tool=tool_name, ok=True, data=data)
-                preview = await x402.prepare_request(
-                    backend=active_backend,
-                    url=url.strip(),
-                    method=method,
-                    headers=headers,
-                    query=query,
-                    json_body=json_body,
-                    text_body=text_body,
-                )
-                preview["purpose"] = purpose.strip()
-                preview = self._annotate_sensitive_payload(
-                    preview,
-                    action_label="x402 paid request",
-                    mode="execute",
-                )
-                self._require_execute_approval(
-                    approval_token=approval_token,
-                    tool_name=tool_name,
-                    summary=preview["confirmation_summary"],
-                    action_label="x402 paid request",
-                    backend=active_backend,
-                )
-                data = await x402.execute_request(
+                data = await x402.pay_and_fetch(
                     backend=active_backend,
                     url=url.strip(),
                     method=method,
@@ -3394,11 +3366,7 @@ class OpenClawWalletAdapter:
                     text_body=text_body,
                 )
                 data["purpose"] = purpose.strip()
-                data = self._annotate_sensitive_payload(
-                    data,
-                    action_label="x402 paid request",
-                    mode="execute",
-                )
+                data = self._annotate_x402_payload(data, mode="execute")
                 return AgentToolResult(tool=tool_name, ok=True, data=data)
 
             if tool_name == "get_wallet_capabilities":

package/agent-wallet/agent_wallet/providers/x402.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import base64
 import hashlib
 import json
+import logging
 from typing import Any
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 
@@ -15,6 +16,7 @@ from agent_wallet.wallet_layer.base import AgentWalletBackend
 
 CDP_BAZAAR_DISCOVERY_BASE_URL = "https://api.cdp.coinbase.com/platform/v2/x402/discovery"
 AGENTIC_MARKET_API_BASE_URL = "https://api.agentic.market/v1"
+X402_EXECUTE_TIMEOUT_SECONDS = 45.0
 SOLANA_CAIP_BY_NETWORK = {
     "mainnet": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
     "devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
@@ -32,6 +34,7 @@ _USDC_IDENTIFIERS = {
     "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
     "epjfwdd5aufqssqem2qn1xzybapc8g4wegkgkzwytdt1v",
 }
+log = logging.getLogger("agent_wallet.x402")
 
 
 def _backend_chain(backend: AgentWalletBackend) -> str:
@@ -137,6 +140,13 @@ def _append_query(url: str, query: dict[str, str]) -> str:
     )
 
 
+def _request_host(url: str) -> str:
+    try:
+        return _trim(urlsplit(url).netloc).lower()
+    except Exception:
+        return ""
+
+
 def _response_text(response: Any) -> str:
     try:
         text = response.text
@@ -513,6 +523,7 @@ def _build_request_metadata(
     )
     return {
         "url": final_url,
+        "host": _request_host(final_url),
         "method": http_method,
         "headers": normalized_headers,
         "query": normalized_query,
@@ -529,6 +540,7 @@ async def _send_request(
     client: Any,
     request: dict[str, Any],
     extra_headers: dict[str, str] | None = None,
+    timeout: float | None = None,
 ) -> Any:
     headers = dict(request["headers"])
     if extra_headers:
@@ -539,6 +551,7 @@ async def _send_request(
         headers=headers,
         json=request["json_body"] if request["json_body"] is not None else None,
         content=request["text_body"] if request["text_body"] is not None else None,
+        timeout=timeout,
     )
 
 
@@ -671,6 +684,96 @@ def _require_executable_payment(
     return selected
 
 
+def _validate_payment_requirement(
+    selected: dict[str, Any] | None,
+    *,
+    backend: AgentWalletBackend,
+    request_url: str,
+) -> dict[str, Any]:
+    if not isinstance(selected, dict):
+        raise ProviderError(
+            "x402-validate",
+            "This endpoint returned HTTP 402 but no compatible payment option was found for the active wallet.",
+            details={
+                "request_url": request_url,
+                "wallet_chain": _backend_chain(backend),
+                "wallet_network": _backend_network(backend),
+            },
+        )
+
+    scheme = _trim(selected.get("scheme")).lower()
+    if scheme != "exact":
+        raise ProviderError(
+            "x402-validate",
+            f"Unsupported x402 payment scheme '{scheme or 'unknown'}'. Only 'exact' is supported.",
+            details={"request_url": request_url, "selected_payment": selected},
+        )
+
+    if not _trim(selected.get("pay_to")):
+        raise ProviderError(
+            "x402-validate",
+            "Payment destination (payTo) is missing from the x402 requirement.",
+            details={"request_url": request_url, "selected_payment": selected},
+        )
+
+    compatibility = _requirement_compatibility(selected, backend)
+    if compatibility["currently_executable"]:
+        return selected
+
+    chain = _backend_chain(backend) or "unknown"
+    network = _backend_network(backend) or "unknown"
+    requirement_network = _trim(selected.get("network")) or "unknown"
+    if chain == "solana" and requirement_network not in SOLANA_CAIP_BY_NETWORK.values():
+        message = (
+            f"This endpoint requires payment on {requirement_network}, but the active wallet is Solana ({network})."
+        )
+    elif chain == "evm" and requirement_network not in EVM_CAIP_BY_NETWORK.values():
+        message = (
+            f"This endpoint requires payment on {requirement_network}, but the active wallet is EVM ({network})."
+        )
+    else:
+        message = str(compatibility["reason"])
+
+    raise ProviderError(
+        "x402-validate",
+        message,
+        details={
+            "request_url": request_url,
+            "selected_payment": selected,
+            "compatibility": compatibility,
+        },
+    )
+
+
+def _validate_request_execution_policy(
+    *,
+    request: dict[str, Any],
+    backend: AgentWalletBackend,
+) -> None:
+    host = _trim(request.get("host")).lower()
+    if host == "x402.alchemy.com":
+        headers = request.get("headers")
+        has_auth = isinstance(headers, dict) and any(
+            str(key).strip().lower() == "authorization" and str(value).strip()
+            for key, value in headers.items()
+        )
+        if not has_auth:
+            raise ProviderError(
+                "x402-validate",
+                (
+                    "Alchemy's x402 gateway needs wallet-auth headers in addition to the payment challenge. "
+                    "The generic x402 tool does not mint Alchemy SIWE/SIWS auth tokens yet, so this endpoint "
+                    "is not safe to execute through the generic flow."
+                ),
+                details={
+                    "request_url": request.get("url"),
+                    "host": host,
+                    "wallet_chain": _backend_chain(backend),
+                    "wallet_network": _backend_network(backend),
+                    "hint": "Use a dedicated Alchemy agent gateway integration or authenticated CLI flow.",
+                },
+            )
+
 def _select_sdk_payment_requirement(
     payment_required: Any,
     *,
@@ -940,15 +1043,57 @@ async def _create_payment_headers(
     )
 
 
-def _extract_settlement_header(response: Any) -> dict[str, Any] | None:
+def _extract_settlement_header(response: Any) -> dict[str, Any]:
     sdk = _load_x402_sdk()
+    settle = sdk["x402HTTPClientBase"]().get_payment_settle_response(
+        lambda name: response.headers.get(name)
+    )
+    return settle.model_dump(by_alias=True, exclude_none=True)
+
+
+def _extract_settlement_header_safe(response: Any) -> dict[str, Any] | None:
     try:
-        settle = sdk["x402HTTPClientBase"]().get_payment_settle_response(
-            lambda name: response.headers.get(name)
+        return _extract_settlement_header(response)
+    except Exception as exc:
+        log.warning(
+            "x402 settlement header parse failed",
+            extra={
+                "status_code": getattr(response, "status_code", None),
+                "payment_response": response.headers.get("PAYMENT-RESPONSE")
+                if hasattr(response, "headers")
+                else None,
+                "x_payment_response": response.headers.get("X-PAYMENT-RESPONSE")
+                if hasattr(response, "headers")
+                else None,
+                "error_type": type(exc).__name__,
+                "error": str(exc) or None,
+            },
         )
-    except Exception:
         return None
-    return settle.model_dump(by_alias=True, exclude_none=True)
+
+
+def _log_x402_execute(
+    *,
+    request: dict[str, Any],
+    selected_payment: dict[str, Any] | None,
+    response: Any,
+    settlement: dict[str, Any] | None,
+) -> None:
+    log.info(
+        "x402 execute completed",
+        extra={
+            "url": request.get("url"),
+            "method": request.get("method"),
+            "request_fingerprint": request.get("request_fingerprint"),
+            "x402_network": selected_payment.get("network") if isinstance(selected_payment, dict) else None,
+            "x402_asset": selected_payment.get("asset") if isinstance(selected_payment, dict) else None,
+            "x402_amount": selected_payment.get("amount") if isinstance(selected_payment, dict) else None,
+            "x402_pay_to": selected_payment.get("pay_to") if isinstance(selected_payment, dict) else None,
+            "status_code": getattr(response, "status_code", None),
+            "transaction": settlement.get("transaction") if isinstance(settlement, dict) else None,
+            "confirmed": bool(settlement and settlement.get("success")),
+        },
+    )
 
 
 async def search_services(
@@ -1250,6 +1395,29 @@ async def execute_request(
     query: dict[str, Any] | None = None,
     json_body: Any | None = None,
     text_body: str | None = None,
+) -> dict[str, Any]:
+    executed = await pay_and_fetch(
+        backend=backend,
+        url=url,
+        method=method,
+        headers=headers,
+        query=query,
+        json_body=json_body,
+        text_body=text_body,
+    )
+    executed["mode"] = "execute"
+    return executed
+
+
+async def pay_and_fetch(
+    *,
+    backend: AgentWalletBackend,
+    url: str,
+    method: str = "GET",
+    headers: dict[str, Any] | None = None,
+    query: dict[str, Any] | None = None,
+    json_body: Any | None = None,
+    text_body: str | None = None,
 ) -> dict[str, Any]:
     preview = await preview_request(
         backend=backend,
@@ -1268,7 +1436,13 @@ async def execute_request(
         executed["confirmed"] = False
         return executed
 
-    selected_payment = _require_executable_payment(preview=preview, backend=backend)
+    selected_payment = _validate_payment_requirement(
+        preview.get("selected_payment")
+        if isinstance(preview.get("selected_payment"), dict)
+        else None,
+        backend=backend,
+        request_url=str(preview.get("request_url") or url),
+    )
     payment_required_header = (
         dict(preview.get("response_headers") or {}).get("payment-required")
     )
@@ -1283,15 +1457,26 @@ async def execute_request(
         json_body=json_body,
         text_body=text_body,
     )
+    _validate_request_execution_policy(request=request, backend=backend)
     payment_headers = await _create_payment_headers(
         backend=backend,
         payment_required_header=payment_required_header,
         selected_payment=selected_payment,
     )
-    payment_headers["Access-Control-Expose-Headers"] = "PAYMENT-RESPONSE,X-PAYMENT-RESPONSE"
     client = get_client()
-    response = await _send_request(client=client, request=request, extra_headers=payment_headers)
-    settlement = _extract_settlement_header(response)
+    response = await _send_request(
+        client=client,
+        request=request,
+        extra_headers=payment_headers,
+        timeout=X402_EXECUTE_TIMEOUT_SECONDS,
+    )
+    settlement = _extract_settlement_header_safe(response)
+    _log_x402_execute(
+        request=request,
+        selected_payment=selected_payment,
+        response=response,
+        settlement=settlement,
+    )
 
     executed = dict(preview)
     executed.update(

package/agent-wallet/agent_wallet/wallet_layer/wdk_evm.py

@@ -33,6 +33,16 @@ def _lifi_chain_id_for_evm_network(network: str) -> str:
     return "1"
 
 
+def _normalize_x402_typed_data_value(value: Any) -> Any:
+    if isinstance(value, (bytes, bytearray)):
+        return "0x" + bytes(value).hex()
+    if isinstance(value, list):
+        return [_normalize_x402_typed_data_value(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _normalize_x402_typed_data_value(item) for key, item in value.items()}
+    return value
+
+
 def _extract_fee_wei(payload: dict[str, Any]) -> str | None:
     for key in ("fee", "maxFee", "totalFee", "gasCost", "cost"):
         value = payload.get(key)
@@ -457,7 +467,7 @@ class WdkEvmLocalWalletBackend(AgentWalletBackend):
                 "domain": domain,
                 "types": types,
                 "primaryType": primary_type,
-                "message": message,
+                "message": _normalize_x402_typed_data_value(message),
             },
         )
         signature = str(data.get("signature") or "").strip()

package/agent-wallet/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openclaw-agent-wallet"
-version = "0.1.27"
+version = "0.1.28"
 description = "Plugin-friendly wallet backend for OpenClaw agents"
 requires-python = ">=3.10"
 dependencies = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayer.tech/wallet",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "NPM installer for the OpenClaw Agent Wallet local runtime.",
   "type": "module",
   "repository": {