io.github.kwizzlesurp10-ctrl/x402-mcp

Official16 toolsLive

by kwizzlesurp10-ctrl · Python

Pay for HTTP APIs and charge for your own: x402 micropayments in USDC on Base.

io.github.kwizzlesurp10-ctrl/x402-mcp (MCP)

This MCP server provides an interface tied to x402 HTTP micropayments. It supports “pay for HTTP APIs and charge for your own” using x402 micropayments denominated in USDC on Base. The project is associated with the x402 ecosystem and Base Mainnet (8453).

🛠️ Key Features

Model Context Protocol (MCP) server
x402 micropayments for HTTP APIs
USDC micropayments on Base
16 tools reported
Topics include MCP, Base, and agent-card

🚀 Use Cases

Charging for HTTP API access via x402
Agent-to-agent payment flows using an A2A v1.0 agent card
Integration with Base Mainnet (8453)

⚡ Developer Benefits

Standard MCP integration for tool discovery
Base-focused deployment target (Base Mainnet)
Uses an A2A v1.0 Agent Card endpoint

⚠️ Limitations

Documentation excerpt is incomplete (“Production MCP server for the [x402]…”) so tool behavior and coverage are not fully described here

Topics

agentic-economyai-agentsbasemcpmcp-servermodelcontextprotocolneverminedx402autonolasa2aagent-cardbase-mainnethttp-402micropaymentsusdc

Captured live from the server via tools/list.

discover_services

Discover x402 Bazaar paid HTTP services via x402 HTTPFacilitatorClient.

Parameters4

query	any	optional
limit	integer	optional
max_price_usdc	any	optional
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "limit": {
      "default": 20,
      "title": "Limit",
      "type": "integer"
    },
    "max_price_usdc": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Price Usdc"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "title": "discover_servicesArguments"
}

get_payment_requirements

Probe a URL for x402 payment requirements using x402HTTPClient SDK.

Parameters4

url	string	required
method	string	optional
headers	any	optional
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "title": "Url",
      "type": "string"
    },
    "method": {
      "default": "GET",
      "title": "Method",
      "type": "string"
    },
    "headers": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Headers"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "required": [
    "url"
  ],
  "title": "get_payment_requirementsArguments"
}

pay_and_fetch

Pay via x402HttpxClient and fetch a protected HTTP resource.

Parameters7

url	string	required
method	string	optional
headers	any	optional
body	any	optional
preferred_network	any	optional
max_price_usdc	any	optional
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "title": "Url",
      "type": "string"
    },
    "method": {
      "default": "GET",
      "title": "Method",
      "type": "string"
    },
    "headers": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Headers"
    },
    "body": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Body"
    },
    "preferred_network": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Preferred Network"
    },
    "max_price_usdc": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Price Usdc"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "required": [
    "url"
  ],
  "title": "pay_and_fetchArguments"
}

build_seller_requirements

Build seller-side x402 payment requirements via x402ResourceServer. Pass resource_url (plus optional discovery_* fields) to embed the Bazaar discovery extension so a settled payment catalogs the endpoint.

Parameters12

network	string	optional
pay_to	any	optional
price	string	optional
scheme	string	optional
description	string	optional
resource_url	any	optional
mime_type	any	optional
discoverable	any	optional
discovery_method	string	optional
discovery_input_example	any	optional
discovery_output_example	any	optional
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "network": {
      "default": "eip155:84532",
      "title": "Network",
      "type": "string"
    },
    "pay_to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pay To"
    },
    "price": {
      "default": "$0.01",
      "title": "Price",
      "type": "string"
    },
    "scheme": {
      "default": "exact",
      "title": "Scheme",
      "type": "string"
    },
    "description": {
      "default": "Paid MCP-backed API access",
      "title": "Description",
      "type": "string"
    },
    "resource_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Resource Url"
    },
    "mime_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": "application/json",
      "title": "Mime Type"
    },
    "discoverable": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Discoverable"
    },
    "discovery_method": {
      "default": "GET",
      "title": "Discovery Method",
      "type": "string"
    },
    "discovery_input_example": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Discovery Input Example"
    },
    "discovery_output_example": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Discovery Output Example"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "title": "build_seller_requirementsArguments"
}

verify_payment_payload

Verify PAYMENT-SIGNATURE via x402ResourceServer + facilitator.

Parameters3

payment_signature	string	required
payment_required	string	required
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "payment_signature": {
      "title": "Payment Signature",
      "type": "string"
    },
    "payment_required": {
      "title": "Payment Required",
      "type": "string"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "required": [
    "payment_signature",
    "payment_required"
  ],
  "title": "verify_payment_payloadArguments"
}

get_supported_networks

List networks, facilitators, and v2 headers via x402 SDK.

Parameters1

agent_id

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "title": "get_supported_networksArguments"
}

get_pro_upgrade_requirements

Build x402 payment requirements to purchase Pro tier (revenue collection).

Parameters1

agent_id

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "title": "get_pro_upgrade_requirementsArguments"
}

activate_pro_tier

Verify pro-tier x402 payment and unlock Pro quota limits.

Parameters3

payment_signature	string	required
payment_required	string	required
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "payment_signature": {
      "title": "Payment Signature",
      "type": "string"
    },
    "payment_required": {
      "title": "Payment Required",
      "type": "string"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "required": [
    "payment_signature",
    "payment_required"
  ],
  "title": "activate_pro_tierArguments"
}

get_tool_credits_requirements

Build x402 payment requirements to purchase per-use MCP tool credits.

Parameters2

credits	any	optional
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "credits": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Credits"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "title": "get_tool_credits_requirementsArguments"
}

purchase_tool_credits

Verify x402 payment and add per-use tool credits (per-call revenue path).

Parameters4

payment_signature	string	required
payment_required	string	required
credits	any	optional
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "payment_signature": {
      "title": "Payment Signature",
      "type": "string"
    },
    "payment_required": {
      "title": "Payment Required",
      "type": "string"
    },
    "credits": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Credits"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "required": [
    "payment_signature",
    "payment_required"
  ],
  "title": "purchase_tool_creditsArguments"
}

create_stripe_checkout

Create Stripe Checkout Session for pro tier or tool credits (fiat rail).

Parameters3

purpose	string	optional
credits	any	optional
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "purpose": {
      "default": "pro_tier_upgrade",
      "title": "Purpose",
      "type": "string"
    },
    "credits": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Credits"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "title": "create_stripe_checkoutArguments"
}

run_swarm_research

Run the swarm Agency: compose a research product and list it for resale. Spends nothing by default — the report is synthesized from free inputs, so unsold inventory costs nothing. Pass allow_paid_inputs=True to buy upstream x402 services first (buy → compose → list), which books a cost basis before knowing whether the composite will sell.

Parameters4

topic	string	required
max_price_usdc	any	optional
agent_id	any	optional
allow_paid_inputs	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "title": "Topic",
      "type": "string"
    },
    "max_price_usdc": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Price Usdc"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    },
    "allow_paid_inputs": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Allow Paid Inputs"
    }
  },
  "required": [
    "topic"
  ],
  "title": "run_swarm_researchArguments"
}

settle_composite_sale

Verify + settle a buyer's x402 payment for a listed composite product and record the realized revenue (sell side).

Parameters4

product_id	string	required
payment_signature	string	required
payment_required	string	required
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "product_id": {
      "title": "Product Id",
      "type": "string"
    },
    "payment_signature": {
      "title": "Payment Signature",
      "type": "string"
    },
    "payment_required": {
      "title": "Payment Required",
      "type": "string"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "required": [
    "product_id",
    "payment_signature",
    "payment_required"
  ],
  "title": "settle_composite_saleArguments"
}

swarm_revenue_report

Portfolio revenue intelligence for the swarm: spend, revenue, LTV:CAC, margins, per-source profit scores.

Parameters1

agent_id

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "title": "swarm_revenue_reportArguments"
}

get_base_pulse

Live Base Network Pulse: synthesized settlement-conditions intelligence (base fee, EIP-1559 projection, utilization trend, USD settlement cost, and a settle-now/hold verdict) computed from real Base RPC data + ETH spot price.

Parameters2

depth	any	optional
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "depth": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Depth"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "title": "get_base_pulseArguments"
}

get_os_metrics

Host OS telemetry: CPU, memory, swap, disk, network, and process signals with an ok/warn/critical health verdict, sampled live from the machine running the server. Optionally includes the top processes by memory.

Parameters2

include_processes	boolean	optional
agent_id	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "include_processes": {
      "default": false,
      "title": "Include Processes",
      "type": "boolean"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    }
  },
  "title": "get_os_metricsArguments"
}

README.md18 KBView on GitHub

x402 Micropayments MCP

smithery badge Base Mainnet

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.

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 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	`0x05e1720bB82F86B5bc7940a99FDC702E32256357`
Explorer	https://basescan.org/address/0x05e1720bB82F86B5bc7940a99FDC702E32256357
Machine cashier	buy any live paid endpoint (e.g. $0.01 property-check)
Bounties protocol	docs/BOUNTIES.md · open a bounty
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). Roadmap: ROADMAP.md.

Features

19 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).
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:

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/USER-GUIDE.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):

code

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.*, commerce.*, swarm.*, pulse.*, ops.*, and city.*.

Tool	Description
`x402.agent_card`	Return the A2A Agent ID Card and MCP server card
`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 HTTP resource external buyers use)

Installation

Smithery

Install via Smithery

Remote Streamable HTTP (no install): https://x402-mcp.onrender.com/mcp/mcp

bash

smithery mcp add https://x402-mcp.onrender.com/mcp/mcp --id x402-mcp

Usage

Connect an MCP client to Streamable HTTP /mcp/mcp. Call x402.discover then x402.probe then x402.pay_and_fetch for paid APIs; city.list → city.sample → city.check for US property compliance.

Environment

Variable	Required	Description
`X402_PAY_TO_ADDRESS`	For selling	Recipient wallet — all x402 sales settle here
`CDP_API_KEY_ID` / `CDP_API_KEY_SECRET`	For Base mainnet	Coinbase CDP facilitator creds (verify + settle on `eip155:8453`)
`SWARM_SELL_NETWORK`	For mainnet listings	Set `eip155:8453` to list products on Base mainnet (default: Base Sepolia)
`EVM_PRIVATE_KEY`	For `pay_and_fetch`	Buyer wallet private key — never set this on a public seller host
`STRIPE_SECRET_KEY`	For Stripe checkout	Fiat payment rail
`STRIPE_WEBHOOK_SECRET`	For `/stripe/webhook`	Webhook signature verification
`X402_FACILITATOR_URL`	No	Default: `https://x402.org/facilitator` (testnet; CDP handles mainnet)
`UPGRADE_URL`	No	Commerce tier upgrade link

Commerce Meta Envelope

Every tool response includes:

json

{
  "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 (swarm spend, composite sales, LTV:CAC, per-source profit) surface via swarm_revenue_report / GET /swarm/revenue — total_revenue_usdc is composites only; first-party SKUs are under storefront. 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

bash

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.

Agent ID Cards & Machine Identity

x402-mcp implements the Agent-to-Agent (A2A) Protocol v1.0 and MCP machine identity for autonomous discovery.

HTTP: GET https://x402-mcp.onrender.com/.well-known/agent-card.json (legacy: /.well-known/agent.json)
MCP tool: x402.agent_card (optional target_id for a skill)
MCP resource: x402://agent-card
Registry: /.well-known/agents.json · payTo: /.well-known/funding.json

Every tool accepts optional agent_id for per-caller quota isolation (free tier 500 calls/mo, 10/min).

MCP Prompts Reference (4 Prompts)

Structured prompts for LLM orchestrators:

onboarding_flow — first-run path: doctor → free sample → paid check
x402_tool_selector — pick buyer/seller/commerce tools for a goal
generate_quote — build seller payment requirements / price quote
troubleshoot_payment — diagnose 402 / facilitator / signature failures

MCP Resources Reference (4 Resources)

x402://agent-card — full A2A Agent Card JSON
x402://server-card — MCP server card (transport + x402 auth)
x402://tools-manifest — live tool inventory
x402://pricing-table — paid HTTP resources and prices

Sample AI Agent Queries & Interactions

Real Estate Compliance Workflow

city.list → pick a city code
city.sample free sample for quality
city.check or GET /us/{code}/property-check?address=… with x402 payment

Base Network Gas & Settlement Timing

pulse.base free briefing
Paid GET /base/tx-decision?urgency=flexible before submit

Service Discovery & Protected API Consumption

x402.discover → x402.probe → x402.pay_and_fetch

Seller API Monetization

x402.build_seller with Bazaar discovery metadata → settle inbound via facilitator

Reference Autonomous Buyer Agent (End-to-End Discovery & Settlement)

Run the autonomous buyer reference implementation (examples/reference_buyer_agent.py) demonstrating discovery, 402 challenge negotiation, EIP-3009 payment authorization, and settlement receipt ingestion into MailRail:

bash

python examples/reference_buyer_agent.py --base-url http://localhost:8000 --service base-tx-decision --dry-run

Docker

bash

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

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.

Install

Tools (16)

discover_servicesget_payment_requirementspay_and_fetchbuild_seller_requirementsverify_payment_payloadget_supported_networksget_pro_upgrade_requirementsactivate_pro_tier

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://x402-mcp.onrender.com/mcp/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "x402-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://x402-mcp.onrender.com/mcp/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.kwizzlesurp10-ctrl/x402-mcp (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

discover_services

get_payment_requirements

pay_and_fetch

build_seller_requirements

verify_payment_payload

get_supported_networks

get_pro_upgrade_requirements

activate_pro_tier

get_tool_credits_requirements

purchase_tool_credits

create_stripe_checkout

run_swarm_research

settle_composite_sale

swarm_revenue_report

get_base_pulse

get_os_metrics

x402 Micropayments MCP

Discover (public + A2A)

Fund (USDC on Base)

Live on Base mainnet

Features

Quickstart & 1-Click Installation

Quick Start (Mission Control)

Local stdio (Cursor)

HTTP server

Paid HTTP Resource: MN Property Check

MCP Tools

Installation

Smithery

Usage

Environment

Commerce Meta Envelope

Agent Ops / Swarm Agency

Base Network Pulse

Testing

Mission Control Dashboard

Agent Ops

Agent ID Cards & Machine Identity

MCP Prompts Reference (4 Prompts)

MCP Resources Reference (4 Resources)

Sample AI Agent Queries & Interactions

Real Estate Compliance Workflow

Base Network Gas & Settlement Timing

Service Discovery & Protected API Consumption

Seller API Monetization

Reference Autonomous Buyer Agent (End-to-End Discovery & Settlement)

Docker

Drive Project Folder

License

Install

Remote endpoint

Related servers