fix(metamask-agent-wallet): correct x402 v2 payment payload and related issues

Review on the PR found the v2 PaymentPayload reused the v1 top-level shape, so a v2 facilitator rejects it for missing 'accepted'. Build the v2 envelope per the spec (nest the chosen requirements under 'accepted', forward the top-level 'resource'); v1 is unchanged.

Also from review: backdate validAfter instead of '0' to match the reference client; prefer the EIP-3009 option over Permit2 and report Permit2-only offers as unsupported; read the settlement receipt from the response body when the header is absent; document the v2 payload difference and multi-network selection. Verified end to end against a real v2 facilitator on Base Sepolia plus spec-vector tests.

Author: basgys

skills/metamask-agent-wallet/references/x402.md

@@ -21,7 +21,25 @@ in the wallet. The script is pure Python standard library (run with `python3`).
 
 The script handles both protocol versions: v1 (requirements in the `402` body, retry header
 `X-PAYMENT`) and v2 (requirements in the `PAYMENT-REQUIRED` header, retry header
-`PAYMENT-SIGNATURE`).
+`PAYMENT-SIGNATURE`). The payload envelope also differs: v1 puts `scheme`/`network` at the top
+level, while v2 nests the chosen requirements under `accepted` and forwards the top-level
+`resource` (see the x402 v2 spec, PaymentPayload schema). The script builds the correct envelope
+per version.
+
+### Supported
+
+- The `exact` scheme on EVM networks (`eip155:*`) using EIP-3009
+  `transferWithAuthorization`, protocol v1 and v2.
+
+### Not supported (rejected with a clear error)
+
+- The Permit2 asset transfer method (`extra.assetTransferMethod: "permit2"`) and its gas-sponsoring
+  extensions. An EIP-3009 option on the same asset is preferred when offered; a Permit2-only offer
+  is reported as unsupported. Signing a Permit2 authorization is a separate flow.
+- Other schemes such as `upto`, and non-EVM networks (e.g. Solana).
+- Offers that omit the EIP-712 domain `name`/`version` in `extra`. The reference client falls back
+  to reading them on-chain; this script does not, so it asks for an offer that includes them rather
+  than risk signing the wrong domain.
 
 ## Usage
 

skills/metamask-agent-wallet/scripts/x402_pay.py

@@ -172,7 +172,11 @@ def asset_meta(chain_id, asset):
 
 
 def parse_402(status, headers, body):
-    """Return (version, [normalized_option, ...]). Raises if not a usable 402."""
+    """Return (version, [option, ...], resource_info). Raises if not a usable 402.
+
+    resource_info is the v2 top-level ResourceInfo object (v2 forwards it into
+    the payment payload); it is None for v1, which carries resource per option.
+    """
     if status != 402:
         raise CeremonyError("expected HTTP 402, got %s" % status)
 
@@ -211,13 +215,14 @@ def parse_402(status, headers, body):
             "amount": str(amount) if amount is not None else None,
             "payTo": a.get("payTo"),
             "asset": a.get("asset"),
-            "maxTimeoutSeconds": a.get("maxTimeoutSeconds", 60),
+            "maxTimeoutSeconds": a.get("maxTimeoutSeconds", 3600),
             "extra": a.get("extra", {}),
             "resource": a.get("resource"),
         })
     if not options:
         raise CeremonyError("402 had no payment options")
-    return version, options
+    resource_info = data.get("resource") if isinstance(data, dict) else None
+    return version, options, resource_info
 
 
 def describe(option):
@@ -228,7 +233,12 @@ def describe(option):
     except CeremonyError:
         chain_id = None
     out["chainId"] = chain_id
-    out["eligible"] = chain_id is not None and option.get("scheme") == "exact"
+    # extra.assetTransferMethod is absent on v1 and on eip3009 v2 offers; only an
+    # explicit "permit2" is ineligible, since this script signs EIP-3009 only.
+    transfer = (option.get("extra") or {}).get("assetTransferMethod")
+    out["assetTransferMethod"] = transfer or "eip3009"
+    out["eligible"] = (chain_id is not None and option.get("scheme") == "exact"
+                       and out["assetTransferMethod"] == "eip3009")
     meta = asset_meta(chain_id, option.get("asset"))
     if meta:
         out["symbol"] = meta["symbol"]
@@ -257,8 +267,15 @@ def select(options, want_asset=None, want_network=None):
             continue
         eligible.append(d)
     if not eligible:
+        exact_on_chain = [d for d in described
+                          if d.get("chainId") is not None and d.get("scheme") == "exact"]
+        if exact_on_chain and all(d["assetTransferMethod"] == "permit2" for d in exact_on_chain):
+            raise CeremonyError(
+                "the only payable options use the permit2 asset transfer method, which this "
+                "script does not support (it signs EIP-3009 transferWithAuthorization only). "
+                "Offered: %s" % json.dumps(described))
         raise CeremonyError(
-            "no eligible option (need scheme 'exact' on a network mm supports). "
+            "no eligible option (need scheme 'exact', EIP-3009, on a network mm supports). "
             "Offered: %s" % json.dumps(described))
     if len(eligible) > 1:
         raise CeremonyError(
@@ -292,14 +309,18 @@ def build_typed_data(option, chain_id, from_addr):
     authorization may live is the wallet's policy, not a constant here. A random
     nonce keeps each authorization single-use.
     """
+    now = int(time.time())
     nonce = "0x" + secrets.token_bytes(32).hex()
-    valid_before = str(int(time.time()) + int(option["maxTimeoutSeconds"]))
     authorization = {
         "from": from_addr,
         "to": option["payTo"],
         "value": option["amount"],
-        "validAfter": "0",
-        "validBefore": valid_before,
+        # Backdate validAfter: the spec allows "0", and the official Python
+        # client uses it, but the TypeScript reference client backdates 10
+        # minutes because some facilitators reject "0" and it absorbs clock
+        # skew. Follow the safer value.
+        "validAfter": str(now - 600),
+        "validBefore": str(now + int(option["maxTimeoutSeconds"])),
         "nonce": nonce,
     }
     typed_data = {
@@ -331,6 +352,37 @@ def build_typed_data(option, chain_id, from_addr):
     return typed_data, authorization
 
 
+def build_payment(version, option, resource_info, signature, authorization, url):
+    """Assemble the PaymentPayload for the chosen option.
+
+    The envelope differs by version (x402 spec section 5.2): v2 nests the chosen
+    requirements under `accepted` and forwards the `resource`, while v1 puts
+    `scheme`/`network` at the top level. A facilitator rejects a v2 payload that
+    is missing `accepted`.
+    """
+    if version == 2:
+        return {
+            "x402Version": 2,
+            "resource": resource_info or {"url": url},
+            "accepted": {
+                "scheme": option["scheme"],
+                "network": option["network"],
+                "amount": option["amount"],
+                "asset": option["asset"],
+                "payTo": option["payTo"],
+                "maxTimeoutSeconds": option["maxTimeoutSeconds"],
+                "extra": option.get("extra", {}),
+            },
+            "payload": {"signature": signature, "authorization": authorization},
+        }
+    return {
+        "x402Version": 1,
+        "scheme": option["scheme"],
+        "network": option["network"],
+        "payload": {"signature": signature, "authorization": authorization},
+    }
+
+
 def validate(option, chain_id):
     """Check the offer is structurally sound before signing.
 
@@ -351,23 +403,38 @@ def validate(option, chain_id):
         raise CeremonyError("402 option missing EIP-712 domain name/version in 'extra'")
 
 
-def settlement(headers, version):
-    """Decode the facilitator's settlement receipt, if the server sent one."""
+def settlement(headers, version, body):
+    """Decode the facilitator's settlement receipt.
+
+    The spec puts it in the X-PAYMENT-RESPONSE / PAYMENT-RESPONSE header, but
+    some servers return it only in the response body, so fall back to the body
+    when the header is absent.
+    """
     name = "X-PAYMENT-RESPONSE" if version == 1 else "PAYMENT-RESPONSE"
     raw = headers.get(name)
-    if not raw:
+    if raw:
+        try:
+            return json.loads(base64.b64decode(raw))
+        except (ValueError, UnicodeDecodeError):
+            pass
+    try:
+        data = json.loads(body.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
         return None
-    return json.loads(base64.b64decode(raw))
+    if isinstance(data, dict) and (data.get("transaction") or data.get("txHash")):
+        return data
+    return None
 
 
 def cmd_inspect(url, method, data, content_type):
     """Print the 402 payment requirement(s) without signing or spending."""
     body, headers = request_parts(data, content_type)
     status, rheaders, rbody = http(url, method, headers, body)
-    version, options = parse_402(status, rheaders, rbody)
+    version, options, resource_info = parse_402(status, rheaders, rbody)
     print(json.dumps({
         "status": "payment_required",
         "x402Version": version,
+        "resource": resource_info,
         "options": [describe(o) for o in options],
     }, indent=2))
 
@@ -380,7 +447,7 @@ def cmd_pay(url, method, data, content_type, confirm, want_asset, want_network):
     body, headers = request_parts(data, content_type)
     # Fetch fresh so the short 402 window is never stale.
     status, rheaders, rbody = http(url, method, headers, body)
-    version, options = parse_402(status, rheaders, rbody)
+    version, options, resource_info = parse_402(status, rheaders, rbody)
     option = select(options, want_asset, want_network)
     chain_id = option["chainId"]
     validate(option, chain_id)
@@ -393,9 +460,7 @@ def cmd_pay(url, method, data, content_type, confirm, want_asset, want_network):
         option["payTo"], url)
     signature = sign_typed_data(chain_id, typed_data, intent)
 
-    payment = {"x402Version": version, "scheme": option["scheme"],
-               "network": option["network"],
-               "payload": {"signature": signature, "authorization": authorization}}
+    payment = build_payment(version, option, resource_info, signature, authorization, url)
     b64 = base64.b64encode(json.dumps(payment).encode()).decode()
     header = "X-PAYMENT" if version == 1 else "PAYMENT-SIGNATURE"
 
@@ -405,7 +470,7 @@ def cmd_pay(url, method, data, content_type, confirm, want_asset, want_network):
         # One attempt only: do not retry a payment.
         raise CeremonyError("payment not accepted (HTTP %s): %s" % (status, rbody.decode("utf-8", "replace")))
 
-    settle = settlement(rheaders, version)
+    settle = settlement(rheaders, version, rbody)
     try:
         resource = json.loads(rbody.decode("utf-8"))
     except ValueError:

skills/metamask-agent-wallet/workflows/x402-pay.md

@@ -41,7 +41,10 @@ the resource body.
 
 - `error` with "no eligible option": the server offered no `exact`-scheme payment on a network mm
   supports. Show the offered options to the user.
-- `error` with "multiple eligible options": rerun `pay` with `--asset` or `--network`.
+- `error` with "multiple eligible options": the server offered the same scheme on several networks
+  or assets (e.g. Base and Polygon). Rerun `pay` with `--network` or `--asset` to choose one.
+- `error` mentioning "permit2": the only options use the Permit2 transfer method, which this skill
+  does not sign (it supports EIP-3009 only). Tell the user it is unsupported.
 - `error` with "payment not accepted": surface it. Do not rerun blindly; rerunning makes a new
   payment.
 - `error` with "not a standard x402 challenge": the endpoint returned a 402 in a different payment