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

AI agents have reached a cool new level where they can find, pay for, and use APIs all by themselves--no OAuth hassles, no embedded card forms, and no need for customized checkouts. In this post, we’ll walk decision-makers through how Payments MCP combined with the x402 protocol makes it super easy to connect wallets to agents using standard HTTP. We’ll break it down into actionable steps, provide some handy code, and outline the necessary guardrails.

---

TL;DR (description)

x402 transforms HTTP 402 into a seamless machine-payments rail. With Payments MCP, you get a handy package that includes a wallet, onramp, and an x402 client, all bundled into an installable MCP server. This setup lets agents pay for requests and fetch paid data--all without needing user accounts or complicated checkout processes. Right now, Coinbase’s facilitator allows fee-free USDC transactions on Base and Solana, with easy discovery through the x402 Bazaar for automatic agent routing. (docs.cdp.coinbase.com)

---

Why this matters now

• Got APIs, internal tools, or data vendors? With agents that can handle unlock per‑call monetization, you can kick back and relax--no need for pre‑shared API keys, no monthly fees, and definitely no humans needed to manage it all. x402 cleverly taps into the underutilized HTTP 402 status code, along with two headers (X-PAYMENT and X-PAYMENT-RESPONSE), allowing payments to happen seamlessly with your regular requests. Check out the details here: (docs.cdp.coinbase.com)
• Payment MCP is your go-to solution with a fully functional MCP server and a handy companion wallet that connects x402 to AI clients like Claude Desktop. This means your agents can easily “see a 402,” make the payment, and keep moving--entirely programmatically. Dive into the project here: (github.com)

---

What are x402 and Payments MCP (in one screen)

• x402: This is an open, HTTP-native payments protocol. When the server sends back a 402, it lays out the machine-readable “payment requirements.” The client then signs off on a payment payload, fires off the request again with X-PAYMENT, and gets back data along with an optional X-PAYMENT-RESPONSE that includes info about on-chain settlement. You can check out the reference packages like x402-express and x402-axios over on GitHub.
• Payments MCP: This is a handy npx-installable MCP server that comes packed with a wallet, an onramp, and an x402 client. It makes things super easy by automatically configuring popular MCP hosts and gives agents the ability to access paid APIs through tools provided by the MCP server. You can find it on GitHub.

---

How x402 actually works (deep but quick)

• Status: The server gives back an HTTP 402 Payment Required response, along with a JSON body that outlines the "accepts[]" payment requirements like network, asset, amount, destination, timeout, and scheme. Instead of opening a checkout, the client goes ahead and creates a cryptographic payment header. You can dive deeper here.
• Headers:
  • X‑PAYMENT: This is where you'll find the base64‑encoded JSON payment proof. It includes the scheme, network, and the payload featuring either EVM EIP‑3009 authorization or a pre-signed Solana transaction. Check it out here.
  • X‑PAYMENT‑RESPONSE: You’ll get the server’s settlement result (like the transaction hash) in the 200 OK response after everything’s verified and settled. More info here.
• Facilitator: This is basically a verification/settlement service that the seller can trust. Coinbase’s CDP facilitator is top-notch, working well on Base and Solana, complete with KYT/OFAC checks and hassle-free USDC settlement. There are also community and self-hosted facilitators, including options for testnets. Check it out here.
• Tokens & chains:
  • EVM: You can use USDC through EIP‑3009’s transferWithAuthorization for gasless, signature-only payments, and it also supports custom EIP‑3009 tokens with EIP‑712 name/version. Find out more here.
  • Solana: Supports SPL and Token‑2022, but just a heads up--no EIP‑712 support here. More details here.
• Discovery (Bazaar): This is a handy machine-readable catalog where agents can pull a list of x402 endpoints, compare price/output schemas, and automatically route. You can learn more here.

---

Payments MCP + x402 reference architecture

• So, your agent host (like Claude Desktop) is going to call up those MCP tools. Check it out here: (docs.cdp.coinbase.com).
• The Payments MCP server, whether it's on your local machine or a remote server, has tools that can grab those protected endpoints. It basically wraps HTTP clients (like axios or fetch) with x402 interceptors. You can find more info here: (docs.cdp.coinbase.com).
• Inside the MCP, the wallet is responsible for signing EIP‑3009 authorizations for EVM or even pre-signing Solana transactions. The cool part? You won’t see any seed phrase prompts during use if you’ve already set up your keys. Get the details here: (github.com).
• As for the resource servers, they enforce x402 policies; meanwhile, the facilitator makes sure everything is verified and settled, and then the MCP sends back the paid data to your agent. More on this can be found at: (docs.cdp.coinbase.com).

---

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

1. Get Payments MCP set up and ready to roll (auto-config Claude Desktop):

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

This command sets up the MCP server bundle in your home directory at ~/.payments-mcp and gets it all registered with your MCP client. You can check it out on GitHub.

2) Start a Paid API (Sample x402 Express Server)

• You can use the x402 example or create your own route. For instance, you might want to charge $0.001 on Base:

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

If the X-PAYMENT header is missing, the server will respond with a 402 status and an empty accepts[] array. You can check it out here.

3) Wire an MCP Tool That Pays Automatically:

Setting up an MCP tool that handles payments on its own can save you a ton of time and hassle. Here’s how you can get it done:

1. Choose Your MCP Tool: Start by picking the right MCP tool for your needs. Research a few options, and make sure it supports automatic payment features. Some popular choices include MCP Tool A, MCP Tool B, and MCP Tool C.
2. Set Up Your Account: Once you’ve selected a tool, create your account. Make sure to fill in all the necessary details for smooth operation.
3. Connect Your Payment Method: Link your preferred payment method--whether it’s a bank account, credit card, or something else. Double-check that everything's correct to avoid any hiccups later on.
4. Configure Payment Settings: Dive into the settings and customize how and when you want payments to be made. You can typically set things up to pay automatically based on a certain schedule, like daily, weekly, or monthly.
5. Testing: Before going live, it’s a good idea to run a few tests. Send a small amount through the system to ensure that everything is functioning as it should.
6. Monitor Transactions: Even though the tool will handle payments for you, make it a habit to check in now and then. Keeping an eye on your transactions can help you catch any potential issues early.
7. Update as Needed: If you ever change your payment method or need to tweak settings, don’t forget to revisit your MCP tool and make those adjustments!

By following these steps, you’ll have a solid setup that lets the MCP tool do the heavy lifting for your payments while you focus on other important stuff. Happy automating!

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 makes a call to /weather, x402‑axios catches a 402 error, grabs some X‑PAYMENT from your wallet, retries the request, and then sends back the data--no checkout hassle involved. Check out the details here.

1. In Claude Desktop, make sure to use the tool. The flow is pretty seamless for you, but if you ever need receipts or transaction hashes, you can grab the settlement details from X‑PAYMENT‑RESPONSE. Check out the details here: (docs.cdp.coinbase.com).

---

Practical patterns we’re adopting at 7Block Labs

• Price Strings for USDC; TokenAmount for Custom EIP‑3009 Assets
  • For USDC, just go with "$0.01". But for any other EIP‑3009 tokens, make sure to use atomic units and include the EIP‑712 name/version, which you can grab from the token’s name()/version() on the appropriate explorer. (docs.cdp.coinbase.com)
• Timeouts & Nonce Hygiene
  • It's a good idea to set maxTimeoutSeconds somewhere between 60 and 300 seconds. On EVM, make use of validBefore and validAfter in EIP‑3009 to keep the signature window in check, and remember to use random 32-byte nonces for each request. (eips.ethereum.org)
• Gasless on EVM: Prefer EIP‑3009
  • With EIP‑3009, the facilitator covers the gas fees, the user only has to sign once, and there's no need for approvals. If you’re working with non‑3009 chains, think about setting up a compatibility layer or running your own custom facilitator. (docs.cdp.coinbase.com)
• Solana Specifics
  • For Solana, make sure to use SPL or Token‑2022. The facilitator can include feePayer in paymentRequirements.extra and handle signing the fees. (docs.cdp.coinbase.com)
• Discovery-First Agents
  • Check out the x402 Bazaar and filter by maxAmountRequired to dynamically choose your endpoints. This approach works wonders for meta‑agents looking to find the best price for each tool. (docs.cdp.coinbase.com)
• Observability
  • Don't forget to keep a record of X‑PAYMENT‑RESPONSE alongside your request logs. This is super helpful for audits, refunds, and support. (build.avax.network)

---

Security and compliance notes for enterprises

• MCP Hardening
  • MCP is super powerful, but it’s still in its early days. We’ve got to watch out for misconfigured servers and prompt-injection risks. It's a good idea to run Payments MCP in a sandboxed process, limit credentials for each server, and keep an eye on the tools and resources that the agent has access to. (itpro.com)
• Protocol-Level Guardrails
  • When you're integrating on-chain, using EIP-3009's receiveWithAuthorization is a smart move to avoid front-running. Make sure to set narrow validBefore windows and keep track of authorization nonces on the server side. (eips.ethereum.org)
• Facilitator Choice
  • For production, stick with CDP’s facilitator for KYT/OFAC compliance and SLAs. If you’re just running internal pilots, feel free to use community facilitators on testnets. Oh, and if you're working on non-EVM networks or have specific policies, consider self-hosting. (docs.cdp.coinbase.com)
• Data Minimization
  • Good news! x402 doesn’t need any PII; payments are handled through cryptographic authorizations. Only reserve KYC for when your business policy really needs it--remember, the facilitator roadmap has optional attestations lined up. (docs.cdp.coinbase.com)

---

Going live in 48 hours: a crisp plan

• Day 1: Get started with a paid endpoint
  • Kick things off by adding some middleware to your Node API: paymentMiddleware("0xPayout", { "/api/report": "$0.01" }) and run it on Base Sepolia. Make sure to test the whole process from a 402 error to payment and then a 200 confirmation with x402‑axios. You can check it out on GitHub.
• Day 2: Connect with your agent and list on Bazaar
  • First, grab the Payments MCP and set up a “getReport” tool that will call /api/report via x402‑axios.
  • Don’t forget to set discoverable: true in your middleware config! This way, your endpoint will pop up in Bazaar for agents to find it easily. For more info, check out the documentation.

---

What’s new in 2025 you should leverage

• Network Support and Tokens
  • Our CDP-hosted facilitator is here for you, supporting both Base (mainnet, Base Sepolia) and Solana (mainnet, devnet). It's totally token-agnostic, working with EIP-3009 on EVM and SPL/Token-2022 on Solana. Check it out here!
• Discovery Layer (Bazaar)
  • We’ve got machine-readable service listings that come packed with price caps, schemas, and auto-ingestion when discoverable is set. It's perfect for agents who need to pick vendors on the fly! Dive deeper here.
• Smart-Wallet Direction of Travel
  • The community is really pushing for x402 to support ERC-4337 UserOperations, including optional Paymaster sponsorship. If you’re thinking about scaling account-abstraction wallets, make sure to keep an eye on the issue here.
• Ecosystem Growth
  • The official x402 repo says it all: “Just 1 line of code to accept digital dollars. No fees, about 2 seconds for settlement, and a minimum of around $0.001.” You can find examples in express, fetch, axios, and more; plus, Rust, Python, and third-party stacks are starting to pop up. Make sure to validate these claims with your own benchmarks! Check it out here.

---

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

1. When the server sends a 402 response, it includes the following in its 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
  }]
}

2) 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>"
  }
}

3) Resend with Header:

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

1. The server replies with a 200 status and includes the X-PAYMENT-RESPONSE for the 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 those helper packages do for you. Check it out here: (docs.g402.ai).

---

Buyer vs. seller setup (concrete steps)

• Buyer (agent/consumer)
  • You’ve got a couple of options here: either use Payments MCP or wrap your HTTP client with x402‑axios/x402‑fetch. Just make sure you have a funded USDC wallet (EIP‑3009) on the network you prefer. If you’re on Solana, you’ll need a wallet that can sign the pre‑built transaction. Check out the details here.
• Seller (API provider)
  • It’s pretty straightforward! Just drop in the x402 middleware (you can use express, next, or hono) along with your payout address and set a price for each route. If you want to be discoverable, make sure to set discoverable: true and add your input/output schemas so agents can easily find and call you from the Bazaar. For more info, take a look here.

---

Governance/controls to add on day one

• Budget ceilings per agent: Set the maximum amount your MCP client is willing to accept (like, keep it under $0.10). Check out the facilitator list() and price filters for more info. (docs.cdp.coinbase.com)
• Allowlist resource origins: Only pay for the hosts that you’ve got on your list (make sure to pin their expected X‑PAYMENT‑RESPONSE network). (build.avax.network)
• Rotate wallets per agent/job: Use short-lived private keys or have embedded wallets for each session. The Payments MCP installs locally and integrates smoothly with your key management. (github.com)
• Compliance: It’s best to go with the CDP facilitator for mainnet use; if you’re dealing with non-supported chains or have a custom policy, think about self-hosting. (docs.cdp.coinbase.com)

---

Emerging best practices we recommend

• For the first production rollout, go with USDC on Base. It’s got the least friction at the moment thanks to a fee-free facilitator and solid documentation. You can always expand to Solana if needed. (docs.cdp.coinbase.com)
• When integrating smart contracts, make sure to use receiveWithAuthorization. This will help you dodge front-running. Just keep those signature windows short and stay on top of nonce tracking. (eips.ethereum.org)
• Make your endpoints easy for agents to work with. Document your inputSchema and outputSchema, ensure responses are predictable, and include price bands in accepts[]. This will boost your discovery ranking and make agents more reliable. (docs.cdp.coinbase.com)
• Don’t forget to log the requestId ↔ X-PAYMENT/X-PAYMENT-RESPONSE. This is super helpful for handling disputes and refunds later on. (build.avax.network)
• For MCP hardening, make sure to run your MCP servers with the least privilege. Keep environment variables separated, and don’t skip audits for prompt-injection and tool abuse during red team drills. (itpro.com)

---

Where this is headed (and how to plan)

• Short term (this quarter): We're all about getting those production rails up and running on Base/Solana, improving Bazaar discovery, and expanding our client/server libraries across TypeScript, Rust, and Python. Check out the details at (docs.cdp.coinbase.com).
• Near term: We're introducing optional attestations (like KYC and geo) and expanding our network/token support with a facilitator. Plus, keep an eye out for smart-wallet (ERC-4337) flows that promote gas sponsorship in paymentRequirements.extra. More info can be found here: (docs.cdp.coinbase.com).

---

FAQ for decision‑makers

• Are there actually no fees here?
  The protocol fees are totally zero, but just a heads up: the facilitator might take care of the gas costs for EIP-3009 flows. Coinbase promotes fee-free USDC settlement through the CDP facilitator, so be sure to check out the total costs in your own setup. (docs.cdp.coinbase.com)
• Do we really need to create checkout UIs?
  Not at all! The agent simply signs a payment header and retries that same HTTP call. Plus, people can use embedded wallets too; so there’s no need for card forms or OAuth. Check it out here: (docs.cdp.coinbase.com)
• Can agents find vendors while they're running?
  Absolutely! Your agent can tap into x402 Bazaar’s list endpoint and metadata. You can easily filter by price or schema and only pay for what you call. Check it out here: (docs.cdp.coinbase.com)

---

Takeaways

• Looking for a way to get agents paying suppliers or internal APIs this month--like, not next year? The Payments MCP + x402 is honestly the quickest and smoothest option we've found. Use Base USDC along with the CDP facilitator for production, kick things off with price caps and discovery, and then solidify your MCP. Check out the details here: (docs.cdp.coinbase.com)

---

Appendices (copy/paste friendly)

• Go ahead and set up Payments MCP and let Claude auto-configure itself:

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

GitHub Repository

• Lightweight 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)

• Simple 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);

Coinbase CDP Documentation

• Here are some useful docs to have on hand:
  • x402 Overview, Networks, MCP example, and Bazaar (great for discovery). (docs.cdp.coinbase.com)
  • Check out the HTTP 402 semantics (MDN) and the EIP‑3009 spec for security windows. (developer.mozilla.org)

If you're interested in having 7Block Labs run a pilot for this in your stack, we can set up a quick two-day proof of concept (POC) for you. It'll include a single-priced route, agent integration through Payments MCP, discovery features, receipts recorded with X-PAYMENT-RESPONSE, and we'll also make sure to incorporate MCP hardening right from the start.