nirium 0.2.0__py3-none-any.whl

nirium/__init__.py

@@ -0,0 +1,6 @@
+"""Nirium — Official Python SDK for the Nirium autonomous DeFi agent."""
+
+from .client import Agent  # type: ignore
+
+__version__ = "0.1.0"
+__all__ = ["Agent"]

nirium/client.py

@@ -0,0 +1,201 @@
+# ═══════════════════════════════════════════════════════════════
+# Nirium Python SDK v0.2.0 — Official Quantitative Client
+# Synced with backend API (real Horizon data, Soroban execution)
+# ═══════════════════════════════════════════════════════════════
+import asyncio
+import json
+import logging
+import aiohttp  # type: ignore
+import websockets  # type: ignore
+from typing import Callable, Dict, Any, List, Optional
+
+logger = logging.getLogger("nirium.client")
+
+
+class Agent:
+    """
+    Nirium Agent — Full API + WebSocket client for the Nirium autonomous agent.
+
+    Usage:
+        agent = Agent(api_url="http://localhost:3001", api_key="nrm_your_key")
+        market = await agent.get_market()
+        print(f"XLM Price: ${market['xlmPrice']:.4f}")
+    """
+
+    def __init__(self, api_url: str = "http://localhost:3001", api_key: Optional[str] = None, token: Optional[str] = None):
+        self.api_url = api_url.rstrip('/')
+        self.ws_url = self.api_url.replace("http", "ws") + "/ws/signals"
+        self.api_key = api_key
+        self.token = token
+
+        api_key_local = self.api_key
+        token_local = self.token
+
+        self.headers: Dict[str, str] = {"Content-Type": "application/json"}
+        if api_key_local is not None:
+            self.headers["x-api-key"] = api_key_local
+        elif token_local is not None:
+            self.headers["Authorization"] = f"Bearer {token_local}"
+
+        self.callbacks: Dict[str, List[Callable]] = {"signal": [], "log": [], "connected": []}
+
+    # ─── Decorators ────────────────────────────────────────────
+
+    def on(self, event_type: str):
+        """Decorator to register event callbacks."""
+        def decorator(func: Callable):
+            if event_type not in self.callbacks:
+                self.callbacks[event_type] = []
+            self.callbacks[event_type].append(func)
+            return func
+        return decorator
+
+    async def _emit(self, event_type: str, data: Any):
+        for callback in self.callbacks.get(event_type, []):
+            if asyncio.iscoroutinefunction(callback):
+                await callback(data)
+            else:
+                callback(data)
+
+    # ─── HTTP Helpers ─────────────────────────────────────────
+
+    async def _get(self, path: str) -> Any:
+        async with aiohttp.ClientSession(headers=self.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 with session.post(f"{self.api_url}{path}", json=payload or {}) as resp:
+                resp.raise_for_status()
+                return await resp.json()
+
+    async def _delete(self, path: str) -> Any:
+        async with aiohttp.ClientSession(headers=self.headers) as session:
+            async with session.delete(f"{self.api_url}{path}") as resp:
+                resp.raise_for_status()
+                return await resp.json()
+
+    # ─── Health ───────────────────────────────────────────────
+
+    async def ping(self) -> bool:
+        """Check if the agent is reachable."""
+        try:
+            data = await self._get("/health")
+            return data.get("status") == "operational"
+        except Exception:
+            return False
+
+    async def health(self) -> Dict[str, Any]:
+        """Get detailed health info."""
+        return await self._get("/health")
+
+    async def system_health(self) -> Dict[str, Any]:
+        """Get full system health (Horizon, Soroban, WebSocket, IPFS, LLM)."""
+        return await self._get("/api/system/health")
+
+    # ─── Market Data ─────────────────────────────────────────
+
+    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_loop_status(self) -> Dict[str, Any]:
+        """Get autonomous loop status."""
+        return await self._get("/api/loop/status")
+
+    async def start_loop(self, config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Start the autonomous scanning loop."""
+        return await self._post("/api/loop/start", {"config": config or {}})
+
+    async def stop_loop(self) -> Dict[str, Any]:
+        """Stop the autonomous scanning loop."""
+        return await self._post("/api/loop/stop")
+
+    async def trigger_scan(self) -> Dict[str, Any]:
+        """Trigger a manual market scan."""
+        return await self._post("/api/loop/scan")
+
+    # ─── 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.
+
+        Strategies: flash-loan-arb, path-arbitrage, cross-dex, blend-yield, soroswap-swap
+        """
+        return await self._post("/api/execute", {
+            "strategy": strategy,
+            "asset": asset,
+            "params": params or {},
+        })
+
+    async def execute_demo(self, strategy: str, asset: str) -> Dict[str, Any]:
+        """Execute a strategy in demo mode (Soroban dry-run, no TX submitted)."""
+        return await self._post("/api/execute-demo", {
+            "strategy": strategy,
+            "asset": asset,
+        })
+
+    # ─── Signals ─────────────────────────────────────────────
+
+    async def get_recent_signals(self, count: int = 20) -> Any:
+        """Get recent market signals."""
+        return await self._get(f"/api/signals/recent?count={count}")
+
+    # ─── Skills ──────────────────────────────────────────────
+
+    async def get_skills(self) -> Any:
+        """List all loaded skills (built-in + user-installed)."""
+        return await self._get("/api/skills")
+
+    async def install_skill(self, source: str) -> Dict[str, Any]:
+        """Install a skill by slug."""
+        return await self._post("/api/skills/install", {"source": source})
+
+    async def uninstall_skill(self, slug: str) -> Dict[str, Any]:
+        """Uninstall a user-installed skill by slug."""
+        return await self._delete(f"/api/skills/{slug}")
+
+    # ─── Webhooks ────────────────────────────────────────────
+
+    async def register_webhook(self, url: str, events: List[str], secret: Optional[str] = None) -> Dict[str, Any]:
+        """Register a webhook endpoint with HMAC signing."""
+        return await self._post("/api/webhooks", {"url": url, "events": events, "secret": secret})
+
+    async def get_webhooks(self) -> List[Dict[str, Any]]:
+        """List all registered webhooks."""
+        return await self._get("/api/webhooks")
+
+    async def delete_webhook(self, webhook_id: str) -> Dict[str, Any]:
+        """Delete a webhook by ID."""
+        return await self._delete(f"/api/webhooks/{webhook_id}")
+
+    async def test_webhook(self, webhook_id: str) -> Dict[str, Any]:
+        """Send a test event to a webhook."""
+        return await self._post(f"/api/webhooks/{webhook_id}/test")
+
+    # ─── WebSocket ───────────────────────────────────────────
+
+    async def subscribe(self, callback: Optional[Callable] = None):
+        """Start real-time WebSocket connection for signals."""
+        if callback:
+            self.callbacks.setdefault("signal", []).append(callback)
+
+        auth_query = f"?token={self.token}" if self.token else ""
+        url = f"{self.ws_url}{auth_query}"
+
+        while True:
+            try:
+                async with websockets.connect(url) as ws:
+                    logger.info("Connected to Nirium Signal Stream")
+                    await self._emit("connected", None)
+
+                    async for message in ws:
+                        data = json.loads(message)
+                        event = data.get("type")
+                        if event in self.callbacks:
+                            await self._emit(event, data)
+            except Exception as e:
+                logger.error(f"WS Disconnected: {e}. Reconnecting in 5s...")
+                await asyncio.sleep(5)

nirium-0.2.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: nirium
+Version: 0.2.0
+Summary: Official Python SDK for the Nirium autonomous DeFi agent on Stellar
+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
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: websockets>=13.0
+
+# nirium
+
+Official Python SDK for the **Nirium Protocol** — autonomous DeFi agent on Stellar/Soroban.
+
+## Install
+
+```bash
+pip install nirium
+```
+
+## Quick Start
+
+```python
+import asyncio
+from nirium import Agent
+
+agent = Agent(
+    api_url="https://api.nirium.xyz",
+    api_key="sk_inst_your_key_here",
+)
+
+async def main():
+    # Health check
+    alive = await agent.ping()
+    print(f"Agent alive: {alive}")
+
+    # Real market data from Stellar Horizon
+    market = await agent.get_market()
+    print(f"XLM Price: ${market['xlmPrice']:.4f}")
+
+    # Execute a strategy
+    result = await agent.execute("flash-loan-arb", "XLM-USDC", {"amount": 5000})
+    print(f"Profit: {result['profit']}")
+
+asyncio.run(main())
+```
+
+## Real-Time Signals (WebSocket)
+
+```python
+agent = Agent(api_url="https://api.nirium.xyz", api_key="sk_inst_...", token="eyJhbG...")
+
+@agent.on("signal")
+async def on_signal(data):
+    print(f"Signal: {data['signal_type']} — {data['data']['details']}")
+
+asyncio.run(agent.subscribe())
+```
+
+## Authentication
+
+```python
+# API Key for REST endpoints
+agent = Agent(api_url="https://api.nirium.xyz", api_key="sk_inst_...")
+
+# With JWT token for WebSocket
+agent = Agent(api_url="https://api.nirium.xyz", api_key="sk_inst_...", token="eyJhbG...")
+```
+
+### Endpoint Access Model
+
+| Access | Endpoints |
+|---|---|
+| **Public** (no key) | `health`, `loop/status`, `execute-demo`, `signals/recent`, `skills` list |
+| **Protected** (API key) | `execute`, `market`, `loop/start\|stop\|scan`, `subscriptions`, `skills/install`, `webhooks` |
+| **WebSocket** (JWT) | `/ws/signals` — real-time signal stream |
+
+## API Coverage
+
+| Category | Methods |
+|---|---|
+| Health | `ping()`, `health()`, `system_health()` |
+| Execution | `execute()`, `execute_demo()` |
+| Market | `get_market()`, `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()` |
+| WebSocket | `subscribe()`, `on()` decorator |
+
+## Requirements
+
+- Python >= 3.10
+- aiohttp >= 3.9.0
+- websockets >= 13.0
+
+## License
+
+MIT — Nirium Protocol

nirium-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+nirium/__init__.py,sha256=J5M-koNyzVHeTn0SGSJYbnTUKQ2B0rEI6zD_NU00z3Q,161
+nirium/client.py,sha256=VrfHjEvp9uyn376T_272enYZXx3E2t2oKX9pQZ6d4Tc,9229
+nirium-0.2.0.dist-info/METADATA,sha256=qvQYJftJCM7KQqNGYSB1IsnR6AEyjkP6kWRw-glFncA,2715
+nirium-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nirium-0.2.0.dist-info/top_level.txt,sha256=zxpE7vZKWqwB4nVbBlI-mtZS6lcRLGJW4ws9zHJA4Dg,7
+nirium-0.2.0.dist-info/RECORD,,

nirium-0.2.0.dist-info/WHEEL

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

nirium-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nirium