Region Fetch MCP server

Region Fetch

Pre-release. Neither package is published to npm yet, so the install

commands below do not work today — build from source (see

Development). The hosted API at regionfetch.dev is live.

Fetch a public HTTPS URL as a visitor in a specific country would see it, and get a signed receipt proving where the retrieval actually came from.

One request. One x402 payment. One Ed25519-signed attestation of the exit country, supplier, final URL, and content hash.

This repository holds the public client packages:

The service itself runs at https://regionfetch.dev.

Quick start

npm install regionfetch

import { RegionFetchClient } from "regionfetch";

const client = new RegionFetchClient();

const result = await client.fetchUrl(
  { url: "https://example.com/pricing", country: "DE", mode: "browser" },
  { paymentSignature },
);

console.log(result.data.body);
console.log(result.receipt.attestation.payload.country); // "DE"

Supported countries and modes

Countries: US, DE, JP, BR, IN. Anything else is rejected locally before a payment is created.

Escalation tiers

max_tier caps how hard the service will work to retrieve a blocked page: L0 and L1 use the standard regional supplier, L2 permits escalation to a managed unblocker and costs more. Defaults to L1.

The client never assumes a price — it authorizes exactly the amount the deployment returns in its challenge, so a dearer tier needs no client change. L3 is not a supported capability and is rejected before any payment is created.

L2 is priced higher than L0/L1 — $0.05 against $0.02 at the time of writing — and the price comes from the challenge, never from the client.

Pricing

The default list price is $0.02 USDC per request on Base (eip155:8453). Price, network, timeout, and response-size limits are deployment-controlled — read them from the 402 challenge rather than hardcoding them.

Paying

Use the scoped @x402/* packages, not x402 or x402-fetch

This matters more than it looks. The deployment speaks x402 protocol v2:

• CAIP-2 networks (eip155:8453), not chain names (base)
• an amount field, not maxAmountRequired
• the challenge in a PAYMENT-REQUIRED response header, with an empty body
• a PAYMENT-SIGNATURE request header, not X-PAYMENT

The unscoped x402 and x402-fetch packages on npm are v1 only. They parse the challenge from the response body, hardcode x402Versions = [1], reject a CAIP-2 network at the schema, and send X-PAYMENT. They cannot pay this API.

Install the v2 stack:

npm install regionfetch @x402/core @x402/evm viem

Wallet mode — a fresh authorization per request

import { RegionFetchClient } from "regionfetch";
import { createX402PaymentProvider } from "regionfetch/x402";

Shortened. The full README is on GitHub.