x402 Micropayments MCP

Production MCP server for the x402 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.

Live on Base mainnet

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

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

Features

• 19 MCP tools for buyer, seller, Stripe fiat, x402 commerce, swarm-agency, US city compliance, 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
• 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): create_stripe_checkout + POST /stripe/checkout + POST /stripe/webhook for card/bank payments
• 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

Quick Start (Mission Control)

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/USER-GUIDE.md · docs/UI-HANDOFF-v2.md

Local stdio (Cursor)

python run_stdio.py

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

HTTP server

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

Environment

Commerce Meta Envelope

Every tool response includes:

{
  "data": { "...": "..." },
  "meta": {
    "tier": "free",
    "calls_this_month": 1,
    "quota_remaining": 499,
    "quota_warning": false,
    "rate_limit_remaining": 9,
    "upgrade_url": "https://forge.example.com/upgrade",
    "agent_id": "..."
  }
}

Agent Ops / Swarm Agency

Cost-effective multi-agent operating group (scout, warden, treasurer, archivist, sovereign, merchant) with budget policy and ledger. See docs/agent-ops.md. Dashboard handoff: docs/UI-HANDOFF.md.

The Swarm Agency (app/swarm/) implements the hybrid resale loop end-to-end: scout discovers cheap upstream x402 services → warden enforces ledger/policy.json spend caps → treasurer pay_and_fetches and records cost basis to ledger/spend.jsonl → archivist composes a research report priced at cost × SWARM_MARKUP → sovereign (profit optimizer) reprices the composite to hit a target LTV:CAC (SWARM_TARGET_LTV_CAC, default 3.0), enforces a margin floor, and scores which upstream sources are actually profitable → merchant lists it via build_seller_requirements; settle_composite_sale records realized revenue. Portfolio economics (spend, revenue, LTV:CAC, per-source profit) surface via swarm_revenue_report / GET /swarm/revenue. Every phase streams to the dashboard's Swarm Activity panel over SSE. Run via the run_swarm_research MCP tool (needs EVM_PRIVATE_KEY + X402_PAY_TO_ADDRESS).

Multi-chain (EVM + Solana). The resource server registers ExactEvmServerScheme for eip155:* and ExactSvmServerScheme for solana:* (via the x402[svm] extra; solana>=0.36,<0.40). Seller requirements build on Base and Solana mainnet (solana:EtWTRAB…), and the buyer client registers an EVM and/or Solana signer from EVM_PRIVATE_KEY / SVM_PRIVATE_KEY — no marketing-vs-code gap.

Selling network / facilitators. The merchant lists on SWARM_SELL_NETWORK (default eip155:84532). The free x402.org facilitator only settles exact on Base Sepolia; to sell/settle on Base mainnet set SWARM_SELL_NETWORK=eip155:8453 and provide Coinbase CDP credentials (CDP_API_KEY_ID + CDP_API_KEY_SECRET) — the seller then routes verify/settle through the CDP facilitator with a per-request Ed25519 JWT (app/cdp_auth.py).

Base Network Pulse

Base Network Pulse (app/pulse.py + app/swarm/publisher.py) is a synthesis publisher: it turns free, high-quality Base RPC data (latest block, EIP-1559 base fee, block gas utilization) plus a live ETH spot price into a priced, x402-payable intelligence report. It projects the next-block base fee from the EIP-1559 formula, converts settlement gas into a live USD cost, and renders a settle-now / hold verdict on current Base settlement conditions. All inputs are real data — no mocks: real Base RPC calls, real Coinbase ETH price, real base-fee math.

Endpoints:

• GET /pulse — live preview of the current synthesized pulse (base fee, utilization, USD settlement cost, verdict).
• POST /pulse/publish — mints an x402-payable listing for the report (402-gated purchase endpoint).
• get_base_pulse MCP tool — the same intelligence surfaced to agents.

This is the synthesis economic model: cost basis is ~$0 because the underlying Base data is free to read; the margin is the analysis itself. The priced report is sold to external buyers through the 402-gated purchase endpoint — pure synthesized value on top of free public data.

Testing

pytest -v

See docs/SETUP.md for expected vs unexpected errors (wallet tools fail clearly until .env is configured).

Mission Control Dashboard

Fintech-terminal ops dashboard at http://localhost:5173. Net position, quota gauge, rate sparkline, activity stream, agent lanes, spend/revenue ledgers (with BaseScan links), 402 Inspector, wallet panel, first-run wizard, and mission progress tracker. Three density modes (Guided/Standard/Operator). cmd+K command palette.

API surface: GET /stats, GET /events (SSE with 15s heartbeat), GET /ledger/{spend|revenue}, GET /doctor, GET /probe, GET /wallet, POST /seller/requirements.

Agent Ops

Cost-effective multi-agent operating group (scout, warden, treasurer, archivist, merchant) with budget policy and ledger. See docs/agent-ops.md.

Docker

docker build -f deployment/Dockerfile -t x402-mcp .
docker run -p 8402:8402 x402-mcp

Drive Project Folder

Target: /Forge/MCP_Projects/x402-micropayments/

code/          → this repository
tests/         → pytest suite
docs/          → architecture.md
screenshots/   → verification images
manifests/     → cursor-mcp.json, /.well-known/mcp
deployment/    → Dockerfile

License

Apache-2.0 compatible with x402 Foundation ecosystem.