nirium 0.2.1__tar.gz → 0.5.0__tar.gz

{nirium-0.2.1 → nirium-0.5.0}/PKG-INFO

@@ -1,17 +1,19 @@
 Metadata-Version: 2.4
 Name: nirium
-Version: 0.2.1
-Summary: Official Python SDK for the Nirium autonomous DeFi agent on Stellar
+Version: 0.5.0
+Summary: Official Python SDK for Nirium autonomous agents on Stellar (x402 + MPP)
 Author: Nirium Protocol
 License: MIT
 Project-URL: Homepage, https://nirium.dev
 Project-URL: Repository, https://github.com/nirium/nirium
 Project-URL: Documentation, https://nirium.dev/docs
-Keywords: nirium,stellar,defi,sdk,soroban,agent
-Requires-Python: >=3.10
+Keywords: nirium,stellar,defi,sdk,soroban,agent,x402,mpp,agentic-payments,usdc
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: websockets>=13.0
+Requires-Dist: stellar-sdk>=11.0.0
+Dynamic: requires-python
 
 # nirium
 
@@ -86,7 +88,7 @@ agent = Agent(api_url="https://api.nirium.xyz", api_key="sk_inst_...", token="ey
 |---|---|
 | Health | `ping()`, `health()`, `system_health()` |
 | Execution | `execute()`, `execute_demo()` |
-| Market | `get_market()`, `get_loop_status()`, `start_loop()`, `stop_loop()`, `trigger_scan()` |
+| Market | `get_tickers()`, `get_market()`, `get_stats()`, `get_loop_status()`, `start_loop()`, `stop_loop()`, `trigger_scan()` |
 | Signals | `get_recent_signals()` |
 | Skills | `get_skills()`, `install_skill()`, `uninstall_skill()` |
 | Webhooks | `register_webhook()`, `get_webhooks()`, `delete_webhook()`, `test_webhook()` |

{nirium-0.2.1 → nirium-0.5.0}/README.md

@@ -71,7 +71,7 @@ agent = Agent(api_url="https://api.nirium.xyz", api_key="sk_inst_...", token="ey
 |---|---|
 | Health | `ping()`, `health()`, `system_health()` |
 | Execution | `execute()`, `execute_demo()` |
-| Market | `get_market()`, `get_loop_status()`, `start_loop()`, `stop_loop()`, `trigger_scan()` |
+| Market | `get_tickers()`, `get_market()`, `get_stats()`, `get_loop_status()`, `start_loop()`, `stop_loop()`, `trigger_scan()` |
 | Signals | `get_recent_signals()` |
 | Skills | `get_skills()`, `install_skill()`, `uninstall_skill()` |
 | Webhooks | `register_webhook()`, `get_webhooks()`, `delete_webhook()`, `test_webhook()` |

{nirium-0.2.1 → nirium-0.5.0}/pyproject.toml

@@ -4,16 +4,17 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nirium"
-version = "0.2.1"
-description = "Official Python SDK for the Nirium autonomous DeFi agent on Stellar"
+version = "0.5.0"
+description = "Official Python SDK for Nirium autonomous agents on Stellar (x402 + MPP)"
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
 authors = [{name = "Nirium Protocol"}]
-keywords = ["nirium", "stellar", "defi", "sdk", "soroban", "agent"]
+keywords = ["nirium", "stellar", "defi", "sdk", "soroban", "agent", "x402", "mpp", "agentic-payments", "usdc"]
 dependencies = [
     "aiohttp>=3.9.0",
     "websockets>=13.0",
+    "stellar-sdk>=11.0.0",
 ]
 
 [project.urls]

nirium-0.5.0/setup.py

@@ -0,0 +1,17 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="nirium",
+    version="0.4.0",
+    package_dir={"": "src"},
+    packages=find_packages(where="src"),
+    install_requires=[
+        "websockets>=11.0.3",
+        "aiohttp>=3.8.4",
+        "stellar-sdk>=11.0.0",
+    ],
+    author="Nirium Team",
+    description="Official Python SDK for Nirium autonomous agents on Stellar (x402 + MPP)",
+    keywords=["nirium", "stellar", "defi", "x402", "mpp", "agentic-payments", "soroban"],
+    python_requires=">=3.9",
+)

{nirium-0.2.1 → nirium-0.5.0}/src/nirium/__init__.py

@@ -2,5 +2,5 @@
 
 from .client import Agent  # type: ignore
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 __all__ = ["Agent"]

{nirium-0.2.1 → nirium-0.5.0}/src/nirium/client.py

@@ -1,5 +1,5 @@
 # ═══════════════════════════════════════════════════════════════
-# Nirium Python SDK v0.2.0 — Official Quantitative Client
+# Nirium Python SDK v0.4.0 — Official Client (x402 + MPP)
 # Synced with backend API (real Horizon data, Soroban execution)
 # ═══════════════════════════════════════════════════════════════
 import asyncio
@@ -8,6 +8,7 @@ import logging
 import aiohttp  # type: ignore
 import websockets  # type: ignore
 from typing import Callable, Dict, Any, List, Optional
+from stellar_sdk import Keypair, Network, Server, TransactionBuilder, Asset  # type: ignore
 
 logger = logging.getLogger("nirium.client")
 
@@ -59,14 +60,16 @@ class Agent:
 
     # ─── HTTP Helpers ─────────────────────────────────────────
 
-    async def _get(self, path: str) -> Any:
-        async with aiohttp.ClientSession(headers=self.headers) as session:
+    async def _get(self, path: str, extra_headers: Optional[Dict[str, str]] = None) -> Any:
+        headers = {**self.headers, **(extra_headers or {})}
+        async with aiohttp.ClientSession(headers=headers) as session:
             async with session.get(f"{self.api_url}{path}") as resp:
                 resp.raise_for_status()
                 return await resp.json()
 
-    async def _post(self, path: str, payload: Optional[Dict[str, Any]] = None) -> Any:
-        async with aiohttp.ClientSession(headers=self.headers) as session:
+    async def _post(self, path: str, payload: Optional[Dict[str, Any]] = None, extra_headers: Optional[Dict[str, str]] = None) -> Any:
+        headers = {**self.headers, **(extra_headers or {})}
+        async with aiohttp.ClientSession(headers=headers) as session:
             async with session.post(f"{self.api_url}{path}", json=payload or {}) as resp:
                 resp.raise_for_status()
                 return await resp.json()
@@ -97,10 +100,18 @@ class Agent:
 
     # ─── Market Data ─────────────────────────────────────────
 
+    async def get_tickers(self) -> Dict[str, Any]:
+        """Get asset price tickers (XLM, USDC) from Stellar Horizon."""
+        return await self._get("/api/tickers")
+
     async def get_market(self) -> Dict[str, Any]:
         """Fetch real market state from Horizon (XLM price, SDEX spread, fees, paths)."""
         return await self._get("/api/market")
 
+    async def get_stats(self) -> Dict[str, Any]:
+        """Get global protocol statistics."""
+        return await self._get("/api/stats/global")
+
     async def get_loop_status(self) -> Dict[str, Any]:
         """Get autonomous loop status."""
         return await self._get("/api/loop/status")
@@ -119,19 +130,37 @@ class Agent:
 
     # ─── Execution ───────────────────────────────────────────
 
-    async def execute(self, strategy: str, asset: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Execute a strategy via real Soroban contract call.
+    async def execute(
+        self,
+        strategy: str,
+        asset: str,
+        params: Optional[Dict[str, Any]] = None,
+        stellar_account: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Execute a strategy via real Soroban contract transaction on Stellar.
 
         Strategies: flash-loan-arb, path-arbitrage, cross-dex, blend-yield, soroswap-swap
+
+        Args:
+            strategy: Strategy name (maps to a NiriumVault contract function)
+            asset: Base asset symbol (e.g. 'XLM')
+            params: Optional dict — supports 'amount' in stroops (default 1000)
+            stellar_account: Your Stellar wallet address. Required for legal consent verification.
         """
-        return await self._post("/api/execute", {
-            "strategy": strategy,
-            "asset": asset,
-            "params": params or {},
-        })
+        extra: Dict[str, str] = {}
+        if stellar_account:
+            extra["x-stellar-account"] = stellar_account
+        payload: Dict[str, Any] = {"strategy": strategy, "asset": asset}
+        if params:
+            payload.update(params)
+        return await self._post("/api/execute", payload, extra_headers=extra)
 
     async def execute_demo(self, strategy: str, asset: str) -> Dict[str, Any]:
-        """Execute a strategy in demo mode (Soroban dry-run, no TX submitted)."""
+        """Execute a strategy in demo mode (Soroban dry-run, no TX submitted).
+
+        Returns a professional market assessment message.
+        Response keys: success, simulated_profit, gas_consumed, message
+        """
         return await self._post("/api/execute-demo", {
             "strategy": strategy,
             "asset": asset,
@@ -175,6 +204,155 @@ class Agent:
         """Send a test event to a webhook."""
         return await self._post(f"/api/webhooks/{webhook_id}/test")
 
+    # ─── x402 Protocol ───────────────────────────────────────
+
+    def init_x402(self, secret_key: str, network: str = "stellar:testnet"):
+        """
+        Initialize x402 pay-per-request client.
+
+        Python SDK implements the x402 HTTP flow directly:
+        1. GET resource -> receive 402 + payment requirements
+        2. Build Soroban SAC USDC transfer auth entry
+        3. Retry with X-PAYMENT header containing signed auth entry
+
+        Args:
+            secret_key: Stellar secret key (S...) for signing
+            network: CAIP-2 network ID ('stellar:testnet' or 'stellar:pubnet')
+        """
+        self._x402_keypair = Keypair.from_secret(secret_key)
+        self._x402_network = network
+        self._x402_passphrase = (
+            Network.TESTNET_NETWORK_PASSPHRASE if "testnet" in network
+            else Network.PUBLIC_NETWORK_PASSPHRASE
+        )
+        self._x402_horizon = Server(
+            "https://horizon-testnet.stellar.org" if "testnet" in network
+            else "https://horizon.stellar.org"
+        )
+
+    async def x402_fetch(self, url: str, method: str = "GET") -> Dict[str, Any]:
+        """
+        Fetch a paid resource via x402 protocol.
+
+        Sends the initial request, receives 402 with payment requirements,
+        builds and signs a USDC payment, retries with the payment proof.
+
+        Returns the JSON payload from the paid resource.
+        """
+        if not hasattr(self, "_x402_keypair"):
+            raise RuntimeError("x402 client not initialized. Call agent.init_x402() first.")
+
+        async with aiohttp.ClientSession() as session:
+            # Step 1: Initial request — expect 402
+            async with session.request(method, url) as resp:
+                if resp.status != 402:
+                    return await resp.json()
+
+                requirements = await resp.json()
+
+            # Step 2: Build USDC payment from requirements
+            pay_req = requirements.get("paymentRequirements", [{}])[0]
+            dest = pay_req.get("receiver") or pay_req.get("destination", "")
+            amount = pay_req.get("maxAmountRequired") or pay_req.get("amount", "0.01")
+            usdc_issuer = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
+            usdc_asset = Asset("USDC", usdc_issuer)
+
+            account = self._x402_horizon.load_account(self._x402_keypair.public_key)
+            tx = (
+                TransactionBuilder(
+                    source_account=account,
+                    network_passphrase=self._x402_passphrase,
+                    base_fee=100,
+                )
+                .append_payment_op(dest, usdc_asset, str(amount))
+                .set_timeout(30)
+                .build()
+            )
+            tx.sign(self._x402_keypair)
+            xdr = tx.to_xdr()
+
+            # Step 3: Retry with payment proof
+            payment_header = json.dumps({"transaction": xdr})
+            headers = {"X-PAYMENT": payment_header, "Content-Type": "application/json"}
+            async with session.request(method, url, headers=headers) as resp:
+                resp.raise_for_status()
+                return await resp.json()
+
+    # ─── MPP Protocol (Charge Mode) ─────────────────────────
+
+    def init_mpp(self, secret_key: str, network: str = "stellar:testnet"):
+        """
+        Initialize MPP Charge client for per-request Soroban SAC payments.
+
+        Python SDK implements the MPP charge flow directly:
+        1. GET resource -> receive 402 + charge challenge
+        2. Sign Soroban auth entries for SAC USDC transfer
+        3. Retry with signed auth in X-PAYMENT header
+
+        Args:
+            secret_key: Stellar secret key (S...) for signing
+            network: CAIP-2 network ID ('stellar:testnet' or 'stellar:pubnet')
+        """
+        self._mpp_keypair = Keypair.from_secret(secret_key)
+        self._mpp_network = network
+        self._mpp_passphrase = (
+            Network.TESTNET_NETWORK_PASSPHRASE if "testnet" in network
+            else Network.PUBLIC_NETWORK_PASSPHRASE
+        )
+        self._mpp_horizon = Server(
+            "https://horizon-testnet.stellar.org" if "testnet" in network
+            else "https://horizon.stellar.org"
+        )
+
+    async def mpp_fetch(self, url: str, method: str = "GET") -> Dict[str, Any]:
+        """
+        Fetch a paid resource via MPP Charge protocol.
+
+        Sends the initial request, receives 402 with charge challenge,
+        builds and signs a USDC payment, retries with payment proof.
+        In pull mode, the server assembles and broadcasts the Soroban tx.
+
+        Returns the JSON payload from the paid resource.
+        """
+        if not hasattr(self, "_mpp_keypair"):
+            raise RuntimeError("MPP client not initialized. Call agent.init_mpp() first.")
+
+        async with aiohttp.ClientSession() as session:
+            # Step 1: Initial request — expect 402
+            async with session.request(method, url) as resp:
+                if resp.status != 402:
+                    return await resp.json()
+
+                challenge = await resp.json()
+
+            # Step 2: Build USDC payment from challenge
+            pay_req = challenge.get("paymentRequirements", [{}])[0]
+            dest = pay_req.get("receiver") or pay_req.get("destination", "")
+            amount = pay_req.get("maxAmountRequired") or pay_req.get("amount", "0.01")
+            usdc_issuer = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
+            usdc_asset = Asset("USDC", usdc_issuer)
+
+            account = self._mpp_horizon.load_account(self._mpp_keypair.public_key)
+            tx = (
+                TransactionBuilder(
+                    source_account=account,
+                    network_passphrase=self._mpp_passphrase,
+                    base_fee=100,
+                )
+                .append_payment_op(dest, usdc_asset, str(amount))
+                .set_timeout(30)
+                .build()
+            )
+            tx.sign(self._mpp_keypair)
+            xdr = tx.to_xdr()
+
+            # Step 3: Retry with payment proof
+            payment_header = json.dumps({"transaction": xdr, "mode": "pull"})
+            headers = {"X-PAYMENT": payment_header, "Content-Type": "application/json"}
+            async with session.request(method, url, headers=headers) as resp:
+                resp.raise_for_status()
+                return await resp.json()
+
     # ─── WebSocket ───────────────────────────────────────────
 
     async def subscribe(self, callback: Optional[Callable] = None):

{nirium-0.2.1 → nirium-0.5.0}/src/nirium.egg-info/PKG-INFO

@@ -1,17 +1,19 @@
 Metadata-Version: 2.4
 Name: nirium
-Version: 0.2.1
-Summary: Official Python SDK for the Nirium autonomous DeFi agent on Stellar
+Version: 0.5.0
+Summary: Official Python SDK for Nirium autonomous agents on Stellar (x402 + MPP)
 Author: Nirium Protocol
 License: MIT
 Project-URL: Homepage, https://nirium.dev
 Project-URL: Repository, https://github.com/nirium/nirium
 Project-URL: Documentation, https://nirium.dev/docs
-Keywords: nirium,stellar,defi,sdk,soroban,agent
-Requires-Python: >=3.10
+Keywords: nirium,stellar,defi,sdk,soroban,agent,x402,mpp,agentic-payments,usdc
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: websockets>=13.0
+Requires-Dist: stellar-sdk>=11.0.0
+Dynamic: requires-python
 
 # nirium
 
@@ -86,7 +88,7 @@ agent = Agent(api_url="https://api.nirium.xyz", api_key="sk_inst_...", token="ey
 |---|---|
 | Health | `ping()`, `health()`, `system_health()` |
 | Execution | `execute()`, `execute_demo()` |
-| Market | `get_market()`, `get_loop_status()`, `start_loop()`, `stop_loop()`, `trigger_scan()` |
+| Market | `get_tickers()`, `get_market()`, `get_stats()`, `get_loop_status()`, `start_loop()`, `stop_loop()`, `trigger_scan()` |
 | Signals | `get_recent_signals()` |
 | Skills | `get_skills()`, `install_skill()`, `uninstall_skill()` |
 | Webhooks | `register_webhook()`, `get_webhooks()`, `delete_webhook()`, `test_webhook()` |

{nirium-0.2.1 → nirium-0.5.0}/src/nirium.egg-info/requires.txt

@@ -1,2 +1,3 @@
 aiohttp>=3.9.0
 websockets>=13.0
+stellar-sdk>=11.0.0

nirium-0.2.1/setup.py

@@ -1,14 +0,0 @@
-from setuptools import setup, find_packages
-
-setup(
-    name="nirium-sdk",
-    version="1.0.0",
-    package_dir={"": "src"},
-    packages=find_packages(where="src"),
-    install_requires=[
-        "websockets>=11.0.3",
-        "aiohttp>=3.8.4",
-    ],
-    author="Nirium Team",
-    description="Official Python SDK for Nirium Autonomous Agents",
-)