# Nirium Agentic Payments

> Scaffold and run an x402 paid API server on Stellar with open-source client libraries: charge AI agents per API call with x402Serve(), a function from the nirium SDK that runs entirely on your own server, scaffold that server with nirium-cli in one command, and separately read live protocol data through the nirium-mcp server. Use when the user wants to charge AI agents for API access on Stellar, needs a working x402 seller in minutes without hand-rolling the facilitator client, or wants an MCP-connected agent to read market state / control an autonomous loop on a running Stellar agent.

- Skill: `jiayaoqijia/nirium-agentic-payments` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add jiayaoqijia/nirium-agentic-payments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiayaoqijia/nirium-agentic-payments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: jiayaoqijia (https://skillmd.com/u/jiayaoqijia)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/jiayaoqijia/nirium-agentic-payments

---


# 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`](https://stellar.expert/explorer/public/tx/8a2487b8545e02324ced5d902fa350f0f5d8c2d5d2210272506a320b36d73170).
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

```bash
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](https://channels.openzeppelin.com/testnet/gen) for testnet, [channels.openzeppelin.com/gen](https://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.

```bash
npm run dev
```

### 2. Charge per request with `x402Serve()`

The scaffolded server is about ten lines because `x402Serve()`, from the
[`nirium`](https://www.npmjs.com/package/nirium) SDK, carries the
facilitator client, the scheme registration, and the route table:

```ts
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](https://channels.openzeppelin.com/testnet/gen)
and a mainnet one at [channels.openzeppelin.com/gen](https://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](https://github.com/nirium-protocol/nirium/blob/main/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`

```bash
npx nirium-mcp
```

Claude Desktop / Cursor MCP config:

```json
{
  "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.

## Reference

- SDK + CLI + MCP source, examples: [github.com/nirium-protocol/nirium](https://github.com/nirium-protocol/nirium)
- CLI: [npmjs.com/package/nirium-cli](https://www.npmjs.com/package/nirium-cli)
- MCP server: [npmjs.com/package/nirium-mcp](https://www.npmjs.com/package/nirium-mcp)
- TypeScript SDK: [npmjs.com/package/nirium](https://www.npmjs.com/package/nirium) · Python: [pypi.org/project/nirium](https://pypi.org/project/nirium/)
- Facilitator API key (required for `x402Serve()`): [channels.openzeppelin.com/gen](https://channels.openzeppelin.com/gen)

