agentsync-sdk 1.0.0__py3-none-any.whl

agentsync/__init__.py

@@ -0,0 +1,88 @@
+"""
+AgentSync Python SDK.
+
+Idiomatic Python client for the AgentSync x402 micropayment gateway
+on the Radix ledger. Supports ROLA authentication, Mode A (credit
+buffer), Mode B (single-pay), and Mode C (RAP/1 bundled non-custodial
+on-chain settlement), plus catalog discovery and withdrawal attestation.
+"""
+
+from .attestation import SignatureEnvelope, verify_platform_attestation
+from .client import AgentSyncClient, CatalogModule, set_default_registry_component
+from .errors import AuthenticationError, GatewayError, InsufficientCreditError
+from .rap import generate_composite_manifest, generate_rap_manifest
+from .types import (
+    AgentSyncClientOptions,
+    AgentSyncFetchOptions,
+    AuthChallengeResponse,
+    AuthVerifyResponse,
+    CatalogEntry,
+    CatalogResponse,
+    CompositeManifestConfig,
+    CompositePurchase,
+    InsufficientCreditPayload,
+    PremiumDataResponse,
+    RadixAccountAddress,
+    RapManifestConfig,
+    RapPublicKey,
+    RapSignatureValue,
+    RapHash,
+    RapRootManifest,
+    RapNotary,
+    RapDraftInputs,
+    RapEconomicParams,
+    RapSignatureFile,
+    RapPayload,
+    RolaSigner,
+    SessionDebitEntry,
+    SessionSummary,
+    SettleResponse,
+    WithdrawalPayload,
+    WithdrawResponse,
+    UsdcDecimal,
+)
+
+__all__ = [
+    # Client
+    "AgentSyncClient",
+    "CatalogModule",
+    "set_default_registry_component",
+    # Standalone functions
+    "generate_composite_manifest",
+    "generate_rap_manifest",
+    "verify_platform_attestation",
+    # Errors
+    "AuthenticationError",
+    "GatewayError",
+    "InsufficientCreditError",
+    # Types
+    "AgentSyncClientOptions",
+    "AgentSyncFetchOptions",
+    "AuthChallengeResponse",
+    "AuthVerifyResponse",
+    "CatalogEntry",
+    "CatalogResponse",
+    "CompositeManifestConfig",
+    "CompositePurchase",
+    "InsufficientCreditPayload",
+    "PremiumDataResponse",
+    "RadixAccountAddress",
+    "RapManifestConfig",
+    "RapPublicKey",
+    "RapSignatureValue",
+    "RapHash",
+    "RapRootManifest",
+    "RapNotary",
+    "RapDraftInputs",
+    "RapEconomicParams",
+    "RapSignatureFile",
+    "RapPayload",
+    "RolaSigner",
+    "SessionDebitEntry",
+    "SessionSummary",
+    "SettleResponse",
+    "SignatureEnvelope",
+    "WithdrawalPayload",
+    "WithdrawResponse",
+    "UsdcDecimal",
+]

agentsync/attestation.py

@@ -0,0 +1,89 @@
+"""
+Platform attestation verification for AgentSync.
+
+Verifies the Ed25519 signature over the SHA-256 pre-hash of an attestation
+payload, mirroring the platform signing path in ``worker/src/attestation.ts``.
+
+Signature scheme: SHA-256 pre-hash → Ed25519 verify (matches Scrypto's
+``verify_ed25519`` convention where messages are hashed before verifying).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from dataclasses import dataclass
+
+from nacl.exceptions import BadSignatureError
+from nacl.signing import VerifyKey
+
+SUPPORTED_ALGORITHM = "ed25519+sha256"
+
+
+@dataclass(frozen=True)
+class SignatureEnvelope:
+    """Attestation envelope produced by the platform."""
+
+    payload: str
+    signature: str
+    public_key: str
+    algorithm: str
+
+
+def verify_platform_attestation(
+    envelope: SignatureEnvelope,
+    trusted_public_key: str,
+) -> bool:
+    """Verify a platform attestation envelope against the trusted platform key.
+
+    The function is pure and synchronous: the trusted public key is injected by
+    the caller, never fetched from the network. To prevent tautological spoofing
+    (an attacker signing a tampered payload with their own key), the envelope's
+    ``public_key`` must match ``trusted_public_key`` before any signature check.
+
+    Args:
+        envelope: Attestation envelope (payload, signature, public key,
+            algorithm) produced by the platform.
+        trusted_public_key: Hex-encoded 32-byte Ed25519 public key the caller
+            has independently verified as the platform's key.
+
+    Returns:
+        ``True`` if the algorithm is supported, the embedded key matches the
+        trusted key, and the signature verifies over ``SHA-256(payload)``.
+    """
+    if envelope.algorithm != SUPPORTED_ALGORITHM:
+        return False
+
+    if not _constant_time_hex_equals(envelope.public_key, trusted_public_key):
+        return False
+
+    public_key = _hex_to_bytes(trusted_public_key)
+    signature = _hex_to_bytes(envelope.signature)
+    if public_key is None or signature is None:
+        return False
+    if len(public_key) != 32 or len(signature) != 64:
+        return False
+
+    # SHA-256 pre-hash — matches the platform's Ed25519(SHA-256(payload)) scheme.
+    message_hash = hashlib.sha256(envelope.payload.encode("utf-8")).digest()
+
+    try:
+        VerifyKey(public_key).verify(message_hash, signature)
+        return True
+    except (BadSignatureError, ValueError):
+        return False
+
+
+def _hex_to_bytes(value: str) -> bytes | None:
+    """Decode a hex string to bytes, returning ``None`` on malformed input."""
+    try:
+        return bytes.fromhex(value)
+    except ValueError:
+        return None
+
+
+def _constant_time_hex_equals(a: str, b: str) -> bool:
+    """Compare two hex strings in constant time."""
+    if len(a) != len(b):
+        return False
+    return hmac.compare_digest(a.encode("utf-8"), b.encode("utf-8"))

agentsync/client.py

@@ -0,0 +1,565 @@
+"""
+AgentSyncClient — primary entry point for the ``agentsync`` Python SDK.
+
+Configuration:
+  - base_url:        Gateway API URL (e.g. https://agentsync-api.rennv-agentsync.workers.dev)
+  - agent_address:   The agent's Radix component/account address
+  - signer:          Optional ROLA signing callback
+
+Public surface:
+  - client.catalog.list()             → list[CatalogEntry]
+  - client.catalog.get_llms_txt()     → str
+  - client.catalog.by_service_id()    → list[CatalogEntry]
+  - client.catalog.by_provider_address() → list[CatalogEntry]
+  - client.fetch(path, opts?)         → httpx.Response (Mode A/B x402)
+  - client.generate_rap_manifest(agent, amount, config) → RTM string (Mode C)
+  - client.settle_session()           → dict with manifest + attestation
+  - client.request_withdrawal(amt)    → dict with manifest + attestation
+"""
+
+from __future__ import annotations
+
+import json as _json
+import os
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import httpx
+
+from .errors import AuthenticationError, GatewayError, InsufficientCreditError
+from .rap import generate_composite_manifest as _generate_composite_manifest_fn
+from .rap import generate_rap_manifest as _generate_rap_manifest_fn
+from .types import (
+    AgentSyncClientOptions,
+    AgentSyncFetchOptions,
+    AuthChallengeResponse,
+    AuthVerifyResponse,
+    CatalogEntry,
+    CatalogResponse,
+    CompositeManifestConfig,
+    CompositePurchase,
+    InsufficientCreditPayload,
+    RapManifestConfig,
+    SettleResponse,
+    WithdrawResponse,
+)
+
+# ── Internal helpers ───────────────────────────────────────────────────
+
+
+# Live Stokenet AgentRegistry component — override via the
+# REGISTRY_COMPONENT env var or ``set_default_registry_component``.
+_LIVE_STOKENET_REGISTRY_COMPONENT = (
+    "component_tdx_2_1cz75s5p3xjnk38puy34hdapqgyddg9v5tmg7juzzpwvw8rgww9ac0c"
+)
+
+_default_registry_component = os.environ.get(
+    "REGISTRY_COMPONENT", _LIVE_STOKENET_REGISTRY_COMPONENT
+)
+
+
+def set_default_registry_component(address: str) -> None:
+    """Override the default registry component address used in generated
+    Radix transaction manifests."""
+    global _default_registry_component
+    _default_registry_component = address
+
+
+# ── Manifest formatters ────────────────────────────────────────────────
+
+
+def _format_settle_manifest(
+    agent_address: str,
+    payload: str,
+    signature: str,
+) -> str:
+    parts = payload.split(":")
+    amount = parts[1] if len(parts) >= 2 else "0.000000"
+    nonce = parts[2] if len(parts) >= 3 else "0"
+
+    return (
+        "CALL_METHOD\n"
+        f'    Address("{_default_registry_component}")\n'
+        '    "settle_agent_session"\n'
+        f'    Decimal("{amount}")\n'
+        f'    Address("{agent_address}")\n'
+        f'    {nonce}u64\n'
+        f'    Bytes("{signature}");'
+    )
+
+
+def _format_withdraw_manifest(
+    agent_address: str,
+    payload: str,
+    signature: str,
+) -> str:
+    parts = payload.split(":")
+    amount = parts[1] if len(parts) >= 2 else "0.000000"
+    nonce = parts[2] if len(parts) >= 3 else "0"
+
+    return (
+        "CALL_METHOD\n"
+        f'    Address("{_default_registry_component}")\n'
+        '    "request_withdrawal"\n'
+        f'    Decimal("{amount}")\n'
+        f'    Address("{agent_address}")\n'
+        f'    {nonce}u64\n'
+        f'    Bytes("{signature}");'
+    )
+
+
+# ── Catalog module ─────────────────────────────────────────────────────
+
+
+class CatalogModule:
+    """Discovery module — browse available data products and fetch
+    AI-agent documentation from the gateway."""
+
+    def __init__(self, client: "AgentSyncClient") -> None:
+        self._client = client
+
+    async def list(self) -> list[CatalogEntry]:
+        """Fetch the full x402 product catalog (filtered ≥ 0.75 XRD floor).
+
+        No authentication required — public endpoint.
+        """
+        resp = await self._client._raw_fetch(
+            f"{self._client._base_url}/v1/catalog",
+            headers={"accept": "application/json"},
+        )
+
+        if not resp.is_success:
+            try:
+                body = resp.json()
+            except Exception:
+                body = {}
+            raise GatewayError(
+                f"Catalog fetch failed: {resp.status_code}",
+                resp.status_code,
+                body,
+            )
+
+        body = resp.json()
+        services = body["data"]["services"]
+        return [
+            CatalogEntry(
+                service_id=s["service_id"],
+                provider_address=s["provider_address"],
+                provider_name=s["provider_name"],
+                name=s["name"],
+                description=s["description"],
+                base_tariff=s["base_tariff"],
+                currency=s.get("currency", "USDC"),
+                endpoint_paths=s.get("endpoint_paths", []),
+                swagger_url=s.get("swagger_url", ""),
+            )
+            for s in services
+        ]
+
+    async def get_llms_txt(self) -> str:
+        """Fetch the ``llms.txt`` markdown documentation.
+
+        No authentication required — public endpoint.
+        """
+        resp = await self._client._raw_fetch(
+            f"{self._client._base_url}/.well-known/llms.txt",
+            headers={"accept": "text/markdown"},
+        )
+
+        if not resp.is_success:
+            raise GatewayError(
+                f"llms.txt fetch failed: {resp.status_code}",
+                resp.status_code,
+                None,
+            )
+
+        return resp.text
+
+    @staticmethod
+    def by_service_id(
+        entries: list[CatalogEntry], service_id: str
+    ) -> list[CatalogEntry]:
+        """Filter catalog entries by ``service_id``."""
+        return [e for e in entries if e.service_id == service_id]
+
+    @staticmethod
+    def by_provider_address(
+        entries: list[CatalogEntry], provider_address: str
+    ) -> list[CatalogEntry]:
+        """Filter catalog entries by ``provider_address``."""
+        return [e for e in entries if e.provider_address == provider_address]
+
+
+# ── Client ─────────────────────────────────────────────────────────────
+
+
+class AgentSyncClient:
+    """Primary entry point for the AgentSync Python SDK.
+
+    Handles ROLA authentication, Mode A/B x402 fetch, Mode C RAP/1
+    bundle settlement, session settlement, and withdrawal attestation.
+    """
+
+    def __init__(self, options: AgentSyncClientOptions) -> None:
+        self._base_url = options.base_url.rstrip("/")
+        self._agent_address = options.agent_address
+        self._signer = options.signer
+        self._options = options
+        self._bearer_token: Optional[str] = None
+        self._token_expires_at: Optional[datetime] = None
+        self._http = httpx.AsyncClient()
+        self.catalog = CatalogModule(self)
+
+    # ── Package-private helpers for CatalogModule ──────────────────────
+
+    @property
+    def _raw_fetch(self):
+        """Raw HTTP fetch for unauthenticated catalog endpoints."""
+        return self._http.get
+
+    # ── ROLA Authentication ───────────────────────────────────────────
+
+    async def authenticate(self) -> None:
+        """Perform the full ROLA challenge-response flow.
+
+        Must be called before any authenticated endpoint unless auto-auth
+        was triggered by a prior call.
+        """
+        if self._signer is None:
+            raise AuthenticationError(
+                "No signer provided — cannot authenticate. "
+                "Pass a `signer` callback in AgentSyncClientOptions.",
+                401,
+            )
+
+        # 1. Request challenge
+        chal_resp = await self._http.post(
+            f"{self._base_url}/v1/auth/challenge",
+            headers={"content-type": "application/json"},
+        )
+
+        if not chal_resp.is_success:
+            raise AuthenticationError(
+                f"Challenge request failed: {chal_resp.status_code}",
+                chal_resp.status_code,
+            )
+
+        challenge = chal_resp.json()
+
+        # 2. Sign challenge via user-provided callback
+        signed = await self._signer(challenge["data"]["challenge"])
+
+        # 3. Verify and get token
+        verify_resp = await self._http.post(
+            f"{self._base_url}/v1/auth/verify",
+            headers={"content-type": "application/json"},
+            json={
+                "challenge": challenge["data"]["challenge"],
+                "signature": signed["signature"],
+                "identity_address": self._agent_address,
+                "public_key": signed["public_key"],
+            },
+        )
+
+        if not verify_resp.is_success:
+            raise AuthenticationError(
+                f"Verification failed: {verify_resp.status_code}",
+                verify_resp.status_code,
+            )
+
+        verified = verify_resp.json()
+        self._bearer_token = verified["data"]["auth_token"]
+        self._token_expires_at = datetime.fromisoformat(
+            verified["data"]["expires_at"]
+        )
+
+    async def _ensure_auth(self) -> str:
+        """Return the current bearer token, authenticating if necessary."""
+        if (
+            self._bearer_token is not None
+            and self._token_expires_at is not None
+            and self._token_expires_at > datetime.now(timezone.utc)
+        ):
+            return self._bearer_token
+        await self.authenticate()
+        return self._bearer_token  # type: ignore[return-value]
+
+    # ── Generic authenticated request ─────────────────────────────────
+
+    async def _request(self, path: str, init: dict[str, Any] | None = None) -> Any:
+        """Low-level authenticated request with standard error handling."""
+        if init is None:
+            init = {}
+        token = await self._ensure_auth()
+
+        headers = {**init.get("headers", {})}
+        headers.setdefault("content-type", "application/json")
+        headers["authorization"] = f"Bearer {token}"
+
+        method = init.get("method", "GET")
+        body = init.get("body") or init.get("json")
+
+        if isinstance(body, dict):
+            resp = await self._http.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=headers,
+                json=body,
+            )
+        elif isinstance(body, (str, bytes)):
+            resp = await self._http.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=headers,
+                content=body,
+            )
+        else:
+            resp = await self._http.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=headers,
+            )
+
+        if not resp.is_success:
+            try:
+                resp_body = resp.json()
+            except Exception:
+                resp_body = {}
+
+            if resp.status_code == 401:
+                self._bearer_token = None
+                self._token_expires_at = None
+                msg = (
+                    resp_body.get("error", {}).get("message")
+                    if isinstance(resp_body, dict)
+                    else "Authentication failed"
+                )
+                raise AuthenticationError(msg, resp.status_code)
+
+            if resp.status_code == 402:
+                details = (
+                    resp_body.get("error", {}).get("details")
+                    if isinstance(resp_body, dict)
+                    else None
+                )
+                raise InsufficientCreditError(
+                    details.get("required", "0") if details else "0",
+                    details.get("available", "0") if details else "0",
+                    resp_body,
+                )
+
+            raise GatewayError(
+                (
+                    resp_body.get("error", {}).get("message")
+                    if isinstance(resp_body, dict)
+                    else f"HTTP {resp.status_code}"
+                ),
+                resp.status_code,
+                resp_body,
+            )
+
+        return resp.json()
+
+    # ── Augmented fetch (x402) ─────────────────────────────────────────
+
+    async def fetch(
+        self,
+        path: str,
+        opts: AgentSyncFetchOptions | None = None,
+    ) -> httpx.Response:
+        """Augmented fetch for premium data endpoints.
+
+        **Mode A (Credit Buffer)**: Default. Automatically injects ROLA
+        auth headers. Throws ``InsufficientCreditError`` on 402.
+
+        **Mode B (Single-Pay)**: Pass ``rap_payload`` (and optional
+        ``requirements``) in opts to send the body
+        ``{ payment: { rap_payload, requirements } }`` — the structure
+        expected by ``handleModeBSponsored``.
+        """
+        if opts is None:
+            opts = AgentSyncFetchOptions()
+
+        token = await self._ensure_auth()
+
+        headers: dict[str, str] = {**(opts.headers or {})}
+        headers["authorization"] = f"Bearer {token}"
+
+        method = opts.method or "GET"
+        body = opts.body
+
+        if opts.rap_payload is not None:
+            method = "POST"
+            headers.setdefault("content-type", "application/json")
+            body = _json.dumps(
+                {
+                    "payment": {
+                        "rap_payload": opts.rap_payload.to_dict(),
+                        "requirements": opts.requirements or {},
+                    }
+                }
+            )
+
+        if body is not None:
+            resp = await self._http.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=headers,
+                content=body if isinstance(body, bytes) else body,
+            )
+        else:
+            resp = await self._http.request(
+                method,
+                f"{self._base_url}{path}",
+                headers=headers,
+            )
+
+        if not resp.is_success:
+            if resp.status_code == 401:
+                self._bearer_token = None
+                self._token_expires_at = None
+                try:
+                    body_json = resp.json()
+                except Exception:
+                    body_json = {}
+                msg = (
+                    body_json.get("error", {}).get("message")
+                    if isinstance(body_json, dict)
+                    else "Authentication failed"
+                )
+                raise AuthenticationError(msg, resp.status_code)
+
+            if resp.status_code == 402:
+                try:
+                    body_json = resp.json()
+                except Exception:
+                    body_json = {}
+                details = (
+                    body_json.get("error", {}).get("details")
+                    if isinstance(body_json, dict)
+                    else None
+                )
+                raise InsufficientCreditError(
+                    details.get("required", "0") if details else "0",
+                    details.get("available", "0") if details else "0",
+                    body_json,
+                )
+
+        return resp
+
+    # ── Mode C: Path A (Non-Custodial) Manifest ────────────────────────
+
+    def generate_rap_manifest(
+        self,
+        agent: str,
+        amount: str,
+        config: RapManifestConfig,
+    ) -> str:
+        """Generate the Radix transaction manifest (RTM) for Mode C
+        bundled settlement — **Path A (non-custodial)**.
+
+        Produces a manifest that withdraws USDC from the agent's on-chain
+        Radix account and routes it through ``process_api_payment`` on
+        the registry. Platform gas is sponsored via ``lock_fee``.
+
+        **Synchronous** — no Ed25519 attestation needed. The agent's
+        Radix account signature on the transaction proves authorization.
+
+        Args:
+            agent: The agent's Radix account address (the withdrawing account).
+            amount: USDC amount to settle as a 6-decimal string.
+            config: Economic parameters (platform account, USDC resource,
+                    registry component, XRD fee loan amount).
+
+        Returns:
+            Raw Radix Transaction Manifest (RTM) string.
+        """
+        return _generate_rap_manifest_fn(agent, amount, config)
+
+    # ── Composite Manifest (Mode B Multi-Endpoint) ─────────────────────
+
+    def generate_composite_manifest(
+        self,
+        config: CompositeManifestConfig,
+        purchases: list[CompositePurchase],
+    ) -> str:
+        """Generate a composite Radix transaction manifest (RTM) that
+        atomically settles multiple API endpoint purchases in a single
+        on-chain transaction.
+
+        Extends Mode B (Single-Pay) to bundle N endpoint purchases into
+        one atomic manifest: a single aggregate ``withdraw`` followed by
+        per-endpoint ``TAKE_FROM_WORKTOP`` + ``CALL_METHOD
+        process_api_payment`` pairs.
+
+        **Synchronous** — no network call. The agent submits the resulting
+        RTM to the Radix network via their wallet.
+
+        Args:
+            config: Economic parameters (agent, platform account, USDC
+                    resource, registry component, XRD fee loan amount).
+            purchases: List of endpoint purchases (endpoint_id + amount).
+
+        Returns:
+            Raw Radix Transaction Manifest (RTM) string.
+        """
+        return _generate_composite_manifest_fn(config, purchases)
+
+    # ── Settlement ────────────────────────────────────────────────────
+
+    async def settle_session(self) -> dict[str, Any]:
+        """Initiate session settlement.
+
+        Calls ``POST /v1/settle`` and returns payload, signature,
+        session summary, and a ready-to-submit RTM string.
+        """
+        data = await self._request("/v1/settle", {"method": "POST"})
+
+        manifest = _format_settle_manifest(
+            self._agent_address,
+            data["data"]["payload"],
+            data["data"]["signature"],
+        )
+
+        return {
+            "payload": data["data"]["payload"],
+            "signature": data["data"]["signature"],
+            "session_summary": data["data"]["session_summary"],
+            "manifest": manifest,
+        }
+
+    # ── Withdrawal ────────────────────────────────────────────────────
+
+    async def request_withdrawal(
+        self, amount_usdc: str
+    ) -> dict[str, Any]:
+        """Request an attested USDC withdrawal from the registry.
+
+        Calls ``POST /v1/withdraw`` and returns payload, signature,
+        withdrawal details, and a ready-to-submit RTM string.
+
+        Args:
+            amount_usdc: USDC amount as a 6-decimal string
+                (e.g. ``"10.000000"``).
+        """
+        data = await self._request(
+            "/v1/withdraw",
+            {"method": "POST", "json": {"amount_usdc": amount_usdc}},
+        )
+
+        manifest = _format_withdraw_manifest(
+            self._agent_address,
+            data["data"]["payload"],
+            data["data"]["signature"],
+        )
+
+        return {
+            "payload": data["data"]["payload"],
+            "signature": data["data"]["signature"],
+            "withdrawal": data["data"]["withdrawal"],
+            "manifest": manifest,
+        }
+
+    async def close(self) -> None:
+        """Release the underlying HTTP client resources."""
+        await self._http.aclose()

agentsync/errors.py

@@ -0,0 +1,50 @@
+"""
+Error types for the AgentSync SDK.
+
+Mirrors the TypeScript error hierarchy in `sdk-typescript/src/errors.ts`.
+All exception classes carry structured fields so calling code can
+programmatically inspect failures without string parsing.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class InsufficientCreditError(Exception):
+    """Thrown when the gateway returns ``402 Payment Required`` — the
+    agent's credit buffer is too low for the requested API call."""
+
+    def __init__(
+        self,
+        required: str,
+        available: str,
+        response_body: Any = None,
+    ) -> None:
+        self.required = required
+        self.available = available
+        self.response_body = response_body
+        super().__init__(
+            f"Insufficient credit: required {required} USDC, "
+            f"available {available} USDC. "
+            "Top up your credit buffer via the on-chain registry's "
+            "top_up_usdc_vault method."
+        )
+
+
+class AuthenticationError(Exception):
+    """Thrown when authentication fails (bad credentials, expired token,
+    etc.)."""
+
+    def __init__(self, message: str, status: int) -> None:
+        self.status = status
+        super().__init__(message)
+
+
+class GatewayError(Exception):
+    """Thrown when the gateway returns an unexpected error response."""
+
+    def __init__(self, message: str, status: int, body: Any = None) -> None:
+        self.status = status
+        self.body = body
+        super().__init__(message)

agentsync/rap.py

@@ -0,0 +1,165 @@
+"""
+RAP/1 Module — Mode C Path A Settlement (Python SDK).
+
+Builds the Path A non-custodial Radix transaction manifest (RTM) for
+on-chain bundled settlement of API consumption sessions.
+
+Path A (non-custodial): USDC is withdrawn directly from the agent's
+on-chain Radix account at settlement time via ``process_api_payment``.
+Platform gas is sponsored via ``lock_fee``. No Ed25519 attestation
+signing is needed in the SDK — the agent's Radix account signature
+on the transaction provides proof of authorization.
+
+Lifecycle:
+    1. ``generate_rap_manifest`` → build Path A RTM string (synchronous)
+    2. Developer submits RTM to Radix network
+"""
+
+from typing import Sequence
+
+from .types import (
+    CompositeManifestConfig,
+    CompositePurchase,
+    RapManifestConfig,
+)
+
+
+def generate_rap_manifest(
+    agent: str,
+    amount: str,
+    config: RapManifestConfig,
+) -> str:
+    """Generate the Radix transaction manifest (RTM) for Mode C bundled
+    settlement — **Path A (non-custodial)**.
+
+    The manifest follows the non-custodial Path A flow:
+
+    1. ``lock_fee`` — platform sponsors XRD network fee
+    2. ``withdraw`` — pull USDC from agent's on-chain Radix account
+    3. ``TAKE_ALL_FROM_WORKTOP`` — take the withdrawn USDC into a bucket
+    4. ``CALL_METHOD process_api_payment`` — split payment via registry
+       (99.5% provider, 0.25% gas vault, 0.25% developer treasury)
+
+    **Synchronous** — no Ed25519 attestation required. The agent's Radix
+    account signature on the transaction proves authorization to withdraw.
+
+    Args:
+        agent: The agent's Radix account address (the withdrawing account).
+        amount: USDC amount to settle as a 6-decimal string.
+        config: Economic parameters (platform account, USDC resource,
+                registry component, XRD fee loan amount).
+
+    Returns:
+        Raw Radix Transaction Manifest (RTM) string.
+    """
+    return "\n".join(
+        [
+            "CALL_METHOD",
+            f'    Address("{config.platform_account}")',
+            '    "lock_fee"',
+            f'    Decimal("{config.fee_loan_amount}");',
+            "CALL_METHOD",
+            f'    Address("{agent}")',
+            '    "withdraw"',
+            f'    Address("{config.usdc_resource}")',
+            f'    Decimal("{amount}");',
+            "TAKE_ALL_FROM_WORKTOP",
+            f'    Address("{config.usdc_resource}")',
+            '    Bucket("payment");',
+            "CALL_METHOD",
+            f'    Address("{config.registry_component}")',
+            '    "process_api_payment"',
+            '    Bucket("payment");',
+            "CALL_METHOD",
+            f'    Address("{config.merchant_account}")',
+            '    "deposit_batch"',
+            '    Expression("ENTIRE_WORKTOP");',
+        ]
+    )
+
+
+# ── Composite Manifest Builder ──────────────────────────────────────────
+
+
+def _sum_usdc_amounts(amounts: Sequence[str]) -> str:
+    """Sum USDC decimal strings via integer micro-unit arithmetic."""
+    total = 0
+    for amt in amounts:
+        total += round(float(amt) * 1_000_000)
+    return f"{total / 1_000_000:.6f}"
+
+
+def generate_composite_manifest(
+    config: CompositeManifestConfig,
+    purchases: Sequence[CompositePurchase],
+) -> str:
+    """Generate a composite Radix transaction manifest (RTM) that atomically
+    settles multiple API endpoint purchases in a single on-chain transaction.
+
+    The manifest follows the non-custodial Path A flow extended for N endpoints:
+
+    1. ``lock_fee`` — platform sponsors XRD network fee
+    2. ``withdraw`` — single aggregate USDC withdrawal from agent's account
+    3. For each purchase:
+       a. ``TAKE_FROM_WORKTOP`` — partition exact USDC into ``payment_{i}`` bucket
+       b. ``CALL_METHOD process_api_payment`` — settle that endpoint via registry
+
+    All ``process_api_payment`` calls execute within the same atomic
+    transaction, so the entire batch either fully succeeds or fully reverts.
+
+    Args:
+        config: Economic parameters (agent, platform account, USDC resource,
+                registry component, XRD fee loan amount).
+        purchases: Ordered sequence of endpoint purchases (endpoint_id + amount).
+
+    Returns:
+        Raw Radix Transaction Manifest (RTM) string.
+    """
+    if not purchases:
+        raise ValueError(
+            "generate_composite_manifest: purchases must not be empty"
+        )
+
+    total = _sum_usdc_amounts([p.amount for p in purchases])
+
+    lines: list[str] = [
+        # 1. Platform sponsors network fee
+        "CALL_METHOD",
+        f'    Address("{config.platform_account}")',
+        '    "lock_fee"',
+        f'    Decimal("{config.fee_loan_amount}");',
+        # 2. Single aggregate withdraw from agent account
+        "CALL_METHOD",
+        f'    Address("{config.agent}")',
+        '    "withdraw"',
+        f'    Address("{config.usdc_resource}")',
+        f'    Decimal("{total}");',
+    ]
+
+    # 3. Per-endpoint: partition worktop → process_api_payment
+    for i, p in enumerate(purchases):
+        bucket = f"payment_{i}"
+        lines.extend(
+            [
+                "TAKE_FROM_WORKTOP",
+                f'    Address("{config.usdc_resource}")',
+                f'    Decimal("{p.amount}")',
+                f'    Bucket("{bucket}");',
+                "CALL_METHOD",
+                f'    Address("{config.registry_component}")',
+                '    "process_api_payment"',
+                f'    Bucket("{bucket}");',
+            ]
+        )
+
+    # 4. Deposit any remaining worktop balance to the merchant account
+    lines.extend(
+        [
+            "CALL_METHOD",
+            f'    Address("{config.merchant_account}")',
+            '    "deposit_batch"',
+            '    Expression("ENTIRE_WORKTOP");',
+        ]
+    )
+
+    return "\n".join(lines)

agentsync/types.py

@@ -0,0 +1,328 @@
+"""
+AgentSync Python SDK — type definitions.
+
+Mirrors the gateway API response shapes from the TypeScript SDK.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Coroutine, Optional, Protocol, runtime_checkable
+
+
+# ── ROLA Auth ──────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class AuthChallengeResponse:
+    ok: bool
+    data: dict[str, str]  # challenge, nonce, expires_at
+
+
+@dataclass(frozen=True)
+class AuthVerifyResponse:
+    ok: bool
+    data: dict[str, str]  # auth_token, expires_at
+
+
+# ── Catalog ────────────────────────────────────────────────────────────
+
+# Radix account component address (e.g. `account_tdx_2_...`)
+RadixAccountAddress = str
+
+# USDC decimal string (e.g. `"0.75"`, `"2.500"`)
+UsdcDecimal = str
+
+
+@dataclass(frozen=True)
+class CatalogEntry:
+    service_id: str
+    provider_address: RadixAccountAddress
+    provider_name: str
+    name: str
+    description: str
+    base_tariff: UsdcDecimal
+    currency: str = "USDC"
+    endpoint_paths: list[str] = field(default_factory=list)
+    swagger_url: str = ""
+
+
+@dataclass(frozen=True)
+class CatalogResponse:
+    ok: bool
+    data: dict[str, Any]  # services, total, platform_floor_usdc, currency
+
+
+# ── Premium Data Proxy ─────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class PremiumDataResponse:
+    ok: bool
+    data: dict[str, Any]  # proxied, mode, remaining_balance?, txid?
+
+
+@dataclass(frozen=True)
+class InsufficientCreditPayload:
+    ok: bool
+    error: dict[str, Any]  # code, message, details (required, available)
+
+
+# ── RAP/1: Mode C (Path A / Non-Custodial) ─────────────────────────────
+
+@dataclass(frozen=True)
+class RapManifestConfig:
+    """Economic configuration for Path A (non-custodial) manifest generation."""
+    platform_account: str
+    usdc_resource: str
+    registry_component: str
+    fee_loan_amount: str
+    merchant_account: str
+
+
+# ── Composite Manifests (Mode B Multi-Endpoint) ──────────────────────────
+
+@dataclass(frozen=True)
+class CompositePurchase:
+    """A single purchase within a composite (multi-endpoint) manifest."""
+    endpoint_id: str
+    amount: str
+
+
+@dataclass(frozen=True)
+class CompositeManifestConfig:
+    """Configuration for generating a composite (multi-endpoint) manifest."""
+    agent: str
+    platform_account: str
+    usdc_resource: str
+    registry_component: str
+    fee_loan_amount: str
+    merchant_account: str
+
+
+# ── Settlement ─────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class SessionDebitEntry:
+    timestamp: str
+    cost_usdc: str
+    provider_address: str
+    service_id: str
+
+
+@dataclass(frozen=True)
+class SessionSummary:
+    total_debits: int
+    total_spent: str
+    by_provider: dict[str, str]
+    by_service: dict[str, str]
+    entries: list[SessionDebitEntry]
+
+
+@dataclass(frozen=True)
+class SettleResponse:
+    ok: bool
+    data: dict[str, Any]  # payload, signature, session_summary
+
+
+# ── Withdrawal ─────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class WithdrawalPayload:
+    agent: str
+    amount: str
+    nonce: int
+
+
+@dataclass(frozen=True)
+class WithdrawResponse:
+    ok: bool
+    data: dict[str, Any]  # payload, signature, withdrawal
+
+
+# ── Auth Signer ────────────────────────────────────────────────────────
+
+@runtime_checkable
+class RolaSigner(Protocol):
+    """Callback protocol for ROLA challenge signing."""
+    def __call__(self, challenge: str) -> Coroutine[Any, Any, dict[str, str]]: ...
+
+
+# ── Client Options ─────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class AgentSyncClientOptions:
+    """Options passed to AgentSyncClient.
+
+    base_url: Gateway API base URL (e.g. ``https://agentsync-api.rennv-agentsync.workers.dev``).
+    """
+    base_url: str
+    agent_address: RadixAccountAddress
+    signer: Optional[RolaSigner] = None
+
+
+# ── Mode B (x402 Sponsored) rap_payload wire shapes ─────────────────────
+
+@dataclass(frozen=True)
+class RapPublicKey:
+    """Wire shape of a public key (serde camelCase)."""
+    curve: str
+    hex: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"curve": self.curve, "hex": self.hex}
+
+
+@dataclass(frozen=True)
+class RapSignatureValue:
+    """Wire shape of a signature value (serde camelCase)."""
+    curve: str
+    hex: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"curve": self.curve, "hex": self.hex}
+
+
+@dataclass(frozen=True)
+class RapHash:
+    """Wire shape of a hash (serde camelCase)."""
+    id: str
+    hex: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"id": self.id, "hex": self.hex}
+
+
+@dataclass(frozen=True)
+class RapRootManifest:
+    """Wire shape of the draft inputs root manifest (serde camelCase)."""
+    kind: str
+    rtm: str
+    source_name: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {"kind": self.kind, "rtm": self.rtm}
+        if self.source_name is not None:
+            result["sourceName"] = self.source_name
+        return result
+
+
+@dataclass(frozen=True)
+class RapNotary:
+    """Wire shape of the draft inputs notary (serde camelCase)."""
+    type: str
+    version: int
+    public_key: RapPublicKey
+    notary_is_signatory: Optional[bool] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "type": self.type,
+            "version": self.version,
+            "publicKey": self.public_key.to_dict(),
+        }
+        if self.notary_is_signatory is not None:
+            result["notaryIsSignatory"] = self.notary_is_signatory
+        return result
+
+
+@dataclass(frozen=True)
+class RapDraftInputs:
+    """Wire shape of ``DraftInputsState`` (serde camelCase)."""
+    state: str
+    network: str
+    root_manifest: RapRootManifest
+    notary: RapNotary
+    agent_public_key: str
+    requested_tariff: str
+    subintents: Optional[Any] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "state": self.state,
+            "network": self.network,
+            "rootManifest": self.root_manifest.to_dict(),
+            "notary": self.notary.to_dict(),
+            "agentPublicKey": self.agent_public_key,
+            "requestedTariff": self.requested_tariff,
+        }
+        if self.subintents is not None:
+            result["subintents"] = self.subintents
+        return result
+
+
+@dataclass(frozen=True)
+class RapEconomicParams:
+    """Wire shape of ``LedgerEconomicParams`` (serde snake_case)."""
+    fee_loan_amount: str
+    registry_component: str
+    lock_fee_payer_account: str
+    usdc_resource: str
+    xrd_gas_vault: str
+    merchant_account: str
+    start_epoch_inclusive: Optional[int] = None
+    end_epoch_exclusive: Optional[int] = None
+    intent_discriminator: Optional[int] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "fee_loan_amount": self.fee_loan_amount,
+            "registry_component": self.registry_component,
+            "lock_fee_payer_account": self.lock_fee_payer_account,
+            "usdc_resource": self.usdc_resource,
+            "xrd_gas_vault": self.xrd_gas_vault,
+            "merchant_account": self.merchant_account,
+        }
+        if self.start_epoch_inclusive is not None:
+            result["start_epoch_inclusive"] = self.start_epoch_inclusive
+        if self.end_epoch_exclusive is not None:
+            result["end_epoch_exclusive"] = self.end_epoch_exclusive
+        if self.intent_discriminator is not None:
+            result["intent_discriminator"] = self.intent_discriminator
+        return result
+
+
+@dataclass(frozen=True)
+class RapSignatureFile:
+    """Wire shape of ``LegacySignatureFile`` (serde camelCase)."""
+    type: str
+    version: int
+    scope: dict[str, Any]
+    signature: RapSignatureValue
+    hash: RapHash
+    public_key: RapPublicKey
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": self.type,
+            "version": self.version,
+            "scope": self.scope,
+            "signature": self.signature.to_dict(),
+            "hash": self.hash.to_dict(),
+            "publicKey": self.public_key.to_dict(),
+        }
+
+
+@dataclass(frozen=True)
+class RapPayload:
+    """The ``rap_payload`` object expected by ``handleModeBSponsored``."""
+    draft_inputs: RapDraftInputs
+    economic_params: RapEconomicParams
+    signatures: RapSignatureFile
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "draft_inputs": self.draft_inputs.to_dict(),
+            "economic_params": self.economic_params.to_dict(),
+            "signatures": self.signatures.to_dict(),
+        }
+
+
+# ── Fetch Extensions ───────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class AgentSyncFetchOptions:
+    """Extended request options for AgentSyncClient.fetch."""
+    method: str = "GET"
+    headers: Optional[dict[str, str]] = None
+    body: Optional[Any] = None
+    # Mode B (Single-Pay): the RAP payload object. The SDK serializes this as
+    # `{ payment: { rap_payload, requirements } }` in the request body.
+    rap_payload: Optional[RapPayload] = None
+    requirements: Optional[dict[str, Any]] = None

agentsync_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: agentsync-sdk
+Version: 1.0.0
+Summary: Python SDK for the AgentSync x402 micropayment gateway on Radix
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: PyNaCl>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
+
+# AgentSync Python SDK
+
+Python SDK for the AgentSync x402 micropayment gateway on Radix.
+
+## Install
+
+```bash
+pip install agentsync-sdk
+```
+
+> Note: the distribution name is `agentsync-sdk`; the import package remains
+> `agentsync` (`from agentsync import ...`). For local development use
+> `pip install -e .` in the repo.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Platform Attestation Verification
+
+Verify a platform-signed attestation envelope against the trusted platform
+Ed25519 public key:
+
+```python
+from agentsync import SignatureEnvelope, verify_platform_attestation
+
+trusted_public_key = "9afcc1cf66b256d7d9567a906fba4317305d92c3e7fd7f27386dffe182332576"
+envelope = SignatureEnvelope(
+    payload="account_tdx_2_...:5.500000:0",
+    signature="<128-char hex>",
+    public_key=trusted_public_key,
+    algorithm="ed25519+sha256",
+)
+
+valid = verify_platform_attestation(envelope, trusted_public_key)  # bool
+```
+
+`verify_platform_attestation()` is pure and synchronous: the trusted key is
+injected by the caller and never fetched from the network. It asserts that the
+envelope's `public_key` matches the trusted key before verifying the
+`Ed25519(SHA-256(payload))` signature.
+
+The TypeScript counterpart lives at [`../sdk-typescript`](../sdk-typescript).

agentsync_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+agentsync/__init__.py,sha256=0zQIqBWkq3Lm06SwVL5BtqlITPU4VkQgxuZFWSMmW0E,2368
+agentsync/attestation.py,sha256=CQu4gM_8eVH5bptBfLBE5zPRuoNXz7GxK9HfJtcU8Zk,2899
+agentsync/client.py,sha256=2tlEFvEOMJnaqGvW8nrMX4VhFcGp7YrTORsWyoKcAOg,20724
+agentsync/errors.py,sha256=UkTaAywvscWMDsEruX_bpCQQ3omRC5Q17TrAQNVJiRY,1550
+agentsync/rap.py,sha256=A15PsV7RiUYKgtpAaVoCRlUMtimvKTDiT4vVK74nTYI,6035
+agentsync/types.py,sha256=f3JfvkYrm69WlFmlAJkQpP7Bz1UhNTjb1z1xOGSBrGI,10582
+agentsync_sdk-1.0.0.dist-info/METADATA,sha256=xfIS2e3_zBD_QvEXPj-F66u88IqZR1bvTrgWXEkQC-Y,2117
+agentsync_sdk-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agentsync_sdk-1.0.0.dist-info/top_level.txt,sha256=8R5D9yLyyVwJIvwInvOWXj2hiEny0OnFg03eJFLvO14,10
+agentsync_sdk-1.0.0.dist-info/RECORD,,

agentsync_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentsync_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentsync