x402-mcp-commerce

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 backthe merchant's artifact with the payment receipt attached. The model never sees a key, neversigns 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 permerchant, per agent, in advance, by a human. x402 inverts that — the merchant advertises a pricein a 402, the agent signs a USDC payment for exactly that amount, and the goods come back inthe same response. A new merchant becomes a new tool by adding four lines to a JSON file. Nosignup, no key distribution, no billing relationship, and a per-call cost the agent can reasonabout because it is printed in the result.

Quickstart

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 withexamples/claude_desktop_config.json, restart, and askfor a table next Friday.

Tools

Twelve commerce tools, generated from config/tools.json, plus threebuilt-ins. Every commerce tool takes an optional rail argument.

Every call returns the same envelope — the merchant's artifact plus the receipt and the exactprice 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 layersdecide which one gets signed — later wins:

auto takes a rail this process holds a key for, EVM first. The choice is honoured strictly: ifthe requested rail isn't in the upstream's accepts, the call fails with RAIL_UNAVAILABLErather than quietly paying on the other one.

The EVM rail signs an EIP-3009 authorization with a viem account. The Solana rail signs an SPLtransferChecked whose network fee is covered by the facilitator's sponsor — so the agent needsUSDC and no SOL.

Spending caps

Checked before any payment is signed, against the real price in the upstream's 402 — so arunaway 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 canexplain itself rather than retry. For purchases that genuinely need to go through, escalate to ahuman with x402-approval-page.

How x402 works

1. The tool calls its upstream route with no payment → 402 Payment Required with an acceptsarray 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 bothland in the tool result.

The inspector's own paid route (GET /attest) speaks the same protocol from the other side:

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 spendingability, 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 itunset 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 anmcp block describing the transport and built-in tools, in the format indexed byx402scan.com, the x402 Bazaar, and agentic.market.
• Not an MCP client? POST /tools/:name runs any tool over HTTP with the same arguments and thesame 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: [email protected]

License

Apache-2.0