PayRouter

Universal agentic payment router. One MCP server, every payment rail.

PayRouter gives any AI agent — Claude, ChatGPT, Cursor, or custom — the ability to pay across multiple payment rails through a single interface, with cross-rail budget enforcement and a unified audit trail.

What it does

┌─────────────────────────────────────────────┐
│              PayRouter Server               │
│                                             │
│   MCP Endpoint    REST API    Dashboard     │
│   /mcp            /api/v1/*   :3000         │
│                                             │
│   ┌─────────────────────────────────────┐   │
│   │         Core Engine                 │   │
│   │  Mandate Engine → Router → Adapter  │   │
│   └─────────────────────────────────────┘   │
│       │         │        │         │        │
│     x402    Lightning  Stripe     UPI       │
│   (USDC)    (BTC/LN)  (Card)   (INR)       │
└─────────────────────────────────────────────┘

• MCP server (Streamable HTTP) — any MCP client connects and gets payment tools
• Mandate engine — cross-rail budget limits, category/merchant restrictions, deny-by-default
• Smart routing — picks the best rail, falls back on failure
• Dashboard — live transactions, budget bars, rail config, setup wizard
• Docs site — Fumadocs + Next 16, Stripe-like documentation

Supported rails

Rail	Protocol	Currency	Status
x402	HTTP 402 + stablecoins	USDC on Base	Working
Lightning	L402 + NWC	BTC (sats)	Working (see examples/l402)
Stripe	Shared Payment Tokens	USD/EUR/GBP	Planned
UPI	Reserve Pay (Razorpay)	INR	Planned

Quick start

git clone https://github.com/ram0verflow/payrouter.git
cd payrouter
nvm use          # Node 22
pnpm install
pnpm -r build
pnpm --filter @payrouter/server start

If no rails are configured, the setup wizard opens at http://localhost:3000/setup.

Connect an agent

Add to your Claude Desktop config:

{
  "mcpServers": {
    "payrouter": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

The agent gets 5 tools: request_payment, check_budget, list_transactions, discover_merchant_rails, revoke_all.

MCP tools

request_payment

merchant: "https://api.example.com"
amount: 0.01
currency: "USD"
preferred_rail: "auto"

Checks mandate → routes to best rail → executes payment → returns normalized receipt.

check_budget

Returns remaining budget across all rails for the current agent.

list_transactions

Recent transaction history with rail/category/date filters.

discover_merchant_rails

Probes a URL to detect which payment rails the merchant accepts (HTTP 402 headers, etc).

revoke_all

Emergency kill switch — revokes all payment capabilities immediately.

Project structure

payrouter/
├── packages/
│   ├── core/              # Mandate engine, router, receipt schema, types
│   ├── adapters/
│   │   └── x402/          # x402 stablecoin adapter
│   └── server/            # MCP + REST API + SQLite
├── apps/
│   ├── dashboard/         # React + Vite + Tailwind
│   └── docs/              # Fumadocs + Next 16
├── examples/
│   └── l402/              # L402 Lightning payment example (testnet)

Configuration

Create payrouter.config.json or use the dashboard setup wizard:

{
  "server": {
    "port": 3001,
    "dashboard_port": 3000,
    "db_path": "./payrouter.db"
  },
  "rails": {
    "x402": {
      "enabled": true,
      "wallet_private_key": "0x...",
      "network": "base-sepolia"
    }
  },
  "mandates": {
    "default": {
      "daily_limit": 100,
      "per_transaction_limit": 50,
      "allowed_categories": ["*"],
      "allowed_merchants": ["*"]
    }
  }
}

Environment variables also work — see .env.example.

Development

pnpm --filter @payrouter/server start    # API server on :3001
pnpm --filter dashboard dev              # Dashboard on :3000
pnpm --filter docs dev                   # Docs on :3002

Tech stack

• TypeScript, pnpm workspaces
• MCP: @modelcontextprotocol/sdk (Streamable HTTP)
• Database: better-sqlite3
• x402: @x402/fetch + @x402/evm + viem
• Lightning: @getalby/sdk (NWC)
• Dashboard: React 19 + Vite + Tailwind CSS
• Docs: Fumadocs + Next.js 16 + Turbopack

License

MIT