Open-source autonomous treasury and agentic payments (x402/MPP) for Stellar/Soroban.
This repository contains the TypeScript and Python SDKs, the MCP server, the CLI, examples and quickstarts that let any developer:
- Get paid by AI agents: put your own API behind an x402 pay-gate in one call with
x402Serve(), or pay for someone else's withinitX402(). - Automate on-chain treasury: a Nirium agent moves idle capital into a CETES strategy (tokenized Mexican T-bills via Etherfuse) and back, over a vault you own. The agent can propose a rebalance without ever holding a signing key; autonomous execution on mainnet (the agent signs) is invite-only while a legal review closes.
- Anchor immutable audit trails: SHA-256 content hash pinned to IPFS, optionally carrying an ed25519 signature that proves who declared the fact, not just that it is unaltered.
Software-only and non-custodial: regulated partners execute settlement, the client signs every fund movement, and Nirium never holds client funds.
| Package | Install | Version | Description |
|---|---|---|---|
| TypeScript SDK | npm install nirium |
 |
Client for the Nirium API, x402/MPP payments, signals, webhooks, plus x402Serve() to charge for your own API. |
| Python SDK | pip install nirium · pip install 'nirium[langchain]' |
 |
Async client with the same surface, plus NiriumX402Tool for LangChain agents. |
| MCP server | npx nirium-mcp |
 |
25 tools for Claude Desktop, Cursor, and any MCP-compatible IDE. |
| CLI | npm install -g nirium-cli |
 |
Scaffold and interact with Nirium from the terminal. |
The source in
packages/matches what is published. The two SDKs have identical client surfaces; TypeScript is one minor ahead becausex402Serve()is Express middleware: server-side Node, with no meaningful Python equivalent. That gap is the honest signal, not a lag.
Signing with a social-login wallet instead of a raw keypair? See nirium-pollar-adapter, a separate package that adapts Pollar's embedded-wallet SDK to sign x402 payments and audit records through this SDK.
npm install niriumimport { Agent } from 'nirium';
const agent = new Agent({ baseUrl: 'https://nirium-agent.fly.dev' });
const market = await agent.getMarket();
console.log(market);The other side of the counter. Wiring x402 by hand is ~25 lines of facilitator client, per-method auth headers, per-network scheme registration and a route table whose shape you have to reverse-engineer. This is the same thing with the defaults that already run in production:
import { x402Serve } from 'nirium';
app.use('/premium', x402Serve({
payTo: 'G...', // your Stellar address
routes: { 'GET /signals': '$0.02' },
}));Any AI agent can now pay for your endpoint in USDC: no account, no card, no subscription, no human awake.
See docs/ for full quickstarts, including "Charge AI agents in 5 minutes", and examples/ for runnable Express, Next.js, LangChain x402, and non-custodial treasury vault integrations. For real production findings (not marketing copy), see the devlog.
Live on both Stellar networks. They are not two copies of the same thing.
Mainnet (real value). The API box holds no signing key by design; a separate process with no HTTP surface signs autonomous rebalances, and clients sign their own fund movements.
| What | Verify |
|---|---|
| First real x402 payment | 3134a51c…7558bc |
| Treasury vault deployed (client signs) | 93ff6284…78416 |
| Autonomous invest (the agent signs) | 82d73f53…6b3d4 |
| API | nirium-agent-mainnet.fly.dev/health |
That third transaction is the point: the agent moved funds it does not own, and the contract gave it no way to take them out. Nirium holds only the vault's RebalanceManager role, and rebalance() accepts no destination address: withdrawal is not forbidden, it is inexpressible.
Testnet (no real value, where the loop and the key live, and where you should build).
| Contract | ID |
|---|---|
| NiriumVault | CBTWMZCG3P72EHFAQ4ZLSEBIOFYJC244H5J6DHZIJ56FHFWJ2CFAWSZU |
| NiriumProtocol | CC2TU5BDTKTPRRRQPEF77I54XYHFQ25XGIRO2TCWKSR7NRJDFR5L5NR5 |
API: nirium-agent.fly.dev/health · node catalog: /api/nodes
Nirium's own NiriumVault treasury contract stays on testnet and is audit-gated: no independent third-party audit has happened yet, and no client funds ever reach it. The mainnet treasury path runs over a DeFindex vault instead: a third-party contract audited by OtterSec (March 2025, 16 findings, all 13 vulnerabilities resolved) on a Blend V2 strategy.
Real bugs found in code we don't control, in other people's repos, confirmed by maintainers with no reason to agree if they weren't real.
x402-foundation/x402#3171 — paymentRequirementsMatchAccepted() in @x402/core threw a raw internal TypeError instead of a protocol-level error when a payment's accepted field was missing or null. We filed it after hitting it live against our own production endpoint. Fixed by an external contributor, JasonColapietro — not us — in PR #3180. Maintainer phdargen approved and merged it: "Thanks for the patch @JasonColapietro, LGTM 🚀" — commit ab1a31a, 55/55 tests passing, issue closed automatically as completed.
OpenZeppelin/relayer-plugin-x402-facilitator#47 — a facilitator sponsor account we rely on went silent for 205+ hours; a different account appeared active on pubnet 3 days later with a matching activity pattern, but we can't confirm ownership from outside. Filed as an open question, not a claim: if it's theirs, it's a config fix on our side; if not, the outage is broader than us. Three independent integrators (us, AgentLedger, and a third party) converged on the same diagnosis across a month of silence on two official OpenZeppelin channels — until a direct tag to maintainers verified as active elsewhere in the org broke it open: "Apologies for the slow response... looking into it now and will update here shortly" (zeljkoX, 9-sep-2026). Open, response received, account still dead — a reply is engagement, not a fix.
stellar/stellar-mpp-sdk#69 — @stellar/mpp's exported USDC_SAC_MAINNET (54 chars) and XLM_SAC_MAINNET (55 chars) both fail StrKey.isValidEd25519PublicKey() — invalid addresses, present in every version including 0.7.1. Filed with the exact byte counts and correct addresses; PR merged the same day. Our own USDC_SAC_OVERRIDE workaround (middleware/mpp.ts) stays until a release actually ships the fix.
Full history, including findings still open, in the devlog.
Contributions welcome: examples, framework adapters, language bindings, docs and tests. This repo ran a GrantFox bounty campaign with Trustless Work through early September 2026 — that campaign is now closed, so there are currently no open, assigned-on-request issues. Watch the issues page for the next round rather than pinging an old thread; a future campaign, if one runs, will be labeled explicitly.
Outside of any campaign, PRs are still welcome — examples, framework adapters, bindings, docs, tests — just note in the PR that it isn't tied to a bounty.
Experimental software. Not financial advice, not an investment product, and no guarantee of yield, dividends or appreciation. Rate data (Blend supply rate, Etherfuse CETES rate) is public protocol information, not a projection. Smart contracts carry risk even when audited. XLM and Stellar assets are volatile.
Apache-2.0: see LICENSE.