Payments MCP + x402: Wiring AI Agents to Wallets Without Custom Checkout

AI agents can now discover, pay, and use APIs on their own—no OAuth, no embedded card forms, no custom checkout. This post shows decision‑makers exactly how Payments MCP plus the x402 protocol lets you plug wallets into agents using standard HTTP, with concrete steps, code, and guardrails.

---

TL;DR (description)

x402 turns HTTP 402 into a machine-payments rail; Payments MCP packages a wallet, onramp, and x402 client into an installable MCP server so agents can pay per request and retrieve paid data—without user accounts or checkout flows. Coinbase’s facilitator supports fee‑free USDC on Base and Solana today, with discovery via the x402 Bazaar for agent auto‑routing. (docs.cdp.coinbase.com)

---

Why this matters now

• Agents that can pay unlock per‑call monetization for your APIs, internal tools, and data vendors—no pre‑shared API keys, no monthly plans, and no human in the loop. x402 uses the dormant HTTP 402 status code and two headers (X-PAYMENT and X‑PAYMENT‑RESPONSE) to complete payments inline with normal requests. (docs.cdp.coinbase.com)
• Payments MCP is a ready‑to‑run MCP server and companion wallet that wires x402 into AI clients like Claude Desktop, so your agents can “see a 402,” pay, and continue—fully programmatically. (github.com)

---

What are x402 and Payments MCP (in one screen)

• x402: an open, HTTP‑native payments protocol. Server replies 402 with machine‑readable “payment requirements.” Client signs a payment payload, resends the request with X‑PAYMENT, and receives data plus optional X‑PAYMENT‑RESPONSE with on‑chain settlement info. Reference packages include x402‑express/x402‑axios. (github.com)
• Payments MCP: npx‑installable MCP server that bundles wallet + onramp + x402 client, auto‑configures popular MCP hosts, and lets agents access paid APIs through tools exposed by the MCP server. (github.com)

---

How x402 actually works (deep but quick)

• Status: server returns HTTP 402 Payment Required with a JSON body listing “accepts[]” payment requirements (network, asset, amount, destination, timeout, scheme). The client doesn’t open a checkout—it creates a cryptographic payment header. (developer.mozilla.org)
• Headers:
  • X‑PAYMENT: base64‑encoded JSON payment proof (scheme, network, payload with EVM EIP‑3009 authorization or pre‑signed Solana tx). (github.com)
  • X‑PAYMENT‑RESPONSE: server’s settlement result (e.g., tx hash) in the 200 OK response after verification/settlement. (github.com)
• Facilitator: a verification/settlement service the seller trusts. Coinbase’s CDP facilitator is production‑grade on Base and Solana with KYT/OFAC checks and fee‑free USDC settlement. Community and self‑hosted facilitators exist, including testnets. (docs.cdp.coinbase.com)
• Tokens & chains:
  • EVM: USDC via EIP‑3009 transferWithAuthorization for gasless, signature‑only payments; custom EIP‑3009 tokens supported with EIP‑712 name/version. (docs.cdp.coinbase.com)
  • Solana: SPL and Token‑2022 supported (no EIP‑712). (docs.cdp.coinbase.com)
• Discovery (Bazaar): a machine‑readable catalog so agents can fetch a list of x402 endpoints, compare price/output schemas, and auto‑route. (docs.cdp.coinbase.com)

---

Payments MCP + x402 reference architecture

• Agent host (e.g., Claude Desktop) calls MCP tools. (docs.cdp.coinbase.com)
• Payments MCP server (your machine or a server) exposes tools that fetch protected endpoints. It wraps HTTP clients (axios/fetch) with x402 interceptors. (docs.cdp.coinbase.com)
• Wallet inside MCP signs EIP‑3009 authorizations (EVM) or pre‑signs Solana transactions; no seed phrase prompts during use if you provision keys. (github.com)
• Resource servers enforce x402; facilitator verifies/settles; MCP returns paid data to the agent. (docs.cdp.coinbase.com)

---

End‑to‑end: Claude + Payments MCP + a paid “weather” API

1. Install and configure Payments MCP (auto‑config Claude Desktop):

npx @coinbase/payments-mcp --client claude --auto-config

This installs the MCP server bundle at ~/.payments-mcp and registers it with your MCP client. (github.com)

1. Start a paid API (sample x402 Express server):

• Use x402 example or your own route, e.g., charge $0.001 on Base:

import { paymentMiddleware } from "x402-express";
app.use(paymentMiddleware("0xYourPayoutAddress", { "/weather": "$0.001" }));

The server responds 402 with accepts[] if X‑PAYMENT is missing. (github.com)

1. Wire an MCP tool that pays automatically:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import axios from "axios";
import { Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { withPaymentInterceptor } from "x402-axios";
import { config } from "dotenv";
config();

// .env: PRIVATE_KEY, RESOURCE_SERVER_URL, ENDPOINT_PATH
const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const client = withPaymentInterceptor(axios.create({ baseURL: process.env.RESOURCE_SERVER_URL! }), account);

const server = new McpServer({ name: "x402 MCP Demo", version: "1.0.0" });
server.tool("get-weather", "Fetch paid weather", {}, async () => {
  const res = await client.get(process.env.ENDPOINT_PATH!);
  return { content: [{ type: "text", text: JSON.stringify(res.data) }] };
});

await server.connect(new StdioServerTransport());

When the tool calls /weather, x402‑axios intercepts a 402, builds X‑PAYMENT from your wallet, retries, and returns the data—no checkout. (docs.cdp.coinbase.com)

1. In Claude Desktop, use the tool. The flow is invisible to the user; settlement details can be captured from X‑PAYMENT‑RESPONSE if you need receipts/tx hashes. (docs.cdp.coinbase.com)

---

Practical patterns we’re adopting at 7Block Labs

• Price strings for USDC; TokenAmount for custom EIP‑3009 assets
  • Use "$0.01" for USDC; for other EIP‑3009 tokens, specify atomic units and EIP‑712 name/version (from the token’s name()/version() on the relevant explorer). (docs.cdp.coinbase.com)
• Timeouts & nonce hygiene
  • Set maxTimeoutSeconds (e.g., 60–300s). On EVM, use validBefore/validAfter in EIP‑3009 to bound the signature window; random 32‑byte nonces per request. (eips.ethereum.org)
• Gasless on EVM: prefer EIP‑3009
  • Facilitator sponsors gas; user signs once; no approvals. If you need non‑3009 chains, consider a compatibility layer or run a custom facilitator. (docs.cdp.coinbase.com)
• Solana specifics
  • Use SPL or Token‑2022; facilitator may include feePayer in paymentRequirements.extra and sign fees. (docs.cdp.coinbase.com)
• Discovery‑first agents
  • Query x402 Bazaar, filter by maxAmountRequired, pick endpoints dynamically; great for meta‑agents that shop for the best price per tool. (docs.cdp.coinbase.com)
• Observability
  • Persist X‑PAYMENT‑RESPONSE alongside your request logs for auditability and refunds/support. (build.avax.network)

---

Security and compliance notes for enterprises

• MCP hardening
  • MCP is powerful but early; misconfigured servers and prompt‑injection are real risks. Run Payments MCP in a sandboxed process, scope credentials per server, and audit tools/resources exposed to the agent. (itpro.com)
• Protocol‑level guardrails
  • Use EIP‑3009 receiveWithAuthorization in on‑chain integrations to prevent front‑running; set narrow validBefore windows and track authorization nonces server‑side. (eips.ethereum.org)
• Facilitator choice
  • For production, use CDP’s facilitator for KYT/OFAC and SLAs; for internal pilots, community facilitators on testnets are fine. Consider self‑hosting for non‑EVM networks or custom policies. (docs.cdp.coinbase.com)
• Data minimization
  • x402 doesn’t require PII; payments are cryptographic authorizations. Reserve KYC only when your business policy requires it (facilitator roadmap includes optional attestations). (docs.cdp.coinbase.com)

---

Going live in 48 hours: a crisp plan

• Day 1: Pilot a paid endpoint
  • Add middleware to your Node API: paymentMiddleware("0xPayout", { "/api/report": "$0.01" }) and run on Base Sepolia. Validate the 402 → pay → 200 flow with x402‑axios. (github.com)
• Day 2: Plug into your agent and list in Bazaar
  • Install Payments MCP; expose a “getReport” tool that calls /api/report through x402‑axios.
  • Set discoverable: true in your middleware config so your endpoint shows in Bazaar for agent auto‑discovery. (docs.cdp.coinbase.com)

---

What’s new in 2025 you should leverage

• Network support and tokens
  • CDP‑hosted facilitator supports Base (mainnet, Base Sepolia) and Solana (mainnet, devnet). Token‑agnostic with EIP‑3009 on EVM; SPL/Token‑2022 on Solana. (docs.cdp.coinbase.com)
• Discovery layer (Bazaar)
  • Machine‑readable service listings with price caps, schemas, and auto‑ingestion when discoverable is set—ideal for agents that select vendors on the fly. (docs.cdp.coinbase.com)
• Smart‑wallet direction of travel
  • Community is pushing x402 to support ERC‑4337 UserOperations with optional Paymaster sponsorship; track the issue if you plan account‑abstraction wallets at scale. (github.com)
• Ecosystem growth
  • Official x402 repo: “1 line of code to accept digital dollars. No fees, ~2s settlement, ~$0.001 minimum” with examples in express/fetch/axios; Rust, Python, and third‑party stacks are appearing. Validate claims in your own benchmarks. (github.com)

---

Example: reading and honoring a 402 by hand (for clarity)

1. Server returns 402 with accepts[]:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "asset": "USDC",
    "maxAmountRequired": "1000",  // 0.001 USDC
    "payTo": "0xA247...cd1c0",
    "resource": "https://api.example.com/weather",
    "maxTimeoutSeconds": 120
  }]
}

1. Client creates payment header (simplified EVM EIP‑3009 payload):

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "authorization": {
      "from": "0xBuyer",
      "to": "0xA247...cd1c0",
      "value": "1000",
      "validAfter": "0",
      "validBefore": "1735689600",
      "nonce": "0x<32-bytes>"
    },
    "signature": "0x<sig>"
  }
}

1. Resend with header:

GET /weather HTTP/1.1
Host: api.example.com
X-PAYMENT: <base64(json)>

1. Server responds 200 with X‑PAYMENT‑RESPONSE for audit:

HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: <base64({"success":true,"transaction":"0x..","network":"base"})>

{"tempC":21.4,"conditions":"Sunny"}

This is exactly what the helper packages automate for you. (docs.g402.ai)

---

Buyer vs. seller setup (concrete steps)

• Buyer (agent/consumer)
  • Use Payments MCP or wrap your HTTP client with x402‑axios/x402‑fetch; keep a funded USDC wallet (EIP‑3009) on your chosen network; for Solana, use a wallet that can sign the pre‑built transaction. (docs.cdp.coinbase.com)
• Seller (API provider)
  • Drop in x402 middleware (express/next/hono) with a payout address and per‑route price. For discovery, set discoverable: true and include input/output schemas so agents can call you correctly from the Bazaar. (github.com)

---

Governance/controls to add on day one

• Budget ceilings per agent: cap maxAmountRequired your MCP client will accept (e.g., < $0.10). See facilitator list() + price filters for discovery. (docs.cdp.coinbase.com)
• Allowlist resource origins: only pay to hosts you list (and pin their expected X‑PAYMENT‑RESPONSE network). (build.avax.network)
• Rotate wallets per agent/job: short‑lived private keys or embedded wallets per session; Payments MCP installs locally and works with your key management. (github.com)
• Compliance: prefer CDP facilitator for mainnet usage; self‑hosted for non‑supported chains or custom policy. (docs.cdp.coinbase.com)

---

Emerging best practices we recommend

• Prefer USDC on Base for first production rollout: lowest friction today with fee‑free facilitator and strong docs; expand to Solana as needed. (docs.cdp.coinbase.com)
• Use receiveWithAuthorization in smart‑contract integrations to avoid front‑running; keep signature windows short and nonce tracking robust. (eips.ethereum.org)
• Make your endpoints agent‑friendly: document inputSchema/outputSchema, keep responses deterministic, and share price bands in accepts[]. This improves discovery ranking and agent reliability. (docs.cdp.coinbase.com)
• Ship with logging of requestId ↔ X‑PAYMENT/X‑PAYMENT‑RESPONSE to support disputes and refunds. (build.avax.network)
• MCP hardening: run MCP servers with least privilege, segregate environment variables, and audit for prompt‑injection/tool abuse during red‑team drills. (itpro.com)

---

Where this is headed (and how to plan)

• Short term (this quarter): production rails on Base/Solana, Bazaar discovery, and growing client/server libraries across TS, Rust, and Python. (docs.cdp.coinbase.com)
• Near term: optional attestations (KYC/geo) and broader network/token support via facilitator; watch for smart‑wallet (ERC‑4337) flows that advertise gas sponsorship in paymentRequirements.extra. (docs.cdp.coinbase.com)

---

FAQ for decision‑makers

• Is this “no fees” really no fees?
  Protocol fees are zero; facilitator may cover gas for EIP‑3009 flows. Coinbase markets fee‑free USDC settlement on CDP’s facilitator; validate end‑to‑end costs in your environment. (docs.cdp.coinbase.com)

• Do we need to build checkout UIs?
  No. The agent signs a payment header and retries the same HTTP call. Humans can also use embedded wallets; either way, no card forms or OAuth. (docs.cdp.coinbase.com)

• Can agents discover vendors at runtime?
  Yes, via x402 Bazaar’s list endpoint and metadata; your agent can filter by price/schema and then pay per call. (docs.cdp.coinbase.com)

---

Takeaways

• If you want agents paying suppliers or internal APIs this month—not next year—Payments MCP + x402 is the fastest, lowest‑friction route we’ve seen. Use Base USDC + CDP facilitator for production, start with price caps and discovery, and harden MCP. (docs.cdp.coinbase.com)

---

Appendices (copy/paste friendly)

• Install Payments MCP and auto‑configure Claude:

npx @coinbase/payments-mcp --client claude --auto-config

(github.com)

• Minimal seller middleware (Express):

import { paymentMiddleware } from "x402-express";
app.use(paymentMiddleware("0xYourPayout", {
  "/api/premium": {
    price: "$0.01",
    network: "base",
    config: {
      discoverable: true,
      description: "Premium endpoint",
    }
  }
}));

(github.com)

• Minimal buyer (agent) HTTP client:

import axios from "axios";
import { withPaymentInterceptor } from "x402-axios";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const api = withPaymentInterceptor(axios.create({ baseURL: "https://api.example.com" }), account);

const res = await api.get("/api/premium");
console.log(res.data);

(docs.cdp.coinbase.com)

• Helpful docs to keep open:
  • x402 Overview, Networks, MCP example, Bazaar (for discovery). (docs.cdp.coinbase.com)
  • HTTP 402 semantics (MDN) and EIP‑3009 spec for security windows. (developer.mozilla.org)

If you want 7Block Labs to pilot this in your stack, we can ship a two‑day POC: one priced route, agent integration via Payments MCP, discovery enabled, receipts logged with X‑PAYMENT‑RESPONSE, and MCP hardening baked in.