agent-intent-x402 0.2.0__py3-none-any.whl

agent_intent_x402/__init__.py

@@ -0,0 +1,57 @@
+"""agent-intent-x402 — pay-per-request access for AI agents over x402.
+
+Declare *what* you want, discover *who* provides it, and pay for the
+request on-chain with a single signature — no accounts, no API keys, no
+platform lock-in. Payment speaks the open `x402 <https://x402.org>`_
+protocol, so the same client works against any compliant gateway.
+
+    from agent_intent_x402 import AIPClient, IntentType, Wallet
+
+    # A wallet lets the client answer HTTP 402 challenges automatically.
+    wallet = Wallet(private_key="0x...")
+    with AIPClient(wallet=wallet) as client:
+        result = client.resolve(IntentType.CHAT_COMPLETION)
+        print(result.best_match.provider_id)
+"""
+
+from .client import DEFAULT_ENDPOINT, AIPClient
+from .errors import (
+    AIPAPIError,
+    AIPAuthError,
+    AIPConnectionError,
+    AIPError,
+    AIPPaymentRequiredError,
+)
+from .models import (
+    Constraints,
+    IntentType,
+    Match,
+    OptimizeFor,
+    Preferences,
+    Pricing,
+    Provider,
+    ResolveResult,
+)
+from .wallet import Wallet, WalletError
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AIPClient",
+    "DEFAULT_ENDPOINT",
+    "Wallet",
+    "WalletError",
+    "AIPError",
+    "AIPAPIError",
+    "AIPAuthError",
+    "AIPConnectionError",
+    "AIPPaymentRequiredError",
+    "IntentType",
+    "OptimizeFor",
+    "Constraints",
+    "Preferences",
+    "Pricing",
+    "Match",
+    "ResolveResult",
+    "Provider",
+]

agent_intent_x402/client.py

@@ -0,0 +1,348 @@
+"""Agent Intent client with built-in x402 payment.
+
+Declare an intent, discover a provider, and pay for the request on-chain
+over the open `x402 <https://x402.org>`_ protocol. When the client is
+given a :class:`~agent_intent_x402.wallet.Wallet`, any HTTP 402 challenge
+is answered automatically: the wallet signs the payment and the request
+is retried with a ``PAYMENT-SIGNATURE`` header — no accounts, no API keys.
+
+The client is vendor-neutral. ``endpoint`` defaults to a hosted gateway
+for convenience but can point at any compliant x402 service.
+
+Example::
+
+    from agent_intent_x402 import AIPClient, IntentType, OptimizeFor, Wallet
+
+    wallet = Wallet(private_key="0x...")
+    client = AIPClient(wallet=wallet)
+    result = client.resolve(
+        IntentType.CHAT_COMPLETION,
+        constraints={"max_price_usd": 0.01},
+        preferences={"optimize_for": OptimizeFor.COST},
+    )
+    print(result.best_match.provider_id, result.best_match.model)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional, Union
+
+import httpx
+
+from .errors import (
+    AIPAPIError,
+    AIPAuthError,
+    AIPConnectionError,
+    AIPPaymentRequiredError,
+)
+from .models import (
+    Constraints,
+    IntentType,
+    Preferences,
+    Provider,
+    ResolveResult,
+)
+from .wallet import Wallet
+
+DEFAULT_ENDPOINT = "https://api.jarvisclaw.ai"
+__version__ = "0.2.0"
+
+_ConstraintsArg = Union[Constraints, dict[str, Any], None]
+_PreferencesArg = Union[Preferences, dict[str, Any], None]
+
+
+def _coerce_constraints(value: _ConstraintsArg) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, Constraints):
+        return value.to_dict()
+    return dict(value)
+
+
+def _coerce_preferences(value: _PreferencesArg) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, Preferences):
+        return value.to_dict()
+    out = dict(value)
+    # normalize enum values so they serialize as plain strings
+    if "optimize_for" in out and out["optimize_for"] is not None:
+        out["optimize_for"] = str(out["optimize_for"])
+    return out
+
+
+class AIPClient:
+    """Synchronous client with built-in x402 payment.
+
+    Args:
+        api_key: Optional bearer token for gateways that still use API-key
+            auth. Falls back to the ``JARVISCLAW_API_KEY`` environment
+            variable. Not required when paying with a wallet.
+        wallet: A :class:`~agent_intent_x402.wallet.Wallet`. When set, HTTP
+            402 responses are answered automatically by signing the payment
+            and retrying with a ``PAYMENT-SIGNATURE`` header.
+        endpoint: Base URL of the gateway. Defaults to a hosted service;
+            override to target any compliant x402 deployment.
+        timeout: Request timeout in seconds.
+        http_client: Optional preconfigured ``httpx.Client`` (for custom
+            transports, proxies, or connection pooling).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        wallet: Optional[Wallet] = None,
+        endpoint: str = DEFAULT_ENDPOINT,
+        timeout: float = 30.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self.api_key = api_key or os.getenv("JARVISCLAW_API_KEY")
+        self.wallet = wallet
+        self.endpoint = endpoint.rstrip("/")
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+    # ── context manager ────────────────────────────────────────────────
+    def __enter__(self) -> "AIPClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client (only if this client owns it)."""
+        if self._owns_client:
+            self._http.close()
+
+    # ── internal request helper ────────────────────────────────────────
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": f"agent-intent-x402/{__version__}",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self.endpoint}{path}"
+        try:
+            resp = self._http.request(
+                method, url, json=json, params=params, headers=self._headers()
+            )
+        except httpx.RequestError as exc:
+            raise AIPConnectionError(f"request to {url} failed: {exc}") from exc
+
+        # x402: answer a payment challenge by signing it and retrying once.
+        if resp.status_code == 402 and self.wallet is not None:
+            resp = self._pay_and_retry(
+                resp, method, url, json=json, params=params
+            )
+
+        if resp.status_code >= 400:
+            self._raise_for_status(resp)
+
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except ValueError as exc:
+            raise AIPAPIError(
+                f"invalid JSON in response from {url}",
+                status_code=resp.status_code,
+                body=resp.text,
+            ) from exc
+
+    def _pay_and_retry(
+        self,
+        resp: httpx.Response,
+        method: str,
+        url: str,
+        *,
+        json: Optional[dict[str, Any]],
+        params: Optional[dict[str, Any]],
+    ) -> httpx.Response:
+        """Sign the 402 challenge and retry the request once.
+
+        Returns the retried response, or the original 402 response if the
+        challenge body could not be parsed (so normal error handling runs).
+        """
+        try:
+            challenge = resp.json()
+        except ValueError:
+            return resp
+
+        signature = self.wallet.sign_challenge(challenge)
+        headers = self._headers()
+        headers["PAYMENT-SIGNATURE"] = signature
+        try:
+            return self._http.request(
+                method, url, json=json, params=params, headers=headers
+            )
+        except httpx.RequestError as exc:
+            raise AIPConnectionError(f"request to {url} failed: {exc}") from exc
+
+    @staticmethod
+    def _raise_for_status(resp: httpx.Response) -> None:
+        detail: Optional[str] = None
+        body: Any = None
+        try:
+            body = resp.json()
+            if isinstance(body, dict):
+                detail = body.get("detail") or body.get("error") or body.get("message")
+        except ValueError:
+            body = resp.text
+            detail = resp.text or None
+
+        message = f"AIP server returned {resp.status_code}"
+        if detail:
+            message = f"{message}: {detail}"
+
+        code = resp.status_code
+        if code in (401, 403):
+            raise AIPAuthError(message, status_code=code, detail=detail, body=body)
+        if code == 402:
+            raise AIPPaymentRequiredError(
+                message, status_code=code, detail=detail, body=body
+            )
+        raise AIPAPIError(message, status_code=code, detail=detail, body=body)
+
+    # ── protocol methods ───────────────────────────────────────────────
+    def resolve(
+        self,
+        intent: Union[IntentType, str],
+        *,
+        constraints: _ConstraintsArg = None,
+        preferences: _PreferencesArg = None,
+    ) -> ResolveResult:
+        """Resolve an intent to ranked provider matches.
+
+        Args:
+            intent: The intent type, e.g. ``IntentType.CHAT_COMPLETION``.
+            constraints: Hard requirements a provider must satisfy. Accepts a
+                :class:`Constraints` instance or a plain dict, e.g.
+                ``{"max_price_usd": 0.01, "features": ["function_calling"]}``.
+            preferences: Soft ranking directives. Accepts a
+                :class:`Preferences` instance or a plain dict, e.g.
+                ``{"optimize_for": "cost", "limit": 5}``.
+
+        Returns:
+            A :class:`ResolveResult`. Use ``.best_match`` for the top provider
+            or ``.matches`` for the full ranked list.
+
+        Endpoint: ``POST /v1/intent/resolve`` (requires authentication).
+        """
+        body: dict[str, Any] = {"intent": str(intent)}
+        c = _coerce_constraints(constraints)
+        if c:
+            body["constraints"] = c
+        p = _coerce_preferences(preferences)
+        if p:
+            body["preferences"] = p
+        data = self._request("POST", "/v1/intent/resolve", json=body)
+        return ResolveResult.from_dict(data or {})
+
+    def resolve_natural(
+        self,
+        query: str,
+        *,
+        session_id: Optional[str] = None,
+        constraints: _ConstraintsArg = None,
+    ) -> dict[str, Any]:
+        """Resolve a natural-language query to providers or a clarification.
+
+        Unlike :meth:`resolve`, the gateway may respond with a follow-up
+        question instead of matches, so the raw response dict is returned.
+
+        Endpoint: ``POST /v1/intent/resolve/natural`` (requires authentication).
+        """
+        body: dict[str, Any] = {"query": query}
+        if session_id is not None:
+            body["session_id"] = session_id
+        c = _coerce_constraints(constraints)
+        if c:
+            body["constraints"] = c
+        return self._request("POST", "/v1/intent/resolve/natural", json=body) or {}
+
+    def discover(
+        self,
+        *,
+        intent_type: Union[IntentType, str, None] = None,
+    ) -> list[Provider]:
+        """Discover providers, optionally filtered by intent type.
+
+        Endpoint: ``GET /v1/intent/discover`` (no authentication required).
+        """
+        params: dict[str, Any] = {}
+        if intent_type is not None:
+            params["intent_type"] = str(intent_type)
+        data = self._request("GET", "/v1/intent/discover", params=params or None)
+        return _extract_providers(data)
+
+    def execute(
+        self,
+        intent: Union[IntentType, str],
+        payload: dict[str, Any],
+        *,
+        constraints: _ConstraintsArg = None,
+        preferences: _PreferencesArg = None,
+    ) -> Any:
+        """Resolve an intent and execute it against the selected provider.
+
+        Args:
+            intent: The intent type to execute.
+            payload: The provider-facing request body (e.g. chat messages).
+            constraints: Hard requirements for provider selection.
+            preferences: Soft ranking directives for provider selection.
+
+        Returns:
+            The raw provider response, proxied through the gateway.
+
+        Endpoint: ``POST /v1/intent/execute`` (requires authentication).
+        """
+        body: dict[str, Any] = {"intent": str(intent), "payload": payload}
+        c = _coerce_constraints(constraints)
+        if c:
+            body["constraints"] = c
+        p = _coerce_preferences(preferences)
+        if p:
+            body["preferences"] = p
+        return self._request("POST", "/v1/intent/execute", json=body)
+
+    def list_intent_types(self) -> list[str]:
+        """List the intent types the gateway supports.
+
+        Endpoint: ``GET /v1/intent/types`` (no authentication required).
+        """
+        data = self._request("GET", "/v1/intent/types")
+        if isinstance(data, dict):
+            return data.get("intent_types", [])
+        return data or []
+
+    def list_providers(self) -> list[Provider]:
+        """List all registered providers.
+
+        Endpoint: ``GET /v1/providers`` (no authentication required).
+        """
+        data = self._request("GET", "/v1/providers")
+        return _extract_providers(data)
+
+
+def _extract_providers(data: Any) -> list[Provider]:
+    """Normalize the various provider list shapes into ``list[Provider]``."""
+    if data is None:
+        return []
+    if isinstance(data, dict):
+        items = data.get("providers", data.get("matches", []))
+    else:
+        items = data
+    return [Provider.from_dict(item) for item in items if isinstance(item, dict)]

agent_intent_x402/errors.py

@@ -0,0 +1,44 @@
+"""Exceptions raised by the Agent Intent Protocol client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class AIPError(Exception):
+    """Base class for all AIP client errors."""
+
+
+class AIPConnectionError(AIPError):
+    """Raised when the request never reached the server (network/timeout)."""
+
+
+class AIPAPIError(AIPError):
+    """Raised when the server returns a non-2xx response.
+
+    Attributes:
+        status_code: HTTP status code returned by the server.
+        detail: Server-provided error detail, when available.
+        body: Raw parsed response body, when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        detail: Optional[str] = None,
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+        self.body = body
+
+
+class AIPAuthError(AIPAPIError):
+    """Raised on 401/403 — missing or invalid API key."""
+
+
+class AIPPaymentRequiredError(AIPAPIError):
+    """Raised on 402 — x402 payment required to complete the request."""

agent_intent_x402/models.py

@@ -0,0 +1,201 @@
+"""Data models for the Agent Intent Protocol.
+
+All models mirror the wire format served by the AIP gateway
+(default platform: https://api.jarvisclaw.ai). Field names match the
+JSON contract exactly so responses deserialize without translation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class IntentType(str, Enum):
+    """Intent types supported by the protocol.
+
+    An intent describes *what* an agent wants to accomplish, decoupled
+    from *which* provider or model fulfils it.
+    """
+
+    CHAT_COMPLETION = "chat_completion"
+    IMAGE_GENERATION = "image_generation"
+    VIDEO_GENERATION = "video_generation"
+    TEXT_TO_SPEECH = "text_to_speech"
+    WEB_SEARCH = "web_search"
+    KNOWLEDGE_SEARCH = "knowledge_search"
+    PROMPT_OPTIMIZATION = "prompt_optimization"
+    DOCUMENT_PROCESSING = "document_processing"
+    UTILITY = "utility"
+    CODE_EXECUTION = "code_execution"
+    DATA_ANALYSIS = "data_analysis"
+    TRANSLATION = "translation"
+    CODE_GENERATION = "code_generation"
+
+    def __str__(self) -> str:  # allow seamless use as a plain string
+        return self.value
+
+
+class OptimizeFor(str, Enum):
+    """Soft optimization strategy used when ranking matched providers."""
+
+    COST = "cost"
+    QUALITY = "quality"
+    LATENCY = "latency"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass
+class Constraints:
+    """Hard requirements a provider MUST satisfy to be considered a match.
+
+    Any field left as ``None`` (or an empty list) is omitted from the
+    request and imposes no constraint.
+    """
+
+    max_price_usd: Optional[float] = None
+    max_latency_ms: Optional[int] = None
+    features: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        if self.max_price_usd is not None:
+            out["max_price_usd"] = self.max_price_usd
+        if self.max_latency_ms is not None:
+            out["max_latency_ms"] = self.max_latency_ms
+        if self.features:
+            out["features"] = list(self.features)
+        return out
+
+
+@dataclass
+class Preferences:
+    """Soft directives that steer ranking without excluding providers."""
+
+    optimize_for: Optional[OptimizeFor | str] = None
+    limit: Optional[int] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        if self.optimize_for is not None:
+            out["optimize_for"] = str(self.optimize_for)
+        if self.limit is not None:
+            out["limit"] = self.limit
+        return out
+
+
+@dataclass
+class Pricing:
+    """Price breakdown for a provider offering."""
+
+    input_per_million: Optional[float] = None
+    output_per_million: Optional[float] = None
+    per_call: Optional[float] = None
+
+    @classmethod
+    def from_dict(cls, data: Optional[dict[str, Any]]) -> Optional["Pricing"]:
+        if not data:
+            return None
+        return cls(
+            input_per_million=data.get("input_per_million"),
+            output_per_million=data.get("output_per_million"),
+            per_call=data.get("per_call"),
+        )
+
+
+@dataclass
+class Match:
+    """A single provider matched to an intent, with score and pricing.
+
+    Unknown fields returned by the server are preserved in ``raw`` so the
+    SDK never silently drops data as the protocol evolves.
+    """
+
+    provider_id: str
+    score: float = 0.0
+    estimated_price_usd: Optional[float] = None
+    pricing: Optional[Pricing] = None
+    endpoint: Optional[str] = None
+    model: Optional[str] = None
+    reason: Optional[str] = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Match":
+        return cls(
+            provider_id=data.get("provider_id", ""),
+            score=data.get("score", 0.0),
+            estimated_price_usd=data.get("estimated_price_usd"),
+            pricing=Pricing.from_dict(data.get("pricing")),
+            endpoint=data.get("endpoint"),
+            model=data.get("model"),
+            reason=data.get("reason"),
+            raw=data,
+        )
+
+
+@dataclass
+class ResolveResult:
+    """Result of resolving an intent to ranked provider matches.
+
+    Mirrors the gateway response ``{matches, intent_type, total_available}``.
+    """
+
+    matches: list[Match] = field(default_factory=list)
+    intent_type: Optional[str] = None
+    total_available: Optional[int] = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def best_match(self) -> Optional[Match]:
+        """The top-ranked match, or ``None`` when nothing matched.
+
+        The gateway returns matches pre-sorted by score, so this is simply
+        the first element — exposed as a property for ergonomic access.
+        """
+        return self.matches[0] if self.matches else None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ResolveResult":
+        return cls(
+            matches=[Match.from_dict(m) for m in data.get("matches", [])],
+            intent_type=data.get("intent_type"),
+            total_available=data.get("total_available"),
+            raw=data,
+        )
+
+
+@dataclass
+class Provider:
+    """A provider entry from the discovery / listing endpoints."""
+
+    id: str
+    name: Optional[str] = None
+    intent_types: list[str] = field(default_factory=list)
+    pricing: Optional[Pricing] = None
+    features: list[str] = field(default_factory=list)
+    endpoint: Optional[str] = None
+    source: Optional[str] = None
+    resource_id: Optional[str] = None
+    server_id: Optional[str] = None
+    description: Optional[str] = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Provider":
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name"),
+            intent_types=data.get("intent_types", []),
+            pricing=Pricing.from_dict(data.get("pricing")),
+            features=data.get("features", []),
+            endpoint=data.get("endpoint"),
+            source=data.get("source"),
+            resource_id=data.get("resource_id"),
+            server_id=data.get("server_id"),
+            description=data.get("description"),
+            raw=data,
+        )

agent_intent_x402/wallet.py

@@ -0,0 +1,218 @@
+"""x402 wallet — sign HTTP 402 payment challenges with an EVM private key.
+
+This is the core of ``agent-intent-x402``: it lets an agent pay for a
+request over the open `x402 <https://x402.org>`_ protocol without any
+platform-specific glue. Given a 402 challenge, the wallet builds and
+signs an EIP-712 ``TransferWithAuthorization`` (EIP-3009) message and
+returns the ``PAYMENT-SIGNATURE`` header value the server expects.
+
+The signing is vendor-neutral: it targets the standard USDC
+``TransferWithAuthorization`` typed-data used across the x402 ecosystem,
+so the same wallet works against any compliant x402 gateway, not just one
+platform.
+
+    from agent_intent_x402 import Wallet
+
+    wallet = Wallet(private_key="0x...")
+    header = wallet.sign_challenge(challenge)  # PAYMENT-SIGNATURE value
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import secrets
+import time
+from typing import Any
+
+# Default asset: USDC on Base (eip155:8453). Used only when a 402 challenge
+# omits the asset address. The EIP-712 domain name/version below match the
+# canonical USDC TransferWithAuthorization contract.
+DEFAULT_NETWORK = "eip155:8453"
+DEFAULT_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+USDC_DOMAIN_NAME = "USD Coin"
+USDC_DOMAIN_VERSION = "2"
+
+# The x402 protocol version this wallet speaks.
+X402_VERSION = 2
+
+
+class WalletError(Exception):
+    """Raised when a 402 challenge cannot be parsed or signed."""
+
+
+def _import_eth_account() -> Any:
+    try:
+        from eth_account import Account  # noqa: WPS433 (local import by design)
+    except ImportError as exc:  # pragma: no cover - exercised via message only
+        raise WalletError(
+            "x402 payment requires the 'eth-account' package. "
+            "Install it with: pip install 'agent-intent-x402[wallet]'"
+        ) from exc
+    return Account
+
+
+class Wallet:
+    """An EVM wallet that signs x402 payment challenges.
+
+    Args:
+        private_key: Hex private key (with or without the ``0x`` prefix).
+
+    The wallet never sends funds itself. It produces a signed
+    authorization that the gateway settles on-chain, so a single signature
+    authorizes exactly the amount named in the challenge and nothing more.
+    """
+
+    def __init__(self, private_key: str) -> None:
+        account_cls = _import_eth_account()
+        key = private_key if private_key.startswith("0x") else f"0x{private_key}"
+        self._account = account_cls.from_key(key)
+        self.address: str = self._account.address
+
+    # ── public API ─────────────────────────────────────────────────────
+    def sign_challenge(self, challenge: Any) -> str:
+        """Sign a 402 challenge and return the ``PAYMENT-SIGNATURE`` value.
+
+        Args:
+            challenge: The parsed JSON body of the 402 response. The first
+                entry of ``accepts`` is used as the payment terms.
+
+        Returns:
+            A base64-encoded x402 v2 payload suitable for the
+            ``PAYMENT-SIGNATURE`` request header.
+        """
+        terms = self._select_terms(challenge)
+        return self._sign_terms(terms)
+
+    # ── internals ──────────────────────────────────────────────────────
+    @staticmethod
+    def _select_terms(challenge: Any) -> dict[str, Any]:
+        if not isinstance(challenge, dict):
+            raise WalletError("402 challenge body is not a JSON object")
+        accepts = challenge.get("accepts")
+        if not isinstance(accepts, list) or not accepts:
+            raise WalletError("402 challenge has no 'accepts' payment terms")
+        terms = accepts[0]
+        if not isinstance(terms, dict):
+            raise WalletError("402 payment terms are malformed")
+        if not terms.get("payTo"):
+            raise WalletError("402 payment terms missing 'payTo'")
+        if terms.get("amount") in (None, ""):
+            raise WalletError("402 payment terms missing 'amount'")
+        return terms
+
+    def _sign_terms(self, terms: dict[str, Any]) -> str:
+        network = terms.get("network") or DEFAULT_NETWORK
+        asset = terms.get("asset") or DEFAULT_USDC
+        pay_to = terms["payTo"]
+        amount = str(terms["amount"])
+        max_timeout = int(terms.get("maxTimeoutSeconds", 60))
+        extra = terms.get("extra")
+
+        chain_id = _chain_id_from_network(network)
+        now = int(time.time())
+        valid_after = 0
+        valid_before = now + max_timeout
+        nonce = "0x" + secrets.token_hex(32)
+
+        signature = self._sign_transfer_authorization(
+            chain_id=chain_id,
+            verifying_contract=asset,
+            from_addr=self.address,
+            to_addr=pay_to,
+            value=amount,
+            valid_after=valid_after,
+            valid_before=valid_before,
+            nonce_hex=nonce,
+        )
+
+        payload = {
+            "x402Version": X402_VERSION,
+            "accepted": {
+                "scheme": terms.get("scheme", "exact"),
+                "network": network,
+                "amount": amount,
+                "asset": asset,
+                "payTo": pay_to,
+                "maxTimeoutSeconds": max_timeout,
+                "extra": extra if extra is not None else {},
+            },
+            "payload": {
+                "signature": signature,
+                "authorization": {
+                    "from": self.address,
+                    "to": pay_to,
+                    "value": amount,
+                    "validAfter": str(valid_after),
+                    "validBefore": str(valid_before),
+                    "nonce": nonce,
+                },
+            },
+            "extensions": {},
+        }
+        payload_json = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        return base64.b64encode(payload_json).decode("ascii")
+
+    def _sign_transfer_authorization(
+        self,
+        *,
+        chain_id: int,
+        verifying_contract: str,
+        from_addr: str,
+        to_addr: str,
+        value: str,
+        valid_after: int,
+        valid_before: int,
+        nonce_hex: str,
+    ) -> str:
+        account_cls = _import_eth_account()
+        from eth_account.messages import encode_typed_data
+
+        full_message = {
+            "types": {
+                "EIP712Domain": [
+                    {"name": "name", "type": "string"},
+                    {"name": "version", "type": "string"},
+                    {"name": "chainId", "type": "uint256"},
+                    {"name": "verifyingContract", "type": "address"},
+                ],
+                "TransferWithAuthorization": [
+                    {"name": "from", "type": "address"},
+                    {"name": "to", "type": "address"},
+                    {"name": "value", "type": "uint256"},
+                    {"name": "validAfter", "type": "uint256"},
+                    {"name": "validBefore", "type": "uint256"},
+                    {"name": "nonce", "type": "bytes32"},
+                ],
+            },
+            "primaryType": "TransferWithAuthorization",
+            "domain": {
+                "name": USDC_DOMAIN_NAME,
+                "version": USDC_DOMAIN_VERSION,
+                "chainId": chain_id,
+                "verifyingContract": verifying_contract,
+            },
+            "message": {
+                "from": from_addr,
+                "to": to_addr,
+                "value": int(value),
+                "validAfter": valid_after,
+                "validBefore": valid_before,
+                "nonce": bytes.fromhex(nonce_hex[2:]),
+            },
+        }
+        signable = encode_typed_data(full_message=full_message)
+        signed = account_cls.sign_message(signable, private_key=self._account.key)
+        # eth-account already yields v in {27, 28}; do not add 27 again.
+        return "0x" + signed.signature.hex()
+
+
+def _chain_id_from_network(network: str) -> int:
+    """Extract the numeric chain id from an ``eip155:<id>`` network string."""
+    if network.startswith("eip155:"):
+        tail = network.split(":", 1)[1]
+        try:
+            return int(tail)
+        except ValueError:
+            pass
+    return 8453  # default to Base

agent_intent_x402-0.2.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: agent-intent-x402
+Version: 0.2.0
+Summary: Pay-per-request access to any service for AI agents, over the open x402 protocol. Declare an intent, discover a provider, and settle on-chain with a single signature.
+Project-URL: Homepage, https://github.com/api-jarvisclaw/agent-intent-x402
+Project-URL: Documentation, https://github.com/api-jarvisclaw/agent-intent-x402#readme
+Project-URL: Repository, https://github.com/api-jarvisclaw/agent-intent-x402
+Project-URL: Issues, https://github.com/api-jarvisclaw/agent-intent-x402/issues
+Project-URL: Protocol, https://github.com/api-jarvisclaw/agent-intent-protocol
+Project-URL: x402, https://x402.org
+Author-email: JarvisClaw <dev@jarvisclaw.ai>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,eip-3009,http-402,intent,llm,payments,usdc,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.11.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-intent-x402
+
+Pay-per-request access to any service, for AI agents — over the open
+[x402](https://x402.org) protocol.
+
+Declare *what* you want, discover *who* provides it, and pay for the
+request on-chain with a single signature. No accounts, no API keys, no
+platform lock-in. Your agent carries a wallet; the service quotes a
+price with HTTP `402 Payment Required`; the client signs and settles.
+Because payment speaks the open x402 standard, the same client works
+against any compliant gateway.
+
+```bash
+pip install agent-intent-x402
+```
+
+## Quick start
+
+Give the client a wallet and it settles `402` challenges automatically —
+sign the payment, retry the request, return the result.
+
+```python
+from agent_intent_x402 import AIPClient, Wallet, IntentType
+
+wallet = Wallet(private_key="0x...")   # your agent's EVM key
+
+with AIPClient(wallet=wallet, endpoint="https://api.example.com") as client:
+    # Resolve an intent to the best-ranked provider. If the gateway
+    # answers 402, the wallet pays and the call transparently retries.
+    result = client.resolve(
+        IntentType.CHAT_COMPLETION,
+        constraints={"max_price_usd": 0.01},
+        preferences={"optimize_for": "cost"},
+    )
+    best = result.best_match
+    print(f"{best.provider_id} · {best.model} · score={best.score}")
+```
+
+The private key can also be supplied via the `AIP_WALLET_KEY`
+environment variable, in which case `Wallet()` needs no arguments.
+
+## How payment works
+
+x402 turns HTTP `402 Payment Required` into a usable payment step:
+
+1. The client makes a normal request.
+2. If payment is due, the gateway replies `402` with the accepted terms
+   (amount, asset, recipient, network) in the body.
+3. The wallet signs an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009)
+   `TransferWithAuthorization` for those exact terms — an EIP-712 typed
+   signature, no gas, no on-chain transaction from your side.
+4. The client retries with a `PAYMENT-SIGNATURE` header. The gateway
+   verifies and settles on-chain, then serves the response.
+
+Payments default to USDC on Base (`eip155:8453`); the network and asset
+come from the gateway's `402` terms, so the wallet always signs exactly
+what it is asked to pay.
+
+## Resolve, then execute
+
+`resolve` returns ranked matches so you can inspect price and score
+before committing. `execute` resolves *and* runs the intent in one call,
+proxying the provider response back:
+
+```python
+response = client.execute(
+    IntentType.CHAT_COMPLETION,
+    payload={"messages": [{"role": "user", "content": "Hello"}]},
+    preferences={"optimize_for": "quality"},
+)
+```
+
+## Natural-language intents
+
+Let the gateway interpret a free-form request. It may resolve directly
+or reply with a clarifying question for a multi-turn exchange:
+
+```python
+reply = client.resolve_natural("I need to transcribe an audio file cheaply")
+if reply.get("status") == "clarify":
+    print(reply["message"])   # follow-up question
+else:
+    print(reply["matches"])   # resolved providers
+```
+
+## Discovery
+
+```python
+# Every intent type the gateway understands.
+client.list_intent_types()
+
+# Providers available for a given intent.
+client.discover(intent_type=IntentType.IMAGE_GENERATION)
+
+# The full provider catalogue.
+client.list_providers()
+```
+
+## Intent types
+
+`chat_completion`, `image_generation`, `video_generation`,
+`text_to_speech`, `web_search`, `knowledge_search`,
+`prompt_optimization`, `document_processing`, `utility`,
+`code_execution`, `data_analysis`, `translation`, `code_generation`.
+
+## Errors
+
+All exceptions derive from `AIPError`:
+
+- `AIPConnectionError` — the request never reached the gateway.
+- `AIPAuthError` — `401`/`403`, missing or invalid credentials.
+- `AIPPaymentRequiredError` — `402`, payment required and no wallet was
+  configured (or the payment was rejected).
+- `AIPAPIError` — any other non-2xx response (`status_code`, `detail`, `body`).
+
+`WalletError` is raised when a `402` challenge cannot be signed (missing
+key, malformed terms).
+
+## Protocol
+
+The intent wire format and endpoint contract are defined in the
+[Agent Intent Protocol specification](https://github.com/api-jarvisclaw/agent-intent-protocol).
+The payment layer follows the open [x402](https://x402.org) protocol.
+
+## License
+
+MIT

agent_intent_x402-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agent_intent_x402/__init__.py,sha256=0p4eNMcxiJm_XsbjM_Or7XAVp1cn4SnvQqysPvRIYKE,1413
+agent_intent_x402/client.py,sha256=Pg0YmXpEEV58jkrNMrIgIuZz1Bx1C5xIIgKxTPq3bXE,12326
+agent_intent_x402/errors.py,sha256=UaENemhpsjNBwEKCmWdRbnRWEFfEvymk1Us7Wr49eCY,1142
+agent_intent_x402/models.py,sha256=4frbg8HCLBuLIQolYibLu0C94SG42wqNUswxRh6DRP4,6290
+agent_intent_x402/wallet.py,sha256=wRDHXyIntmidJfTUpgs9Fzz7gPrT6PnbEW3pCruc3-s,8286
+agent_intent_x402-0.2.0.dist-info/METADATA,sha256=7AmWTwaNxURxR4gaLm1lT6QJuVhP1JpaZEHogiRtz3s,5811
+agent_intent_x402-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agent_intent_x402-0.2.0.dist-info/licenses/LICENSE,sha256=9GbKF5fGyJEKXfs105z_AatKU7Rvox0xpwxppmuJGuM,1067
+agent_intent_x402-0.2.0.dist-info/RECORD,,

agent_intent_x402-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_intent_x402-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JarvisClaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.