oryne 0.1.0__tar.gz

oryne-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+node_modules
+dist
+*.local
+.DS_Store
+.env
+# Local API database and downloaded contract builds
+services/api/data/
+.oryne/
+
+# The admin site lives in its own repository (git init inside apps/admin).
+apps/admin/
+
+# SDK builds for npm (npm run packages)
+packages/*/npm/
+
+# TypeScript incremental build caches
+*.tsbuildinfo
+
+# Soroban test snapshots, written by every cargo test run
+test_snapshots/
+
+# Python SDK
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/

oryne-0.1.0/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.

oryne-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,123 @@
+# 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/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "oryne"
+version = "0.1.0"
+description = "Give an AI agent a wallet it can spend from, with limits it cannot break: x402 payments in USDC on Stellar."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Oryne" }]
+keywords = ["stellar", "x402", "ai-agents", "agent-payments", "usdc", "soroban"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "stellar-sdk>=17.0.1,<18",
+  "httpx>=0.27,<1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://oryne.org"
+Source = "https://github.com/m2moryne/Oryne/tree/master/packages/python"
+Issues = "https://github.com/m2moryne/Oryne/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oryne"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["testnet: runs against Stellar testnet and the hosted Oryne API (set ORYNE_TESTNET=1)"]

oryne-0.1.0/src/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",
+]