x402-mcp-commerce
Use this MCP server to give Claude/GPT agents paid commerce tools that charge upstream x402 endpoints in USDC on Base or Solana per call and return the merchant artifact plus payment receipt.
List all commerce tools with upstream, price, and rail; show spending caps/session ledger; discover any x402 service manifest.
Search/price flights, find/book restaurant tables, search hotels, check weather, browse/buy storefront items, search places/news, check domains, and normalize confirmations into portable records/ICS invites.
Choose the payment rail per call (
auto,evm,solana) with strict rail honoring, spending caps enforced before signing, and no wallet keys exposed to the model.Use over MCP stdio or HTTP
POST /tools/:name; all paid calls share a standard envelope with artifact, receipt, and exact price.
Provides a Solana payment rail for x402 commerce tools, enabling agents to pay upstream endpoints in USDC per call via signed SPL transferChecked transactions, with Solana selectable as the rail and network fees sponsored by the facilitator.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@x402-mcp-commerce book a table for two next Friday at 7pm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
x402-mcp-commerce
MCP server that gives Claude/GPT agents commerce tools — each tool call pays an upstream x402 endpoint and returns its artifact.
Pay in USDC on Base or Solana — the agent picks the rail, per call.
Give a model a wallet, a spending cap, and a dozen merchants. book_table, search_flights,
buy_item, check_weather — each tool call pays an upstream x402 route in USDC and hands back
the merchant's artifact with the payment receipt attached. The model never sees a key, never
signs anything, and cannot spend past a cap it doesn't control.
Why x402 for this
Tool-using agents hit a wall the moment a tool costs money: API keys have to be provisioned per
merchant, per agent, in advance, by a human. x402 inverts that — the merchant advertises a price
in a 402, the agent signs a USDC payment for exactly that amount, and the goods come back in
the same response. A new merchant becomes a new tool by adding four lines to a JSON file. No
signup, no key distribution, no billing relationship, and a per-call cost the agent can reason
about because it is printed in the result.
Related MCP server: intelligence-api
Quickstart
Run the published MCP server without cloning:
npx @nirholas/x402-mcp-commerce # MCP server over stdioOr work from source:
git clone https://github.com/nirholas/x402-mcp-commerce
cd x402-mcp-commerce && npm install
# rehearse the whole toolbox against the sandbox — costs a fraction of a cent
git clone https://github.com/nirholas/x402-agent-sandbox
(cd ../x402-agent-sandbox && npm install && npm run dev &) # :4038
X402_TOOLS_CONFIG=./config/tools.sandbox.json npx tsx examples/agent-client.ts
# the real thing
npm run mcp # MCP server over stdio — what Claude Desktop launches
npm run dev # the HTTP inspector on :4039Add it to Claude Desktop with
examples/claude_desktop_config.json, restart, and ask
for a table next Friday.
Tools
Twelve commerce tools, generated from config/tools.json, plus three
built-ins. Every commerce tool takes an optional rail argument.
Tool | Upstream | Price | What you get back |
| x402-flight-search | $0.005 | Priced offers for a route and date. |
| x402-flight-search | $0.003 | Live price + availability for one offer. |
| x402-tablebook | $0.001 | Open reservation slots. |
| x402-tablebook | $0.01 | Confirmed reservation + cancel token + refund terms + ICS invite. |
| x402-hotel-search | $0.005 | Room offers for a city and date range. |
| x402-weather-guard | $0.001 | Forecast with a plan-relevant summary. |
| x402-storefront | free | Items, prices, buy routes. |
| x402-storefront | per item | Digital: signed download URL + license. Physical: signed order + fulfillment record. |
| x402-places | $0.002 | Places near a point or in an area. |
| x402-news-wire | $0.003 | Coverage of a topic in a window. |
| x402-domains | $0.001 | Registration status, holder, expiry. |
| x402-confirmations | $0.005 | Any merchant confirmation → portable record + ICS. |
| — | free | Capabilities, ledger, and any x402 service's manifest. |
Every call returns the same envelope — the merchant's artifact plus the receipt and the exact price paid:
{
"tool": "book_table",
"paid": true,
"rail": { "requested": "auto", "used": "evm" },
"artifact": { "reservationId": "res_…", "cancelToken": "…", "ics": "…" },
"receipt": { "success": true, "network": "base-sepolia", "transaction": "0x…", "payer": "0x…" },
"price": { "usd": 0.01, "atomic": "10000", "asset": "0x036C…" }
}Full reference: docs/api.md · openapi.json
Choosing a payment rail
Every suite merchant offers USDC on Base and USDC on Solana in the same 402. Five layers decide which one gets signed — later wins:
Layer | Where | Example |
Registry default |
|
|
Server-wide | env |
|
Per tool, in config | the tool's |
|
Per tool, from env | env |
|
Per call | the model |
|
auto takes a rail this process holds a key for, EVM first. The choice is honoured strictly: if
the requested rail isn't in the upstream's accepts, the call fails with RAIL_UNAVAILABLE
rather than quietly paying on the other one.
The EVM rail signs an EIP-3009 authorization with a viem account. The Solana rail signs an SPL
transferChecked whose network fee is covered by the facilitator's sponsor — so the agent needs
USDC and no SOL.
Spending caps
Checked before any payment is signed, against the real price in the upstream's 402 — so a runaway loop stops at the ledger, not at the chain.
MAX_PER_CALL_USD=0.05 # most this agent will pay for one call
MAX_SESSION_USD=1 # total for this process
MAX_CALLS=200 # total paid calls
ALLOWED_TOOLS= # comma-separated allowlist; empty = allA blocked call returns the cap that stopped it plus the current spending state, so the model can explain itself rather than retry. For purchases that genuinely need to go through, escalate to a human with x402-approval-page.
How x402 works
The tool calls its upstream route with no payment →
402 Payment Requiredwith anacceptsarray listing both rails.This server picks the rail (config, per-tool override, or the model's own
railargument), checks the real price against its caps, and signs that payment.It retries with the base64
X-PAYMENTheader; the merchant's facilitator verifies and settles.200— the artifact comes back in the body, the receipt inX-PAYMENT-RESPONSE, and both land in the tool result.
The inspector's own paid route (GET /attest) speaks the same protocol from the other side:
rail | network (default) | mainnet | payTo | facilitator |
EVM |
|
|
|
|
Solana |
|
|
|
|
Both ship with the suite's public receive addresses pre-filled in .env.example, so npm run dev works with zero configuration.
Real backend / API keys
Self-contained: no third-party APIs and no keys of its own. What the envs unlock is spending ability, not data:
PRIVATE_KEY— the EVM wallet that signs Base payments. Without it the EVM rail is unavailable.SOLANA_PRIVATE_KEY— base58 or JSON-array secret key for the Solana rail. Optional; leave it unset and the agent simply never takes that rail.SOLANA_RPC_URL— used to build the SPL transfer. The public endpoint is heavily rate limited.SIGNING_SECRET— HMAC key behind the attestation signature.
Upstream services have their own key policies; this server just pays them.
For AI agents
skill.md— agent-facing capability sheet, served atGET /skill.md.GET /.well-known/x402— machine-readable manifest (source) with anmcpblock describing the transport and built-in tools, in the format indexed by x402scan.com, the x402 Bazaar, and agentic.market.Not an MCP client?
POST /tools/:nameruns any tool over HTTP with the same arguments and the same envelope. It is free to call and spends your wallet — keep it off the public internet.Guide: docs/agents.md · Claude wiring: examples/mcp-tool.md.
Docs
Site: https://nirholas.github.io/x402-mcp-commerce/ — tutorial · API · agents · curl walkthrough
Part of the x402 Suite.
Support
Questions, bugs, integration help: nichxbt@gmail.com
License
Star History
Support the project
If x402-mcp-commerce saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.
Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit
Built for AI agents too
Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/x402-mcp-commerce and it has the context it needs.
More from the same author
All repositories by nirholas: the full catalog, grouped by topic
three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
Questions or ideas: open an issue or start a discussion
Contributors
Available Tools
15 toolsbook_tableA
Book a restaurant table. Returns the confirmed reservation with a cancel token, refund terms and a calendar invite. The hold is refundable. Costs $0.01 per call, paid in USDC over x402 to x402-tablebook. Returns the merchant's artifact and the payment receipt.
Inputs: date (required), name (required), time (required), party (required), +2 more.
browse_catalogB
List a storefront's items with prices and buy routes. Free at the merchant. Costs free per call, paid in USDC over x402 to x402-storefront. Returns the merchant's artifact and the payment receipt.
Inputs: rail.
buy_itemA
Buy an item from a storefront. Digital goods return a signed download URL and license; physical goods return a signed order confirmation and fulfillment record. Costs per item per call, paid in USDC over x402 to x402-storefront. Returns the merchant's artifact and the payment receipt.
Inputs: sku (required), name, rail, address, +1 more.
check_domainA
Check whether a domain is registered, and if so who holds it and when it expires. Costs $0.001 per call, paid in USDC over x402 to x402-domains. Returns the merchant's artifact and the payment receipt.
Inputs: domain (required), rail.
check_weatherA
Forecast for a location, with the plan-relevant summary an agent needs to decide whether an outdoor booking is a good idea. Costs $0.001 per call, paid in USDC over x402 to x402-weather-guard. Returns the merchant's artifact and the payment receipt.
Inputs: lat (required), lon (required), date, rail.
discover_serviceA
Read any x402 service's /.well-known/x402 manifest to learn its routes, prices, payment rails, and response schemas. Free — no payment is made.
Inputs: baseUrl (required).
find_tablesA
List open restaurant reservation slots for a date and party size. Costs $0.001 per call, paid in USDC over x402 to x402-tablebook. Returns the merchant's artifact and the payment receipt.
Inputs: date, days, rail, party.
list_commerce_toolsA
List every commerce tool this server exposes, with its upstream service, price, and configured payment rail. Free — no payment is made.
Inputs: no named parameters.
price_flightA
Confirm the live price and availability of a specific flight offer before booking. Costs $0.003 per call, paid in USDC over x402 to x402-flight-search. Returns the merchant's artifact and the payment receipt.
Inputs: offerId (required), rail.
search_flightsA
Search flights between two airports on a date. Returns priced offers with airline, times, stops and fare basis. Costs $0.005 per call, paid in USDC over x402 to x402-flight-search. Returns the merchant's artifact and the payment receipt.
Inputs: origin (required), destination (required), departureDate (required), rail, +3 more.
search_hotelsA
Search hotel rooms and offers for a city and date range. Costs $0.005 per call, paid in USDC over x402 to x402-hotel-search. Returns the merchant's artifact and the payment receipt.
Inputs: checkIn (required), checkOut (required), cityCode (required), rail, +1 more.
search_newsA
Query the global news wire for coverage of a topic in a time window. Costs $0.003 per call, paid in USDC over x402 to x402-news-wire. Returns the merchant's artifact and the payment receipt.
Inputs: q (required), rail, limit, since.
search_placesA
Find places — restaurants, shops, landmarks — near a point or in a named area. Costs $0.002 per call, paid in USDC over x402 to x402-places. Returns the merchant's artifact and the payment receipt.
Inputs: q, lat, lon, kind, +2 more.
spending_reportA
Show this agent's spending caps, how much it has spent so far, and every payment it has made in this session. Free — no payment is made.
Inputs: no named parameters.
track_confirmationA
Normalize any merchant confirmation into a portable record plus an ICS calendar invite. Feed it the artifact any booking tool returned. Costs $0.005 per call, paid in USDC over x402 to x402-confirmations. Returns the merchant's artifact and the payment receipt.
Inputs: rail, type, rawText, confirmation.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool is scoped to a distinct merchant/action pair (flights, tables, hotels, weather, storefront, places, news, domains), and search vs. confirm (search_flights vs. price_flight) is spelled out. The only real friction is between find_tables and search_places, which can both surface restaurants, and browse_catalog vs. search_places, though descriptions mostly disambiguate.
Nearly all tools follow a verb_noun snake_case pattern (search_flights, book_table, check_domain, list_commerce_tools). The exceptions are spending_report (noun-only, no verb) and the mixed verb choice of find_tables vs. search_places/search_hotels for what is conceptually similar listing behavior.
15 tools is right at the top of the ideal range and each maps to a distinct paid upstream service or a genuinely useful meta-operation (list_commerce_tools, spending_report, discover_service). Nothing appears redundant or padded for a multi-merchant commerce aggregator.
The flight flow dead-ends: search_flights and price_flight exist but there is no book_flight, and search_hotels has no matching book_hotel, so two of the three major booking domains cannot be completed. Cancellation is also missing despite book_table returning a cancel token, leaving agents stuck after a booking.
Maintenance
Related MCP Connectors
MCP server for X420's pay-per-call agent services (x402, USDC on Base, paid from your own wallet).
371Agent-commerce MCP server for x402/USDC payments and affiliate splits on Base.
Monetize any MCP server: x402 paywall, pay-per-call billing in USDC on Base, agent marketplace.
Remote MCP utilities for agents: structured data, commerce checks, and x402 paid API discovery.
Related MCP Servers
- AlicenseAqualityFmaintenanceMCP server for the402.ai — an open marketplace where AI agents discover and purchase services from third-party providers via x402 micropayments (USDC on Base). Browse the catalog, purchase services, manage conversation threads, and list services as a provider.302MIT
- AlicenseAqualityDmaintenanceMCP server that wraps Shopify, Amazon, and Google Maps intelligence tools. AI agents pay autonomously in USDC on Base via x402 — no API keys or accounts needed.62MIT
- AlicenseCqualityDmaintenanceMCP server bringing 100+ x402-paid APIs to AI agents (Claude, Cursor, MCP-aware clients). Auto-discovers tools from CDP Bazaar; handles USDC micropayments on Base.10083 npm1MIT
- FlicenseAqualityCmaintenanceMCP server for a live x402 payment gateway on Base (USDC). Lets AI agents discover, preview for free, then pay per call — with prepaid gasless payments, signed receipts, and delta delivery.7-