agentscore-commerce 1.0.0__py3-none-any.whl

agentscore_commerce/__init__.py

@@ -0,0 +1,12 @@
+"""Agent commerce SDK — identity middleware + payment helpers + 402 builders + discovery + Stripe multichain.
+
+Submodules:
+    agentscore_commerce.identity   - per-framework gate adapters
+    agentscore_commerce.payment    - networks/usdc/rails registries, directives, x402/mpp helpers
+    agentscore_commerce.discovery  - probe + .well-known/mpp.json + llms.txt + OpenAPI snippets
+    agentscore_commerce.challenge  - 402-body builders
+    agentscore_commerce.stripe_multichain - multichain PaymentIntent helpers
+    agentscore_commerce.api        - AgentScore SDK re-export
+"""
+
+__version__ = "1.0.0"

agentscore_commerce/api/__init__.py

@@ -0,0 +1,23 @@
+"""AgentScore SDK re-export — single import path for the underlying agentscore-py.
+
+Vendors install only ``agentscore-commerce`` and reach everything from the underlying
+``agentscore-py`` here. Don't add ``agentscore-py`` as a separate dep; the two can
+drift versions and cause subtle type mismatches.
+
+Use this for: programmatic API calls (sessions, credentials, reputation) and the
+test-mode address fixtures for integration tests.
+"""
+
+from agentscore import (
+    AGENTSCORE_TEST_ADDRESSES,
+    AgentScore,
+    AgentScoreError,
+    is_agentscore_test_address,
+)
+
+__all__ = [
+    "AGENTSCORE_TEST_ADDRESSES",
+    "AgentScore",
+    "AgentScoreError",
+    "is_agentscore_test_address",
+]

agentscore_commerce/challenge/__init__.py

@@ -0,0 +1,86 @@
+"""402-body builders + pricing/receipt/agent-memory helpers."""
+
+from agentscore_commerce.challenge.accepted_methods import (
+    BuildAcceptedMethodsInput,
+    StripeConfig,
+    TempoConfig,
+    X402BaseConfig,
+    X402SolanaConfig,
+    build_accepted_methods,
+)
+from agentscore_commerce.challenge.agent_instructions import (
+    BuildAgentInstructionsInput,
+    build_agent_instructions,
+)
+from agentscore_commerce.challenge.agent_memory import (
+    AgentMemoryHint,
+    build_agent_memory_hint,
+    first_encounter_agent_memory,
+)
+from agentscore_commerce.challenge.body import Build402BodyInput, X402PaymentRequired, build_402_body
+from agentscore_commerce.challenge.how_to_pay import (
+    BuildHowToPayInput,
+    HowToPayRails,
+    StripeRailConfig,
+    TempoRailConfig,
+    X402BaseRailConfig,
+    X402SolanaRailConfig,
+    build_how_to_pay,
+)
+from agentscore_commerce.challenge.identity import (
+    IdentityMetadataInput,
+    IdentityMode,
+    SignerMatchResult,
+    build_identity_metadata,
+)
+from agentscore_commerce.challenge.order_receipt import (
+    OrderNextSteps,
+    OrderProductInfo,
+    OrderReceipt,
+    ShippingAddress,
+)
+from agentscore_commerce.challenge.pricing import PricingBlock, build_pricing_block
+from agentscore_commerce.challenge.respond_402 import Respond402Input, Respond402Result, respond_402
+from agentscore_commerce.challenge.validation_error import (
+    BuildValidationErrorInput,
+    build_validation_error,
+)
+
+__all__ = [
+    "AgentMemoryHint",
+    "Build402BodyInput",
+    "BuildAcceptedMethodsInput",
+    "BuildAgentInstructionsInput",
+    "BuildHowToPayInput",
+    "BuildValidationErrorInput",
+    "HowToPayRails",
+    "IdentityMetadataInput",
+    "IdentityMode",
+    "OrderNextSteps",
+    "OrderProductInfo",
+    "OrderReceipt",
+    "PricingBlock",
+    "Respond402Input",
+    "Respond402Result",
+    "ShippingAddress",
+    "SignerMatchResult",
+    "StripeConfig",
+    "StripeRailConfig",
+    "TempoConfig",
+    "TempoRailConfig",
+    "X402BaseConfig",
+    "X402BaseRailConfig",
+    "X402PaymentRequired",
+    "X402SolanaConfig",
+    "X402SolanaRailConfig",
+    "build_402_body",
+    "build_accepted_methods",
+    "build_agent_instructions",
+    "build_agent_memory_hint",
+    "build_how_to_pay",
+    "build_identity_metadata",
+    "build_pricing_block",
+    "build_validation_error",
+    "first_encounter_agent_memory",
+    "respond_402",
+]

agentscore_commerce/challenge/accepted_methods.py

@@ -0,0 +1,90 @@
+"""accepted_methods[] builder for enriched 402 bodies."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class TempoConfig:
+    recipient: str
+    network: str = "tempo-mainnet"
+    chain_id: int = 4217
+    token: str = "0x20C000000000000000000000b9537d11c60E8b50"
+    symbol: str = "USDC.e"
+    decimals: int = 6
+
+
+@dataclass
+class X402BaseConfig:
+    recipient: str
+    network: str = "eip155:8453"
+    chain_id: int = 8453
+    token: str = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+    symbol: str = "USDC"
+    decimals: int = 6
+
+
+@dataclass
+class X402SolanaConfig:
+    recipient: str
+    network: str = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
+    token: str = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+    symbol: str = "USDC"
+    decimals: int = 6
+
+
+@dataclass
+class StripeConfig:
+    profile_id: str | None = None
+    rails: list[str] = field(default_factory=lambda: ["card", "link", "shared_payment_token"])
+
+
+@dataclass
+class BuildAcceptedMethodsInput:
+    tempo: TempoConfig | None = None
+    x402_base: X402BaseConfig | None = None
+    x402_solana: X402SolanaConfig | None = None
+    stripe: StripeConfig | None = None
+
+
+def build_accepted_methods(input: BuildAcceptedMethodsInput) -> list[dict[str, Any]]:
+    """Build the accepted_methods[] array. Each rail entry conditionally included if vendor passed it."""
+    out: list[dict[str, Any]] = []
+    if input.tempo:
+        out.append(
+            {
+                "method": "tempo/charge",
+                "network": input.tempo.network,
+                "chain_id": input.tempo.chain_id,
+                "token": input.tempo.token,
+                "symbol": input.tempo.symbol,
+                "decimals": input.tempo.decimals,
+                "pay_to": input.tempo.recipient,
+            }
+        )
+    if input.x402_base:
+        out.append(
+            {
+                "method": "x402/exact",
+                "network": input.x402_base.network,
+                "chain_id": input.x402_base.chain_id,
+                "token": input.x402_base.token,
+                "symbol": input.x402_base.symbol,
+                "decimals": input.x402_base.decimals,
+                "pay_to": input.x402_base.recipient,
+            }
+        )
+    if input.x402_solana:
+        out.append(
+            {
+                "method": "x402/exact",
+                "network": input.x402_solana.network,
+                "token": input.x402_solana.token,
+                "symbol": input.x402_solana.symbol,
+                "decimals": input.x402_solana.decimals,
+                "pay_to": input.x402_solana.recipient,
+            }
+        )
+    if input.stripe:
+        out.append({"method": "stripe/charge", "rails": input.stripe.rails, "profile_id": input.stripe.profile_id})
+    return out

agentscore_commerce/challenge/agent_instructions.py

@@ -0,0 +1,117 @@
+"""agent_instructions block builder for the 402 body."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+_TEMPO_WARNING = (
+    "Do NOT use `tempo wallet transfer` to pay to the address above. That moves USDC on-chain but does not "
+    "notify this server, leaving your order in pending_identity state. Use `tempo request` instead — it performs "
+    "the full MPP handshake (signs, submits Authorization: Payment, waits for server confirmation)."
+)
+_X402_WARNING = (
+    "Do NOT send USDC manually to the x402 deposit addresses (e.g. via a bare wallet `transfer`). Use "
+    "`agentscore-pay pay` so the X-Payment credential is signed and submitted; otherwise the order stays in "
+    "pending_identity even though the deposit lands."
+)
+_TEMPO_TOOL = "`tempo request` for Tempo USDC (installs via `tempo add request`)"
+_AGENTSCORE_PAY_TOOL = (
+    "`agentscore-pay` (npm: `@agent-score/pay`) — single CLI for x402 on Base + Solana, "
+    "also speaks tempo MPP via `--chain tempo`"
+)
+
+DEFAULT_WALLET_COMPATIBILITY = (
+    "No specific wallet stack required. The 402 challenge is rail-neutral: any client that can produce a valid "
+    "MPP credential (Authorization: Payment) or x402 X-Payment header is accepted. The CLI commands above are "
+    "the easiest path; sign-it-yourself is fine too."
+)
+
+
+def _default_recommended_tools(how_to_pay: dict[str, Any]) -> list[str]:
+    tools: list[str] = []
+    has_tempo = "tempo" in how_to_pay
+    has_x402 = "x402_base" in how_to_pay or "x402_solana" in how_to_pay
+    if has_tempo:
+        tools.append(_TEMPO_TOOL)
+    if has_tempo or has_x402:
+        tools.append(_AGENTSCORE_PAY_TOOL)
+    return tools
+
+
+def _default_warnings(how_to_pay: dict[str, Any]) -> list[str]:
+    w: list[str] = []
+    if "tempo" in how_to_pay:
+        w.append(_TEMPO_WARNING)
+    if "x402_base" in how_to_pay or "x402_solana" in how_to_pay:
+        w.append(_X402_WARNING)
+    return w
+
+
+def _default_compatible_clients(how_to_pay: dict[str, Any]) -> dict[str, list[str]] | None:
+    """Default ``compatible_clients`` derived from the rails declared in ``how_to_pay``.
+
+    Lists clients the AgentScore team has smoke-verified end-to-end against an
+    ``agentscore-commerce`` merchant; entries appear only for rails the vendor actually
+    offers. Vendors override this in ``BuildAgentInstructionsInput(compatible_clients=...)``
+    to add their own tested clients or remove entries that don't fit their endpoint.
+
+    Verified state as of the SDK release. The same data is also published as a docs page
+    for humans (rationale, per-rail commands, why some clients don't fully work, last
+    verified date) — this default keeps the merchant-side surface in sync.
+    """
+    out: dict[str, list[str]] = {}
+    if "tempo" in how_to_pay:
+        out["tempo_mpp"] = ["agentscore-pay", "tempo request", "x402-proxy"]
+    if "x402_base" in how_to_pay:
+        out["x402_base"] = ["agentscore-pay", "x402-proxy", "purl (omit --network flag)"]
+    if "x402_solana" in how_to_pay:
+        out["x402_solana"] = ["agentscore-pay"]
+    if "stripe" in how_to_pay:
+        out["stripe"] = ["link-cli"]
+    return out or None
+
+
+@dataclass
+class BuildAgentInstructionsInput:
+    how_to_pay: dict[str, Any]
+    recommended_tools: list[str] | None = None
+    wallet_compatibility: str | None = None
+    timeout_seconds: int = 300
+    warnings: list[str] | None = None
+    recommended: str | None = None
+    # Per-rail list of client names the merchant has verified work end-to-end.
+    # Vendors set this from their own smoke matrix — defaults to None, in which case
+    # the field is not emitted (avoids vouching for clients the merchant has not tested).
+    # Keys are rail identifiers (e.g. "x402_base", "tempo_mpp"); values are display labels.
+    compatible_clients: dict[str, list[str]] | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+def build_agent_instructions(input: BuildAgentInstructionsInput) -> dict[str, Any]:
+    """Build the agent_instructions block — combines how_to_pay with tools, warnings, compat note, timeout.
+
+    Defaults adapt to the rails declared in ``how_to_pay``: only tempo-relevant warnings/tools
+    appear if ``how_to_pay["tempo"]`` is set, only x402-relevant ones if ``x402_base``/
+    ``x402_solana`` are set. Vendors override ``warnings``/``recommended_tools`` for full control.
+    """
+    recommended_tools = (
+        input.recommended_tools if input.recommended_tools is not None else _default_recommended_tools(input.how_to_pay)
+    )
+    warnings = input.warnings if input.warnings is not None else _default_warnings(input.how_to_pay)
+    compatible_clients = (
+        input.compatible_clients
+        if input.compatible_clients is not None
+        else _default_compatible_clients(input.how_to_pay)
+    )
+    out: dict[str, Any] = {
+        "how_to_pay": input.how_to_pay,
+        "recommended_tools": recommended_tools,
+        "wallet_compatibility": input.wallet_compatibility or DEFAULT_WALLET_COMPATIBILITY,
+        "timeout_seconds": input.timeout_seconds,
+        "warnings": warnings,
+    }
+    if input.recommended:
+        out["recommended"] = input.recommended
+    if compatible_clients:
+        out["compatible_clients"] = compatible_clients
+    out.update(input.extra)
+    return out

agentscore_commerce/challenge/agent_memory.py

@@ -0,0 +1,50 @@
+"""Helpers for emitting the cross-merchant ``agent_memory`` hint on merchant 402 responses.
+
+The gate (:mod:`agentscore_commerce.identity`) emits ``agent_memory`` on identity-related
+responses (sessions, credentials, missing_identity bootstraps). Merchants can ALSO include
+the hint in their own 402 challenge bodies on first-encounter requests so agents persist
+the cross-merchant pattern even when entering the ecosystem through a merchant-side
+endpoint rather than a direct AgentScore API call.
+
+Usage pattern:
+    - Merchant tracks per-operator (or per-IP / per-fingerprint) "have I seen this agent
+      before?" in their own DB
+    - On first encounter, include the hint so the agent saves the pattern
+    - On subsequent encounters, skip — the agent already has it (or never will)
+
+The hint contents come from :func:`build_agent_memory_hint` (re-exported here for
+convenience). Keep it stateless: AgentScore's pattern doesn't depend on the merchant's
+identity, so every merchant emits the same shape.
+"""
+
+from __future__ import annotations
+
+from agentscore_commerce.identity.types import AgentMemoryHint, build_agent_memory_hint
+
+
+def first_encounter_agent_memory(
+    first_encounter: bool,
+) -> AgentMemoryHint | None:
+    """Return the ``agent_memory`` hint when this is a first encounter, otherwise ``None``.
+
+    Use directly with the ``agent_memory`` field of :func:`build_402_body`::
+
+        body = build_402_body(Build402BodyInput(
+            accepted_methods=accepted,
+            agent_instructions=instructions,
+            pricing=pricing,
+            agent_memory=first_encounter_agent_memory(
+                first_encounter=not has_seen_operator(operator_token),
+            ),
+        ))
+
+    Returning ``None`` means ``build_402_body`` cleanly skips the field instead of
+    emitting ``agent_memory: null`` (which would imply "I tried but failed" rather than
+    "didn't apply").
+    """
+    if not first_encounter:
+        return None
+    return build_agent_memory_hint()
+
+
+__all__ = ["AgentMemoryHint", "build_agent_memory_hint", "first_encounter_agent_memory"]

agentscore_commerce/challenge/body.py

@@ -0,0 +1,67 @@
+"""build_402_body — full enriched 402 response body builder."""
+
+from dataclasses import asdict, dataclass, field, is_dataclass
+from typing import Any, Literal
+
+from agentscore_commerce.challenge.pricing import PricingBlock
+from agentscore_commerce.payment.wwwauthenticate import alias_amount_fields
+
+
+@dataclass
+class X402PaymentRequired:
+    accepts: list[Any]
+    version: Literal[1, 2] = 2
+
+
+@dataclass
+class Build402BodyInput:
+    accepted_methods: list[dict[str, Any]]
+    agent_instructions: dict[str, Any] | None = None
+    identity_metadata: dict[str, Any] | None = None
+    agent_memory: Any = None
+    pricing: PricingBlock | None = None
+    amount_usd: str | None = None
+    currency: str | None = None
+    order_id: str | None = None
+    product: dict[str, str] | None = None
+    retry_body: Any = None
+    recommended: str | None = None
+    x402: X402PaymentRequired | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+def build_402_body(input: Build402BodyInput) -> dict[str, Any]:
+    """Assemble the full enriched 402 response body. Each section conditionally included if vendor passed it."""
+    body: dict[str, Any] = {"payment_required": True, "accepted_methods": input.accepted_methods}
+    if input.x402:
+        body["x402Version"] = input.x402.version
+        body["accepts"] = alias_amount_fields(input.x402.accepts)
+    if input.amount_usd is not None:
+        body["amount_usd"] = input.amount_usd
+    if input.currency:
+        body["currency"] = input.currency
+    if input.pricing:
+        body["pricing"] = input.pricing.to_dict()
+    if input.order_id is not None:
+        body["order_id"] = input.order_id
+    if input.product:
+        body["product"] = input.product
+    if input.recommended:
+        body["recommended"] = input.recommended
+    if input.retry_body is not None:
+        body["retry_body"] = input.retry_body
+    if input.identity_metadata:
+        body.update(input.identity_metadata)
+    if input.agent_instructions:
+        body["agent_instructions"] = input.agent_instructions
+    if input.agent_memory is not None:
+        # AgentMemoryHint is a dataclass; merchants pass it directly via
+        # first_encounter_agent_memory(...). Convert here so JSONResponse /
+        # json.dumps can serialise without per-merchant boilerplate.
+        body["agent_memory"] = (
+            asdict(input.agent_memory)
+            if is_dataclass(input.agent_memory) and not isinstance(input.agent_memory, type)
+            else input.agent_memory
+        )
+    body.update(input.extra)
+    return body

agentscore_commerce/challenge/how_to_pay.py

@@ -0,0 +1,199 @@
+"""how_to_pay block builder — per-rail setup/command/what_it_does for 402 agent_instructions."""
+
+import math
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+@dataclass
+class TempoRailConfig:
+    recipient: str
+    network_name: str = "tempo-mainnet"
+    chain_id: int = 4217
+    recommend: Literal["tempo", "agentscore-pay", "both"] = "both"
+
+
+@dataclass
+class X402BaseRailConfig:
+    recipient: str
+    network: str = "eip155:8453"
+
+
+@dataclass
+class X402SolanaRailConfig:
+    recipient: str
+    network: str = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
+
+
+@dataclass
+class StripeRailConfig:
+    profile_id: str | None = None
+    product_name: str | None = None
+
+
+@dataclass
+class HowToPayRails:
+    tempo: TempoRailConfig | None = None
+    x402_base: X402BaseRailConfig | None = None
+    x402_solana: X402SolanaRailConfig | None = None
+    stripe: StripeRailConfig | None = None
+
+
+@dataclass
+class BuildHowToPayInput:
+    url: str
+    retry_body_json: str
+    total_usd: float | str
+    rails: HowToPayRails
+    op_token_placeholder: str = "<your_opc_token>"
+    max_spend: float | str | None = None
+
+
+TEMPO_SETUP = [
+    "curl -fsSL https://tempo.xyz/install | bash",
+    "tempo wallet login",
+    "tempo wallet whoami",
+    "tempo wallet fund   # if balance is zero",
+]
+PAY_SETUP_BASE = [
+    "npm install -g @agent-score/pay   # or: brew install agentscore/tap/agentscore-pay",
+    "agentscore-pay wallet create --chain base",
+    "agentscore-pay balance --chain base   # fund the printed address with USDC on Base",
+]
+PAY_SETUP_SOLANA = [
+    "npm install -g @agent-score/pay   # or: brew install agentscore/tap/agentscore-pay",
+    "agentscore-pay wallet create --chain solana",
+    "agentscore-pay balance --chain solana   # fund the printed address with USDC on Solana",
+]
+
+
+def build_how_to_pay(input: BuildHowToPayInput) -> dict[str, Any]:
+    """Build the agent_instructions.how_to_pay block.
+
+    Generates per-rail setup/command/what_it_does so agents see concrete commands per rail in the 402 body.
+    """
+    total_num = float(input.total_usd) if isinstance(input.total_usd, str) else input.total_usd
+    max_spend = str(input.max_spend) if input.max_spend is not None else f"{math.ceil(total_num) + 1:.2f}"
+    op_token = input.op_token_placeholder
+    block: dict[str, Any] = {}
+
+    if input.rails.tempo:
+        t = input.rails.tempo
+        tempo_command = (
+            f"tempo request -X POST -H 'X-Operator-Token: {op_token}' -H 'Content-Type: application/json' "
+            f"--json '{input.retry_body_json}' --max-spend {max_spend} {input.url}"
+        )
+        pay_command = (
+            f"agentscore-pay pay POST {input.url} --chain tempo -H 'X-Operator-Token: {op_token}' "
+            f"-H 'Content-Type: application/json' -d '{input.retry_body_json}' --max-spend {max_spend}"
+        )
+        entry: dict[str, Any] = {
+            "setup": TEMPO_SETUP,
+            "prerequisite": (
+                f"Run `tempo wallet whoami` and confirm USDC.e balance on {t.network_name} (chain {t.chain_id}) "
+                f"is at least ${max_spend}. If the tempo CLI is not installed, run the setup commands above first."
+            ),
+            "command": pay_command if t.recommend == "agentscore-pay" else tempo_command,
+            "what_it_does": (
+                f"Hits this endpoint, receives this same 402, signs the MPP challenge on {t.network_name}, and "
+                "submits the credential back via Authorization: Payment. Either client (tempo request or "
+                "agentscore-pay pay --chain tempo) works — both run the full MPP handshake."
+            ),
+        }
+        if t.recommend == "both":
+            entry["alternative_command"] = pay_command
+        elif t.recommend == "agentscore-pay":
+            entry["alternative_command"] = tempo_command
+        block["tempo"] = entry
+
+    if input.rails.x402_base:
+        b = input.rails.x402_base
+        block["x402_base"] = {
+            "setup": PAY_SETUP_BASE,
+            "prerequisite": (
+                f"Run `agentscore-pay balance --chain base` and confirm USDC balance on Base ({b.network}) is at "
+                f"least ${max_spend}. If the CLI is not installed, run the setup commands above first."
+            ),
+            "command": (
+                f"agentscore-pay pay POST {input.url} --chain base -H 'X-Operator-Token: {op_token}' "
+                f"-H 'Content-Type: application/json' -d '{input.retry_body_json}' --max-spend {max_spend}"
+            ),
+            "what_it_does": (
+                "Hits this endpoint, receives this same 402, signs an EIP-3009 USDC TransferWithAuthorization "
+                "on Base, submits via X-Payment header. Server verifies + settles via the Coinbase facilitator + "
+                "returns 200 with the completed order."
+            ),
+        }
+
+    if input.rails.x402_solana:
+        s = input.rails.x402_solana
+        block["x402_solana"] = {
+            "setup": PAY_SETUP_SOLANA,
+            "prerequisite": (
+                f"Run `agentscore-pay balance --chain solana` and confirm USDC balance on Solana ({s.network}) "
+                f"is at least ${max_spend}. If the CLI is not installed, run the setup commands above first."
+            ),
+            "command": (
+                f"agentscore-pay pay POST {input.url} --chain solana -H 'X-Operator-Token: {op_token}' "
+                f"-H 'Content-Type: application/json' -d '{input.retry_body_json}' --max-spend {max_spend}"
+            ),
+            "what_it_does": (
+                "Hits this endpoint, receives this same 402, signs an SPL Token TransferChecked transaction on "
+                "Solana, submits via X-Payment header. Server verifies + settles via the Coinbase facilitator + "
+                "returns 200 with the completed order."
+            ),
+        }
+
+    if input.rails.stripe:
+        cfg = input.rails.stripe
+        amount_cents = round(total_num * 100)
+        link_cli_blocked = amount_cents > 50000
+        product_name = cfg.product_name or "this purchase"
+        spt_context = (
+            f'Purchasing "{product_name}" via the agent commerce API. The user authorized this purchase '
+            f"through their AI agent for ${total_num}; charge to be settled via shared payment token over the "
+            "Machine Payments Protocol."
+        )
+        stripe_block: dict[str, Any] = {
+            "prerequisite": (
+                "Either your own Stripe account with Shared Payment Token acceptance, OR a Stripe Link wallet "
+                "(any user with link.com)."
+            ),
+            "instructions": (
+                "Mint a SharedPaymentToken scoped to the profile_id advertised in accepted_methods, then submit "
+                "via Authorization: Payment MPP header with method=stripe/charge."
+            ),
+        }
+        if cfg.profile_id and not link_cli_blocked:
+            stripe_block["setup_link_cli"] = [
+                "npm install -g @stripe/link-cli   # or use npx -y @stripe/link-cli for one-shot",
+                "link-cli auth login   # one-time, opens your Link wallet",
+                "link-cli payment-methods list --output-json   # copy a csmrpd_... id",
+            ]
+            stripe_block["command_link_cli"] = [
+                (
+                    "SPEND_ID=$(link-cli spend-request create "
+                    "--payment-method-id <csmrpd_id_from_payment_methods_list> "
+                    f"--credential-type shared_payment_token --network-id {cfg.profile_id} "
+                    f"--amount {amount_cents} "
+                    f'--context "{spt_context}" --request-approval --output-json | jq -r .id)'
+                ),
+                (
+                    f"link-cli mpp pay {input.url} --spend-request-id $SPEND_ID --method POST "
+                    f"--data '{input.retry_body_json}' --header 'X-Operator-Token: {op_token}' --output-json"
+                ),
+            ]
+            stripe_block["what_it_does_link_cli"] = (
+                "For users who have a Stripe Link wallet: step 1 mints a one-time-use SharedPaymentToken scoped to "
+                "this purchase and pushes a notification to the user for approval (blocks until approved); step 2 "
+                "submits the SPT via the MPP handshake along with your AgentScore operator credential."
+            )
+        elif link_cli_blocked:
+            stripe_block["note"] = (
+                "link-cli SPT path not available for this purchase — Stripe link-cli caps spend requests at $500.00 "
+                f"($50000 cents); your total is ${total_num}. Use your own Stripe account with the SharedPaymentToken "
+                "API instead."
+            )
+        block["stripe"] = stripe_block
+
+    return block