create-pay-gate 0.1.1

package/dist/index.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout, argv } from "node:process";
+import { mkdirSync, writeFileSync, copyFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = join(__dirname, "..", "template");
+async function main() {
+    const projectName = argv[2] || "";
+    console.log();
+    console.log("  pay-gate — x402 payment gateway for Cloudflare Workers");
+    console.log();
+    const rl = createInterface({ input: stdin, output: stdout });
+    const name = projectName || await rl.question("  Project name: ");
+    const providerAddress = await rl.question("  Provider wallet address (0x...): ");
+    const proxyTarget = await rl.question("  Origin URL (e.g. https://api.example.com): ");
+    const defaultRoute = await rl.question("  Paid route glob (e.g. /api/v1/*): ");
+    const priceStr = await rl.question("  Price per request in USD (e.g. 0.01): ");
+    rl.close();
+    if (!name) {
+        console.error("  Error: project name is required.");
+        process.exit(1);
+    }
+    if (!providerAddress.startsWith("0x") || providerAddress.length !== 42) {
+        console.error("  Error: provider address must be a 42-character hex address (0x...).");
+        process.exit(1);
+    }
+    if (!proxyTarget.startsWith("http")) {
+        console.error("  Error: origin URL must start with http:// or https://.");
+        process.exit(1);
+    }
+    const price = parseFloat(priceStr) || 0.01;
+    const settlement = price <= 1.0 ? "tab" : "direct";
+    const outDir = resolve(name);
+    if (existsSync(outDir)) {
+        console.error(`  Error: directory "${name}" already exists.`);
+        process.exit(1);
+    }
+    // Create project
+    mkdirSync(join(outDir, "src"), { recursive: true });
+    // Copy template source files
+    const templateSrc = join(TEMPLATE_DIR, "src");
+    for (const file of readdirSync(templateSrc)) {
+        copyFileSync(join(templateSrc, file), join(outDir, "src", file));
+    }
+    // Generate wrangler.toml
+    writeFileSync(join(outDir, "wrangler.toml"), wranglerToml(name, providerAddress, proxyTarget));
+    // Generate package.json
+    writeFileSync(join(outDir, "package.json"), packageJson(name));
+    // Copy tsconfig.json
+    copyFileSync(join(TEMPLATE_DIR, "tsconfig.json"), join(outDir, "tsconfig.json"));
+    // Generate routes.json (initial KV data)
+    writeFileSync(join(outDir, "routes.json"), routesJson(defaultRoute, price.toString(), settlement));
+    console.log();
+    console.log(`  Created ${name}/`);
+    console.log();
+    console.log("  Next steps:");
+    console.log(`    cd ${name}`);
+    console.log("    npm install");
+    console.log("    # Create KV namespace: npx wrangler kv namespace create ROUTES");
+    console.log("    # Update wrangler.toml with the KV namespace ID");
+    console.log("    # Upload routes: npx wrangler kv bulk put routes.json --namespace-id <id>");
+    console.log("    npx wrangler dev     # local development");
+    console.log("    npx wrangler deploy  # deploy to Cloudflare");
+    console.log();
+}
+function wranglerToml(name, provider, target) {
+    return `name = "${name}"
+main = "src/index.ts"
+compatibility_date = "2026-04-01"
+
+# Heartbeat cron — sends discovery heartbeat hourly.
+# Only fires if DISCOVERY_BASE_URL is set.
+[triggers]
+crons = ["0 * * * *"]
+
+[vars]
+PROVIDER_ADDRESS = "${provider}"
+PROXY_TARGET = "${target}"
+DEFAULT_ACTION = "passthrough"
+FAIL_MODE = "closed"
+LOG_LEVEL = "info"
+
+# IMPORTANT: FACILITATOR_URL controls which network your gate accepts payments on.
+#   Mainnet (REAL money):       https://pay-skill.com/x402         (default if omitted)
+#   Testnet (WORTHLESS tokens): https://testnet.pay-skill.com/x402
+# Setting testnet in production means accepting worthless tokens for real API calls.
+FACILITATOR_URL = "https://pay-skill.com/x402"
+
+# Optional: discovery config — set these to appear in \`pay discover\`.
+# DISCOVERY_BASE_URL = "${target}"
+# DISCOVERY_NAME = "${name}"
+# DISCOVERY_DESCRIPTION = "Short description of your API"
+# DISCOVERY_KEYWORDS = "keyword1,keyword2"
+# DISCOVERY_CATEGORY = "data"
+
+[[kv_namespaces]]
+binding = "ROUTES"
+id = "REPLACE_WITH_KV_NAMESPACE_ID"
+`;
+}
+function packageJson(name) {
+    return JSON.stringify({
+        name,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: {
+            dev: "wrangler dev",
+            deploy: "wrangler deploy",
+            typecheck: "tsc --noEmit",
+        },
+        dependencies: {
+            hono: "^4.4.0",
+        },
+        devDependencies: {
+            "@cloudflare/workers-types": "^4.20240620.0",
+            typescript: "^5.5.0",
+            wrangler: "^3.60.0",
+        },
+    }, null, 2) + "\n";
+}
+function routesJson(path, price, settlement) {
+    const routes = [
+        { path: path || "/api/*", price, settlement },
+        { path: "/health", free: true },
+    ];
+    return JSON.stringify(routes, null, 2) + "\n";
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "create-pay-gate",
+  "version": "0.1.1",
+  "description": "Create a pay-gate x402 payment gateway for Cloudflare Workers",
+  "type": "module",
+  "bin": {
+    "create-pay-gate": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "x402",
+    "pay",
+    "payment",
+    "gateway",
+    "cloudflare",
+    "workers"
+  ],
+  "author": "pay-skill",
+  "license": "BSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pay-skill/gate.git",
+    "directory": "create-pay-gate"
+  },
+  "homepage": "https://pay-skill.com/docs/gate/",
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "@types/node": "^25.5.2"
+  }
+}

package/template/src/config.ts

@@ -0,0 +1,105 @@
+import type { Env, RouteConfig } from "./types";
+
+const ETH_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const URL_RE = /^https?:\/\/.+/;
+
+/** Load and validate route config from KV (or fallback to empty). */
+export async function loadRoutes(env: Env): Promise<RouteConfig[]> {
+  const raw = await env.ROUTES.get("routes", "json");
+  if (!raw || !Array.isArray(raw)) return [];
+  return validateRoutes(raw as RouteConfig[]);
+}
+
+/** Validate an array of route configs. Throws on invalid. */
+export function validateRoutes(routes: RouteConfig[]): RouteConfig[] {
+  for (const r of routes) {
+    if (!r.path || typeof r.path !== "string") {
+      throw new Error(`Route missing 'path'`);
+    }
+    if (r.free) continue;
+    if (r.price_endpoint && !URL_RE.test(r.price_endpoint)) {
+      throw new Error(`Route ${r.path}: invalid price_endpoint URL`);
+    }
+    if (!r.price && !r.price_endpoint) {
+      throw new Error(`Route ${r.path}: must have 'price' or 'price_endpoint'`);
+    }
+    if (r.price) validatePrice(r.price, r.path);
+    if (r.settlement && r.settlement !== "direct" && r.settlement !== "tab") {
+      throw new Error(`Route ${r.path}: settlement must be 'direct' or 'tab'`);
+    }
+    if (r.method) {
+      const m = r.method.toUpperCase();
+      if (!["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"].includes(m)) {
+        throw new Error(`Route ${r.path}: invalid method '${r.method}'`);
+      }
+    }
+  }
+  return routes;
+}
+
+/** Validate a price string: positive decimal, not "0.00". */
+function validatePrice(price: string, path: string): void {
+  const n = parseFloat(price);
+  if (isNaN(n) || n <= 0) {
+    throw new Error(`Route ${path}: price must be a positive number, got '${price}'`);
+  }
+}
+
+/** Validate top-level env config. Throws on invalid. */
+export function validateEnv(env: Env): void {
+  if (!ETH_ADDRESS_RE.test(env.PROVIDER_ADDRESS)) {
+    throw new Error(`Invalid PROVIDER_ADDRESS: '${env.PROVIDER_ADDRESS}'`);
+  }
+  if (!URL_RE.test(env.PROXY_TARGET)) {
+    throw new Error(`Invalid PROXY_TARGET: '${env.PROXY_TARGET}'`);
+  }
+  if (env.DEFAULT_ACTION !== "passthrough" && env.DEFAULT_ACTION !== "block") {
+    throw new Error(`DEFAULT_ACTION must be 'passthrough' or 'block', got '${env.DEFAULT_ACTION}'`);
+  }
+  if (env.FAIL_MODE !== "closed" && env.FAIL_MODE !== "open") {
+    throw new Error(`FAIL_MODE must be 'closed' or 'open', got '${env.FAIL_MODE}'`);
+  }
+}
+
+/** Get facilitator URL (mainnet default). */
+export function facilitatorUrl(env: Env): string {
+  return env.FACILITATOR_URL || "https://pay-skill.com/x402";
+}
+
+/** Parse global allowlist from comma-separated env var. */
+export function globalAllowlist(env: Env): string[] {
+  const raw = env.GLOBAL_ALLOWLIST;
+  if (!raw) return [];
+  return raw.split(",").map((a) => a.trim().toLowerCase()).filter(Boolean);
+}
+
+/** Convert dollar price string to micro-USDC string (6 decimals). */
+export function priceToMicroUsdc(price: string): string {
+  const dollars = parseFloat(price);
+  const micro = Math.round(dollars * 1_000_000);
+  return micro.toString();
+}
+
+/** Auto-select settlement mode based on price. */
+export function autoSettlement(price: string): "direct" | "tab" {
+  const dollars = parseFloat(price);
+  return dollars <= 1.0 ? "tab" : "direct";
+}
+
+/** Derive chain ID from facilitator URL. */
+export function chainId(env: Env): number {
+  const url = facilitatorUrl(env);
+  return url.includes("testnet") ? 84532 : 8453;
+}
+
+/** USDC contract address for a given chain. */
+export function usdcAddress(chain: number): string {
+  return chain === 8453
+    ? "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+    : "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+}
+
+/** CAIP-2 network identifier. */
+export function caip2Network(chain: number): string {
+  return `eip155:${chain}`;
+}

package/template/src/gate.ts

@@ -0,0 +1,89 @@
+import type { RouteConfig, RouteMatch } from "./types";
+import { autoSettlement, globalAllowlist } from "./config";
+import type { Env } from "./types";
+
+/**
+ * Match a request against route config. First match wins.
+ * Returns the match result (paid, free, allowlisted, passthrough, or blocked).
+ */
+export function matchRoute(
+  path: string,
+  method: string,
+  routes: RouteConfig[],
+  env: Env,
+  agentAddress?: string,
+): RouteMatch {
+  // Check global allowlist first
+  if (agentAddress) {
+    const global = globalAllowlist(env);
+    if (global.includes(agentAddress.toLowerCase())) {
+      return { kind: "allowlisted", agent: agentAddress };
+    }
+  }
+
+  for (const route of routes) {
+    if (!pathMatches(route.path, path)) continue;
+    if (route.method && route.method.toUpperCase() !== method.toUpperCase()) continue;
+
+    // Per-route allowlist check
+    if (agentAddress && route.allowlist) {
+      const lower = route.allowlist.map((a) => a.toLowerCase());
+      if (lower.includes(agentAddress.toLowerCase())) {
+        return { kind: "allowlisted", agent: agentAddress };
+      }
+    }
+
+    if (route.free) return { kind: "free", route };
+
+    const price = route.price || "0";
+    const settlement = route.settlement || autoSettlement(price);
+    return { kind: "paid", route, price, settlement };
+  }
+
+  // No route matched — use default action
+  return env.DEFAULT_ACTION === "passthrough"
+    ? { kind: "passthrough" }
+    : { kind: "blocked" };
+}
+
+/** Glob-style path matching. Supports * (one segment) and ** (any). */
+export function pathMatches(pattern: string, path: string): boolean {
+  // Exact match
+  if (pattern === path) return true;
+
+  // Convert glob to regex
+  const parts = pattern.split("/");
+  let regex = "^";
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!;
+    if (part === "**") {
+      regex += "/.*";
+    } else if (part === "*") {
+      regex += "/[^/]+";
+    } else if (part.endsWith("*")) {
+      // e.g. "premium*" → match any segment starting with "premium"
+      const prefix = escapeRegex(part.slice(0, -1));
+      regex += "/" + prefix + "[^/]*";
+    } else if (part === "") {
+      // leading slash
+      continue;
+    } else {
+      regex += "/" + escapeRegex(part);
+    }
+  }
+  regex += "$";
+
+  return new RegExp(regex).test(path);
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Extract agent address from request.
+ * Checks X-Pay-Agent header (for allowlist lookups on unpaid requests).
+ */
+export function extractAgentAddress(headers: Headers): string | undefined {
+  return headers.get("x-pay-agent") || undefined;
+}

package/template/src/heartbeat.ts

@@ -0,0 +1,88 @@
+import type { Env, HeartbeatPayload, HeartbeatRoute, RouteConfig } from "./types";
+import { facilitatorUrl, loadRoutes, autoSettlement } from "./config";
+
+/** Send a heartbeat to the facilitator's discover endpoint. */
+export async function sendHeartbeat(env: Env): Promise<void> {
+  if (!env.DISCOVERY_BASE_URL || !env.DISCOVERY_NAME) return;
+
+  const baseUrl = env.DISCOVERY_BASE_URL.trim();
+  if (!baseUrl.startsWith("https://")) {
+    console.warn("DISCOVERY_BASE_URL must use HTTPS, skipping heartbeat");
+    return;
+  }
+
+  const domain = extractDomain(baseUrl);
+  if (!domain) {
+    console.warn("Could not extract domain from DISCOVERY_BASE_URL, skipping heartbeat");
+    return;
+  }
+
+  let routes: RouteConfig[];
+  try {
+    routes = await loadRoutes(env);
+  } catch {
+    console.warn("Could not load routes for heartbeat");
+    return;
+  }
+
+  const heartbeatRoutes = buildRoutes(routes);
+  const settlementMode = heartbeatRoutes.some((r) => r.settlement === "tab") ? "tab" : "direct";
+
+  const payload: HeartbeatPayload = {
+    domain,
+    base_url: baseUrl,
+    provider_address: env.PROVIDER_ADDRESS,
+    name: env.DISCOVERY_NAME,
+    description: env.DISCOVERY_DESCRIPTION || "",
+    keywords: env.DISCOVERY_KEYWORDS ? env.DISCOVERY_KEYWORDS.split(",").map((k) => k.trim()).filter(Boolean) : [],
+    category: env.DISCOVERY_CATEGORY || "other",
+    website: env.DISCOVERY_WEBSITE || undefined,
+    docs_url: env.DISCOVERY_DOCS_URL || undefined,
+    routes: heartbeatRoutes,
+    pricing: {},
+    settlement_mode: settlementMode,
+    gate_version: "0.1.0",
+  };
+
+  const facUrl = facilitatorUrl(env);
+  const url = facUrl.replace("/x402", "/api/v1/discover") + "/heartbeat";
+
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const resp = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+      if (resp.ok) {
+        console.log(`Discovery heartbeat sent to ${url}`);
+        return;
+      }
+      console.warn(`Heartbeat rejected (attempt ${attempt + 1}): ${resp.status}`);
+    } catch (err) {
+      console.warn(`Heartbeat failed (attempt ${attempt + 1}):`, err);
+    }
+  }
+
+  console.error("Discovery heartbeat failed after 3 attempts");
+}
+
+function buildRoutes(routes: RouteConfig[]): HeartbeatRoute[] {
+  return routes
+    .filter((r) => !r.free)
+    .map((r) => ({
+      path: r.path,
+      method: r.method || "*",
+      price: r.price,
+      settlement: r.settlement || (r.price ? autoSettlement(r.price) : "auto"),
+      hint: r.hint,
+    }));
+}
+
+function extractDomain(url: string): string | null {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}

package/template/src/index.ts

@@ -0,0 +1,345 @@
+import { Hono } from "hono";
+import type { Env, RouteConfig } from "./types";
+import { loadRoutes, validateEnv, facilitatorUrl, priceToMicroUsdc, autoSettlement, chainId, usdcAddress } from "./config";
+import { matchRoute, extractAgentAddress } from "./gate";
+import { verifyPayment, checkFacilitatorHealth } from "./verify";
+import { make402Response, make403Response, make429Response, make503Response, buildRequirements, buildSettlementResponse } from "./response";
+import { sendHeartbeat } from "./heartbeat";
+
+const app = new Hono<{ Bindings: Env }>();
+
+// In-memory rate limit counters (per-isolate, reset on deploy)
+const rateCounts = new Map<string, { count: number; resetAt: number }>();
+
+// ── Health endpoint ─────────────────────────────────────────────
+app.get("/__pay/health", async (c) => {
+  const start = Date.now();
+  const url = facilitatorUrl(c.env);
+  const chain = chainId(c.env);
+  const network = chain === 8453 ? "mainnet" : "testnet";
+  const reachable = await checkFacilitatorHealth(url);
+  return c.json({
+    status: reachable ? "ok" : "degraded",
+    facilitator: reachable ? "reachable" : "unreachable",
+    network,
+    chain_id: chain,
+    version: "0.1.0",
+    uptime: Math.floor((Date.now() - start) / 1000),
+  });
+});
+
+// ── Sidecar check endpoint ──────────────────────────────────────
+app.post("/__pay/check", async (c) => {
+  const originalUri = c.req.header("x-original-uri") || "/";
+  const originalMethod = c.req.header("x-original-method") || "GET";
+  const paymentSig = c.req.header("payment-signature");
+
+  let routes: RouteConfig[];
+  try {
+    validateEnv(c.env);
+    routes = await loadRoutes(c.env);
+  } catch (err) {
+    return c.json({ error: "config_error", message: String(err) }, 500);
+  }
+
+  const agentAddr = extractAgentAddress(c.req.raw.headers);
+  const match = matchRoute(originalUri, originalMethod, routes, c.env, agentAddr);
+
+  if (match.kind === "free") {
+    return new Response(null, {
+      status: 200,
+      headers: { "X-Pay-Verified": "free" },
+    });
+  }
+
+  if (match.kind === "passthrough") {
+    return new Response(null, { status: 200 });
+  }
+
+  if (match.kind === "blocked") {
+    return make403Response();
+  }
+
+  if (match.kind === "allowlisted") {
+    return new Response(null, {
+      status: 200,
+      headers: {
+        "X-Pay-Verified": "allowlisted",
+        "X-Pay-From": match.agent,
+      },
+    });
+  }
+
+  // Paid route
+  return handlePaidRequest(c.env, match, paymentSig, c.req.header("accept"), originalUri);
+});
+
+// ── CORS preflight — always pass through ────────────────────────
+app.options("*", () => {
+  return new Response(null, { status: 204 });
+});
+
+// ── Gate middleware for all other routes ─────────────────────────
+app.all("*", async (c) => {
+  let routes: RouteConfig[];
+  try {
+    validateEnv(c.env);
+    routes = await loadRoutes(c.env);
+  } catch (err) {
+    return c.json({ error: "config_error", message: String(err) }, 500);
+  }
+
+  const path = new URL(c.req.url).pathname;
+  const method = c.req.method;
+  const agentAddr = extractAgentAddress(c.req.raw.headers);
+  const match = matchRoute(path, method, routes, c.env, agentAddr);
+
+  // Free route — proxy directly
+  if (match.kind === "free") {
+    return proxyToOrigin(c.env, c.req.raw, undefined, match.route);
+  }
+  if (match.kind === "passthrough") {
+    return proxyToOrigin(c.env, c.req.raw);
+  }
+
+  // Blocked
+  if (match.kind === "blocked") {
+    return make403Response();
+  }
+
+  // Allowlisted agent — proxy with headers
+  if (match.kind === "allowlisted") {
+    return proxyToOrigin(c.env, c.req.raw, {
+      "X-Pay-Verified": "allowlisted",
+      "X-Pay-From": match.agent,
+    });
+  }
+
+  // Paid route — check for dynamic pricing first
+  let price = match.price;
+  let settlement = match.settlement;
+
+  if (match.route.price_endpoint) {
+    const dynamic = await fetchDynamicPrice(match.route.price_endpoint, path, method, c.req.raw.headers);
+    if (dynamic) {
+      price = dynamic;
+      settlement = match.route.settlement || autoSettlement(dynamic);
+    } else if (!match.route.price) {
+      return make503Response();
+    }
+  }
+
+  // Rate limit check (per source IP)
+  const clientIp = c.req.header("cf-connecting-ip") || c.req.header("x-forwarded-for") || "unknown";
+  if (isRateLimited(clientIp, c.env)) {
+    return make429Response();
+  }
+
+  const paymentSig = c.req.header("payment-signature");
+  const chain = chainId(c.env);
+  const asset = usdcAddress(chain);
+  const facUrl = facilitatorUrl(c.env);
+  const amount = priceToMicroUsdc(price);
+  const reqs = buildRequirements(amount, settlement, c.env.PROVIDER_ADDRESS, facUrl, chain, asset);
+
+  if (!paymentSig) {
+    return make402Response(reqs, path, price, c.req.header("accept"));
+  }
+
+  // Verify payment with facilitator
+  const result = await verifyPayment(facUrl, paymentSig, reqs);
+
+  // Facilitator unreachable
+  if (!result) {
+    if (c.env.FAIL_MODE === "open") {
+      console.warn("Facilitator unreachable, fail_mode=open, passing through");
+      return proxyToOrigin(c.env, c.req.raw, undefined, match.route);
+    }
+    return make503Response();
+  }
+
+  // Verification failed
+  if (!result.isValid) {
+    return make402Response(reqs, path, price, c.req.header("accept"), result.invalidReason);
+  }
+
+  // Verification succeeded — proxy with payment headers
+  const extraHeaders: Record<string, string> = {
+    "X-Pay-Verified": "true",
+    "X-Pay-Amount": amount,
+    "X-Pay-Settlement": settlement,
+  };
+  if (result.payer) extraHeaders["X-Pay-From"] = result.payer;
+
+  const resp = await proxyToOrigin(c.env, c.req.raw, extraHeaders, match.route);
+
+  // Add v2 settlement response as PAYMENT-RESPONSE header
+  const receipt = buildSettlementResponse(result.payer, chain);
+  const newResp = new Response(resp.body, resp);
+  newResp.headers.set("PAYMENT-RESPONSE", receipt);
+  return newResp;
+});
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+async function handlePaidRequest(
+  env: Env,
+  match: Extract<import("./types").RouteMatch, { kind: "paid" }>,
+  paymentSig: string | null | undefined,
+  accept: string | null | undefined,
+  requestUrl: string,
+): Promise<Response> {
+  const chain = chainId(env);
+  const asset = usdcAddress(chain);
+  const facUrl = facilitatorUrl(env);
+  const amount = priceToMicroUsdc(match.price);
+  const reqs = buildRequirements(amount, match.settlement, env.PROVIDER_ADDRESS, facUrl, chain, asset);
+
+  if (!paymentSig) {
+    return make402Response(reqs, requestUrl, match.price, accept);
+  }
+
+  const result = await verifyPayment(facUrl, paymentSig, reqs);
+
+  if (!result) {
+    return env.FAIL_MODE === "open"
+      ? new Response(null, { status: 200, headers: { "X-Pay-Verified": "free" } })
+      : make503Response();
+  }
+
+  if (!result.isValid) {
+    return make402Response(reqs, requestUrl, match.price, accept, result.invalidReason);
+  }
+
+  const headers: Record<string, string> = {
+    "X-Pay-Verified": "true",
+    "X-Pay-Amount": amount,
+    "X-Pay-Settlement": match.settlement,
+  };
+  if (result.payer) headers["X-Pay-From"] = result.payer;
+
+  const receipt = buildSettlementResponse(result.payer, chain);
+  headers["PAYMENT-RESPONSE"] = receipt;
+
+  return new Response(null, { status: 200, headers });
+}
+
+async function proxyToOrigin(
+  env: Env,
+  req: Request,
+  extraHeaders?: Record<string, string>,
+  route?: import("./types").RouteConfig,
+): Promise<Response> {
+  const url = new URL(req.url);
+  const target = new URL(env.PROXY_TARGET);
+  url.protocol = target.protocol;
+  url.hostname = target.hostname;
+  url.port = target.port;
+
+  // Apply route-level path rewrite (e.g. /weather → /v1/forecast.json)
+  if (route?.proxy_rewrite) {
+    url.pathname = route.proxy_rewrite;
+  }
+
+  // Inject route-level default query params (e.g. key=xxx&days=3)
+  if (route?.proxy_params) {
+    for (const [k, v] of Object.entries(route.proxy_params)) {
+      if (!url.searchParams.has(k)) {
+        url.searchParams.set(k, v);
+      }
+    }
+  }
+
+  const headers = new Headers(req.headers);
+  headers.delete("host");
+  headers.set("host", target.hostname);
+
+  if (extraHeaders) {
+    for (const [k, v] of Object.entries(extraHeaders)) {
+      headers.set(k, v);
+    }
+  }
+
+  // Strip payment headers — don't forward to origin
+  headers.delete("payment-signature");
+
+  const proxyReq = new Request(url.toString(), {
+    method: req.method,
+    headers,
+    body: req.body,
+    redirect: "manual",
+  });
+
+  try {
+    return await fetch(proxyReq);
+  } catch (err) {
+    console.error("Origin proxy error:", err);
+    return new Response(
+      JSON.stringify({ error: "bad_gateway", message: "Origin server unreachable." }),
+      { status: 502, headers: { "Content-Type": "application/json" } },
+    );
+  }
+}
+
+async function fetchDynamicPrice(
+  endpoint: string,
+  path: string,
+  method: string,
+  headers: Headers,
+): Promise<string | null> {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3_000);
+    const resp = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        method,
+        path,
+        headers: Object.fromEntries(headers.entries()),
+      }),
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    if (!resp.ok) return null;
+    const body = (await resp.json()) as { price?: string };
+    return body.price || null;
+  } catch {
+    return null;
+  }
+}
+
+function isRateLimited(key: string, env: Env): boolean {
+  const limitStr = env.RATE_LIMIT_PER_AGENT || "1000";
+  const limit = parseInt(limitStr, 10) || 1000;
+  const now = Date.now();
+  const entry = rateCounts.get(key);
+
+  if (!entry || now >= entry.resetAt) {
+    rateCounts.set(key, { count: 1, resetAt: now + 60_000 });
+    return false;
+  }
+
+  entry.count++;
+  return entry.count > limit;
+}
+
+function logNetworkWarning(env: Env): void {
+  const chain = chainId(env);
+  if (chain !== 8453) {
+    console.warn("========================================================");
+    console.warn("  TESTNET MODE — payments use worthless test USDC.");
+    console.warn("  Set FACILITATOR_URL to https://pay-skill.com/x402");
+    console.warn("  for production (mainnet).");
+    console.warn("========================================================");
+  }
+}
+
+export default {
+  fetch: app.fetch,
+  async scheduled(_event: ScheduledEvent, env: Env, _ctx: ExecutionContext) {
+    logNetworkWarning(env);
+    await sendHeartbeat(env);
+  },
+};

package/template/src/response.ts

@@ -0,0 +1,160 @@
+import type { PaymentRequired, PaymentRequirementsV2, SettlementResponse, GateError } from "./types";
+import { caip2Network } from "./config";
+
+/**
+ * Build a base64-encoded v2 PAYMENT-REQUIRED header value.
+ */
+export function buildPaymentRequiredHeader(pr: PaymentRequired): string {
+  return btoa(JSON.stringify(pr));
+}
+
+/**
+ * Build a v2 PaymentRequired object.
+ */
+export function buildPaymentRequired(
+  reqs: PaymentRequirementsV2,
+  requestUrl: string,
+): PaymentRequired {
+  return {
+    x402Version: 2,
+    resource: {
+      url: requestUrl,
+      description: "Paid API endpoint",
+      mimeType: "application/json",
+    },
+    accepts: [reqs],
+    extensions: {},
+  };
+}
+
+/**
+ * Build a v2 PaymentRequirementsV2 object.
+ */
+export function buildRequirements(
+  amount: string,
+  settlement: "direct" | "tab",
+  providerAddress: string,
+  facilitatorUrl: string,
+  chain: number,
+  asset: string,
+): PaymentRequirementsV2 {
+  return {
+    scheme: "exact",
+    network: caip2Network(chain),
+    amount,
+    asset,
+    payTo: providerAddress,
+    maxTimeoutSeconds: 60,
+    extra: {
+      name: "USDC",
+      version: "2",
+      facilitator: facilitatorUrl,
+      settlement,
+    },
+  };
+}
+
+/**
+ * Build a base64-encoded v2 SettlementResponse for the PAYMENT-RESPONSE header.
+ */
+export function buildSettlementResponse(payer: string | undefined, chain: number): string {
+  const resp: SettlementResponse = {
+    success: true,
+    transaction: "",
+    network: caip2Network(chain),
+    payer,
+    extensions: {},
+  };
+  return btoa(JSON.stringify(resp));
+}
+
+/**
+ * Build a 402 JSON response body.
+ */
+export function build402JsonBody(price: string, reason?: string): GateError {
+  const body: GateError = {
+    error: "payment_required",
+    message: `This endpoint requires payment. $${price} per request.`,
+    docs: "https://pay-skill.com/gate",
+  };
+  if (reason) body.reason = reason;
+  return body;
+}
+
+/**
+ * Build a 402 HTML response body for browser clients.
+ */
+export function build402Html(price: string): string {
+  return [
+    "<html><head><title>Payment Required</title></head><body>",
+    "<h1>Payment Required</h1>",
+    `<p>This endpoint requires a payment of $${price} per request.</p>`,
+    "<p>Use an x402-compatible agent or SDK to access this API.</p>",
+    '<p><a href="https://pay-skill.com/gate">Learn more about pay-gate</a></p>',
+    "</body></html>",
+  ].join("\n");
+}
+
+/**
+ * Check if request accepts HTML (browser detection).
+ */
+export function wantsHtml(accept: string | null | undefined): boolean {
+  if (!accept) return false;
+  return accept.includes("text/html") && !accept.includes("application/json");
+}
+
+/**
+ * Build a full 402 Response with v2 PAYMENT-REQUIRED header.
+ */
+export function make402Response(
+  reqs: PaymentRequirementsV2,
+  requestUrl: string,
+  price: string,
+  accept: string | null | undefined,
+  reason?: string,
+): Response {
+  const pr = buildPaymentRequired(reqs, requestUrl);
+  const header = buildPaymentRequiredHeader(pr);
+
+  if (wantsHtml(accept)) {
+    return new Response(build402Html(price), {
+      status: 402,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        "PAYMENT-REQUIRED": header,
+      },
+    });
+  }
+
+  return new Response(JSON.stringify(build402JsonBody(price, reason)), {
+    status: 402,
+    headers: {
+      "Content-Type": "application/json",
+      "PAYMENT-REQUIRED": header,
+    },
+  });
+}
+
+/** Build a 403 Forbidden response (blocked by default_action). */
+export function make403Response(): Response {
+  return new Response(
+    JSON.stringify({ error: "forbidden", message: "This endpoint is not available." }),
+    { status: 403, headers: { "Content-Type": "application/json" } },
+  );
+}
+
+/** Build a 429 Too Many Requests response. */
+export function make429Response(): Response {
+  return new Response(
+    JSON.stringify({ error: "rate_limited", message: "Too many requests." }),
+    { status: 429, headers: { "Content-Type": "application/json" } },
+  );
+}
+
+/** Build a 503 Service Unavailable response (facilitator down, fail_mode closed). */
+export function make503Response(): Response {
+  return new Response(
+    JSON.stringify({ error: "service_unavailable", message: "Payment facilitator is unreachable." }),
+    { status: 503, headers: { "Content-Type": "application/json" } },
+  );
+}

package/template/src/types.ts

@@ -0,0 +1,127 @@
+/** Route configuration — loaded from KV or env. */
+export interface RouteConfig {
+  path: string;
+  method?: string;
+  price?: string;
+  settlement?: "direct" | "tab";
+  free?: boolean;
+  allowlist?: string[];
+  price_endpoint?: string;
+  /** Free-form usage hint for agents. e.g. "?q={city}" or '{"prompt": "string"}' */
+  hint?: string;
+  /** Rewrite the path before proxying to origin. e.g. "/v1/forecast.json" */
+  proxy_rewrite?: string;
+  /** Default query params injected into every proxied request. e.g. {"key": "abc", "days": "3"} */
+  proxy_params?: Record<string, string>;
+}
+
+/** Top-level env bindings for the CF Worker. */
+export interface Env {
+  ROUTES: KVNamespace;
+  PROVIDER_ADDRESS: string;
+  PROXY_TARGET: string;
+  DEFAULT_ACTION: string;
+  FAIL_MODE: string;
+  FACILITATOR_URL?: string;
+  LOG_LEVEL?: string;
+  RATE_LIMIT_PER_AGENT?: string;
+  RATE_LIMIT_VERIFICATION?: string;
+  GLOBAL_ALLOWLIST?: string;
+  /** Discovery config — set these to register in pay discover catalog. */
+  DISCOVERY_BASE_URL?: string;
+  DISCOVERY_NAME?: string;
+  DISCOVERY_DESCRIPTION?: string;
+  DISCOVERY_KEYWORDS?: string;
+  DISCOVERY_CATEGORY?: string;
+  DISCOVERY_DOCS_URL?: string;
+  DISCOVERY_WEBSITE?: string;
+}
+
+/** Heartbeat payload sent to facilitator for service discovery. */
+export interface HeartbeatPayload {
+  domain: string;
+  base_url: string;
+  provider_address: string;
+  name: string;
+  description: string;
+  keywords: string[];
+  category: string;
+  website?: string;
+  docs_url?: string;
+  routes: HeartbeatRoute[];
+  pricing: Record<string, unknown>;
+  settlement_mode: string;
+  gate_version: string;
+}
+
+export interface HeartbeatRoute {
+  path: string;
+  method: string;
+  price?: string;
+  settlement: string;
+  hint?: string;
+}
+
+/** x402 v2 top-level 402 response (base64-encoded in PAYMENT-REQUIRED header). */
+export interface PaymentRequired {
+  x402Version: 2;
+  resource: { url: string; description?: string; mimeType?: string };
+  accepts: PaymentRequirementsV2[];
+  extensions: Record<string, unknown>;
+}
+
+/** x402 v2 payment requirements (one entry in the `accepts` array). */
+export interface PaymentRequirementsV2 {
+  scheme: "exact";
+  network: string;
+  amount: string;
+  asset: string;
+  payTo: string;
+  maxTimeoutSeconds: number;
+  extra?: {
+    name?: string;
+    version?: string;
+    facilitator?: string;
+    settlement?: string;
+  };
+}
+
+/** x402 v2 facilitator /verify request body. */
+export interface VerifyRequestV2 {
+  x402Version: 2;
+  paymentPayload: unknown;
+  paymentRequirements: PaymentRequirementsV2;
+}
+
+/** x402 v2 facilitator /verify response body. */
+export interface VerifyResponseV2 {
+  isValid: boolean;
+  invalidReason?: string;
+  payer?: string;
+}
+
+/** x402 v2 settlement response (base64-encoded in PAYMENT-RESPONSE header). */
+export interface SettlementResponse {
+  success: boolean;
+  errorReason?: string;
+  transaction: string;
+  network: string;
+  payer?: string;
+  extensions: Record<string, unknown>;
+}
+
+/** Result of matching a request against route config. */
+export type RouteMatch =
+  | { kind: "paid"; route: RouteConfig; price: string; settlement: "direct" | "tab" }
+  | { kind: "free"; route: RouteConfig }
+  | { kind: "allowlisted"; agent: string }
+  | { kind: "passthrough" }
+  | { kind: "blocked" };
+
+/** Structured gate error for responses. */
+export interface GateError {
+  error: string;
+  message: string;
+  reason?: string;
+  docs?: string;
+}

package/template/src/verify.ts

@@ -0,0 +1,74 @@
+import type { PaymentRequirementsV2, VerifyRequestV2, VerifyResponseV2 } from "./types";
+
+const FACILITATOR_TIMEOUT_MS = 5_000;
+
+/**
+ * Call the Pay facilitator's /verify endpoint with v2 wire format.
+ * Decodes PAYMENT-SIGNATURE from base64 into a JSON payload.
+ * Returns the verify response, or null if the facilitator is unreachable.
+ */
+export async function verifyPayment(
+  facilitatorUrl: string,
+  paymentHeader: string,
+  requirements: PaymentRequirementsV2,
+): Promise<VerifyResponseV2 | null> {
+  let paymentPayload: unknown;
+  try {
+    paymentPayload = JSON.parse(atob(paymentHeader));
+  } catch {
+    return null;
+  }
+
+  const body: VerifyRequestV2 = {
+    x402Version: 2,
+    paymentPayload,
+    paymentRequirements: requirements,
+  };
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FACILITATOR_TIMEOUT_MS);
+
+  try {
+    const resp = await fetch(`${facilitatorUrl}/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    if (!resp.ok) {
+      console.error(`Facilitator returned ${resp.status}: ${await resp.text()}`);
+      return null;
+    }
+
+    return (await resp.json()) as VerifyResponseV2;
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") {
+      console.error("Facilitator timeout after 5s");
+    } else {
+      console.error("Facilitator error:", err);
+    }
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Check if the facilitator is reachable (for health endpoint).
+ */
+export async function checkFacilitatorHealth(facilitatorUrl: string): Promise<boolean> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3_000);
+
+  try {
+    const resp = await fetch(`${facilitatorUrl}/supported`, {
+      signal: controller.signal,
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/template/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx"
+  },
+  "include": ["src"]
+}