How to Add x402 Payment Checks to Your MCP Server
· 2 min read
If your AI agent pays x402 APIs through an MCP server, you can add a safety check before every payment with Lumière PayCheck's free MCP tools. The agent sends the quote's amount and payout wallet to check_payment, and pays only when the answer is allow.
Lumière PayCheck doesn't process or hold payments, and it never moves anyone's money. It checks an endpoint and a quote before your agent spends anything. This guide shows how to add the tools and where they fit in your agent's payment flow.
Add the PayCheck MCP tools
There are two ways to connect, and neither needs an API key or an account:
- Remote: point your MCP client at
https://lumierepaycheck.org/mcp(Streamable HTTP). - Local: install the npm package.
npm install lumiere-paycheck-mcpEither way, your agent gets tools such as check_endpoint, check_payment and report_outcome.
Check the quote before paying
With x402, an API asks for payment by answering 402 Payment Required with a quote: a price, a network, a token and a payout wallet (payTo). Amounts are in atomic units, written as a string. USDC has six decimals, so "10000" is $0.01.
Before your agent signs a payment, have it call check_payment with the endpoint's url and the quote's amount and payTo (and the network and asset). Over HTTP, the same check is POST /v1/check-payment.
The answer is allow: true or allow: false, with the reasons for a denial. If it's false, the agent shouldn't pay. Each field catches a different trick: a raised price, a swapped wallet, a swapped network or a swapped token.
Get a quick grade for an endpoint
To look before writing any code, paste an endpoint at https://lumierepaycheck.org/check. In code, use the check_endpoint tool or GET /v1/score?url=<endpoint>. Both are free.
You get a grade and one of these verdicts:
- proceed: a real paid test delivered, and the endpoint is reliable in monitoring.
- caution: something isn't confirmed yet, often because it hasn't been paid-tested. It doesn't mean "don't pay".
- avoid: buyers shouldn't pay it.
- insufficient_data: too new to judge.
PayCheck monitors more than 140,000 x402 endpoints.
Report what happened after paying
A settled payment proves money moved, not that the API delivered. PayCheck makes real paid test calls to check delivery, and each one comes with a receipt signed with Ed25519, at GET /v1/test-receipts?url=<endpoint>.
Your agent can add to that record. After a paid call, use report_outcome to say whether the endpoint delivered what it promised.
Watch for payout wallet changes
PayCheck watches each endpoint's payout wallet. A change nobody declared is flagged as a possible hijack, and check_payment won't allow a payment to a wallet that doesn't match. Wallets are also screened against the OFAC sanctions list.
FAQ
Does this add payments to my own MCP tools? No. This guide is for agents that pay other people's x402 APIs. To charge for your own MCP tools, use an x402 server library, then add your endpoint to PayCheck so buyers can check it.
What's the difference between caution and avoid? Caution means something isn't confirmed yet, often that no paid test has run. Avoid means buyers shouldn't pay the endpoint.
Does Lumière PayCheck hold my money? No. It never moves anyone's money. It only checks endpoints and quotes before you pay.
Start checking x402 endpoints for free at https://lumierepaycheck.org/check
More from the blog
How AI Agents Pay for APIs with USDC
AI agents pay for APIs with USDC using x402: the API answers with a price, and the agent signs a USDC payment for exactly that amount and sends it with its…
x402 Seller Checklist: Verify Your Endpoint Before Buyers Pay
Before AI agents pay your x402 endpoint, many of them check it first. This checklist covers what they look at and how to get your endpoint to a proceed…
Stablecoin Payment APIs for AI Agents: What Developers Should Check
Looking for a stablecoin payment API for an AI agent? The x402 standard lets an agent pay an API per call in USDC, with no account or API key. Before your…