Nirium: charge AI agents and read live signals on Stellar

Nirium publishes open-source client libraries for x402 agentic payments on Stellar - a TypeScript/Python SDK, a scaffolding CLI, and an MCP server. x402Serve(), the function these scaffold around, runs on your own server: Nirium doesn't operate, host, or route through anything in that path, and never sees your end users' requests. It's not a demo - Nirium's own mainnet endpoint runs the identical function. Its first mainnet settlement, 9 July 2026, is verifiable on Stellar Expert: 8a2487b8…d73170. Those settlements came from our own test wallets and an integration partner's tests, not paying customers; the most recent was 29 September 2026.

You're responsible for your own compliance. x402Serve() is a general-purpose library, not a service Nirium provides to your end users - you choose what to charge for, who payTo is, and which jurisdiction you operate in. You remain solely responsible for complying with the financial, tax, and consumer-protection laws that apply to your own use of it.

Do this

1. Scaffold a paid API in one command

npm install -g nirium-cli
nirium create x402 --name my-paid-api
cd my-paid-api && npm install

Fill two values in the generated .env:

Variable	Where it comes from
`STELLAR_PAY_TO`	the Stellar account that receives payments (`G...`)
`X402_FACILITATOR_API_KEY`	free - keys are per network, and the scaffold defaults `STELLAR_NETWORK` to `testnet`: channels.openzeppelin.com/testnet/gen for testnet, channels.openzeppelin.com/gen for mainnet

The API key is not optional - the facilitator rejects unauthenticated servers on both testnet and mainnet, so without it your routes never get as far as offering a 402.

npm run dev

2. Charge per request with `x402Serve()`

The scaffolded server is about ten lines because x402Serve(), from the nirium SDK, carries the facilitator client, the scheme registration, and the route table:

import { x402Serve } from 'nirium';

app.use('/premium', x402Serve({
    payTo: 'G...',
    facilitatorApiKey: process.env.X402_FACILITATOR_API_KEY,
    network: 'stellar:testnet',
    routes: { 'GET /signals': '$0.02' },
}));

facilitatorApiKey is required: without it x402Serve() throws when the server starts. The key is free and per network: get a testnet one at channels.openzeppelin.com/testnet/gen and a mainnet one at channels.openzeppelin.com/gen. A mainnet key returns 401 against testnet. For mainnet, also set network: 'stellar:pubnet'.

A caller without payment gets a 402 carrying the terms; one that pays gets the data, and the USDC transfer settles on Stellar before your handler returns. No subscription, no card, no invoice, no human in the middle. This is the exact pattern Nirium's own mainnet endpoint runs in production against real callers - see the devlog for a real incident (and its fix) from operating it at scale: docs/devlog.md.

Optional, off by default: set NIRIUM_X402SERVE_TELEMETRY=true if you want to send Nirium a non-blocking usage ping (your payTo, a SHA-256 hash of your facilitatorApiKey - never the key itself, network, route/request counts, SDK version). It never affects a payment either way, on or off.

3. Read live protocol data with `nirium-mcp`

npx nirium-mcp

Claude Desktop / Cursor MCP config:

{
  "mcpServers": {
    "nirium": {
      "command": "npx",
      "args": ["-y", "nirium-mcp"],
      "env": { "AGENT_API_URL": "https://nirium-agent-mainnet.fly.dev" }
    }
  }
}

No key needed for the read-only tools below - they work against the live mainnet agent right now:

get_market_state - XLM/USDC price, SDEX spread, base fee, Blend rate, CETES rate
get_loop_status - autonomous loop status, scan count, last decision
get_nodes - execution nodes with live status, custody model, network
get_wallet_info - the configured x402/MPP wallet and which tools are enabled

Paid tools (get_premium_signals $0.02, get_premium_market $0.05, execute_paid_strategy $0.25, over x402; get_mpp_signals $0.02, get_mpp_market $0.05, over MPP) need a funded STELLAR_SECRET_KEY and are testnet only today, with one exception: get_premium_market is also payable on mainnet (/api/v1/premium/market answers 402). On mainnet, /api/v1/premium/signals and /api/v1/premium/execute return 501: the mainnet box holds no signing key by design, so it does not charge for an endpoint it cannot serve. Don't tell a user the other paid tools settle on mainnet; they do not yet.