Skip to main content
Glama

x402-mcp-commerce

MCP server that gives Claude/GPT agents commerce tools — each tool call pays an upstream x402 endpoint and returns its artifact.

License x402 USDC Rails MCP

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 stdio

Or 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 :4039

Add 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

search_flights

x402-flight-search

$0.005

Priced offers for a route and date.

price_flight

x402-flight-search

$0.003

Live price + availability for one offer.

find_tables

x402-tablebook

$0.001

Open reservation slots.

book_table

x402-tablebook

$0.01

Confirmed reservation + cancel token + refund terms + ICS invite.

search_hotels

x402-hotel-search

$0.005

Room offers for a city and date range.

check_weather

x402-weather-guard

$0.001

Forecast with a plan-relevant summary.

browse_catalog

x402-storefront

free

Items, prices, buy routes.

buy_item

x402-storefront

per item

Digital: signed download URL + license. Physical: signed order + fulfillment record.

search_places

x402-places

$0.002

Places near a point or in an area.

search_news

x402-news-wire

$0.003

Coverage of a topic in a window.

check_domain

x402-domains

$0.001

Registration status, holder, expiry.

track_confirmation

x402-confirmations

$0.005

Any merchant confirmation → portable record + ICS.

list_commerce_tools · spending_report · discover_service

—

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

config/tools.json → defaults.rail

"rail": "auto"

Server-wide

env

X402_RAIL=solana

Per tool, in config

the tool's rail field

"rail": "evm"

Per tool, from env

env

X402_RAIL_BOOK_TABLE=evm

Per call

the model

book_table({…, rail: "solana"})

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 = all

A 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

  1. The tool calls its upstream route with no payment → 402 Payment Required with an accepts array listing both rails.

  2. This server picks the rail (config, per-tool override, or the model's own rail argument), checks the real price against its caps, and signs that payment.

  3. It retries with the base64 X-PAYMENT header; the merchant's facilitator verifies and settles.

  4. 200 — the artifact comes back in the body, the receipt in X-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

base-sepolia

NETWORK=base

PAY_TO_ADDRESS

FACILITATOR_URL (default https://x402.org/facilitator)

Solana

solana

SOLANA_NETWORK=devnet for testing

SOLANA_PAY_TO_ADDRESS

SOLANA_FACILITATOR_URL (default https://facilitator.payai.network)

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 at GET /skill.md.

  • GET /.well-known/x402 — machine-readable manifest (source) with an mcp block 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/:name runs 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

Apache-2.0

Star History

Star History Chart

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

Contributors

Contributors


Available Tools

15 tools
book_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

    A3.7/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers