x402 Ethereum RPC MCP server

x402-rpc-gateway

A Cloudflare Worker that sells JSON-RPC access to your own Ethereum node, one request at a time, over x402. No accounts, no API keys, no invoices: a caller signs a USDC authorization on Base and gets the answer in the same exchange.

Running in production at 402rpc.com.

Why this exists

Selling RPC access normally means building signup, billing, key rotation and rate plans before you serve a single request. x402 removes all of it — but a naive gateway that simply charges per call creates two new problems, and this template solves both.

Callers must never pay for an answer you cannot give. Every request is checked before the paywall. A blocked namespace, a block below your history floor, a log range that is too wide — all return HTTP 400, and x402 does not settle on a response of 400 or higher. Node failures return 502 for the same reason.

Flat pricing loses money. ethgetLogs across ten thousand blocks costs your node hundreds of times more than ethblockNumber. Prices here scale with the work a method actually costs.

Your node's own refusals arrive as HTTP 200. A node that says "no state available at that block" or "too many logs in one response" returns a JSON-RPC error with a 200 status — and x402 settles on a 200. Left alone, your customers pay for answers you could not give. This template translates that class of error into a 4xx so nothing settles. Errors that are a real answer, execution reverted for instance, stay chargeable.

What you get

• Per-method pricing, configurable, with a ceiling so a batch never surprises anyone
• A policy layer that refuses before charging, with reasons a caller can act on
• Raw transactions relayed through public RPCs instead of your own node — see Privacy
• Discovery metadata so agents can find and use the service without a human
• A landing page for humans and JSON for machines, chosen by the Accept header
• An MCP server, so any agent can use it as a tool
• A fallback example: one line to add your gateway as a paid standby behind a primary

Setup

npm install
cp wrangler.jsonc.example wrangler.jsonc   # edit the vars
npx wrangler deploy

At minimum, set PAYTOADDRESS, ORIGINURL and PUBLICURL. Everything else has a working default.

For a mainnet network you need Coinbase CDP credentials — the public x402.org facilitator serves testnets only:

npx wrangler secret put CDP_API_KEY_ID
npx wrangler secret put CDP_API_KEY_SECRET

Without them the Worker deliberately answers 503 rather than issuing payment challenges it cannot settle.

Three things the documentation will not tell you

The facilitator has an undocumented floor. Amounts around $0.0002 are rejected with amounttoolow; $0.001 goes through. Price differentiation therefore only works upward from roughly a tenth of a cent.

The Bazaar only indexes x402 version 2. Every one of the twenty resources I checked runs v2; none run v1. If you build on the v1 packages (x402-hono, x402-fetch — last published April 2026) your service works but is invisible to the discovery layer agents actually query. This template uses v2 throughout.

Pin resource to your public URL. Left to derive it from the request, the middleware puts your Worker's internal hostname — which contains your Cloudflare account name — into every payment challenge, right next to your receiving address.

Verify your own claims

Everything this template puts in your payment terms and landing page is a promise to a paying stranger. Test them against what your node actually does, not against what you believe it does. Three that bit us:

Shortened. The full README is on GitHub.