nirium

Autonomous treasury and agentic-payments infrastructure for Nirium Protocol on Stellar/Soroban — Python client.

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}")

    # Trigger a demo strategy on Nirium's own shared testnet vault — a real,
    # working transaction, not a simulation, but it moves Nirium's testnet
    # funds, not yours. To rebalance YOUR OWN vault, see Treasury Rebalance below.
    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

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.

Treasury Rebalance

Two ways to rebalance a DeFindex vault between idle cash and an invested strategy. Neither is a swap — the contract's rebalance() exposes exactly two instructions, Unwind and Invest, and neither accepts a destination address, so withdrawing anywhere but back into the vault itself is not expressible.

Propose — you review and sign, available to everyone today

The agent decides what it would do, using the same decision logic as the autonomous signer below, but it never signs. Public, no allowlist, no invite required — works for any vault where you're already the on-chain rebalance manager.

proposal = await agent.propose_treasury_rebalance(
    vault="CABC...",
    caller="GABC...",   # must already be this vault's rebalanceManager on-chain
    enter_at=2.5,        # your own mandate — Nirium never supplies a default here
    exit_at=2.0,
)

if proposal["instructions"]:
    signed_xdr = sign_with_your_wallet(proposal["xdr"])
    await agent.submit_treasury_tx(signed_xdr)
else:
    print("Nothing to propose:", proposal["reason"])

Autonomous — Nirium signs, invite-only during legal review

execute_treasury_rebalance() has Nirium sign and submit with its own RebalanceManager key — full autonomy, no per-cycle approval. This is invite-only while a specific legal question stays open: whether executing on a client's behalf without taking custody still counts as regulated facilitation under Mexican law. It only runs against vaults explicitly allowlisted server-side; calling it against any other vault returns 403, and Nirium's mainnet infrastructure returns 501 for it entirely, since that box holds no signing key by design. Ask if you want autonomous execution today — otherwise, propose_treasury_rebalance() above gives you the same decision-making with you as the one who signs.

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

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