# 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

```bash
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:

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

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

```bash
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