X402 Rpc Gateway 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. eth_getLogs across ten thousand blocks costs your node hundreds of times more than eth_blockNumber. 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 PAY_TO_ADDRESS, ORIGIN_URL and PUBLIC_URL. 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 amount_too_low; $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:

• "History from block N onward" — check block N and N-1.
• "Historical state calls are refused, not charged" — a node's own refusal arrives as HTTP 200, so without translation it settles. See nodeRefusal in policy.ts.
• "eth_getLogs up to N blocks" — your client has its own cap on logs per response (Nethermind defaults to 20,000), which bites long before your block limit does.

Getting found

Ranking in the Bazaar is driven by measured usage — l30DaysTotalCalls and l30DaysUniquePayers — not by how well you write your description. Worth knowing before you spend an afternoon on copy.

Worth knowing too: as of August 2026 the entire visible Bazaar handled roughly 1,200 paid calls in thirty days across eighty services. The busiest Ethereum RPC among them served fourteen. Build for the market this becomes, not the one it is.

What this template does for you anyway: a bazaar discovery extension so you are indexed at all, an iconUrl, and payment accepted on Base, Polygon and Arbitrum so more wallets can reach you. What it deliberately does not do is inflate your own call count — that buys a position in a list nobody reads yet, with your own money.

Protecting your origin

Set ORIGIN_TOKEN as a secret and have your origin require the matching X-Origin-Token header. Without it, anyone who learns your origin hostname uses your node for free and the paywall is decorative. A minimal reference proxy is in examples/origin-proxy.py.

Privacy

The receiving address is necessarily public: it is in every payment challenge. Your node's IP is also public, because it takes part in the peer-to-peer network. The link between the two is what you protect.

Someone who submits a transaction through your gateway and watches which IP broadcasts it first learns where your service physically runs. Setting RELAY_URLS sends raw transactions out through public endpoints instead, and that trail disappears. Every other method only returns answers and reveals nothing.

Client usage

Any x402 client pays and retries automatically:

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";

const x402 = new x402Client().register("eip155:8453", new ExactEvmScheme(account));
const fetchWithPay = wrapFetchWithPayment(fetch, x402);
await fetchWithPay("https://your-gateway/rpc", { method: "POST", body });

As a paid fallback behind your own node — see examples/fallback.mjs:

transport: fallback([
  http(YOUR_OWN_RPC),
  http("https://your-gateway/rpc", { fetchFn: fetchWithPay }),
], { retryCount: 0 })

A standby you never use costs nothing. That is the property a subscription cannot offer, and it is the strongest reason to run one of these.

Licence

MIT.