NanoRoute

x402 payment facilitator for Nano (XNO) — enabling AI agents to pay for APIs with zero-fee, sub-second micropayments.

NanoRoute is an open-source x402 facilitator that lets AI agents pay for any API or digital resource using Nano. It handles the full payment lifecycle: verification, on-chain broadcast, off-chain ledger tracking, and batch settlement to merchants — all with zero transaction fees.

Why Nano for x402?

The x402 protocol enables AI agents to pay for APIs at the HTTP level — no accounts, no API keys, just pay-per-request. NanoRoute implements this for Nano because:

• Zero fees — No gas costs, ever. A payment of 0.0001 XNO costs 0.0001 XNO. Settlement is free too.
• Sub-second finality — Transactions confirm in under 1 second. Agents don't wait.
• Truly micro — 1 XNO = 10^30 raw. You can charge 0.000001 XNO per request without fees eating the payment.
• No smart contract risk — Native L1 transfers. No approval transactions, no token allowances, no exploitable contracts.

How It Works

AI Agent                    Merchant API                NanoRoute Facilitator
   │                            │                              │
   ├── GET /api/data ──────────▶│                              │
   │                            │◀── 402 Payment Required ─────│
   │◀── 402 + price + payTo ───│                              │
   │                            │                              │
   │  [sign Nano send block]  │                              │
   │                            │                              │
   ├── POST /api/data ─────────▶│                              │
   │   + X-PAYMENT header       │── POST /x402/verify ────────▶│
   │                            │                              │── broadcast block to Nano L1
   │                            │                              │── record in off-chain ledger
   │                            │◀── { valid: true, txHash } ──│
   │◀── 200 + data ────────────│                              │
   │                            │                              │
   │                            │     [settlement engine runs periodically]
   │                            │                              │── batch-settle to merchant on Nano L1

1. Agent requests a paid resource → gets HTTP 402 with price and facilitator URL
2. Agent signs a Nano send block to the facilitator's pool address
3. Agent retries the request with the signed block in the X-PAYMENT header
4. Merchant's middleware forwards the payment to NanoRoute's /x402/verify
5. NanoRoute broadcasts the block on-chain, records routing fee, queues merchant payout
6. Settlement engine periodically batch-settles merchant payouts (also feeless)

Live Public Node

A public NanoRoute facilitator is running and available for anyone to use:

Merchants can point their middleware at this URL to start accepting Nano payments immediately — no need to run your own node.

Quick Start

# Clone
git clone https://github.com/robgilmore26/nanoroute.git
cd nanoroute

# Install
npm install

# Configure
cp .env.example .env
# Edit .env — set your POOL_SEED (generate at https://nault.cc)

# Run
npx tsx src/index.ts

You should see:

  ╔══════════════════════════════════════════════╗
  ║        NanoRoute — x402 Nano Facilitator     ║
  ╠══════════════════════════════════════════════╣
  ║  Pool:   nano_3mcj4sh6sshg551wyqzww8pd...   ║
  ║  Fee:    0 bps (0%)                          ║
  ║  Settle: every 300s                          ║
  ║  Port:   3402                                ║
  ╚══════════════════════════════════════════════╝

Dashboard: http://localhost:3402/dashboard

For Merchants: Gate Your API in One Line

Install the middleware and add it to your Express app:

import { nanorouteMiddleware } from 'nanoroute-express';

app.use(nanorouteMiddleware({
  facilitator: 'http://204.168.181.90:3402',   // public node (or run your own)
  merchantAddress: 'nano_1youraddress...',
  routes: {
    '/api/market-data':  { amount: '0.0001', description: 'Market data' },
    '/api/premium':      { amount: '0.001',  description: 'Premium analytics' },
    '/api/reports/*':    { amount: '0.005',  description: 'Research reports' },
  }
}));

Unpaid requests get a 402 with pricing. Paid requests pass through to your route handler with req.nanoroute.txHash attached.

For AI Agents: Pay in Three Lines

import { NanoRouteAgent } from 'nanoroute-agent';

const agent = new NanoRouteAgent({
  seed: process.env.AGENT_SEED,
  accountIndex: 1,
  maxPaymentXno: '0.01',  // safety cap
});

// One-liner: probe, pay, and fetch
const result = await agent.fetch('http://api.example.com/market-data');
console.log(result.body);  // the paid resource

Or inspect the quote first:

const quote = await agent.getQuote('http://api.example.com/market-data');
console.log(`Cost: ${quote.amountFormatted}`);  // "0.0001 XNO"
const result = await agent.pay(quote);

API Endpoints

Running Your Own Node

You can use the public node or run your own. Anyone can run a NanoRoute facilitator node. The routing fee is configurable — set ROUTING_FEE_BPS=0 for free routing, or set a fee (e.g., 100 = 1%) if you want to earn from transaction volume.

# .env
POOL_SEED=your_64_or_128_hex_seed
ROUTING_FEE_BPS=0          # 0 = free routing, 100 = 1% fee
SETTLEMENT_INTERVAL_SECONDS=300

E2E Demo

Run the full agent-pays-merchant flow locally:

# Terminal 1: Start facilitator
npx tsx src/index.ts

# Terminal 2: Start example merchant
npx tsx examples/merchant-server.ts

# Terminal 3: Run agent (needs funded wallet)
npx tsx examples/agent-sdk-demo.ts

Project Structure

nanoroute/
├── src/
│   ├── index.ts              # Entry point
│   ├── types/index.ts        # Core type definitions
│   ├── db/ledger.ts          # SQLite off-chain ledger
│   ├── routes/api.ts         # Express API routes
│   └── services/
│       ├── verifier.ts       # x402 payment verification + routing
│       ├── settlement.ts     # Batch settlement engine
│       ├── nano-rpc.ts       # Multi-node RPC client with failover
│       └── auto-receive.ts   # Auto-pocket receivable blocks
├── packages/
│   ├── agent-sdk/            # nanoroute-agent — SDK for paying agents
│   └── middleware/           # nanoroute-express — merchant middleware
├── examples/
│   ├── merchant-server.ts    # Example gated API server
│   ├── agent-pays-merchant.ts # Manual E2E flow
│   └── agent-sdk-demo.ts    # SDK-based E2E flow
└── dashboard/
    └── index.html            # Live monitoring dashboard

Related Projects

NanoRoute builds on the growing Nano x402 ecosystem:

• x402 — The open x402 protocol standard
• x402nano — x402 scheme implementations for Nano
• x402.NanoSession — Session-based x402 micropayments
• NanoGPT — AI platform accepting Nano via x402
• Subnano — Micropayment content platform on Nano
• Faremeter — x402 middleware for Nano

Tech Stack

• TypeScript + Express
• nanocurrency-web — Nano block signing and key derivation
• better-sqlite3 — Off-chain ledger (WAL mode)
• Nano RPC — Multi-node with automatic failover

License

MIT — see LICENSE