Metadata-Version: 2.4
Name: nirium
Version: 0.9.0
Summary: Official Python SDK for Nirium autonomous agents on Stellar (x402 + MPP)
Author: Nirium Team
Author-email: Nirium Protocol <niriumprotocol@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://nirium.xyz
Project-URL: Repository, https://github.com/nirium-protocol/nirium-sdk
Project-URL: Documentation, https://nirium.xyz/docs
Project-URL: Bug Tracker, https://github.com/nirium-protocol/nirium-sdk/issues
Keywords: nirium,stellar,soroban,defi,sdk,agent,autonomous,treasury,x402,mpp,agentic-payments,usdc,cetes,etherfuse,rwa
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: websockets>=13.0
Requires-Dist: stellar-sdk>=11.0.0
Dynamic: author
Dynamic: requires-python

# nirium

Official Python SDK for the **Nirium Protocol** — autonomous AI treasury infrastructure on Stellar/Soroban.

Nirium agents rebalance USDC ↔ CETES (tokenized Mexican T-bills via Etherfuse) 24/7 without human intervention. Built for developers who want to integrate autonomous treasury management, agentic payments (x402 + MPP), and real-time market signals into their applications.

## Install

```bash
pip install nirium
```

## Quick Start

```python
import asyncio
from nirium import Agent

agent = Agent(
    api_url="https://nirium-agent.fly.dev",
    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 treasury rebalance strategy
    result = await agent.execute("blend-yield", "USDC", {"amount": 5000})
    print(f"Success: {result['success']} | TX: {result.get('txHash')}")

asyncio.run(main())
```

## Real-Time Signals (WebSocket)

```python
agent = Agent(api_url="https://nirium-agent.fly.dev", 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://nirium-agent.fly.dev", api_key="sk_inst_...")

# With JWT token for WebSocket
agent = Agent(api_url="https://nirium-agent.fly.dev", api_key="sk_inst_...", token="eyJhbG...")
```

## Payment Protocols

### x402 — Pay-Per-Request
```python
agent.init_x402(
    secret_key="S...",          # Stellar secret key
    network="stellar:testnet"
)

response = await agent.x402_fetch("https://nirium-agent.fly.dev/api/v1/premium/signals")
```

### MPP — Session-Based Budget Delegation
```python
agent.init_mpp(
    secret_key="S...",
    network="stellar:testnet",
)

response = await agent.mpp_fetch("https://nirium-agent.fly.dev/api/v1/mpp/signals")
```

### 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 |
| **x402 Premium** | `/api/v1/premium/signals` ($0.02 USDC), `/api/v1/premium/market` ($0.05 USDC) |
| **MPP** | `/api/v1/mpp/signals`, `/api/v1/mpp/market` |

## Payouts

Batch disbursement, non-custodial: the node builds an **unsigned** transaction, you sign it with your own wallet and broadcast it. Nirium never holds funds and never sees your keys.

```python
run = await agent.create_payout_run(
    recipients=[{"wallet": "GABC...", "amount": "250.00"}],
    acknowledge_terms=True,   # required on every network — 403 without it
)

signed_xdr = sign_with_your_wallet(run["xdr"])
settled = await agent.submit_payout(run["runId"], signed_xdr)
print(settled["txHash"], settled["cid"])   # on-chain hash + IPFS receipt
```

Licensed for **independent service payments only** — contractors, freelancers, B2B. Not for subordinate-employee salary. Read `get_payout_terms()` before integrating; classifying recipients and meeting tax and labor obligations is the client's responsibility.

Mainnet is invite-only during early access and additionally requires `client_info`.

## Audit Trail

Anchor evidence to IPFS and get back a CID — an integrity seal, not notarization.

```python
anchor = await agent.anchor_audit_record(
    hash="sha-256:9f86d081...",   # hash of your own file or event
    tag="invoice-batch-jul",
)
print(anchor["cid"])
```

Anchor a **hash** rather than the data itself: IPFS content cannot be deleted, so raw personal data would outlive any erasure request.

## API Coverage

| Category | Methods |
|---|---|
| Health | `ping()`, `health()`, `system_health()` |
| Execution | `execute()`, `execute_demo()` |
| Market | `get_tickers()`, `get_market()`, `get_stats()`, `get_loop_status()`, `start_loop()`, `stop_loop()`, `trigger_scan()` |
| Signals | `create_subscription()`, `get_subscriptions()`, `delete_subscription()`, `get_subscription_stats()`, `get_recent_signals()` |
| Skills | `get_skills()`, `install_skill()`, `uninstall_skill()`, `get_skill_marketplace()`, `execute_skill_action()` |
| Strategies | `get_strategies()` |
| Webhooks | `register_webhook()`, `get_webhooks()`, `delete_webhook()`, `test_webhook()` |
| Auth | `get_auth_token()`, `create_auth_key()`, `get_auth_keys()`, `revoke_auth_key()` |
| Revenue | `get_revenue()`, `get_info()` |
| Nodes | `get_nodes()` |
| Payouts | `create_payout_run()`, `submit_payout()`, `onboard_payout_recipient()`, `submit_payout_onboard()`, `get_payout_runs()`, `get_payout_terms()`, `get_payout_info()` |
| Audit Trail | `anchor_audit_record()`, `get_audit_info()` |
| Reporting | `get_reporting_summary()`, `get_reporting_export()` |
| Admin | `configure_llm()` |
| WebSocket | `subscribe()`, `on()` decorator |
| x402 Payments | `init_x402()`, `x402_fetch()` |
| MPP Payments | `init_mpp()`, `mpp_fetch()` |

## Requirements

- Python >= 3.10
- aiohttp >= 3.9.0
- websockets >= 13.0

## Links

- [Documentation](https://nirium.xyz/docs)
- [Developer Sandbox](https://nirium.xyz/sandbox)
- [API Reference](https://nirium.xyz/docs/api)
- [MCP Server Integration](https://nirium.xyz/docs/mcp)
- [GitHub](https://github.com/nirium-protocol/nirium-sdk)

## License

Apache 2.0 — Nirium Protocol
