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 coordinationService; 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. A related but different mechanism is shipped: the SDK's client-side pre-sign policy hook (initX402({ policy }), experimental since 0.16.0) lets a payer - not Nirium's own execution - get an ALLOW/DENY from their own policy before any x402 payment is signed. See packages/sdk/README.md#pre-sign-policy-hook-experimental 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…, 96d43d6f…); mainnet unverified, no confirmed mainnet settlement (Update, 2026-10-07, checked live against Horizon and /api/v1/mpp/info: this row previously read "Live: market 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 verification-failed, 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. Update, 2026-10-15: re-tested with nirium@0.16.1 against the testnet box: pull and push both settled and delivered, so the 1 Oct failure no longer reproduces. Mainnet is still untested.)	/api/v1/mpp/info
Treasury: vault deployed	6 Aug 2026, client signs	93ff6284…78416
Treasury: autonomous invest	6 Aug 2026, the agent signs	82d73f53…6b3d4
Treasury: the vault itself	Client-owned, roles readable on-chain	CAMDXG6L…K57MH
Payouts	Live, invite-only (tier-gated + terms acceptance)	/api/payroll/info
Trustless Work escrow: deploy path timing, 3 Sep 2026	Real deploys, self-owned wallets only - not the milestone fast-signer below, which stays testnet-only	65568e79…f2f3d6e (Horizon direct) · 7d5690cf…02e4b9e6 (via Trustless Work's own relay)
Trustless Work escrow: full cycle, 3 Sep 2026	deploy → fund → approve → release, real 0.50 USDC, self-directed (one key, every role, no third-party client). Proves the mechanism - not a decision to open this flow to Payouts production, which stays behind legal review	4110dd16…12aefe84 → 7b181a13…451c09c → a3aa35a2…4096ca5 → 0c533088…a8192b - receiver balance moved by exactly 0.4985 USDC, 0.50 minus Trustless Work's fixed 0.3% fee
Audit + Reporting	Live	/api/audit/info · /api/reporting/info
Autonomous rebalancing	Invite-only while a legal review closes	enabling a vault takes a commit to this repo, with author and date
NiriumVault (our own contract)	❌ Not on mainnet: audit-gated	n/a
MPP Channel mode	❌ Not on mainnet: deposit contract = temporary custody, same audit gate	channel.enabled: false
LCP legal layer	❌ Off: terms pending legal review	n/a

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	8c89ede2…5921f13
Autonomous rebalancing	Live and open: this is the demonstration	/api/loop/status
x402 signals / execute	Live and paid: the loop and the key exist here	/api/v1/premium/signals → 402

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.

Document	CID
Milestone attestation	QmYNvmR7C5Fivm7G1THbo5qd7jCp1nYoWMDkbmBmHibYvk · Update, 2026-10-07: this CID returned 404 on two checks against the Pinata gateway, so it is not currently retrievable from there.
Dispute attestation	QmSSZdtt3dQ8BqUm62zrKQ85E4BUHYiVfvDgZmHfJsqU1U · Update, 2026-10-07: the Pinata gateway answered 404 on one check and 200 on another, so availability is intermittent. Verify before relying on this link.

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:

Step	Who signs	Transaction
Deploy vault	the client	93ff6284…78416
Invest into strategy	the agent	82d73f53…6b3d4

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	Two mainnet SAC contract addresses in the official MPP SDK fail Stellar's own StrKey validation (USDC_SAC_MAINNET 54 chars, XLM_SAC_MAINNET 55) - we wrote the fix.	Merged as #69. Follow-up #72 (contributor jeesunikim, open) derives the literals from asset code + network passphrase so the typo class can't recur.
  2026-09-09	OpenZeppelin/relayer-plugin-x402-facilitator#47	OpenZeppelin's mainnet x402 facilitator sponsor (GA5SXMFJ…) has gone 30+ days with zero successful settlements while still listed as the sole stellar:pubnet signer - the mainnet paid path is down for every integrator.	Fixed and closed by an OpenZeppelin maintainer on 2026-09-14. After a month across two official channels the facilitator was restored; we confirmed it with an unmodified mainnet payment on 2026-09-11 and a second integrator confirmed the same on 2026-09-12. Update, 2026-10-12 (checked against the GitHub API that day): this row previously read "Open ... investigating"; the issue closed on 2026-09-14 and the row had not been revisited.
  2026-09-05	stellar/stellar-dev-skill#97	Production patterns for x402 + MPP, through multi-round review from the Foundation's own bot.	Merged. The review surfaced two real security bugs in our own production code - a paid route that could silently serve for free when its payment middleware wasn't initialized - fixed in MPP (c54c707d) and, once confirmed live, in the mainnet-settling x402 route (e88b2360).
  2026-08/09	stellar/js-stellar-sdk#1655, #1683, #1681, #1700	Delegate-signing path (needsNonInvokerSigningBy()/signAuthEntries()/authorizeEntry()) wasn't walking CAP-71 delegate trees or verifying signers beyond the root node. Our own PR for this, #1672, never merged - replaced by the maintainer's own fix.	#1655 fixed via maintainer's PR #1747 (28-sep); #1683 via PR #1742 (24-sep); #1681 via PR #1743 + #1744, closed by us after confirming both merged; #1700 closed via a docs-only PR (#1745) documenting the gap as a known limitation, not a code fix. A fifth report, #1699, we withdrew ourselves as not_planned - never a real bug.
  2026-09-02	stellar/smart-account-kit#7	Uncapped @stellar/stellar-sdk peer range lets a routine install resolve a version whose API removed a method the library calls in 9+ production files - a runtime crash, live today.	Fixed by the maintainer (PR #10, merged 2026-09-08, caps the SDK range at ^16.3.0); issue closed as completed.
  Protocol 28	OpenZeppelin/stellar-contracts#865	A non-exhaustive match on ContractExecutable in production code that compiles clean today but fails to build (error[E0004], reproduced against the real compiler) the day the crate's soroban-sdk pin moves to 28.x - ahead of the 2026-09-16 mainnet vote.	Fixed by the maintainer (#866, fix #865, merged 2026-09-26): get_validated_context_by_id now handles ContractExecutable::ExternalRef, and main pins stable soroban-sdk 28.0.0. Reported 2026-09-02, closed as completed 2026-09-26.
  2026-08	x402-foundation/x402#3171	Reported a crash in @x402/core when payload.accepted is null/undefined.	Fixed - external contributor JasonColapietro wrote and merged #3180.
  2026-08	stellar/stellar-dev-skill#96	Add Nirium to the Foundation's community developer-skills catalog.	Merged.
  2026-08	OpenZeppelin/stellar-contracts#840	Read the fee-abstraction Lazy-mode expiration check as validating the wrong value; proposed a fix (#844).	Closed - maintainer treats the Lazy-mode value as intended behavior. Our reading, corrected by theirs.
  2026-08	x402-foundation/x402#3148	Original header claim was corrected by a reviewer; reframed as a proposal for a payment-rejection reason-code vocabulary, grounded in five measured failure modes from production integrators.	Open, awaiting maintainer response on the proposal.

• From Fer, founder of AgentLedger, who now also works with Nirium part-time:

  "We verify everything a 402 claims, whoever it comes from, and with Nirium it all checked out... And when things did come up, they got resolved fast. They warned us about a risk in our integration - that the collection account rotated on mainnet - before it bit us, and the bugs we reported were fixed the same day, not in the next release. That tells me more than any number on a landing page."

  • Fer, AgentLedger

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-repayment
• path-arbitrage / path-vector → execute_path_arbitrage: path payment discovery for XLM-USDC corridors
• cross-dex → execute_cross_dex: cross-venue routing
• blend-yield → execute_blend_yield: non-custodial allocation on Blend Protocol
• soroswap-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)

SDK	Package	Version	Install
TypeScript	nirium (npm)	0.16.1	npm install nirium
Python	nirium (PyPI)	0.11.0	pip install nirium
MCP server	nirium-mcp (npm)	0.6.3	npx nirium-mcp
Pollar adapter	nirium-pollar-adapter (npm)	0.5.0	npm install nirium-pollar-adapter

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: community@stellar.org

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

Document	Description
SDKs.md	Full TypeScript + Python SDK documentation
API_DOCUMENTATION_OPENAPI.yaml	OpenAPI specification
MCP_INTEGRATION_GUIDE.md	MCP v0.6.3, 25 tools for Claude Desktop / Cursor
INTERNAL_SECURITY_AUDIT.md	Internal security self-review: method, findings, fixes, out of scope
NIRIUM_TECHNICAL_PAPER.md	Technical whitepaper
SECURITY.md	Responsible vulnerability disclosure policy
CONTRIBUTING.md	Open source contribution guide

---

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

Channel	Link
Website	nirium.xyz
API (testnet)	nirium-agent.fly.dev
API (mainnet)	nirium-agent-mainnet.fly.dev
Build Hub	nirium.xyz/build
X / Twitter	@Niriumstellar
SCF / Community	communityfund.stellar.org
Security	niriumprotocol@gmail.com

---

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.