v2.5.0

Author: primersystems-dev

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.5.0 — 2026-07-03
+
+### Changed
+- x402 v2 payment requirements are read correctly: amount from the v2 `amount` field and resource from the top-level `resource` object, in addition to the v1 fields. The version is taken from `x402Version`, or inferred when absent; payloads whose version conflicts with their fields are rejected.
+- The signed payment returned for a v2 request now uses the v2 `PAYMENT-SIGNATURE` shape — an `accepted` block (including `extra`) and a top-level `resource` — so resource servers can verify it. v1 requests keep the flat v1 shape.
+- Payment skill examples updated to x402 v2 (v1 still supported).
+
 ## 2.4.1 — 2026-06-29
 
 ### Fixed
@@ -21,3 +28,52 @@
 
 ### Added
 - `platformdirs` dependency for cross-platform data directory resolution.
+
+## 2.3.0 — 2026-05-20
+
+### Fixed
+- Amount display now uses 6 decimals consistently (sub-cent payments no longer show as 0.00).
+- Removed the redundant "$" prefix from amount displays.
+
+## 2.2.2 — 2026-05-20
+
+### Fixed
+- Windows taskbar now shows the MultiClaw icon instead of the Python icon (pip install).
+
+### Docs
+- SKILL.md updated to v2-first format (CAIP-2 networks, `PAYMENT-SIGNATURE` header).
+
+## 2.2.1 — 2026-05-19
+
+### Fixed
+- SKILL.md is now bundled in the pip package, so the `/agent` endpoint works for pip installs.
+
+## 2.2.0 — 2026-04-21
+
+### Added
+- Market tab — browse and search x402 services from agentic.market in the GUI, with category filtering and copy-to-clipboard agent snippets.
+- Service discovery in SKILL.md — agents can discover x402 services via the Agentic.Market API, with budget-aware filtering against their spend policy.
+- MultiClaw Skills package — `npx skills add primer-systems/multiclaw-skills` installs setup, payment, and discovery skills.
+
+### Docs
+- Updated the system interactions diagram.
+
+## 2.1.0 — 2026-04-02
+
+### Added
+- Published to PyPI — `pip install multiclaw` (or `multiclaw[gui]`).
+- Restructured as a proper Python package (`src/multiclaw/`).
+- Assets bundled with the pip install.
+
+## 2.0.0 — 2026-03-31
+
+### Added
+- CLI mode with an interactive REPL and scriptable single commands.
+- Headless daemon mode for server deployments.
+- In-GUI console window (File → Console).
+- Single-instance architecture: CLI connects to a running GUI via HTTP.
+
+## 1.0.0 — 2026-02-19
+
+### Added
+- Initial release.

README.md

@@ -251,34 +251,5 @@ pip install multiclaw         # CLI only
 
 ## Changelog
 
-### v2.3.0
-- **Fix:** Amount display now uses 6 decimals consistently (sub-cent payments no longer show as 0.00)
-- **Fix:** Removed redundant "$" prefix from amount displays (shows "0.002000 USDC" instead of "$0.00 USDC")
-
-### v2.2.2
-- **Fix:** Windows taskbar now shows MultiClaw icon instead of Python icon (pip install)
-- **Docs:** SKILL.md updated to v2-first format (CAIP-2 networks, `PAYMENT-SIGNATURE` header)
-
-### v2.2.1
-- **Fix:** SKILL.md now correctly bundled in pip package — `/agent` endpoint works for pip installs (was only working for PyInstaller builds)
-
-### v2.2.0
-- **Market tab** — browse and search x402 services from [agentic.market](https://agentic.market) directly in the GUI, with category filtering and copy-to-clipboard agent snippets
-- **Service discovery in SKILL.md** — agents can now discover x402 services via the Agentic.Market API, with budget-aware filtering against their MultiClaw spend policy
-- **MultiClaw Skills package** — `npx skills add primer-systems/multiclaw-skills` installs setup, payment, and discovery skills for any AI coding agent
-- Updated system interactions diagram in documentation
-
-### v2.1.0
-- Published to PyPI — install with `pip install multiclaw` or `pip install multiclaw[gui]`
-- Restructured as a proper Python package (`src/multiclaw/`)
-- Assets bundled with pip install (logo, icons)
-
-### v2.0.0
-- Added CLI mode with interactive REPL and scriptable single commands
-- Added headless daemon mode for server deployments
-- Added in-GUI console window (File → Console)
-- Single-instance architecture: CLI connects to running GUI via HTTP
-
-### v1.0.0
-- Initial release
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "multiclaw"
-version = "2.4.1"
+version = "2.5.0"
 description = "Desktop x402 payment manager for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"

src/multiclaw/services/eip3009.py

@@ -18,16 +18,23 @@
 
 @dataclass
 class PaymentRequirements:
-    """Parsed payment requirements from a 402 response."""
+    """Parsed payment requirements from a 402 response.
+
+    This is MultiClaw's single, version-neutral representation. Whichever x402
+    dialect came in on the wire (v1 or v2), the amount lives in
+    `max_amount_required` and the resource in `resource` - downstream code
+    (policy checks, signing, receipts) never touches the raw dialect fields.
+    """
     scheme: str
     network: str  # CAIP-2 format (e.g., 'eip155:8453')
     chain_id: int
-    max_amount_required: str
+    max_amount_required: str  # atomic units, as a string
     asset: str
     pay_to: str
     resource: Optional[str] = None
     token_name: Optional[str] = None
     token_version: Optional[str] = None
+    x402_version: int = 2  # the wire version this was parsed from (1 or 2)
 
 
 def parse_caip_network(network: str) -> int:
@@ -79,50 +86,138 @@ def to_caip_network(network: str) -> str:
         return network
 
 
-def parse_payment_requirements(x402_data: Dict[str, Any]) -> PaymentRequirements:
+def _resolve_x402_version(x402_data: Dict[str, Any], req: Dict[str, Any]) -> int:
     """
-    Parse x402 v2 payment requirements.
+    Decide which x402 dialect a payment is, decisively.
 
-    Args:
-        x402_data: The x402 response data with 'accepts' array
+    Rule (agreed):
+    - If `x402Version` is present, it is authoritative. Reject if the body's
+      amount field contradicts it - we do not guess a payment past a
+      mismatched version tag.
+    - If `x402Version` is absent (legacy v1 emitters often omit it), infer from
+      the one field that differs between dialects: the amount field name.
+      `maxAmountRequired` -> v1, `amount` -> v2. Both or neither -> reject.
 
-    Returns:
-        PaymentRequirements object
+    Returns the resolved version (1 or 2); raises ValueError otherwise.
+    """
+    has_v1_amount = req.get("maxAmountRequired") is not None
+    has_v2_amount = req.get("amount") is not None
+
+    declared = x402_data.get("x402Version")
+    if declared is not None:
+        if declared not in (1, 2):
+            raise ValueError(f"Unsupported x402Version: {declared!r} (expected 1 or 2)")
+        if declared == 1 and not has_v1_amount and has_v2_amount:
+            raise ValueError(
+                "x402Version is 1 but the amount is given as the v2 field 'amount' "
+                "(expected 'maxAmountRequired'); refusing to guess"
+            )
+        if declared == 2 and not has_v2_amount and has_v1_amount:
+            raise ValueError(
+                "x402Version is 2 but the amount is given as the v1 field 'maxAmountRequired' "
+                "(expected 'amount'); refusing to guess"
+            )
+        return declared
+
+    # No declared version - infer from the amount field name.
+    if has_v1_amount and has_v2_amount:
+        raise ValueError(
+            "Ambiguous payment: both 'maxAmountRequired' (v1) and 'amount' (v2) present "
+            "and no x402Version to disambiguate"
+        )
+    if has_v1_amount:
+        return 1
+    if has_v2_amount:
+        return 2
+    raise ValueError(
+        "Missing amount: expected 'maxAmountRequired' (v1) or 'amount' (v2) in accepts"
+    )
+
+
+def _extract_resource(x402_data: Dict[str, Any], req: Dict[str, Any], version: int) -> Optional[str]:
+    """
+    Pull the resource URL out, tolerant of both dialects.
+
+    - v2: resource is a top-level object {url, description, mimeType}.
+    - v1: resource is a per-accept string.
+    We prefer the location the resolved version specifies but fall back to the
+    other so a slightly-off emitter still yields a usable URL.
+    """
+    top = x402_data.get("resource")
+    top_url = top.get("url") if isinstance(top, dict) else top
+    per_accept = req.get("resource")
+    if version == 2:
+        return top_url or per_accept
+    return per_accept or top_url
+
+
+def parse_x402(x402_data: Dict[str, Any]) -> PaymentRequirements:
+    """
+    Parse an x402 payment requirement (v1 or v2) into the neutral
+    PaymentRequirements. This is the single intake parser - the only place that
+    knows the difference between the dialects. Everything downstream reads the
+    result, never the raw wire fields.
 
     Raises:
-        ValueError: If data is invalid or unsupported
+        ValueError: on any malformed or contradictory payload (never guesses).
     """
-    version = x402_data.get("x402Version")
-    if version != 2:
-        raise ValueError(f"Unsupported x402 version: {version}. Expected 2.")
+    if not isinstance(x402_data, dict):
+        raise ValueError("x402 data must be an object")
 
-    accepts = x402_data.get("accepts", [])
-    if not accepts:
-        raise ValueError("No payment options in accepts array")
+    accepts = x402_data.get("accepts")
+    if accepts is None:
+        raise ValueError("Missing 'accepts' array")
+    if not isinstance(accepts, list):
+        raise ValueError("'accepts' must be an array")
+    if len(accepts) == 0:
+        raise ValueError("Empty 'accepts' array")
 
-    # Use first accepted payment option
     req = accepts[0]
-    network = req.get("network", "")
+    if not isinstance(req, dict):
+        raise ValueError("Invalid accepts[0] format")
+
+    version = _resolve_x402_version(x402_data, req)
+
+    # Amount - read the field the resolved version dictates.
+    if version == 1:
+        amount = req.get("maxAmountRequired")
+        if amount is None:
+            raise ValueError("Missing 'maxAmountRequired' in accepts")
+    else:
+        amount = req.get("amount")
+        if amount is None:
+            raise ValueError("Missing 'amount' in accepts")
+
+    network = req.get("network")
+    if not network:
+        raise ValueError("Missing 'network' in accepts")
+
+    pay_to = req.get("payTo")
+    if not pay_to:
+        raise ValueError("Missing 'payTo' in accepts")
+
+    asset = req.get("asset")
+    if not asset:
+        raise ValueError("Missing 'asset' in accepts")
 
     # Normalize to CAIP-2
     caip_network = to_caip_network(network)
     chain_id = parse_caip_network(caip_network)
 
-    # Extract token metadata from 'extra' field if available
-    extra = req.get("extra", {})
-    token_name = extra.get("name")
-    token_version = extra.get("version")
+    # Extract token metadata from 'extra' field if available (same in both dialects)
+    extra = req.get("extra") or {}
 
     return PaymentRequirements(
         scheme=req.get("scheme", "exact"),
         network=caip_network,
         chain_id=chain_id,
-        max_amount_required=str(req.get("maxAmountRequired", "0")),
-        asset=req.get("asset", ""),
-        pay_to=req.get("payTo", ""),
-        resource=req.get("resource"),
-        token_name=token_name,
-        token_version=token_version
+        max_amount_required=str(amount),
+        asset=asset,
+        pay_to=pay_to,
+        resource=_extract_resource(x402_data, req, version),
+        token_name=extra.get("name"),
+        token_version=extra.get("version"),
+        x402_version=version,
     )
 
 
@@ -213,23 +308,66 @@ def sign_transfer_authorization(
     return sig_hex
 
 
+def _build_accepted(requirements: PaymentRequirements, accepted_raw: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """
+    Build the `accepted` block for a v2 PaymentPayload: the chosen payment
+    requirement echoed back to the server. Uses the normalized values from
+    `requirements` (correct v2 field names, CAIP-2 network) and carries through
+    `maxTimeoutSeconds` / `extra` from the merchant's original offer. `extra`
+    (the USDC EIP-712 domain name/version) matters — the server reads it to
+    reconstruct the verification domain.
+    """
+    raw = accepted_raw if isinstance(accepted_raw, dict) else {}
+    accepted = {
+        "scheme": requirements.scheme,
+        "network": requirements.network,  # CAIP-2
+        "amount": requirements.max_amount_required,
+        "asset": requirements.asset,
+        "payTo": requirements.pay_to,
+    }
+    if "maxTimeoutSeconds" in raw:
+        accepted["maxTimeoutSeconds"] = raw["maxTimeoutSeconds"]
+    extra = raw.get("extra")
+    if extra is not None:
+        accepted["extra"] = extra
+    elif requirements.token_name is not None or requirements.token_version is not None:
+        accepted["extra"] = {"name": requirements.token_name, "version": requirements.token_version}
+    return accepted
+
+
+def _normalize_resource(resource: Any) -> Optional[Dict[str, Any]]:
+    """Return the top-level v2 resource object {url, description, mimeType}."""
+    if isinstance(resource, dict):
+        return resource
+    if isinstance(resource, str):
+        return {"url": resource, "description": "", "mimeType": ""}
+    return None
+
+
 def create_payment(
     private_key: str,
     requirements: PaymentRequirements,
     token_name: Optional[str] = None,
-    token_version: Optional[str] = None
+    token_version: Optional[str] = None,
+    accepted: Optional[Dict[str, Any]] = None,
+    resource: Any = None,
 ) -> Dict[str, Any]:
     """
-    Create a signed x402 v2 payment payload.
+    Create a signed x402 v2 PaymentPayload.
 
     Args:
         private_key: Hex-encoded private key
         requirements: Parsed payment requirements
         token_name: Token name (defaults to requirements or 'USD Coin')
         token_version: Token version (defaults to requirements or '2')
+        accepted: The merchant's selected `accepts[]` entry (echoed back in the
+            v2 `accepted` block). Falls back to `requirements` if not given.
+        resource: The request's top-level resource (object or url string),
+            emitted as the v2 top-level `resource`.
 
     Returns:
-        x402 v2 payment payload ready for PAYMENT-SIGNATURE header
+        x402 v2 PaymentPayload ready for the PAYMENT-SIGNATURE header, shaped as
+        {x402Version, accepted, resource?, payload{signature, authorization}}.
     """
     # Ensure private key format
     if not private_key.startswith("0x"):
@@ -267,11 +405,13 @@ def create_payment(
         nonce=nonce_bytes
     )
 
-    # Build x402 v2 payload
-    return {
+    # Build x402 v2 PaymentPayload: the chosen requirement is echoed back in
+    # `accepted` (with `extra`), the resource sits at the top level, and only
+    # `authorization` is signed. scheme/network live inside `accepted`, not at
+    # the top level (that was the v1 shape).
+    payment = {
         "x402Version": X402_VERSION,
-        "scheme": "exact",
-        "network": requirements.network,  # CAIP-2 format
+        "accepted": _build_accepted(requirements, accepted),
         "payload": {
             "signature": signature,
             "authorization": {
@@ -284,3 +424,7 @@ def create_payment(
             }
         }
     }
+    resource_obj = _normalize_resource(resource if resource is not None else requirements.resource)
+    if resource_obj is not None:
+        payment["resource"] = resource_obj
+    return payment