a2a-protocol-core 0.1.0__tar.gz → 0.2.1__tar.gz

a2a_protocol_core-0.2.1/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to `a2a-protocol-core` are documented here. This project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.1] — 2026-07-20
+
+Conformance fix for the XRPL exact scheme's field placement. Required before
+the server drops its deprecated top-level mirrors (scheduled after 2026-10-01)
+— a 0.2.0 client will stop attaching `InvoiceID` at that point and be rejected
+by the server's mandatory invoice binding.
+
+### Fixed
+- `pay_alias_xrp` now reads `invoiceId` and `sourceTag` from the x402
+  requirement's `extra` block, where the XRPL exact scheme
+  (`scheme_exact_xrpl.md`) places them, falling back to the deprecated
+  top-level mirrors for not-yet-updated servers. Previously only the top-level
+  copies were read, so a spec-conformant server that stopped mirroring them
+  would silently produce payments without `InvoiceID` — which the invoice
+  binding (the anti-replay mechanism) mandatorily rejects.
+
+## [0.2.0] — 2026-07-11
+
+Adds the one-call x402 pay-path so an agent can pay a `pay:` alias from its own
+wallet — the "make it actually easy" client, still fully non-custodial.
+
+### Added
+- `pay_alias_xrp(...)` — resolve the x402 requirement for a `pay:` alias, sign +
+  submit the XRP payment **locally with the caller's own seed** (the seed never
+  leaves the process), then verify + fetch the signed resolve/verify/OFAC-screen
+  attestation. One call, end to end.
+- `attest_settled_payment(...)` — bring-your-own already-settled tx hash (e.g. an
+  agent paying through its own wallet stack / a Coinbase Agentic Wallet) and get
+  the read-only verify + attestation. No `[xrpl]` extra needed.
+- Pure, network-free helpers: `fetch_requirement`, `decode_payment_required`,
+  `build_x_payment_header`, `invoice_id_hash`, `summarize_attestation`, plus
+  `AttestationSummary` / `X402PaymentResult` / `X402PayError`.
+- New optional extra `[xrpl]` (pulls `xrpl-py`) — only needed for the local
+  signing in `pay_alias_xrp`; the base install stays `pydantic` + `requests`.
+
+## [0.1.0] — 2026-06-28
+
+Initial public protocol-core extraction from the DNS of Money Financial
+Autonomy Stack. Published to PyPI.
+
+### Added
+- `pay:` URI addressing (FAS-1 grammar): `is_valid_pay_uri`, `assert_valid_pay_uri`,
+  `PAY_URI_PATTERN`.
+- A2A-009 semantic normalizer: `normalize_action`, `normalize_message`,
+  `compute_semantic_hash`, `SYNONYM_MAP`, `CANONICAL_ACTIONS`.
+- A2A-008 canonical hashing: `compute_canonical_hash` — metadata-stable,
+  vocabulary-stable payment-intent hashing.
+- A2A-041 wire schemas: `A2APaymentHookRequest`, `A2APaymentHookResponse`,
+  `ResolutionDetail`, `SettlementDetail`, `A2ACapabilities`.
+- `A2APaymentHookClient` — synchronous payment-hook + capabilities client with
+  client-side validation.
+- Test suite covering addressing, normalization, canonical hashing, and schema
+  validation.
+- Apache-2.0 license, `py.typed` marker, runnable example.

{a2a_protocol_core-0.1.0 → a2a_protocol_core-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: a2a-protocol-core
-Version: 0.1.0
+Version: 0.2.1
 Summary: Open, deterministic protocol core for the DNS of Money A2A payment surface (FAS-1 pay: addressing, canonical hashing, payment-hook client).
 Project-URL: Homepage, https://dnsofmoney.com
 Project-URL: Specification, https://github.com/dnsofmoney/dns-of-money
@@ -20,6 +20,8 @@ Requires-Dist: requests>=2.31.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.3.0; extra == 'dev'
 Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: xrpl
+Requires-Dist: xrpl-py>=2.5.0; extra == 'xrpl'
 Description-Content-Type: text/markdown
 
 # a2a-protocol-core
@@ -81,6 +83,47 @@ print(result.settlement_result.status, result.iso_message_ref)
 
 See [`examples/trigger_payment_hook.py`](examples/trigger_payment_hook.py).
 
+## Pay a `pay:` alias in one call (non-custodial)
+
+Resolve the price, pay from **your own wallet**, and get back a signed
+resolve/verify/OFAC-screen attestation — one function, and your seed never leaves
+your process:
+
+```bash
+pip install "a2a-protocol-core[xrpl]"
+```
+
+```python
+from a2a_protocol_core import pay_alias_xrp
+
+result = pay_alias_xrp(
+    base_url="https://api.dnsofmoney.com",
+    alias="pay:vendor.alpha",
+    amount_xrp="0.10",
+    seed="s...",             # YOUR XRPL wallet seed — signs locally, never transmitted
+    api_key="fas_live_...",  # attributes the settle leg
+)
+print(result.tx_hash, result.summary.verdict)   # e.g. "A1B2…", "CLEAR"
+```
+
+Already settled the payment through your own wallet stack (or a Coinbase Agentic
+Wallet)? Skip the signing and just fetch the attestation — no `[xrpl]` extra:
+
+```python
+from a2a_protocol_core import attest_settled_payment
+
+result = attest_settled_payment(
+    base_url="https://api.dnsofmoney.com",
+    alias="pay:vendor.alpha",
+    amount_xrp="0.10",
+    tx_hash="A1B2C3...",     # your already-validated XRPL tx
+    api_key="fas_live_...",
+)
+```
+
+DNS of Money **verifies an already-settled transaction and returns metadata** — it
+never holds your keys or your funds.
+
 ## Why canonical hashing?
 
 Two agents describing the same payment with different words ("send" vs

{a2a_protocol_core-0.1.0 → a2a_protocol_core-0.2.1}/README.md

@@ -57,6 +57,47 @@ print(result.settlement_result.status, result.iso_message_ref)
 
 See [`examples/trigger_payment_hook.py`](examples/trigger_payment_hook.py).
 
+## Pay a `pay:` alias in one call (non-custodial)
+
+Resolve the price, pay from **your own wallet**, and get back a signed
+resolve/verify/OFAC-screen attestation — one function, and your seed never leaves
+your process:
+
+```bash
+pip install "a2a-protocol-core[xrpl]"
+```
+
+```python
+from a2a_protocol_core import pay_alias_xrp
+
+result = pay_alias_xrp(
+    base_url="https://api.dnsofmoney.com",
+    alias="pay:vendor.alpha",
+    amount_xrp="0.10",
+    seed="s...",             # YOUR XRPL wallet seed — signs locally, never transmitted
+    api_key="fas_live_...",  # attributes the settle leg
+)
+print(result.tx_hash, result.summary.verdict)   # e.g. "A1B2…", "CLEAR"
+```
+
+Already settled the payment through your own wallet stack (or a Coinbase Agentic
+Wallet)? Skip the signing and just fetch the attestation — no `[xrpl]` extra:
+
+```python
+from a2a_protocol_core import attest_settled_payment
+
+result = attest_settled_payment(
+    base_url="https://api.dnsofmoney.com",
+    alias="pay:vendor.alpha",
+    amount_xrp="0.10",
+    tx_hash="A1B2C3...",     # your already-validated XRPL tx
+    api_key="fas_live_...",
+)
+```
+
+DNS of Money **verifies an already-settled transaction and returns metadata** — it
+never holds your keys or your funds.
+
 ## Why canonical hashing?
 
 Two agents describing the same payment with different words ("send" vs

a2a_protocol_core-0.2.1/examples/agent_pay_alias.py

@@ -0,0 +1,87 @@
+"""
+Example: an AI agent pays a DNS of Money ``pay:`` alias and screens the counterparty.
+
+The scenario the agent-payment world actually needs solved: your agent knows *who*
+it wants to pay (a human-readable ``pay:`` name, not a raw r-address), needs to pay
+in one step, and wants proof it screened the counterparty before releasing funds.
+
+This is the whole loop in ~10 lines using ``a2a-protocol-core``:
+
+    quote  → resolve the x402 price for the alias           (no wallet needed)
+    pay    → sign + submit XRP from the agent's OWN wallet   (self-custody; seed never sent)
+    verify → get back a signed resolve/verify/OFAC-screen attestation
+    act    → the agent decides based on the screen verdict
+
+Works today for any XRPL-holding agent — e.g. one built on Ripple's XRPL AI Starter
+Kit, Crossmint agent wallets, or a Xaman/xApp wallet. DNS of Money is non-custodial:
+it verifies an already-settled tx and returns metadata; it never holds your keys or
+funds.
+
+Run (quote only — safe, no spend):
+    X402_BASE=https://api.dnsofmoney.com X402_ALIAS=pay:dnsofmoney \
+    python examples/agent_pay_alias.py
+
+Run (real payment — needs the [xrpl] extra + your funded XRPL wallet + an API key):
+    pip install "a2a-protocol-core[xrpl]"
+    X402_BASE=https://api.dnsofmoney.com X402_ALIAS=pay:vendor.alpha X402_AMOUNT=0.10 \
+    FAS_API_KEY=fas_live_... XRPL_AGENT_SEED=s... \
+    python examples/agent_pay_alias.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from a2a_protocol_core import (
+    X402PayError,
+    fetch_requirement,
+    pay_alias_xrp,
+)
+
+
+def main() -> int:
+    base_url = os.getenv("X402_BASE", "https://api.dnsofmoney.com")
+    alias = os.getenv("X402_ALIAS", "pay:dnsofmoney")
+    amount = os.getenv("X402_AMOUNT", "0.01")
+    seed = os.getenv("XRPL_AGENT_SEED", "").strip()
+    api_key = os.getenv("FAS_API_KEY", "").strip()
+    rpc = os.getenv("XRPL_RPC_URL", "https://xrplcluster.com")
+
+    # 1) QUOTE — resolve what this alias costs, on which rail. No wallet, no spend.
+    try:
+        req = fetch_requirement(base_url=base_url, alias=alias, amount_xrp=amount)
+    except X402PayError as exc:
+        print(f"[quote] could not get a price for {alias}: {exc}")
+        return 1
+    print(f"[quote] {alias} -> pay {req['maxAmountRequired']} drops to {req['payTo']} on {req['network']}")
+
+    # Quote-only mode: stop here unless the agent is configured to actually pay.
+    if not (seed and api_key):
+        print("[dry-run] set XRPL_AGENT_SEED (your wallet) + FAS_API_KEY to pay for real.")
+        return 0
+
+    # 2-3) PAY + VERIFY — one call: the agent signs from its own wallet, DNS of Money
+    #      verifies read-only and returns the signed attestation.
+    try:
+        result = pay_alias_xrp(
+            base_url=base_url, alias=alias, amount_xrp=amount, seed=seed, api_key=api_key, xrpl_rpc_url=rpc
+        )
+    except X402PayError as exc:
+        print(f"[pay] failed: {exc}")
+        return 1
+
+    s = result.summary
+    print(f"[paid] tx={result.tx_hash} settled={result.settled} ({'signed' if s.signed else 'unsigned'} attestation)")
+    print(f"[screen] overall={s.verdict}  payee={s.payee_verdict}  payer={s.payer_verdict}")
+
+    # 4) ACT — the agent does its own thing based on the compliance verdict.
+    if s.verdict == "BLOCKED":
+        print("[decide] counterparty screened BLOCKED — the agent would halt / escalate here.")
+        return 2
+    print("[decide] counterparty clear — the agent proceeds with the delivered service.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{a2a_protocol_core-0.1.0 → a2a_protocol_core-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "a2a-protocol-core"
-version = "0.1.0"
+version = "0.2.1"
 description = "Open, deterministic protocol core for the DNS of Money A2A payment surface (FAS-1 pay: addressing, canonical hashing, payment-hook client)."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,6 +30,12 @@ Specification = "https://github.com/dnsofmoney/dns-of-money"
 Source = "https://github.com/dnsofmoney/a2a-protocol-core"
 
 [project.optional-dependencies]
+# The one-call pay-path (pay_alias_xrp) signs an XRP payment with the caller's own
+# wallet — that needs xrpl-py. Kept optional so the base package stays dep-light
+# (resolve/hash/attest work without it).
+xrpl = [
+    "xrpl-py>=2.5.0",
+]
 dev = [
     "pytest>=8.3.0",
     "ruff>=0.8.0",

{a2a_protocol_core-0.1.0 → a2a_protocol_core-0.2.1}/src/a2a_protocol_core/__init__.py

@@ -34,8 +34,19 @@ from a2a_protocol_core.semantic_normalizer import (
     normalize_action,
     normalize_message,
 )
+from a2a_protocol_core.x402_pay import (
+    AttestationSummary,
+    X402PaymentResult,
+    X402PayError,
+    attest_settled_payment,
+    build_x_payment_header,
+    decode_payment_required,
+    fetch_requirement,
+    pay_alias_xrp,
+    summarize_attestation,
+)
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "__version__",
@@ -59,4 +70,14 @@ __all__ = [
     "A2ACapabilities",
     # client
     "A2APaymentHookClient",
+    # x402 pay-path (one-call; signing needs the [xrpl] extra)
+    "pay_alias_xrp",
+    "attest_settled_payment",
+    "fetch_requirement",
+    "decode_payment_required",
+    "build_x_payment_header",
+    "summarize_attestation",
+    "AttestationSummary",
+    "X402PaymentResult",
+    "X402PayError",
 ]

a2a_protocol_core-0.2.1/src/a2a_protocol_core/x402_pay.py

@@ -0,0 +1,297 @@
+"""
+One-call x402 pay-path — pay a ``pay:`` alias from YOUR own wallet.
+
+This is the "make it actually easy" helper: an agent developer calls one function
+to resolve the x402 requirement for a ``pay:`` alias, sign + submit an XRP payment
+**with their own wallet seed**, and hand the proof back to DNS of Money for a
+read-only verify + the signed resolve/verify/OFAC-screen attestation.
+
+Non-custodial by construction: the seed is used to sign locally, in *your* process,
+and is never sent over the wire. DNS of Money verifies an already-settled tx and
+returns metadata — it never holds your keys or your funds.
+
+    pip install "a2a-protocol-core[xrpl]"
+
+    from a2a_protocol_core import pay_alias_xrp
+
+    result = pay_alias_xrp(
+        base_url="https://api.dnsofmoney.com",
+        alias="pay:vendor.alpha",
+        amount_xrp="0.10",
+        seed="s...",            # YOUR XRPL wallet seed — signs locally, never sent
+        api_key="fas_live_...", # attributes the settle leg
+    )
+    print(result.tx_hash, result.summary.verdict)
+
+The pure helpers (``decode_payment_required``, ``build_x_payment_header``,
+``summarize_attestation``) have no network/xrpl dependency and are unit-tested; the
+XRPL signing lazy-imports ``xrpl-py`` so the base package stays dependency-light.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Any, Optional, Union
+
+import requests
+
+# Public mainnet XRPL JSON-RPC (multi-host cluster). Override for testnet/devnet.
+DEFAULT_XRPL_RPC = "https://xrplcluster.com"
+DEFAULT_TIMEOUT = 60
+
+
+class X402PayError(RuntimeError):
+    """Raised when the x402 pay-path fails (bad challenge, failed settle, or signing error)."""
+
+
+# ── Pure helpers (no network, no xrpl — unit-tested) ─────────────────────────────
+
+
+def decode_payment_required(header_value: str) -> dict:
+    """Decode the base64(JSON) PAYMENT-REQUIRED header into the XRP requirement dict."""
+    return json.loads(base64.b64decode(header_value))
+
+
+def build_x_payment_header(tx_hash: str, payer: Optional[str] = None) -> str:
+    """Build the X-PAYMENT header: base64(JSON) proof of the settled tx hash."""
+    payload: dict = {"txHash": tx_hash}
+    if payer:
+        payload["payer"] = payer
+    envelope = {"x402Version": 2, "payload": payload}
+    return base64.b64encode(json.dumps(envelope).encode()).decode()
+
+
+def invoice_id_hash(invoice_id: str) -> str:
+    """The on-chain InvoiceID that binds a payment to a 402 challenge.
+
+    Matches the server verifier: SHA-256 of the requirement's ``invoiceId``, hex,
+    uppercased. Setting it on the Payment replay-binds the tx to this challenge.
+    """
+    return hashlib.sha256(invoice_id.encode("utf-8")).hexdigest().upper()
+
+
+@dataclass
+class AttestationSummary:
+    """The deliverable at a glance — the resolve/verify/OFAC-screen verdicts."""
+
+    verdict: Optional[str]  # overall: CLEAR / REVIEW / BLOCKED / UNKNOWN
+    payee_verdict: Optional[str]
+    payer_verdict: Optional[str]
+    tx_id: Optional[str]
+    signed: bool
+
+
+def summarize_attestation(attestation: dict) -> AttestationSummary:
+    """One-glance summary of the attestation (signed VC or unsigned flat form)."""
+    subject = attestation.get("credentialSubject", attestation)
+    screen = subject.get("screen") or {}
+    settlement = subject.get("settlement") or {}
+    return AttestationSummary(
+        verdict=screen.get("verdict"),
+        payee_verdict=(screen.get("payee") or {}).get("verdict"),
+        payer_verdict=(screen.get("payer") or {}).get("verdict"),
+        tx_id=settlement.get("txid"),
+        signed=bool(attestation.get("proof")),
+    )
+
+
+@dataclass
+class X402PaymentResult:
+    """The outcome of a completed x402 pay-path."""
+
+    tx_hash: str
+    payer: Optional[str]
+    settled: bool
+    idempotent: bool
+    attestation: dict
+    proof: dict
+    summary: AttestationSummary
+    raw: dict
+
+
+# ── HTTP legs (challenge + settle) ───────────────────────────────────────────────
+
+
+def _pay_url(base_url: str, alias: str) -> str:
+    return f"{base_url.rstrip('/')}/api/v1/x402/pay/{alias}"
+
+
+def fetch_requirement(
+    *,
+    base_url: str,
+    alias: str,
+    amount_xrp: Union[str, Decimal],
+    session: Optional[requests.Session] = None,
+    timeout: int = DEFAULT_TIMEOUT,
+) -> dict:
+    """GET the 402 challenge and return the decoded XRP payment requirement.
+
+    Raises ``X402PayError`` if the server does not answer 402 (e.g. x402 disabled,
+    alias not payable, or the alias has no XRPL address).
+    """
+    http = session or requests.Session()
+    resp = http.get(_pay_url(base_url, alias), params={"amount": str(amount_xrp), "currency": "XRP"}, timeout=timeout)
+    if resp.status_code != 402:
+        raise X402PayError(f"expected a 402 challenge, got {resp.status_code}: {resp.text[:200]}")
+    header = resp.headers.get("PAYMENT-REQUIRED")
+    if not header:
+        raise X402PayError("402 response missing the PAYMENT-REQUIRED header")
+    return decode_payment_required(header)
+
+
+def _settle(
+    *,
+    base_url: str,
+    alias: str,
+    amount_xrp: Union[str, Decimal],
+    tx_hash: str,
+    payer: Optional[str],
+    api_key: str,
+    session: requests.Session,
+    timeout: int,
+) -> dict:
+    headers = {"X-PAYMENT": build_x_payment_header(tx_hash, payer), "X-API-Key": api_key}
+    resp = session.get(
+        _pay_url(base_url, alias),
+        params={"amount": str(amount_xrp), "currency": "XRP"},
+        headers=headers,
+        timeout=timeout,
+    )
+    if resp.status_code != 200:
+        raise X402PayError(f"settle leg failed {resp.status_code}: {resp.text[:300]}")
+    return resp.json()
+
+
+def _result_from_body(body: dict) -> X402PaymentResult:
+    attestation = body.get("attestation") or {}
+    proof = body.get("proof") or {}
+    return X402PaymentResult(
+        tx_hash=proof.get("transaction") or "",
+        payer=proof.get("payer"),
+        settled=bool(body.get("settled")),
+        idempotent=bool(body.get("idempotent")),
+        attestation=attestation,
+        proof=proof,
+        summary=summarize_attestation(attestation),
+        raw=body,
+    )
+
+
+# ── XRPL signing (lazy xrpl-py import — the [xrpl] extra) ─────────────────────────
+
+
+def _sign_and_submit_xrp(
+    *, pay_to: str, drops: str, seed: str, rpc_url: str, invoice_id: Optional[str], source_tag: Optional[int]
+) -> tuple[str, str]:
+    """Sign + submit an XRP Payment to ``pay_to`` for ``drops`` with the caller's seed.
+
+    Returns ``(tx_hash, payer_address)``. The seed never leaves this process.
+    """
+    try:
+        from xrpl.clients import JsonRpcClient
+        from xrpl.models.transactions import Payment
+        from xrpl.transaction import submit_and_wait
+        from xrpl.wallet import Wallet
+    except ImportError as exc:  # pragma: no cover - import guard
+        raise X402PayError(
+            "signing requires the 'xrpl' extra — install with: pip install 'a2a-protocol-core[xrpl]'"
+        ) from exc
+
+    wallet = Wallet.from_seed(seed)
+    client = JsonRpcClient(rpc_url)
+    fields: dict[str, Any] = {"account": wallet.address, "destination": pay_to, "amount": str(drops)}
+    if invoice_id:
+        fields["invoice_id"] = invoice_id
+    if source_tag is not None:
+        fields["source_tag"] = source_tag
+    resp = submit_and_wait(Payment(**fields), client, wallet)
+    result = resp.result
+    tx_result = (result.get("meta") or {}).get("TransactionResult")
+    if result.get("validated") and tx_result == "tesSUCCESS":
+        return result["hash"], wallet.address
+    raise X402PayError(f"XRPL payment did not succeed (result={tx_result})")
+
+
+# ── One-call entry points ────────────────────────────────────────────────────────
+
+
+def pay_alias_xrp(
+    *,
+    base_url: str,
+    alias: str,
+    amount_xrp: Union[str, Decimal],
+    seed: str,
+    api_key: str,
+    xrpl_rpc_url: str = DEFAULT_XRPL_RPC,
+    session: Optional[requests.Session] = None,
+    timeout: int = DEFAULT_TIMEOUT,
+) -> X402PaymentResult:
+    """Pay a ``pay:`` alias in XRP from your own wallet, end to end.
+
+    Resolve the x402 requirement (402 challenge) → sign + submit the XRP payment
+    locally with ``seed`` → hand the proof to DNS of Money for read-only verify +
+    the signed attestation. Non-custodial: the seed signs in-process and is never
+    transmitted. Requires the ``[xrpl]`` extra. Raises ``X402PayError`` on failure.
+    """
+    http = session or requests.Session()
+    req = fetch_requirement(base_url=base_url, alias=alias, amount_xrp=amount_xrp, session=http, timeout=timeout)
+    # The XRPL exact scheme carries scheme fields in `extra`; the top-level copies
+    # are our own deprecated mirrors (removed after 2026-10-01). Prefer `extra`, fall
+    # back to top-level so this client still works against not-yet-updated servers.
+    extra = req.get("extra") or {}
+    invoice = extra.get("invoiceId") or req.get("invoiceId")
+    source_tag = extra.get("sourceTag") if extra.get("sourceTag") is not None else req.get("sourceTag")
+    tx_hash, payer = _sign_and_submit_xrp(
+        pay_to=req["payTo"],
+        drops=req["maxAmountRequired"],
+        seed=seed,
+        rpc_url=xrpl_rpc_url,
+        invoice_id=invoice_id_hash(invoice) if invoice else None,
+        source_tag=source_tag,
+    )
+    body = _settle(
+        base_url=base_url,
+        alias=alias,
+        amount_xrp=amount_xrp,
+        tx_hash=tx_hash,
+        payer=payer,
+        api_key=api_key,
+        session=http,
+        timeout=timeout,
+    )
+    return _result_from_body(body)
+
+
+def attest_settled_payment(
+    *,
+    base_url: str,
+    alias: str,
+    amount_xrp: Union[str, Decimal],
+    tx_hash: str,
+    api_key: str,
+    payer: Optional[str] = None,
+    session: Optional[requests.Session] = None,
+    timeout: int = DEFAULT_TIMEOUT,
+) -> X402PaymentResult:
+    """Get the attestation for a payment you ALREADY settled on XRPL (bring-your-own tx).
+
+    Same settle leg as :func:`pay_alias_xrp`, minus the signing — for agents that pay
+    through their own wallet stack (or a Coinbase Agentic Wallet) and just want the
+    read-only verify + attestation. No ``[xrpl]`` extra needed.
+    """
+    http = session or requests.Session()
+    body = _settle(
+        base_url=base_url,
+        alias=alias,
+        amount_xrp=amount_xrp,
+        tx_hash=tx_hash,
+        payer=payer,
+        api_key=api_key,
+        session=http,
+        timeout=timeout,
+    )
+    return _result_from_body(body)

a2a_protocol_core-0.2.1/tests/test_cross_language_vectors.py

@@ -0,0 +1,59 @@
+"""
+Cross-language conformance — the Python side of the shared contract.
+
+Both this suite and the TS `@dnsofmoney/a2a-protocol-core` suite assert against
+the SAME `vectors/canonical_vectors.json` (generated from this Python reference
+by `generate_vectors.py`). The canonical/semantic hashes are byte-for-byte
+identical across languages; this test pins Python to the vectors so neither side
+can silently drift.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from a2a_protocol_core import (
+    compute_canonical_hash,
+    compute_semantic_hash,
+    is_valid_pay_uri,
+    normalize_action,
+)
+
+VECTORS = json.loads((Path(__file__).parent / "vectors" / "canonical_vectors.json").read_text(encoding="utf-8"))
+
+
+def test_pay_uri_vectors():
+    for v in VECTORS["pay_uri"]:
+        assert is_valid_pay_uri(v["input"]) is v["valid"], v["input"]
+
+
+def test_normalize_action_ok_vectors():
+    for v in VECTORS["normalize_action"]["ok"]:
+        assert normalize_action(v["input"]) == v["output"], v["input"]
+
+
+def test_normalize_action_error_vectors():
+    for bad in VECTORS["normalize_action"]["error"]:
+        with pytest.raises(ValueError):
+            normalize_action(bad)
+
+
+def test_canonical_hash_matches_vectors():
+    for c in VECTORS["canonical_hash"]:
+        assert compute_canonical_hash(c["request"]) == c["expected_hash"], c["name"]
+
+
+def test_canonical_hash_equivalence_groups():
+    by_name = {c["name"]: c["expected_hash"] for c in VECTORS["canonical_hash"]}
+    for group in VECTORS["canonical_hash_equivalence_groups"]:
+        first = by_name[group[0]]
+        for name in group:
+            assert by_name[name] == first, name
+
+
+def test_semantic_hash_matches_vectors():
+    for s in VECTORS["semantic_hash"]:
+        assert compute_semantic_hash(s["normalized"]) == s["expected_hash"], s["name"]