x402-mcp

# x402 Micropayments MCP

[![smithery badge](https://smithery.ai/badge/kwizzlesurp10/x402-mcp)](https://smithery.ai/server/kwizzlesurp10/x402-mcp)
[![US City Open-Data Compliance Network on the 24K Labs curated list](https://24klabs.ai/badge.svg?resource=https%3A%2F%2Fx402-mcp.onrender.com%2F.well-known%2Fx402)](https://24klabs.ai/listing/us-city-open-data-compliance-network)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Base Mainnet](https://img.shields.io/badge/Network-Base%20Mainnet%20(8453)-0052FF.svg)](https://base.org)
[![A2A Protocol](https://img.shields.io/badge/Identity-A2A%20v1.0%20Agent%20Card-green.svg)](https://x402-mcp.onrender.com/.well-known/agent-card.json)

Production MCP server for the [x402](https://x402.org) HTTP micropayment protocol — **live on Base mainnet, selling real data products to AI agents for USDC today**. Agents discover paid services, probe `402 Payment Required` responses, pay with stablecoins, and build/verify seller payment configs; the server runs both sides of that market.

[![US City Open-Data Compliance Network on the 24K Labs curated list](https://24klabs.ai/card.svg?resource=https%3A%2F%2Fx402-mcp.onrender.com%2F.well-known%2Fx402)](https://24klabs.ai/listing/us-city-open-data-compliance-network)

## Discover (public + A2A)

Machine surfaces agents and directories crawl first:

| Surface | URL |
|---------|-----|
| A2A Agent Card | https://x402-mcp.onrender.com/.well-known/agent-card.json |
| Agents registry | https://x402-mcp.onrender.com/.well-known/agents.json |
| Agentic.Market | https://x402-mcp.onrender.com/.well-known/agentic-market.json |
| x402 catalog | https://x402-mcp.onrender.com/.well-known/x402 |
| Funding / payTo | https://x402-mcp.onrender.com/.well-known/funding.json |
| MCP manifest | https://x402-mcp.onrender.com/.well-known/mcp |
| MCP server card | https://x402-mcp.onrender.com/.well-known/mcp/server-card.json |
| LLM docs | https://x402-mcp.onrender.com/llms.txt |
| OpenAPI | https://x402-mcp.onrender.com/openapi.json |
| Free city catalog | https://x402-mcp.onrender.com/us/cities |

Agent Card declares the [a2a-x402](https://github.com/google-a2a/a2a-x402) extension, AP2-style `payments.rails[]` (USDC on Base), and explicit `funding.payTo`.

## Fund (USDC on Base)

Payment for delivered products / documentation artifacts, or a voluntary tip. **Not a token, not equity, not a raise.**

| Field | Value |
|-------|-------|
| Network | Base `eip155:8453` |
| Asset | USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| payTo | `0x0d25A44f74868eCE53B305C97139CF4B62963410` |
| Explorer | https://basescan.org/address/0x0d25A44f74868eCE53B305C97139CF4B62963410 |
| Machine cashier | buy any live paid endpoint (e.g. $0.01 property-check) |
| Bounties protocol | [docs/BOUNTIES.md](docs/BOUNTIES.md) · [open a bounty](https://github.com/kwizzlesurp10-ctrl/x402-mcp/issues/new?template=paid-bounty.md) |
| GitHub FUNDING.yml | [.github/FUNDING.yml](.github/FUNDING.yml) |

Fiat Sponsors (GitHub Sponsors / Polar / thanks.dev) do **not** credit `payTo` on-chain.

## Live on Base mainnet

**Storefront:** https://x402-mcp.onrender.com — x402 v2 challenges served, USDC verified + settled through the Coinbase CDP facilitator (`eip155:8453`).

| Product | Price | What you get |
|---------|-------|--------------|
| `GET /mn/property-check?address=…` | $0.01 USDC | Minneapolis rental-compliance snapshot composed from 3 live City of Minneapolis open datasets — the first machine-payable housing-compliance data for agents |
| `GET /us/{code}/property-check?address=…` | $0.01 USDC | **US City Open-Data Compliance Network** (public catalog; see `/us/cities`) — same wire protocol; free catalog `/us/cities` + free `/sample`; MCP: `city.list` → `city.sample` → `city.check` |
| `GET /swarm/products/d22bbf5f3c4b4666a6f80980c7bc7c50/purchase` | $0.05 USDC | Base Network Pulse: live settlement-conditions intelligence (EIP-1559 math + real RPC + ETH spot), pinned listing with the x402 Bazaar discovery extension |

The public seller host holds **no spend key** — it only verifies and settles inbound payments ([docs/SELLER-STOREFRONT.md](docs/SELLER-STOREFRONT.md)). Roadmap: [ROADMAP.md](ROADMAP.md).

## Features

- **20 MCP tools** for buyer, seller, x402 commerce, swarm-agency, US city compliance, Agent ID cards, and ops-monitoring flows — canonical inventory in `app/tools_registry.py` (single source for README, `/.well-known/mcp`, and tests); guarded by `tests/test_readme.py` and `tests/test_manifest.py`. MailRail send/inbound is operator-only ([docs/MAILRAIL-PUBLIC-SURFACE.md](docs/MAILRAIL-PUBLIC-SURFACE.md)).
- **4 MCP prompts** (`onboarding_flow`, `x402_tool_selector`, `generate_quote`, `troubleshoot_payment`) for LLM orchestrators
- **4 MCP resources** (`x402://agent-card`, `x402://server-card`, `x402://tools-manifest`, `x402://pricing-table`) exposing live machine descriptors
- **A2A Protocol v1.0 Agent ID Cards** — HTTP Agent Card + MCP `x402.agent_card` / `x402://agent-card` with per-`agent_id` quota isolation
- **x402/Coinbase rail** (primary): x402 v2 wire format end to end — challenge generation, verify + settle via the CDP facilitator on Base mainnet, Bazaar discoverability on listings
- **Stripe payment rail** (fiat alternative, HTTP only): `POST /stripe/checkout` + `POST /stripe/webhook` for card/bank payments (not exposed as an MCP tool)
- **Commerce overlay:** 500 calls/month, 10/min rate limit, `meta` envelope on every response
- **FastMCP** + **FastAPI** with `/.well-known/mcp` manifest
- **stdio** (Cursor/Grok local) and **HTTP/SSE** (remote connector) transports
- **Redis-ready** quota store (in-memory default)
- **Operator dashboard** at `/dashboard` — live health, per-agent quota burn-down meters, tool matrix, and revenue paths (single-file, zero build step)
- **Hermetic test suite** — a local mock facilitator/discovery backend spins up automatically; no internet required. Set `X402_LIVE_TESTS=1` to run against x402.org

## Quickstart & 1-Click Installation

Install `kwizzlesurp10/x402-mcp` into your favorite MCP client using the [Smithery CLI](https://smithery.ai/server/kwizzlesurp10/x402-mcp):

```bash
# Claude Desktop
npx -y @smithery/cli install kwizzlesurp10/x402-mcp --client claude

# Cursor
npx -y @smithery/cli install kwizzlesurp10/x402-mcp --client cursor

# Windsurf
npx -y @smithery/cli install kwizzlesurp10/x402-mcp --client windsurf
```

## Quick Start (Mission Control)

```bash
git clone <repo> && cd x402-mcp
python -m venv .venv && .venv\Scripts\pip install -r requirements.txt && cd dashboard && pnpm install && cd ..
cp .env.example .env
make up
```

Open http://localhost:5173 — setup wizard runs with doctor checks. Toggle **Demo** to preview every panel with zero wallet.

**Docs:** [docs/SETUP.md](docs/SETUP.md) · [docs/USER-GUIDE.md](docs/USER-GUIDE.md) · [docs/UI-HANDOFF-v2.md](docs/UI-HANDOFF-v2.md)

### Local stdio (Cursor)

```bash
python run_stdio.py
```

Add to Cursor MCP config (`manifests/cursor-mcp.json`).

### HTTP server

```bash
uvicorn app.main:app --host 0.0.0.0 --port 8402
curl http://localhost:8402/.well-known/mcp
curl http://localhost:8402/health
# then open http://localhost:8402/dashboard
```

## Paid HTTP Resource: MN Property Check

First-party sellable endpoint (the seller side of this repo's own tooling):

```
GET /mn/property-check?address=1700%20Penn%20Ave%20N
```

x402-gated at **$0.01 USDC** (`MN_PROPERTY_CHECK_PRICE`). Unpaid requests get a
`402` with x402 v2 `PAYMENT-REQUIRED` terms; paid requests are verified and
settled via the facilitator, then served with a `PAYMENT-RESPONSE` receipt.

One call returns a composite Minneapolis rental-compliance snapshot from live
City of Minneapolis Open Data: active rental license (status, tier, licensed
units, expiration, ward/neighborhood), regulatory violation case history
(APN-joined), and condemned/boarded status. Owner phone/email in the source
data are intentionally never served. Public records, as-is; not legal advice.

## MCP Tools

Tool names use domain.action trees so clients can route `x402.*`, `a2a.*`, `commerce.*`, `swarm.*`, `pulse.*`, `ops.*`, and `city.*`.

| Tool | Description |
|------|-------------|
| `x402.agent_card` | Return the A2A Agent ID Card and MCP server card |
| `a2a.resolve_card` | Discover and inspect an external A2A Agent Card by domain or URL |
| `x402.discover` | Query x402 Bazaar for paid HTTP APIs |
| `x402.probe` | Probe URL for `PAYMENT-REQUIRED` on 402 |
| `x402.pay_and_fetch` | Auto-pay and fetch protected resource |
| `x402.build_seller` | Build seller payment requirements |
| `x402.verify` | Verify payment via facilitator |
| `x402.networks` | Networks, facilitators, v2 headers |
| `commerce.pro_requirements` | Build x402 payment requirements for Pro tier upgrade |
| `commerce.activate_pro` | Verify x402 payment and unlock Pro tier quota |
| `commerce.credits_requirements` | Build x402 payment requirements for per-use tool credits |
| `commerce.purchase_credits` | Verify x402 payment and add per-use tool credits |
| `swarm.research` | Swarm Agency: compose a research report and list it for resale |
| `swarm.settle` | Verify + settle a buyer's payment for a listed composite and record revenue |
| `swarm.revenue` | Swarm composite economics: spend, composite sales, LTV:CAC, margins; `storefront` is the full settled ledger |
| `pulse.base` | Live Base Network Pulse: synthesized settlement-conditions intelligence (base fee, utilization, USD cost, verdict) from real RPC data |
| `ops.metrics` | Host OS telemetry: CPU, memory, swap, disk, network, and process signals with an ok/warn/critical health verdict |
| `city.list` | Free US City Open-Data Compliance catalog (codes, paid_url, sample_url, MCP golden path) |
| `city.sample` | Free fixed-address property compliance sample for one city code |
| `city.check` | Paid city property compliance via x402 (same HT