Nirium Protocol: Institutional Infrastructure on Stellar
⚠️ MANDATORY LEGAL DISCLAIMER
Nirium is experimental software. Nirium's own NiriumVault treasury contract remains on Stellar Testnet, audit-gated: no independent third-party audit has occurred yet, and no real client funds ever reach that contract.
The autonomous treasury node runs on mainnet over a DeFindex vault the client owns: a third-party contract audited by OtterSec, not ours. Nirium holds only the vault's RebalanceManager role, which by the contract's own design cannot withdraw funds, change roles, or pause anything. Autonomous rebalancing on mainnet is invite-only while a legal review closes. A separate set of receive-only nodes (x402 micropayments, IPFS audit anchoring, non-custodial Payouts, Reporting) also run in mainnet early access; several move real USDC under the client's own wallet signature - see the evidence table below for which ones. MPP Charge is testnet-only and experimental: verified with settled payments on testnet (15 Oct 2026), but it has never settled on mainnet - see the evidence table's MPP row for the exact status. Nirium never custodies funds.
Update, 2026-10-08 (checked against the live /api/tickers on both networks that day): until today the site, the API and the docs showed a CETES rate of 5.57% under labels such as "Banxico ref", "Today" and, on one dashboard card, "LIVE". It was a fixed reference value read once from app.etherfuse.com/b/cetes in June 2026, not a live reading and not from Banxico. The labels are corrected; the value itself is unchanged and still not live. The same release stops publishing 1 / xlmPrice as the USDC price in /api/tickers: that figure (about 5.25) was how many XLM one dollar buys, and is now null.
Nirium is not financial advice. It is not an investment product. It does not guarantee yields, dividends, asset appreciation, or returns of any kind. Reference rate data shown on the dashboard (Blend supply rate, Etherfuse CETES rate) is public protocol information only, not projections or promises of return. XLM and Stellar assets are volatile. Smart contracts carry risk even when audited. Use at your own risk.
This project does not use grant funds for speculation, trading, investment advice, or marketing of products promising interest or appreciation, in accordance with the Stellar Community Fund Official Rules.
Nirium is an Infrastructure-as-Software provider: autonomous treasury and agentic payments (x402; MPP experimental) on Stellar/Soroban, not a consumer dashboard.
The hero product is the rail, not the data. A 102-endpoint API and TypeScript/Python SDKs that let any B2B fintech both pay for machine-to-machine services and charge for its own, plus autonomous execution nodes that run treasury operations 24/7 without manual CFO intervention.
Execution Nodes
| # | Node | Status | Network | What it does |
|---|
| 1 | Settlement (x402 active; MPP Charge experimental) | x402 ✅ Active · MPP ⚠️ Experimental | both | Per-request micropayments for AI agents. Pay for others' APIs with initX402() today - x402 has confirmed mainnet settlements (see the evidence table below). MPP Charge is implemented but experimental: verified on testnet on 15 Oct 2026 with settled payments in pull and push mode (it had rejected a valid payment on 1 Oct); mainnet is unverified. Update, 2026-10-07: this previously said charging for your own with x402Serve() was invite-only, same gate as Treasury and Payouts - there is no such gate. x402Serve() is a general-purpose library that runs on the integrator's own server; Nirium does not operate or gate it. Legal review of third-party use is open - compliance is the integrator's own responsibility. |
| 2 | Audit Trail | ✅ Active | both | Evidence anchored to IPFS as immutable receipts, optionally signed by the agent that produced it (ed25519 over a domain-separated statement), so the CID proves not just that a fact is unaltered but who declared it. |
| 3 | Payouts | ✅ Active (mainnet invite-only) | both | Non-custodial batch disbursements, up to 100 recipients per transaction. Mainnet is invite-only; independent service payments only (contractors, freelancers, B2B); never subordinate-employee salary. A milestone variant (Trustless Work Multi-Release - one contract, a distinct receiver per milestone) runs on testnet: GET /api/payroll/escrow/info. |
| 4 | Treasury Rebalance | ✅ Active (mainnet invite-only) | both | Moves idle capital into a CETES strategy and back, on its own, over a DeFindex vault the client owns. Live on mainnet, invite-only during legal review. |
| 5 | Reporting | ✅ Active | both | Institutional-format summaries and CSV/JSON exports over anchored receipts. Read-only; regulatory filings remain the client's responsibility. |
| 6 | Compliance Sentinel | 🟡 Proposed | testnet | Not built, for Nirium's own proposed transfers specifically: the intent is a server-side auditor that validates each one against a policy before it is signed. What exists today for that exact direction is the agent-to-agent x402 client pattern in ; the auditor endpoint it calls does not exist yet, and the call fails open by design so a downed auditor never blocks execution. Do not rely on this as a control. : the SDK's client-side pre-sign policy hook (, experimental since 0.16.0) lets a - not Nirium's own execution - get an ALLOW/DENY from their own policy before any x402 payment is signed. See for its scope and limits. |
The framework supports up to 10 nodes per vault. Live catalog: GET /api/nodes.
What runs where, and how to check it yourself
Every claim below is a link. Nothing here asks to be believed.
Status at a glance
| Product | Status |
|---|
| x402 | Live in production, mainnet |
| Audit Trail | Live in production, mainnet |
| Reporting | Live in production, mainnet |
| Treasury Rebalance | Mainnet, invite-only |
| Payouts | Mainnet, invite-only |
Policy hook (pre-sign ALLOW/DENY) | Experimental |
| MPP Charge | Testnet only |
The detailed tables below back each row with a transaction hash or a live endpoint - this one is just the summary.
Mainnet (real value)
| What | Status | Verify |
|---|
| API box | Live, receive-only, holds no signing key, enforced at startup | /health · /api/nodes |
| x402: first real payment | Settled 9 Jul 2026 | 3134a51c…7558bc |
| x402: paid from a social login (Pollar) | Settled 5 Aug 2026, holding zero XLM end to end | e4fa3df9…16ed9 |
nirium-pollar-adapter: end-to-end from a clean npm install | Settled 27 Jul 2026, standard Stellar keypair signer (the pluggable-signer test, not Pollar-specific) | 48136451…3795e · receipt QmRzgTtVPg… · Update, 2026-10-07: the receipt above no longer resolves on the Pinata gateway (404 on two checks). The original bytes are not kept in this repo, so it was not re-pinned under the same CID. The payment itself is verifiable on Stellar Expert. |
| MPP Charge | Experimental: implemented, charge.enabled: true on both networks; testnet verified 2026-10-15 with settled payments in pull and push mode (b8c4ed56…, ); mainnet unverified, no confirmed mainnet settlement ( this row previously read "Live: charges and delivers" without a transaction hash, unlike every other row in this table. A 2026-10-01 end-to-end test found the testnet box rejecting real payment proofs with , including a push flow where the payment settled on-chain but the content was never delivered; the root cause was not determined. No MPP Charge-tagged credit appears anywhere in the mainnet recipient's payment history, past or since. re-tested with against the testnet box: and both settled and delivered, so the 1 Oct failure no longer reproduces. Mainnet is still untested.) |
Testnet (no real value, where the loop and the key live)
| What | Status | Verify |
|---|
| API box | Live, full autonomous loop, agent holds a key | /health · /api/loop/status |
| NiriumVault | Live: treasury, delegation, flash loans, 2-of-3 multisig | CBTWMZCG…AWSZU |
| NiriumProtocol | Live: ELO, marketplace, scoring, skill gate | CC2TU5BD…FR5L5NR5 |
| Policy Account | Live: one CallContract rule, no Default rule | CCZW2WIF…B5LML |
| Treasury: full cycle, 5 Aug 2026 | deploy → deposit → autonomous invest | a96eec81…a2662 → 2c4df5a8…2c3b7 → c53d4746…52ed3 |
| Trustless Work escrow: full cycle, 2 Sep 2026 | deploy (human) → allowlist gate confirmed blocking, then permitting → approve + release milestone, both agent-signed | |
Signed audit evidence (anyone can verify with only the CID)
Each document carries an ed25519 signature over nirium-audit-v1:<content_sha256>, so the CID proves not only that the fact is unaltered, but who declared it.
The two networks are not two copies of the same thing. Testnet is where the agent holds a key and rebalances on demand. That is the demonstration. Mainnet is where real value moves, and there the API box holds no key at all: a separate process with no HTTP surface signs the rebalances, and every fund movement a client makes is signed by the client. Never quote a testnet figure as if it were mainnet: deploying a vault costs ~0.038 XLM on testnet and ~1.4 XLM on mainnet, 47× more.
The Treasury Node: how an agent moves someone else's money without being able to take it
This is the part that took the longest to get right, and it is worth stating precisely because the safety does not come from our promises.
The client deploys a DeFindex vault (a third-party Soroban contract) with their own signature. That vault has four roles:
| Role | Held by | Can do |
|---|
| Manager | the client | everything: pause, rescue, change roles |
| Emergency Manager | the client | emergency stop |
| Fee Receiver | the client | collect the vault fee (we set it to 0) |
| RebalanceManager | Nirium | rebalance() and nothing else |
rebalance() accepts four instructions: Invest, Unwind, SwapExactIn, SwapExactOut. None of them takes a destination address: to is hardcoded to the vault itself in every branch. Withdrawal is not forbidden, it is inexpressible. This was verified by reading DeFindex's source (not its docs) and confirmed by submitting real transactions: Soroban's simulator records require_auth() without verifying signatures, so simulating gives a false pass.
The client can call set_rebalance_manager and remove us unilaterally, without notice, and we cannot stop them.
Verified on mainnet, with real funds:
That second transaction is the whole argument turned into evidence: the agent moved someone else's funds, and the contract gave it no way to take them out.
Audit scope, stated honestly: the vault is DeFindex, audited by OtterSec (March 2025, 16 findings total - 13 of them vulnerabilities, all resolved; the other 3 were non-vulnerability suggestions), running a Blend V2 strategy (3 independent audits). The deployed WASM matches the public 1.0.0 release. What is not covered is the Etherfuse pool as an external dependency and each instance's configuration. Fees: Nirium takes no percentage of your capital; DeFindex, the protocol behind the vault, takes 20% of the yield it generates.
Update, 2026-10-24 (checked against the live SCF Integration List and on-chain contract data that day): the CETES strategy above runs on a Blend lending pool (CDMAVJPFXPADND3YRL4BSM3AKZWCTFMX27GLLXCML3PD62HEQS5FPVAI, read directly from the strategy's own on-chain config). Blend currently carries "Note: Blend temporarily removed from list" on SCF's own Integration List (stellar/scf-handbook), its entire row struck through, while under review. Two real 2026 incidents hit Blend: YieldBlox/Blend V2 (~22-Feb-2026, ~$10.2-10.8M, an oracle misconfiguration via thin USTRY liquidity) and the Comet BLND-USDC backstop pool (~25-Aug-2026, ~$717K, a same-asset swap-accounting bug that paused Blend's backstop). Neither incident's affected pool is this one - YieldBlox's exploit drained a different pool entirely (CCCCIQSDILITHMM7PBSLVDT5MISSY7R26MNZXCX4H7J5JQ5FPIYOGYFS), and the Comet incident hit a separate backstop AMM pool (CAS3FL6TLZKDGGSISDBWGGPXT3NRR4DYTZD7YOD3HMYO6LTJUVGRVEAM), not any lending pool; Blend itself stated lending-pool depositors were not at risk in the August incident, only backstop depositors. This is not a claim that the Etherfuse/CETES pool is risk-free - only that it was not the pool involved in either known 2026 incident.
The mainnet signer is a separate process with its own key and no HTTP surface: the mainnet API box holds no signing key at all, by design, and enforces it at startup.
Why now
Market context, high-confidence sources only - this is not traction (see the next section for that), and none of it implies any relationship with Nirium unless stated.
- Mastercard published Verifiable Intent (mastercard.com), an open standard for proving what a user actually authorized in an agent payment. Its own spec repo has two open issues asking the exact question Audit Trail already answers: #37 ("does VI check that a purchase matches what the user asked for, not only that it was authorized?") and #42 (what evidence anchors a decision after the fact). Verifying the payment is not the same problem as verifying the decision - that gap is Audit Trail's whole premise.
- Tokenized RWA on Stellar grew 360%+ in 2026, nearing $4B, with roughly $490M of it non-U.S. sovereign debt - CETES included - per Cointelegraph (cointelegraph.com). This is the asset class the Treasury Node rebalances into.
- MPP shipped on a production mainnet: Stripe and Tempo launched the Machine Payments Protocol on Tempo's mainnet in March 2026 (theblock.co). Nirium's own MPP Charge mode is testnet-only (see the status table above) - cited here as evidence the protocol itself is moving toward production elsewhere, not as our own traction.
- Institutional auto-renewal infrastructure went live on Stellar: Ascend and M1X Global completed the first institutional repo on Stellar using a sovereign-bond-backed stablecoin, with 72 automated hourly rolls over three days, announced 23-oct-2026 (businesswire.com). Unrelated to Nirium - cited only as a market signal that institutional-grade automation is landing on this chain.
Market Traction: Developer Adoption & Verifiable On-Chain Activity
Traction is self-generated and independently verifiable. It does not depend on third-party announcements:
-
Published SDKs on npm and PyPI (nirium) with recorded downloads across multiple versions.
-
Live autonomous agent running 24/7 on Stellar Testnet, every rebalance verifiable on Stellar Expert.
-
Real mainnet activity: x402 micropayments settling in production, and a full treasury cycle executed with real funds (hashes above).
-
Open API + free sandbox keys, so any developer can integrate and exercise the contracts directly.
-
Real upstream engagement - issues we filed and fixes we shipped against the
Stellar and x402 ecosystems, most recent first. Every row links to the public thread;
status is as of 2026-10-22 - the two most recent rows were verified live that day
against the GitHub API, the rest were re-verified 2026-10-12 and carry their own
row-by-row status.
| Date | Where | What we reported / did | Outcome |
|---|
| 2026-10-22 | x402-foundation/x402#3338 | A documented ceiling on SettlementOverrides.amount (never more than PaymentRequirements.amount) was never actually enforced. Fix lives in @x402/core's resource server, upstream of any one integrator. | Merged by maintainer CarsonRoscoe. Team-wide upstream contribution, not exclusive to this product - the same author also ships Periplo on x402, and both projects' own traction docs cite this merge. |
| 2026-10-22 | x402-foundation/x402#3339 | Docs: areFeesSponsored: false is accepted on the Stellar scheme constructor with no validation, and the resulting limitation wasn't cross-referenced where a developer would read it. Fix lives in @x402/mechanisms/stellar's facilitator scheme, the shared Stellar mechanism every x402-on-Stellar integrator imports. | Merged by maintainer CarsonRoscoe. Team-wide upstream contribution, not exclusive to this product - see the #3338 note above. |
| 2026-09-09 | stellar/stellar-mpp-sdk#68 |
We provide the middleware; regulated operators (e.g. Etherfuse) hold the licenses and execute settlement. We are open to integration conversations with regional fintechs. We have two signed letters of intent: Pollar (2026-10-08) and Trustless Work (October 2026, the letter carries no day). A letter of intent states what each side means to build; it is not a pilot, a paid engagement, or production use, and we make no claim of signed pilots.
Update, 2026-10-12: this sentence previously read only "make no claim of signed pilots". That was still true, but it left out the two letters of intent. The Pollar date is the signing date; the Trustless Work letter is dated only by month. Neither counterparty is running Nirium in production today.
Architecture
Fintech / Institution (B2B / A2A)
|
v
[Next.js 15 Dashboard: nirium.xyz]
[i18n: EN / ES, 27 routes]
|
v
[Agent API: dual network, 102 endpoints]
|-- nirium-agent.fly.dev (testnet, full autonomous loop, agent holds a key)
|-- nirium-agent-mainnet.fly.dev (mainnet, receive-only, NO signing key by design)
|-- Auth (JWT / API key / sandbox tiers)
|-- legalShield middleware (SCF CoC compliance)
|-- x402 + MPP payment middleware
|-- Sliding-window rate limiting (300 rpm institutional)
|-- domainLock + obfuscation code exists but is not mounted on any route
| (Update, 2026-10-07: this line previously also listed "AML screening" as part
| of the Agent API. That middleware was never imported or mounted anywhere in
| the codebase since it was written - dead code, not a live control - and has
| been removed. domainLock and obfuscation remain in the repo, equally unmounted.)
|
v
[Autonomous Execution Layer]
|-- Autonomous node: LLM proposes, deterministic fallback decides if it stalls
|-- Mainnet rebalancer: separate process, own key, no HTTP surface,
| deterministic rule with no model in the signing path
|-- Composable framework: up to 10 Execution Nodes per vault
|
v
[Soroban Contracts]
|-- Testnet: NiriumVault (treasury, flash loans, delegation, 2-of-3 multisig)
|-- Testnet: NiriumProtocol (ELO reputation, strategy registry, scoring, skill gate)
|-- Testnet: Policy Account (scopes the agent key to ONE vault: one CallContract
| rule, no Default rule; that absence IS the mechanism)
|-- Mainnet: DeFindex vault (third-party, OtterSec-audited, owned by the client;
| Nirium holds RebalanceManager only)
|
v
[Supabase] ← logs, auth_keys, webhooks, payroll_runs, treasury_vaults, subscriptions
[IPFS / Pinata] ← immutable receipts; daily digest of confirmed executions
Core Features
Institutional API (102 endpoints: 101 HTTP + 1 WebSocket)
Multi-tier authentication with sandbox accounts, self-service API keys (/keys, wallet-signed via SEP-53), tiers (free/sandbox/institutional/enterprise), and JWT for WebSocket. Full RBAC, sliding-window rate limiting. Update, 2026-10-07: this previously also said "AML checks, and domain lock" as live controls. Neither was ever mounted on any route - the AML middleware has been removed as dead code, and the domainLock/obfuscation modules remain in the repo, unused.
| Access level | Endpoints |
|---|
| Public (no key) | health, loop/status, execute-demo, signals/recent, skills, nodes, netdiag |
| Protected (API key) | execute, market, tickers, stats, loop control, webhooks, subscriptions, skills/install, payroll/*, treasury/* |
| Paid (x402 / MPP) | premium/*, mpp/* |
| WebSocket (JWT) | /ws/signals, real-time signal stream |
| Admin only | system/health, config/llm |
Endpoints charge where the capability exists, not where it reads better. The mainnet box holds no signing key and runs no autonomous loop, so premium/signals and premium/execute return 501 there instead of charging for an empty answer. premium/market charges and delivers on both networks.
Full specification: API_DOCUMENTATION_OPENAPI.yaml
Autonomous On-Chain Execution (Soroban)
Strategies dispatched to the NiriumVault contract on testnet, all verifiable on Stellar Expert:
flash-loan-arb / flash-loan → flash_loan_execute: atomic flash loans with automatic revert on non-repaymentpath-arbitrage / path-vector → execute_path_arbitrage: path payment discovery for XLM-USDC corridorscross-dex → execute_cross_dex: cross-venue routingblend-yield → execute_blend_yield: non-custodial allocation on Blend Protocolsoroswap-swap → execute_soroswap_swap: multi-hop execution with minimum-slippage enforcement
The mainnet treasury path does not go through this router. It goes through the client-owned DeFindex vault described above.
x402 + MPP + MCP
Any AI agent (Claude, GPT, custom) can access Nirium's premium data per request by paying USDC on Stellar: no account, no subscription. Adopted on launch day alongside emerging industry standards:
- x402 integrated April 2, 2026: same day as the Linux Foundation x402 Foundation launch
- MPP integrated April 3, 2026: 16 days after the spec was published (March 18, 2026)
Both directions are supported. initX402() pays for someone else's API, live today. x402Serve() charges for yours. Update, 2026-10-07: this previously said third-party facilitator use was invite-only, same gate as Treasury and Payouts - there is no such gate. x402Serve() is a general-purpose library that runs on the integrator's own server; Nirium does not operate or gate it. Legal review of third-party use is open - compliance is the integrator's own responsibility:
import { x402Serve } from 'nirium';
app.use('/premium', x402Serve({
payTo: 'G...',
routes: { 'GET /signals': '$0.02' },
}));
MPP Charge is experimental: implemented and verified on testnet (settled payments in pull and push mode, 15 Oct 2026); mainnet is unverified. Its design: the client signs a complete USDC transfer inside the request, the server validates it by simulation and broadcasts it, with no external facilitator. MPP's Channel mode is implemented but disabled, because its setup phase deploys a channel contract holding a deposit, which is temporary custody and falls under the same audit gate as our own vault.
The MCP server exposes Nirium as 25 tools for Claude Desktop, Cursor, and any MCP-compatible IDE: 10 free, 9 authenticated, 1 informational, 3 paid over x402, 2 MPP tools (experimental).
Audit Trail Engine
Agent action or third-party event
→ SHA-256 content hash
→ optional agent attestation: ed25519 signature over
"nirium-audit-v1:<content_sha256>" (domain-separated on purpose:
without it, a signature made for a login could be replayed as evidence)
→ pinned to IPFS, CID returned
→ verifiable by anyone holding only the CID
An invalid signature returns 400 and nothing is anchored: IPFS has no delete, so a false attestation would be permanent. Third-party apps anchor through POST /api/audit/log. Anchor hashes, not raw personal data.
Live Market Ticker (Reference Data)
Public protocol information. Not investment advice and not a return projection.
| Ticker | Source | Description |
|---|
| XLM/USDC | Reflector → CoinGecko → Stellar Expert | Multi-tier oracle price feed |
| SDEX spread | Stellar Horizon orderbook | Live XLM/USDC spread in basis points |
| Blend rate | Blend Protocol on-chain | Liquidity reference rate |
| CETES rate | Etherfuse (fixed reference) | Fixed reference value 5.57%, read 2026-06 from app.etherfuse.com/b/cetes; not updated live |
| Base fee | Stellar Horizon | Live network base fee |
Published SDKs (npm + PyPI)
The two SDKs share full Treasury parity (12 methods, proposeTreasuryRebalance()/propose_treasury_rebalance() included) since 10-sep-2026. x402Serve() stays TypeScript-only - it's Express middleware, server-side Node, with no meaningful equivalent in an async Python client. Going the other way, Python ships a resilient, auto-reconnecting WebSocket client (backoff, jitter, dedup) and a LangChain BaseTool (pip install nirium[langchain]) that TypeScript doesn't have yet - the gap runs both directions, not just one.
import { Agent } from 'nirium';
const agent = new Agent({ apiKey: 'sk_inst_...', baseUrl: 'https://nirium-agent.fly.dev' });
const market = await agent.getMarket();
const nodes = await agent.getNodes();
await agent.anchorAuditRecord({ hash: '...' });
agent.subscribe(signal => console.log(signal));
import asyncio
from nirium import Agent
async def main():
agent = Agent(api_url="https://nirium-agent.fly.dev", api_key="sk_inst_...")
market = await agent.get_market()
await agent.anchor_audit_record(hash="...")
@agent.on("signal")
async def on_signal(data):
print(data)
await agent.subscribe()
asyncio.run(main())
See SDKs.md for full SDK documentation.
Deployed Contracts
| Contract | Network | Contract ID | Function |
|---|
| NiriumVault (Vault ID 1 active) | Testnet | CBTWMZCG3P72EHFAQ4ZLSEBIOFYJC244H5J6DHZIJ56FHFWJ2CFAWSZU | Core treasury: vaults, agent delegation, strategy execution, flash loans, 2-of-3 multisig |
| NiriumProtocol | Testnet | CC2TU5BDTKTPRRRQPEF77I54XYHFQ25XGIRO2TCWKSR7NRJDFR5L5NR5 | Unified registry: ELO reputation, strategy marketplace, agent scoring, skill gate (x402) |
| Policy Account | Testnet | CCZW2WIFAD7OQX35U5AILTNF32TCHQUYVPNB32GGKEKKPII2HF7B5LML | Scopes an agent key to a single vault: one CallContract rule, no Default rule |
| DeFindex vault (reference) | Mainnet | CAMDXG6L4LXLXXV675KZSHM3BMSETZ4NVMC7JYIQCZ2JTG54OMSK57MH | Third-party, OtterSec-audited, owned by its deployer; Nirium holds RebalanceManager only |
Verifiable at Stellar Expert.
Side Projects
/build: Startup Ideas Hub
Interactive dashboard with 12 production-ready startup ideas buildable on the Nirium API and SDKs, with code examples in TypeScript, Python, cURL, and MCP.
Live: nirium.xyz/build
Quick Start
Requirements
- Node.js >=22.12.0, pnpm 9+ (
@stellar/stellar-sdk 16.x requires 22.12.0+; an older Node resolves an older, incompatible SDK silently)
- Freighter Wallet for dashboard interactions
Run locally
pnpm install
pnpm dev # web (port 3000) + agent API (port 3002) in parallel
Deploy
pnpm ship # → vercel --prod (frontend)
fly deploy # agent API → Fly.io (run from the repo root)
SDK quick start
npm install nirium # TypeScript SDK
pip install nirium # Python SDK
Project Structure
nirium-core/ (public repo)
├── apps/web/ → Next.js 15 dashboard (nirium.xyz), 27 routes, i18n (EN/ES)
├── packages/sdk/ → TypeScript SDK v0.16.1 (npm: nirium)
├── packages/sdk-python/ → Python SDK v0.11.0 (PyPI: nirium)
├── nirium-soroban-contracts/ → Soroban contracts (Rust): NiriumVault + NiriumProtocol, both deployed on testnet, 5 fuzz targets
├── packages/policy-account/ → Soroban policy account (Rust), scopes a key to one vault
├── .github/workflows/ → CI, release, security-gate, desktop release
│
├── packages/agent/ → [private] Express 5 API, 102 endpoints (101 HTTP + 1 WebSocket)
├── packages/mcp/ → [public] MCP server v0.6.3, 25 tools
├── packages/cli/ → [public] CLI v3.0.0 (npm: nirium-cli)
├── packages/desktop/ → [private] Tauri desktop wrapper
Security
- Internal self-review only. No external audit and no penetration test has been done. The report lists method, findings, fixes and what was left out; it carries no score and no certification.
- Methodology: static analysis (
cargo clippy, grep), runtime checks on testnet, cargo audit + pnpm audit in CI, fuzz smoke runs (5 cargo-fuzz targets), manual code review
- Update, 2026-10-12 (checked against
INTERNAL_SECURITY_AUDIT.md and CI that day): this section previously stated "83/83 vectors checked" and named the method "full-spectrum pentesting". The score and that label were removed: no pentest was performed and a pass count over our own checklist is not evidence an outside reader can check.
- A formal independent audit is planned before any mainnet deployment of NiriumVault. The mainnet nodes running today do not depend on it: they either never touch funds (x402, audit, reporting), or the client signs every fund movement themselves (Payouts), or they operate a third-party contract already audited by OtterSec in a role that cannot withdraw (Treasury).
- The mainnet API box holds no signing key, enforced at startup. The autonomous mainnet signer is a separate process with no HTTP surface.
- See SECURITY.md for responsible disclosure, and INTERNAL_SECURITY_AUDIT.md for the full report.
Stellar Code of Conduct Alignment
Nirium operates in alignment with the Stellar Code of Conduct.
| Principle | Nirium status |
|---|
| Stellar must be core and valuable, not auxiliary | ✅ Soroban contracts, SDEX, Blend, DeFindex, x402; MPP experimental; Stellar is the execution layer |
| No speculation, wash trading, or insider trading with grant funds | ✅ Grant funds allocated to development, not trading |
| No investment advice or yield promises | ✅ Prominent disclaimer; rates displayed as protocol reference data only |
| No marketing promising interest, dividends, or appreciation | ✅ Language focuses on workflow automation, not guaranteed returns |
| Open source, contracts and SDKs publicly available | ✅ Soroban contracts + TypeScript SDK + Python SDK in the public repo |
| Transparency | ✅ Every protocol action auditable on-chain via Stellar Expert |
| Integrity | ✅ No front-running or predatory extraction |
| Safety | ✅ Non-custodial by design; the user is the sole custodian of their keys |
To report violations: [email protected]
SCF Instawards
Nirium received two Stellar Community Fund Instawards, through the Stellar Ambassador Program (a regional chapter assists the submission), with full KYC complete (Airtable + Persona + W-8BEN). Instawards are SCF's early-stage awards for prototyping and local validation, up to $15,000 per project. More info: communityfund.stellar.org
Update, 2026-10-12: this section was titled "SCF Kickstart" and described the awards under that name. Sources, read from the SCF handbook (stellar/scf-handbook) on 2026-10-12: additional-support/history-of-scf.md says SCF Kickstart is the former Startup Camp (a bootcamp), not the awards program; scf-awards/instawards/README.md describes Instawards as offered through local Stellar Ambassador Chapters.
Roadmap
| Milestone | Status |
|---|
| Core infrastructure + x402 on testnet | ✅ Complete · MPP experimental |
| Institutional API (102 endpoints) + published SDKs | ✅ Complete |
| Internal security self-review (no external audit; see report) | ✅ Complete |
| MCP server v0.6.3, 25 tools | ✅ Complete |
| Etherfuse CETES integration (testnet + SPEI sandbox) | ✅ Complete |
Self-service API keys console (/keys, wallet-signed via SEP-53) | ✅ Live |
| Mainnet receive-only nodes (x402, Audit Trail, Reporting) | ✅ Live, early access |
| MPP Charge, mainnet receive-only node | 🟡 Implemented, experimental - no confirmed mainnet settlement yet, see the evidence table above |
| Payouts node, non-custodial batch disbursements | ✅ Live, mainnet invite-only |
x402Serve(), charge for your own API in one call | ✅ Shipped in SDK. Update, 2026-10-07: previously said third-party use was invite-only during legal review - there is no such gate. It's a general-purpose library the integrator runs on their own server; Nirium does not operate or gate it; compliance is theirs |
| Agent attestation in the audit trail (signed evidence) | ✅ Shipped |
| Treasury node on mainnet over a client-owned DeFindex vault | ✅ Live, invite-only during legal review |
| Legal opinion on the treasury node (MX + cross-border) | 🔄 In progress: gates opening it beyond invite-only |
| Etherfuse, enterprise KYB onboarding | Update, 2026-10-14: this row previously read "In progress". Etherfuse told us they cannot commit to a partnership or KYB track at this time, only co-marketing. Closed, not in progress. |
| Stellar Community Fund Build Award | 🔄 Building verifiable third-party traction before applying |
| Formal independent audit of NiriumVault | Planned, ahead of any NiriumVault mainnet deployment |
| NiriumVault mainnet deployment (real treasury funds) | Post formal audit |
External Credentials
- 3rd place, Fintech World Cup Mexico 2026: Sui Loop (founder's prior project; architecture migrated to Nirium on Stellar)
- Stellar Community Fund Instawards (2), via the Stellar Ambassador Program; full KYC complete (Airtable + Persona + W-8BEN)
- Update, 2026-10-12 (checked against this repository): this list previously included "Stellar Scale / Kickstart: 83/100 Bootcamp Impact; active graduate with ongoing SDF mentorship". The line was removed because it could not be verified (no source for the 83/100 figure or for an SDF mentorship), not reworded.
- Update, 2026-10-14 (confirmed directly with Etherfuse): this line previously read "active technical integration (CETES on testnet + SPEI sandbox); enterprise KYB onboarding in progress". We used Etherfuse's CETES vault via DeFindex (4 mainnet rebalances, 6-Aug-2026); no partnership or KYB is in progress.
Documentation
Developer Quick Start
# Testnet: no real funds required
curl https://nirium-agent.fly.dev/health
# The node catalog: no key needed
curl https://nirium-agent.fly.dev/api/nodes
# Sandbox API key (free)
curl https://nirium-agent.fly.dev/api/sandbox/status \
-H "x-api-key: YOUR_SANDBOX_KEY"
# WebSocket: real-time signals
wscat -c "wss://nirium-agent.fly.dev/ws/signals?token=YOUR_JWT"
Contact
Legal
The code in this repository (smart contracts, libraries, MCP server, CLI and web app) is open-source and licensed under the Apache License 2.0, which covers the Stellar Community Fund open-source requirement for smart contracts. The hosted agent API (packages/agent) and the desktop wrapper are private and are not part of the public repository.
For full details, see LICENSING.md.
This project operates under the Stellar Community Fund framework and the Stellar Code of Conduct.
Nirium Protocol: experimental software. Not financial advice. NiriumVault is testnet-only and audit-gated; the mainnet treasury node runs over a client-owned, third-party audited DeFindex vault in a role that cannot withdraw. Updated October 23, 2026.
