feat(commerce): dual-emit accepts (amount + maxAmountRequired) + x402 sample in discovery probe

Mirror of node-commerce 6fcf928. Two related changes for compat with v1-only
x402 parsers (notably Coinbase awal at payments-mcp.coinbase.com, hardcoded to
read maxAmountRequired):

1. payment_required_header + build_402_body run accepts[] through
   alias_amount_fields. Each entry gets BOTH `amount` (v2 spec) AND
   `maxAmountRequired` (v1 spec). Strict v2 parsers ignore the alias; v1-only
   parsers find their field. Idempotent + symmetric.

2. build_discovery_probe_response accepts an optional `x402_sample`
   (X402SampleProbe). When set, the probe response also carries:
   - `payment-required` header (base64 PaymentRequired with sample accepts)
   - `accepts` array in the body

   Lets x402 discovery clients find merchant's x402 support from an empty-body
   POST. Awal x402 details now extracts requirements end-to-end.

489 tests pass, ruff + ty clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vvillait88

agentscore_commerce/challenge/body.py

@@ -4,6 +4,7 @@
 from typing import Any, Literal
 
 from agentscore_commerce.challenge.pricing import PricingBlock
+from agentscore_commerce.payment.wwwauthenticate import alias_amount_fields
 
 
 @dataclass
@@ -34,7 +35,7 @@ def build_402_body(input: Build402BodyInput) -> dict[str, Any]:
     body: dict[str, Any] = {"payment_required": True, "accepted_methods": input.accepted_methods}
     if input.x402:
         body["x402Version"] = input.x402.version
-        body["accepts"] = input.x402.accepts
+        body["accepts"] = alias_amount_fields(input.x402.accepts)
     if input.amount_usd is not None:
         body["amount_usd"] = input.amount_usd
     if input.currency:

agentscore_commerce/discovery/__init__.py

@@ -20,6 +20,7 @@
 from agentscore_commerce.discovery.probe import (
     DiscoveryProbeOptions,
     DiscoveryProbeResponse,
+    X402SampleProbe,
     build_discovery_probe_response,
     is_discovery_probe_request,
 )
@@ -40,6 +41,7 @@
     "LlmsTxtSection",
     "PaymentMethodConfig",
     "WellKnownMppInput",
+    "X402SampleProbe",
     "agentscore_denial_schemas",
     "agentscore_openapi_snippets",
     "agentscore_payment_required_schema",

agentscore_commerce/discovery/probe.py

@@ -1,16 +1,36 @@
 """Discovery probe — answers empty-body POSTs from MPP crawlers (mppscan, link-cli) with a sample 402."""
 
+import base64
 import json
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import UTC, datetime, timedelta
-from typing import Any, Protocol
+from typing import Any, Literal, Protocol
 
 from agentscore_commerce.payment.directive import (
     PaymentDirectiveInput,
     PaymentRequestInput,
     build_payment_request_blob,
     payment_directive,
 )
+from agentscore_commerce.payment.wwwauthenticate import (
+    PaymentRequiredHeaderInput,
+    payment_required_header,
+)
+
+
+@dataclass
+class X402SampleProbe:
+    """Sample x402 accepts to embed in the discovery probe's PAYMENT-REQUIRED header.
+
+    Crawlers (e.g. ``awal x402 details``) can find this endpoint's x402 support
+    without a real business-shaped request. Each entry is run through
+    ``alias_amount_fields`` so v1-only parsers find ``maxAmountRequired`` and
+    v2-strict parsers find ``amount``.
+    """
+
+    accepts: list[Any]
+    version: Literal[1, 2] = 2
+    resource_url: str | None = None
 
 
 @dataclass
@@ -23,6 +43,7 @@ class DiscoveryProbeOptions:
     ttl_seconds: int = 300
     docs_url: str | None = None
     message: str | None = None
+    x402_sample: X402SampleProbe | None = field(default=None)
 
 
 @dataclass
@@ -54,9 +75,29 @@ def build_discovery_probe_response(opts: DiscoveryProbeOptions) -> DiscoveryProb
     }
     if opts.docs_url:
         body_obj["docs"] = opts.docs_url
+    headers: dict[str, str] = {"content-type": "application/json", "www-authenticate": directive}
+
+    if opts.x402_sample is not None:
+        x402v = opts.x402_sample.version
+        # payment_required_header internally runs alias_amount_fields, so v1+v2
+        # parsers both find their expected field name on the header decode.
+        header_kwargs: dict[str, Any] = {"x402_version": x402v, "accepts": opts.x402_sample.accepts}
+        if opts.x402_sample.resource_url:
+            header_kwargs["resource"] = {
+                "url": opts.x402_sample.resource_url,
+                "mimeType": "application/json",
+            }
+        encoded = payment_required_header(PaymentRequiredHeaderInput(**header_kwargs))
+        headers["payment-required"] = encoded
+        # Mirror the aliased accepts in the body so clients that fall back from
+        # header → body (e.g. awal's discover) can still extract requirements.
+        decoded = json.loads(base64.b64decode(encoded).decode())
+        body_obj["x402Version"] = x402v
+        body_obj["accepts"] = decoded["accepts"]
+
     return DiscoveryProbeResponse(
         status=402,
-        headers={"content-type": "application/json", "www-authenticate": directive},
+        headers=headers,
         body=json.dumps(body_obj, separators=(",", ":")),
     )
 

agentscore_commerce/payment/__init__.py

@@ -42,6 +42,7 @@
 from agentscore_commerce.payment.usdc import USDC
 from agentscore_commerce.payment.wwwauthenticate import (
     PaymentRequiredHeaderInput,
+    alias_amount_fields,
     payment_required_header,
     www_authenticate_header,
 )
@@ -107,6 +108,7 @@
     "X402AcceptsBlock",
     "X402FacilitatorChoice",
     "X402SymbolicRail",
+    "alias_amount_fields",
     "build_idempotency_key",
     "build_payment_directive",
     "build_payment_headers",

agentscore_commerce/payment/wwwauthenticate.py

@@ -14,6 +14,31 @@ def www_authenticate_header(directives: list[str]) -> str:
     return ", ".join(directives)
 
 
+def alias_amount_fields(accepts: list[Any]) -> list[Any]:
+    """Add the v1↔v2 amount-field alias to each accepts entry. Idempotent.
+
+    Used by both ``payment_required_header`` (header emit) and ``build_402_body``
+    (body emit) so every x402 entry on the wire carries BOTH ``amount`` (v2 spec)
+    AND ``maxAmountRequired`` (v1 spec). Strict v1-only parsers (e.g. Coinbase
+    awal at ``payments-mcp.coinbase.com``, hardcoded to read ``maxAmountRequired``)
+    work alongside strict v2 parsers, which ignore the alias.
+    """
+    out: list[Any] = []
+    for entry in accepts:
+        if not isinstance(entry, dict):
+            out.append(entry)
+            continue
+        has_amount = "amount" in entry
+        has_max_amount = "maxAmountRequired" in entry
+        if has_amount and not has_max_amount:
+            out.append({**entry, "maxAmountRequired": entry["amount"]})
+        elif has_max_amount and not has_amount:
+            out.append({**entry, "amount": entry["maxAmountRequired"]})
+        else:
+            out.append(entry)
+    return out
+
+
 @dataclass
 class PaymentRequiredHeaderInput:
     x402_version: Literal[1, 2]
@@ -22,8 +47,12 @@ class PaymentRequiredHeaderInput:
 
 
 def payment_required_header(input: PaymentRequiredHeaderInput) -> str:
-    """Encode the standard x402 PAYMENT-REQUIRED header (base64-encoded JSON)."""
-    body: dict[str, Any] = {"x402Version": input.x402_version, "accepts": input.accepts}
+    """Encode the standard x402 PAYMENT-REQUIRED header (base64-encoded JSON).
+
+    Each accepts entry is post-processed via :func:`alias_amount_fields` so v1-only
+    clients (e.g. awal) and v2-strict clients can both read it.
+    """
+    body: dict[str, Any] = {"x402Version": input.x402_version, "accepts": alias_amount_fields(input.accepts)}
     if input.resource is not None:
         body["resource"] = input.resource
     raw = json.dumps(body, separators=(",", ":")).encode()

tests/test_challenge.py

@@ -148,3 +148,19 @@ def test_build_402_body_assembles_full_response():
     assert body["pricing"]["total"] == "108"
     assert body["identity_mode"] == "wallet"
     assert body["agent_instructions"]["how_to_pay"] == {}
+
+
+def test_build_402_body_emits_v1_alias_on_accepts_entries():
+    """Each accepts entry carries both `amount` (v2) and `maxAmountRequired` (v1)."""
+    body = build_402_body(
+        Build402BodyInput(
+            accepted_methods=[],
+            x402=X402PaymentRequired(
+                accepts=[{"scheme": "exact", "network": "eip155:84532", "amount": "110000"}],
+                version=2,
+            ),
+        )
+    )
+    entry = body["accepts"][0]
+    assert entry["amount"] == "110000"
+    assert entry["maxAmountRequired"] == "110000"

tests/test_payment_misc.py

@@ -68,6 +68,33 @@ def test_payment_required_header_base64_encodes_json():
     assert decoded["resource"]["url"] == "https://x"
 
 
+def test_payment_required_header_emits_v1_alias_for_v2_clients():
+    """v1-only parsers (Coinbase awal) read maxAmountRequired; v2-strict parsers read amount.
+
+    Header carries both so either side works.
+    """
+    from agentscore_commerce.payment import alias_amount_fields
+
+    h = payment_required_header(
+        PaymentRequiredHeaderInput(
+            x402_version=2,
+            accepts=[{"scheme": "exact", "network": "eip155:84532", "amount": "110000"}],
+        )
+    )
+    decoded = json.loads(base64.b64decode(h))
+    assert decoded["accepts"][0]["amount"] == "110000"
+    assert decoded["accepts"][0]["maxAmountRequired"] == "110000"
+
+    # Reverse: vendor emitting v1 shape gets amount alias added.
+    aliased = alias_amount_fields([{"scheme": "exact", "maxAmountRequired": "110000"}])
+    assert aliased[0]["amount"] == "110000"
+    assert aliased[0]["maxAmountRequired"] == "110000"
+
+    # Idempotent: both already set → unchanged.
+    both = alias_amount_fields([{"amount": "1", "maxAmountRequired": "1"}])
+    assert both[0] == {"amount": "1", "maxAmountRequired": "1"}
+
+
 def test_settlement_override_header_returns_name_value_pair():
     name, value = settlement_override_header(SettlementOverrides(amount="1500"))
     assert name == SETTLEMENT_OVERRIDES_HEADER