nirium 0.8.0

Official Python SDK for Nirium autonomous agents on Stellar (x402 + MPP)

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

pip install nirium

Quick Start

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)

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

# 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

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

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.

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.

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
• Developer Sandbox
• API Reference
• MCP Server Integration
• GitHub

License

Apache 2.0 — Nirium Protocol