oryne 0.1.0__py3-none-any.whl

oryne/__init__.py

@@ -0,0 +1,55 @@
+"""Oryne: give an AI agent a wallet it can spend from, with limits it cannot break.
+
+>>> from oryne import OryneAgent, PaymentRefusedError
+>>> agent = OryneAgent(secret=os.environ["ORYNE_AGENT_SECRET"])
+>>> response = agent.fetch("https://api.example.com/search?q=stellar")
+"""
+
+from .agent import (
+    DEFAULT_API_URL,
+    Approval,
+    OryneAgent,
+    OryneAPIError,
+    PaymentEvent,
+    PaymentRefusedError,
+    RefusalSource,
+)
+from .guard import BeforePay, PayeeRule, PaymentCheck, parse_payee_rule, payee_refusal
+from .payment import (
+    PAYMENT_HEADER,
+    PAYMENT_RESPONSE_HEADER,
+    PaymentRequirements,
+    SettleResponse,
+    StellarError,
+    agent_signature_scval,
+    contract_error_name,
+    sign_payment,
+)
+from .units import from_base_units, to_base_units
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_API_URL",
+    "PAYMENT_HEADER",
+    "PAYMENT_RESPONSE_HEADER",
+    "Approval",
+    "BeforePay",
+    "OryneAPIError",
+    "OryneAgent",
+    "PayeeRule",
+    "PaymentCheck",
+    "PaymentEvent",
+    "PaymentRefusedError",
+    "PaymentRequirements",
+    "RefusalSource",
+    "SettleResponse",
+    "StellarError",
+    "agent_signature_scval",
+    "contract_error_name",
+    "from_base_units",
+    "parse_payee_rule",
+    "payee_refusal",
+    "sign_payment",
+    "to_base_units",
+]

oryne/agent.py

@@ -0,0 +1,299 @@
+"""An agent's connection to Oryne.
+
+Give it the agent's secret key (S…, shown once when the owner connects the
+agent) and use ``agent.fetch()`` wherever you'd make an HTTP request: when a
+service answers 402 Payment Required, it pays from the agent's wallet, inside
+its mandate, and retries.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Literal, TypedDict
+from urllib.parse import urljoin
+
+import httpx
+from stellar_sdk import Keypair, SorobanServer
+
+from .guard import BeforePay, PayeeRule, PaymentCheck, hook_refusal, payee_refusal
+from .payment import (
+    PAYMENT_HEADER,
+    PAYMENT_RESPONSE_HEADER,
+    PaymentRequirements,
+    SettleResponse,
+    decode_header,
+    encode_header,
+    sign_payment,
+)
+from .units import from_base_units, to_base_units
+
+#: The hosted Oryne API, on Stellar testnet.
+DEFAULT_API_URL = "https://oryne.onrender.com"
+
+#: How long directory lookups are reused, in seconds.
+DIRECTORY_TTL = 5 * 60
+
+#: Who refused: ``"wallet"`` is the contract (or the service failing to settle),
+#: after the agent signed; ``"client"`` is this SDK, before anything was signed.
+RefusalSource = Literal["wallet", "client"]
+
+
+class PaymentRefusedError(Exception):
+    """A payment wasn't made. ``reason`` says why, ``source`` says who refused."""
+
+    def __init__(self, reason: str, requirements: PaymentRequirements, source: RefusalSource = "wallet") -> None:
+        self.reason = reason
+        self.requirements = requirements
+        self.source = source
+        prefix = "Payment refused by the wallet" if source == "wallet" else "Payment refused before signing"
+        super().__init__(f"{prefix}: {reason}")
+
+
+class OryneAPIError(Exception):
+    """The Oryne API answered with an error."""
+
+    def __init__(self, message: str, status: int) -> None:
+        self.status = status
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class PaymentEvent:
+    """Passed to ``on_payment``: ``paying``, then ``paid`` or ``refused``."""
+
+    type: Literal["paying", "paid", "refused"]
+    #: In token units, e.g. "0.05".
+    amount: str
+    requirements: PaymentRequirements
+    settlement: SettleResponse | None = None
+    reason: str | None = None
+    source: RefusalSource | None = None
+
+
+class Approval(TypedDict):
+    id: str
+    status: Literal["pending", "approved", "declined", "expired", "used"]
+    amount: str
+    payee: str
+    description: str
+
+
+class OryneAgent:
+    """An Oryne agent: an HTTP client that pays 402 Payment Required from the agent's wallet.
+
+    >>> agent = OryneAgent(secret=os.environ["ORYNE_AGENT_SECRET"])
+    >>> response = agent.fetch("https://api.example.com/search?q=stellar", max_price="0.10")
+
+    :param secret: The agent's secret key (``S…``).
+    :param api_url: Oryne API. Defaults to ``ORYNE_API_URL``, then the hosted testnet API.
+    :param max_per_request: Most this client pays for one request, whatever a service asks, e.g. ``"1"``.
+    :param payees: Who it may pay: ``"any"`` (default), ``"directory"`` (only services in the
+        Oryne directory, at the address listed for that host) or a list of Stellar addresses.
+        Checked before signing; the wallet's on-chain mandate still applies on top.
+    :param before_pay: Last say before signing. Return ``True`` to pay, or ``False`` or a reason to refuse.
+    :param on_payment: Called with a :class:`PaymentEvent` as a payment progresses.
+    :param http: An ``httpx.Client`` to use, e.g. with your own timeouts or proxies.
+    """
+
+    def __init__(
+        self,
+        secret: str,
+        *,
+        api_url: str | None = None,
+        max_per_request: str | None = None,
+        payees: PayeeRule = "any",
+        before_pay: BeforePay | None = None,
+        on_payment: Callable[[PaymentEvent], None] | None = None,
+        http: httpx.Client | None = None,
+    ) -> None:
+        self.keypair = Keypair.from_secret(secret)
+        self.api_url = (api_url or os.environ.get("ORYNE_API_URL") or DEFAULT_API_URL).rstrip("/")
+        self.max_per_request = to_base_units(max_per_request) if max_per_request is not None else None
+        self.payees = payees
+        self.before_pay = before_pay
+        self.on_payment = on_payment
+        self._http = http or httpx.Client(follow_redirects=True, timeout=60)
+        self._info: dict[str, Any] | None = None
+        self._listings: dict[str, tuple[float, list[dict]]] = {}
+
+    @property
+    def public_key(self) -> str:
+        return self.keypair.public_key
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> OryneAgent:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------ Oryne API
+
+    def api(self, path: str, *, method: str = "GET", body: Any = None) -> Any:
+        """Calls the Oryne API as this agent; each request is signed with the agent key."""
+        url = f"{self.api_url}/v1/agent{path}"
+        pathname = httpx.URL(url).path
+        timestamp = int(time.time())
+        message = f"oryne-agent\n{method.upper()}\n{pathname}\n{timestamp}".encode()
+        signature = base64.b64encode(self.keypair.sign(message)).decode()
+        response = self._http.request(
+            method,
+            url,
+            headers={"x-oryne-agent": f"{self.public_key}.{timestamp}.{signature}"},
+            json=body,
+        )
+        try:
+            data = response.json()
+        except ValueError:
+            data = {}
+        if response.is_error:
+            error = data.get("error") if isinstance(data, dict) else None
+            raise OryneAPIError(error or f"Oryne API {response.status_code}", response.status_code)
+        return data
+
+    def me(self, refresh: bool = False) -> dict[str, Any]:
+        """The agent, its wallet, its limits and what it has left. Cached after the first call."""
+        if self._info is None or refresh:
+            self._info = self.api("")
+        return self._info
+
+    def directory(self, origin: str) -> list[dict]:
+        """The Oryne directory's listings for an origin. Cached for a few minutes; failures aren't cached."""
+        cached = self._listings.get(origin)
+        if cached and time.monotonic() - cached[0] < DIRECTORY_TTL:
+            return cached[1]
+        host = origin.split("://", 1)[1]
+        response = self._http.get(f"{self.api_url}/v1/services", params={"host": host})
+        if response.is_error:
+            raise OryneAPIError(f"directory answered {response.status_code}", response.status_code)
+        listings = response.json().get("services") or []
+        self._listings[origin] = (time.monotonic(), listings)
+        return listings
+
+    # ------------------------------------------------------------ paying
+
+    def fetch(self, url: str, method: str = "GET", *, max_price: str | None = None, **kwargs: Any) -> httpx.Response:
+        """Makes an HTTP request, paying a 402 Payment Required from the agent's wallet.
+
+        Takes the same keyword arguments as ``httpx.Client.request`` (``params``,
+        ``json``, ``headers``, ``content``…), plus ``max_price``: refuse to pay more
+        than this for this request, in token units, e.g. ``"0.10"``.
+
+        Raises :class:`PaymentRefusedError` when the payment isn't made.
+        """
+        first = self._http.request(method, url, **kwargs)
+        if first.status_code != 402:
+            return first
+
+        try:
+            challenge = first.json()
+        except ValueError:
+            return first
+        info = self.me()
+        requirements: PaymentRequirements | None = next(
+            (
+                option
+                for option in (challenge or {}).get("accepts") or []
+                if option.get("scheme") == "exact"
+                and option.get("network") == info["network"]
+                and option.get("asset") == info["token"]
+            ),
+            None,
+        )
+        if requirements is None:
+            return first
+
+        amount = int(requirements["maxAmountRequired"])
+        display = from_base_units(amount)
+        refusal = self._refusal(str(first.url), requirements, amount, display, max_price)
+        if refusal:
+            self._emit(PaymentEvent("refused", display, requirements, reason=refusal, source="client"))
+            raise PaymentRefusedError(refusal, requirements, "client")
+
+        self._emit(PaymentEvent("paying", display, requirements))
+        payload = sign_payment(
+            rpc_server=SorobanServer(info["rpcUrl"]),
+            network_passphrase=info["networkPassphrase"],
+            agent=self.keypair,
+            wallet=info["agent"]["wallet"],
+            requirements=requirements,
+            simulation_source=info["simulationSource"],
+        )
+
+        headers = dict(kwargs.pop("headers", None) or {})
+        headers[PAYMENT_HEADER] = encode_header(payload)
+        paid = self._http.request(method, url, headers=headers, **kwargs)
+
+        receipt = paid.headers.get(PAYMENT_RESPONSE_HEADER)
+        settlement: SettleResponse | None = decode_header(receipt) if receipt else None
+        if paid.status_code == 402:
+            try:
+                body = paid.json()
+            except ValueError:
+                body = {}
+            reason = (settlement or {}).get("errorReason") or (body or {}).get("error") or "Payment was not accepted"
+            self._emit(PaymentEvent("refused", display, requirements, settlement, reason, "wallet"))
+            raise PaymentRefusedError(reason, requirements, "wallet")
+        if settlement:
+            self._emit(PaymentEvent("paid", display, requirements, settlement))
+        return paid
+
+    def _refusal(
+        self,
+        url: str,
+        requirements: PaymentRequirements,
+        amount: int,
+        display: str,
+        max_price: str | None,
+    ) -> str | None:
+        """Why this agent shouldn't sign the payment, or ``None`` if it may."""
+        if amount <= 0:
+            return f"Asks a payment of {display}"
+        if self.max_per_request is not None and amount > self.max_per_request:
+            return f"Asks {display}, above this client's max_per_request of {from_base_units(self.max_per_request)}"
+        if max_price is not None and amount > to_base_units(max_price):
+            return f"Asks {display}, above the {max_price} expected for this request"
+        payee = payee_refusal(self.payees, url, requirements["payTo"], self.directory)
+        if payee:
+            return payee
+        return hook_refusal(self.before_pay, PaymentCheck(url, requirements, display))
+
+    def _emit(self, event: PaymentEvent) -> None:
+        if self.on_payment:
+            self.on_payment(event)
+
+    # ------------------------------------------------------------ approvals
+
+    def request_approval(
+        self,
+        *,
+        pay_to: str,
+        amount: str,
+        description: str,
+        resource: str | None = None,
+        reason: str | None = None,
+    ) -> Approval:
+        """Asks the owner to approve a payment the mandate refused. Returns the pending approval."""
+        body = {"payTo": pay_to, "amount": amount, "description": description}
+        if resource:
+            body["resource"] = resource
+        if reason:
+            body["reason"] = reason
+        return self.api("/approvals", method="POST", body=body)
+
+    def approval(self, approval_id: str) -> Approval:
+        return self.api(f"/approvals/{approval_id}")
+
+    def wait_for_approval(self, approval_id: str, *, timeout: float = 600, interval: float = 3) -> Approval:
+        """Polls until the owner decides, or ``timeout`` seconds pass."""
+        deadline = time.monotonic() + timeout
+        while True:
+            approval = self.approval(approval_id)
+            if approval["status"] != "pending" or time.monotonic() > deadline:
+                return approval
+            time.sleep(interval)

oryne/guard.py

@@ -0,0 +1,114 @@
+"""Checks the agent makes before it signs a payment.
+
+The wallet contract is the hard limit: it refuses anything outside the
+mandate, whatever the agent signs. These checks sit in front of it and decide
+whether the agent should agree to a 402 at all, for example because the
+service asks to be paid at an address that isn't the one it's listed with.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Literal, Union
+from urllib.parse import urlsplit
+
+from .payment import PaymentRequirements
+
+#: Who the agent may pay:
+#:
+#: - ``"any"``: whoever the service names (the wallet's on-chain payee list still applies);
+#: - ``"directory"``: only services listed in the Oryne directory, and only at
+#:   the address their listing gives for that host;
+#: - a list of Stellar addresses: only those.
+PayeeRule = Union[Literal["any", "directory"], "list[str]"]
+
+
+@dataclass(frozen=True)
+class PaymentCheck:
+    """A payment the agent is about to sign."""
+
+    #: The URL that answered 402, after any redirects.
+    url: str
+    requirements: PaymentRequirements
+    #: The amount in token units, e.g. "0.05".
+    amount: str
+
+
+#: Return ``True`` to pay, or ``False`` or a reason to refuse.
+BeforePay = Callable[[PaymentCheck], Union[bool, str]]
+
+#: Looks up the directory listings (dicts with ``url`` and ``payTo``) for an origin.
+DirectoryLookup = Callable[[str], "list[dict]"]
+
+
+def origin_of(url: str) -> str | None:
+    """``https://api.example.com:8443/x?y`` -> ``https://api.example.com:8443``, like ``URL.origin``."""
+    try:
+        parts = urlsplit(url)
+    except ValueError:
+        return None
+    if not parts.scheme or not parts.hostname:
+        return None
+    default_port = {"http": 80, "https": 443}.get(parts.scheme)
+    try:
+        port = parts.port
+    except ValueError:
+        return None
+    host = parts.hostname
+    if ":" in host:
+        host = f"[{host}]"
+    suffix = f":{port}" if port is not None and port != default_port else ""
+    return f"{parts.scheme}://{host}{suffix}"
+
+
+def host_of(origin: str) -> str:
+    return origin.split("://", 1)[1]
+
+
+def _short(address: str) -> str:
+    return f"{address[:4]}…{address[-4:]}"
+
+
+def payee_refusal(rule: PayeeRule, url: str, pay_to: str, directory: DirectoryLookup) -> str | None:
+    """Why the agent should not pay ``pay_to`` for ``url`` under ``rule``, or ``None`` if it may."""
+    if rule == "any":
+        return None
+    if not isinstance(rule, str):
+        return None if pay_to in rule else f"Payee {_short(pay_to)} is not in this agent's allowed payees"
+    if rule != "directory":
+        raise ValueError(f"Unknown payee rule: {rule!r}")
+
+    origin = origin_of(url)
+    if not origin:
+        return f"Can't tell which service {url} is"
+    try:
+        listings = [listing for listing in directory(origin) if origin_of(str(listing.get("url", ""))) == origin]
+    except Exception as error:  # noqa: BLE001 - any lookup failure refuses the payment
+        return f"Could not check the Oryne directory: {error}"
+    host = host_of(origin)
+    if not listings:
+        return f"{host} is not listed in the Oryne directory"
+    if any(listing.get("payTo") == pay_to for listing in listings):
+        return None
+    listed = ", ".join(dict.fromkeys(_short(str(listing.get("payTo", ""))) for listing in listings))
+    return f"{host} asks to be paid at {_short(pay_to)}, but its directory listing pays {listed}"
+
+
+def hook_refusal(hook: BeforePay | None, payment: PaymentCheck) -> str | None:
+    """Runs a ``before_pay`` hook and turns its answer into a refusal reason, or ``None`` to pay."""
+    if hook is None:
+        return None
+    answer = hook(payment)
+    if answer is True:
+        return None
+    return answer if isinstance(answer, str) and answer else "Refused by before_pay"
+
+
+def parse_payee_rule(value: str | None) -> PayeeRule | None:
+    """Reads a payee rule from text, as in an environment variable: "any", "directory" or "G…,G…"."""
+    text = (value or "").strip()
+    if not text:
+        return None
+    if text in ("any", "directory"):
+        return text  # type: ignore[return-value]
+    return [address.strip() for address in text.split(",") if address.strip()]

oryne/payment.py

@@ -0,0 +1,222 @@
+"""The payment format Oryne speaks, modelled on x402.
+
+1. A service answers ``402 Payment Required`` with payment requirements.
+2. The agent signs a Soroban authorization entry for
+   ``token.transfer(from = its wallet, to = payTo, amount)`` with its own key,
+   and retries with the ``X-PAYMENT`` header.
+3. The service hands the payload to a facilitator, which submits the
+   transfer. The wallet contract's ``__check_auth`` enforces the mandate.
+
+The agent's key never leaves the agent, and the facilitator can't change the
+payee or amount: they are inside what the agent signed.
+
+This mirrors ``@oryne/core`` (TypeScript) byte for byte.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from typing import Any, TypedDict
+
+from stellar_sdk import Keypair, SorobanServer, TransactionBuilder, scval
+from stellar_sdk import xdr as stellar_xdr
+from stellar_sdk.address import Address
+from stellar_sdk.auth import authorization_payload_hash, authorize_entry
+
+X402_VERSION = 1
+SCHEME = "exact"
+PAYMENT_HEADER = "X-PAYMENT"
+PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE"
+
+#: How long a signed payment stays valid, in ledgers (about 5 seconds each).
+DEFAULT_VALID_FOR_LEDGERS = 24
+
+
+class PaymentRequirements(TypedDict, total=False):
+    scheme: str
+    #: "stellar-testnet" or "stellar-mainnet"
+    network: str
+    #: Token contract ID.
+    asset: str
+    #: Base units, as a decimal string.
+    maxAmountRequired: str
+    payTo: str
+    resource: str
+    description: str
+    #: Where the service settles payments.
+    facilitator: str
+    maxTimeoutSeconds: int
+
+
+class SettleResponse(TypedDict, total=False):
+    success: bool
+    #: Transaction hash when settled.
+    transaction: str
+    ledger: int
+    payer: str
+    #: Contract error name or another reason when not.
+    errorReason: str
+
+
+# ---------------------------------------------------------------- contract errors
+
+#: The agent-wallet contract's error enum, by number.
+CONTRACT_ERRORS = {
+    1: "UnknownAgent",
+    2: "AgentPaused",
+    3: "AgentExpired",
+    4: "NotATransfer",
+    5: "WrongToken",
+    6: "PayeeNotAllowed",
+    7: "OverPerTxLimit",
+    8: "OverBudget",
+    9: "InvalidAmount",
+    10: "AgentExists",
+    11: "InvalidPolicy",
+    12: "NoPasskey",
+    13: "InvalidPasskeySignature",
+    14: "InvalidExpiry",
+    15: "AgentRemoved",
+}
+
+#: Errors of the Stellar Asset Contract (the token, e.g. USDC) that a payment can hit.
+TOKEN_ERRORS = {
+    6: "AccountMissing",
+    8: "NegativeAmount",
+    10: "InsufficientBalance",
+    11: "BalanceDeauthorized",
+    12: "Overflow",
+    13: "TrustlineMissing",
+}
+
+
+def contract_error_name(message: str) -> str | None:
+    """Finds ``Error(Contract, #8)`` in a simulation or submission error and names it.
+
+    The wallet and the token number their errors separately, so when the
+    diagnostic log shows the error came from the contract ``transfer`` was
+    called on, it's named from the token's errors.
+    """
+    match = re.search(r"Error\(Contract, #(\d+)\)", message)
+    if not match:
+        return None
+    code = int(match.group(1))
+    raised_by = re.search(r"contract:(C[A-Z2-7]{55}), topics:\[error, Error\(Contract, #\d+\)\]", message)
+    if raised_by and f"topics:[fn_call, {raised_by.group(1)}, transfer]" in message:
+        return TOKEN_ERRORS.get(code, f"TokenError{code}")
+    return CONTRACT_ERRORS.get(code, f"ContractError{code}")
+
+
+class StellarError(Exception):
+    """A failure from Stellar, with the contract error named when there is one."""
+
+    def __init__(self, message: str, detail: str) -> None:
+        self.contract_error = contract_error_name(detail)
+        self.detail = detail
+        super().__init__(f"{message}: {self.contract_error or detail[:300]}")
+
+
+# ---------------------------------------------------------------- encoding
+
+
+def encode_header(value: Any) -> str:
+    return base64.b64encode(json.dumps(value, separators=(",", ":")).encode()).decode()
+
+
+def decode_header(value: str) -> Any:
+    return json.loads(base64.b64decode(value))
+
+
+def agent_signature_scval(public_key: bytes, signature: bytes) -> stellar_xdr.SCVal:
+    """``Signature::Agent``: what an agent attaches to an authorization entry.
+
+    A ``#[contracttype]`` enum variant with one value is ``vec[symbol, value]``,
+    and a struct is a map with symbol keys.
+    """
+    return scval.to_vec(
+        [
+            scval.to_symbol("Agent"),
+            scval.to_map(
+                {
+                    scval.to_symbol("public_key"): scval.to_bytes(public_key),
+                    scval.to_symbol("signature"): scval.to_bytes(signature),
+                }
+            ),
+        ]
+    )
+
+
+def _address_of(entry: stellar_xdr.SorobanAuthorizationEntry) -> str | None:
+    credentials = entry.credentials
+    kind = stellar_xdr.SorobanCredentialsType
+    if credentials.type == kind.SOROBAN_CREDENTIALS_ADDRESS:
+        node = credentials.address
+    elif credentials.type == kind.SOROBAN_CREDENTIALS_ADDRESS_V2:
+        node = credentials.address_v2
+    else:
+        return None
+    return Address.from_xdr_sc_address(node.address).address if node else None
+
+
+# ---------------------------------------------------------------- signing
+
+
+def sign_payment(
+    *,
+    rpc_server: SorobanServer,
+    network_passphrase: str,
+    agent: Keypair,
+    wallet: str,
+    requirements: PaymentRequirements,
+    simulation_source: str,
+    valid_for_ledgers: int = DEFAULT_VALID_FOR_LEDGERS,
+) -> dict[str, Any]:
+    """Builds the transfer, simulates it to get the authorization entry the
+    wallet must sign, and signs it with the agent key.
+
+    ``simulation_source`` is any funded account; it pays for nothing.
+    Returns the payment payload to send in the ``X-PAYMENT`` header.
+    """
+    amount = int(requirements["maxAmountRequired"])
+    source = rpc_server.load_account(simulation_source)
+    tx = (
+        TransactionBuilder(source, network_passphrase, base_fee=100)
+        .append_invoke_contract_function_op(
+            contract_id=requirements["asset"],
+            function_name="transfer",
+            parameters=[
+                scval.to_address(wallet),
+                scval.to_address(requirements["payTo"]),
+                scval.to_int128(amount),
+            ],
+        )
+        .set_timeout(120)
+        .build()
+    )
+    sim = rpc_server.simulate_transaction(tx)
+    if sim.error:
+        raise StellarError("Simulation failed", sim.error)
+
+    entries = [
+        stellar_xdr.SorobanAuthorizationEntry.from_xdr(raw)
+        for result in sim.results or []
+        for raw in result.auth or []
+    ]
+    entry = next((candidate for candidate in entries if _address_of(candidate) == wallet), None)
+    if entry is None:
+        raise RuntimeError("The transfer did not ask the wallet for authorization")
+
+    def signer(preimage: stellar_xdr.HashIDPreimage) -> stellar_xdr.SCVal:
+        payload = authorization_payload_hash(preimage)
+        return agent_signature_scval(agent.raw_public_key(), agent.sign(payload))
+
+    latest = rpc_server.get_latest_ledger().sequence
+    signed = authorize_entry(entry, signer, latest + valid_for_ledgers, network_passphrase)
+    return {
+        "x402Version": X402_VERSION,
+        "scheme": SCHEME,
+        "network": requirements["network"],
+        "payload": {"from": wallet, "authorization": signed.to_xdr()},
+    }

oryne/units.py

@@ -0,0 +1,34 @@
+"""Token amounts: Stellar assets have 7 decimals, so 1 USDC is 10_000_000 base units."""
+
+from __future__ import annotations
+
+import re
+
+DECIMALS = 7
+
+_AMOUNT = re.compile(r"^\d+(\.\d+)?$")
+
+
+def to_base_units(amount: str | int, decimals: int = DECIMALS) -> int:
+    """``"0.008"`` -> ``80_000``. Rejects anything that isn't a plain positive decimal.
+
+    Floats are refused on purpose: ``0.1 + 0.2`` is not ``0.3``, and money
+    should not depend on that. Pass amounts as strings.
+    """
+    if isinstance(amount, bool) or not isinstance(amount, (str, int)):
+        raise TypeError(f"Pass amounts as strings, e.g. '0.05', not {type(amount).__name__}")
+    text = str(amount).strip()
+    if not _AMOUNT.match(text):
+        raise ValueError(f"Invalid amount: {amount!r}")
+    whole, _, fraction = text.partition(".")
+    if len(fraction) > decimals:
+        raise ValueError(f"Too many decimals in {amount!r}")
+    return int(whole) * 10**decimals + int(fraction.ljust(decimals, "0") or "0")
+
+
+def from_base_units(units: int, decimals: int = DECIMALS) -> str:
+    """``80_000`` -> ``"0.008"``"""
+    sign = "-" if units < 0 else ""
+    whole, fraction = divmod(abs(units), 10**decimals)
+    fraction_text = str(fraction).rjust(decimals, "0").rstrip("0")
+    return f"{sign}{whole}{'.' + fraction_text if fraction_text else ''}"

oryne-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: oryne
+Version: 0.1.0
+Summary: Give an AI agent a wallet it can spend from, with limits it cannot break: x402 payments in USDC on Stellar.
+Project-URL: Homepage, https://oryne.org
+Project-URL: Source, https://github.com/m2moryne/Oryne/tree/master/packages/python
+Project-URL: Issues, https://github.com/m2moryne/Oryne/issues
+Author: Oryne
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-payments,ai-agents,soroban,stellar,usdc,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: stellar-sdk<18,>=17.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# oryne (Python)
+
+Give an AI agent a wallet it can spend from, with limits it cannot break.
+
+`agent.fetch()` makes an HTTP request. When a service answers `402 Payment Required` ([x402](https://x402.org)), it pays in USDC from the agent's Oryne wallet on Stellar and retries. The wallet's smart contract checks every payment against the mandate the owner set: per-payment limit, budget, allowed payees, expiry. Nothing the agent does can get past it.
+
+The same SDK as [`@oryne/agent`](https://www.npmjs.com/package/@oryne/agent) for TypeScript, for Python agents: LangChain, CrewAI, LlamaIndex, or a plain script.
+
+```sh
+pip install oryne
+```
+
+Needs Python 3.10 or later.
+
+## Use
+
+Connect an agent in the [Oryne dashboard](https://oryne.org/app). You get its secret key once.
+
+```python
+import os
+from oryne import OryneAgent
+
+agent = OryneAgent(os.environ["ORYNE_AGENT_SECRET"])
+
+response = agent.fetch("https://api.example.com/search", params={"q": "stellar"})
+print(response.json())
+```
+
+`fetch` takes the same keyword arguments as `httpx.Client.request` (`params`, `json`, `headers`, `content`, …) and returns an `httpx.Response`.
+
+When the wallet refuses a payment, `fetch` raises `PaymentRefusedError` with the reason (`OverPerTxLimit`, `OverBudget`, `PayeeNotAllowed`, …). The agent can then ask the owner:
+
+```python
+from oryne import PaymentRefusedError
+
+try:
+    agent.fetch(url)
+except PaymentRefusedError as refused:
+    if refused.source != "wallet":
+        raise  # refused before signing, see below
+    approval = agent.request_approval(
+        pay_to=refused.requirements["payTo"],
+        amount="30",
+        description="Research report for the weekly summary",
+        resource=refused.requirements["resource"],
+        reason=refused.reason,
+    )
+    agent.wait_for_approval(approval["id"])  # the owner approves in the dashboard
+    agent.fetch(url)                         # now within what was approved
+```
+
+## Check a payment before signing
+
+The wallet contract is the hard limit. Before signing, the SDK can also check whether a payment request makes sense at all. That catches a request that is inside the mandate but still wrong: a service that suddenly asks for more, or a hijacked endpoint that asks to be paid at someone else's address.
+
+```python
+agent = OryneAgent(
+    os.environ["ORYNE_AGENT_SECRET"],
+    payees="directory",  # only services in the Oryne directory, at the address they're listed with
+    # Your own rule, last before signing: True to pay, or a reason to refuse.
+    before_pay=lambda payment: payment.url.startswith("https://api.example.com/") or "only example.com",
+)
+
+# This search should cost at most 0.10; a 402 asking more is refused unpaid.
+agent.fetch("https://api.example.com/search?q=stellar", max_price="0.10")
+```
+
+A refusal here raises `PaymentRefusedError` with `source == "client"`. Nothing was signed and no money moved. Refusals from the wallet contract have `source == "wallet"`.
+
+The directory doesn't verify who owns a listed URL yet. `payees="directory"` stops payments to unlisted hosts and to addresses a host isn't listed with, but for a guarantee, set the allowed payees in the agent's on-chain mandate in the dashboard.
+
+## Options
+
+| Option | |
+|---|---|
+| `secret` | The agent's secret key (`S…`). |
+| `api_url` | Oryne API. Defaults to `ORYNE_API_URL`, then `https://oryne.onrender.com` (Stellar testnet). |
+| `max_per_request` | Most this client pays for one request, whatever a service asks, e.g. `"1"`. |
+| `payees` | Who it may pay: `"any"` (default), `"directory"`, or a list of Stellar addresses. |
+| `before_pay` | `(PaymentCheck) -> True \| False \| reason`. Last say before signing. |
+| `on_payment` | Called with a `PaymentEvent`: `paying`, then `paid` or `refused`. |
+| `http` | Your own `httpx.Client`, e.g. with other timeouts or a proxy. |
+
+Per request: `agent.fetch(url, max_price="0.10")`.
+
+Amounts are strings (`"0.05"`), never floats, so money doesn't depend on float rounding.
+
+Other methods: `agent.me()` (the agent, its mandate and what's left of its budget), `agent.approval(id)`. `OryneAgent` is a context manager that closes its HTTP client.
+
+## As a tool for your agent framework
+
+`fetch` is a plain function, so wrapping it as a tool is a few lines. With LangChain:
+
+```python
+from langchain_core.tools import tool
+
+@tool
+def fetch_paid(url: str, max_price: str = "1") -> str:
+    """Fetch a URL. If it costs money, pay up to max_price USDC from the agent's wallet."""
+    try:
+        return agent.fetch(url, max_price=max_price).text[:20_000]
+    except PaymentRefusedError as refused:
+        return f"Not paid: {refused.reason}"
+```
+
+## Develop
+
+```sh
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest                                  # unit tests, no network
+ORYNE_TESTNET=1 .venv/bin/pytest -m testnet       # end to end on Stellar testnet
+```
+
+The unit tests compare signatures and encodings with fixtures produced by the TypeScript SDK, so the two can't drift apart.
+
+## Links
+
+- [Oryne](https://oryne.org)
+- [@oryne/agent](https://www.npmjs.com/package/@oryne/agent): the TypeScript SDK
+- [@oryne/mcp](https://www.npmjs.com/package/@oryne/mcp): the same as tools for MCP clients like Claude
+- [Source](https://github.com/m2moryne/Oryne/tree/master/packages/python)
+
+MIT licensed.

oryne-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+oryne/__init__.py,sha256=OiC-b6Q2kHBbfJYxmhe2lgOncrqxG3mzFtBGKyXfsuE,1303
+oryne/agent.py,sha256=L06tlb7XZ4zF86F1V0IhPd_RkFV7gyKfNmqFv5gO90U,11942
+oryne/guard.py,sha256=TpzIMHn6RhA9G7xz3QR91a1XMCk-5Gf1w9IB4hDMoOg,4234
+oryne/payment.py,sha256=4J46TbYj80cWwSmhQWyzhWpGRfrD__LJT14OF8XKW-U,7351
+oryne/units.py,sha256=9CtPES43WMBjNwIhzcKtzu5c570Fa0duXfjofkBXo18,1331
+oryne-0.1.0.dist-info/METADATA,sha256=C7NkX2JGTlcMcwuuAQwEeO0In7Xa6BRsVgdRkqdXSVg,6254
+oryne-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+oryne-0.1.0.dist-info/licenses/LICENSE,sha256=bwHHmBL92uS-uVx0pmc-45GFF06tFHu8Qtzv1zvjX4Y,1062
+oryne-0.1.0.dist-info/RECORD,,

oryne-0.1.0.dist-info/WHEEL

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

oryne-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oryne
+
+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.