x402 on Stellar · live on mainnet

Charge AI agents for your API.

Try it on testnet in 5 minutes: your API answers 402, the agent pays in USDC on Stellar, settled in ~4s. Funds go straight from payer to you - Nirium never touches them.

$0.05

Per x402 request

~4s

On-chain settlement

Funds custodied

Third-party facilitator use of x402Serve() on mainnet is invite-only while legal review closes - same gate as Treasury and Payouts.

server.js

import express from 'express';
import { x402Serve } from 'nirium';

const app = express();
app.use(x402Serve({
  payTo: process.env.PAY_TO,                       // your G... address
  facilitatorApiKey: process.env.FACILITATOR_KEY,  // free testnet key
  routes: { 'GET /weather': '$0.05' },             // testnet by default
}));
app.get('/weather', (_req, res) => res.json({ tempC: 21 }));
app.listen(3000);

Ran verbatim with nirium@0.16.0 on testnet: 402, then paid, then 200.

x402Serve() is a library that runs on your own server, with your own facilitator key. You remain responsible for compliance in your jurisdiction; restricted jurisdictions apply.

Try it on testnet

Three steps, no real money. Node.js 22.12 or newer.

Install

The package plus the x402 pieces x402Serve() loads on demand.

npm i nirium express @x402/express @x402/core @x402/stellar

Charge per request

Get a free testnet facilitator key from OpenZeppelin, set PAY_TO to a testnet address with a USDC trustline, and run server.js. Without payment, GET /weather answers 402 with the price.

channels.openzeppelin.com/testnet/gen

Pay it from an agent

Any x402 client works. With the same package, from a testnet account that holds USDC:

pay.mjs

import { Agent } from 'nirium';

const agent = new Agent({ apiKey: 'unused' });
agent.initX402({ secretKey: process.env.PAYER_SECRET, network: 'stellar:testnet' });
const res = await agent.x402Fetch('http://localhost:3000/weather'); // 402 → sign → 200

What Nirium adds on top of x402

x402 moves the payment. These are the parts you would otherwise write yourself.

Since 0.15.0 · opt-in

Replay guard and rate limit

Pass a guard store to x402Serve() and a replayed payment proof is refused: one payment, one response. Add a per-IP sliding-window rate limit on top. Replay protection fails closed (503) if the store is down. Generalized from a production integrator’s own implementation, credited in the changelog.

CHANGELOG

Live on mainnet · free beta

Verifiable receipts with Audit Trail

Anchor the settlement hash, or the sha-256 of any record, and get back an IPFS receipt anyone can check from the CID alone. Sign it with any Stellar key and the receipt also proves who declared it. One API call. Anchor hashes, not raw personal data.

GET /api/audit/info

New in 0.16.0 · experimental

Buyer-side policy hook

On the paying side, initX402({ policy }) asks your policy engine after the Stellar authorization is built and before anything is signed. Only an ALLOW bound to that exact authorization reaches the signer. Not solved yet: L01, concurrent requests that see the same remaining capacity, and L02, code in the same process that holds the raw signer. The shape can still change before 1.0.

PR #98 · #96