@profullstack/x402-gateway 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @profullstack/x402-gateway
+
+Sell crawl access to AI training crawlers, by the day, over [x402](https://x402.org), settled by [CoinPay](https://coinpayportal.com).
+
+People read your site free. So do search engines and the retrieval crawlers behind AI answers, because they send readers back. A crawler that copies pages into a training corpus sends nobody back, so it pays: every page answers `402 Payment Required` with an x402 offer, paying the offer returns a signed pass, and the pass opens the site for a day.
+
+One middleware. No database. Runs in Node, Bun and at the edge.
+
+```
+npm install @profullstack/x402-gateway
+```
+
+## What it does
+
+| Visitor | Gets |
+| --- | --- |
+| A person, Googlebot, Bingbot, Applebot, OAI-SearchBot, Claude-SearchBot, PerplexityBot… | the site, untouched |
+| GPTBot, ClaudeBot, CCBot, meta-externalagent, Bytespider, Applebot-Extended… | `402` with an x402 offer, or the HTML sales page if it asked for HTML |
+| Anyone at `/crawl` | the sales page (HTML) or the offer (JSON), and the place to pay |
+| A request with a valid pass | the site |
+
+The sales page explains the price, how to pay with an x402 client, and how to pay with the CoinPay CLI:
+
+```
+npm install -g @profullstack/coinpay
+coinpay x402 pay https://your-site.com/crawl --output pass.json
+curl -H "x-crawl-pass: $(node -p "require('./pass.json').pass")" https://your-site.com/
+```
+
+## Hono
+
+```js
+import { Hono } from 'hono';
+import { createGateway } from '@profullstack/x402-gateway';
+import { x402Gateway } from '@profullstack/x402-gateway/hono';
+
+const gateway = createGateway({
+  siteUrl: 'https://your-site.com',
+  coinpay: { apiKey: process.env.COINPAY_X402_KEY },
+  payTo: process.env.CRAWL_PAY_TO,
+});
+
+const app = new Hono();
+app.use('*', x402Gateway(gateway));
+app.get('/robots.txt', (c) => c.text(gateway.robotsTxt({ disallow: ['/login', '/api/'] })));
+```
+
+## Next.js
+
+`src/proxy.ts` on Next 16, `middleware.ts` before that. One per app; if you already have one, compose.
+
+```ts
+import { createGateway } from '@profullstack/x402-gateway';
+import { x402Proxy } from '@profullstack/x402-gateway/next';
+
+export const gateway = createGateway({
+  siteUrl: 'https://your-site.com',
+  coinpay: { apiKey: process.env.COINPAY_X402_KEY },
+  payTo: process.env.CRAWL_PAY_TO,
+});
+
+export const proxy = x402Proxy(gateway);
+export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };
+```
+
+```ts
+// app/robots.txt/route.ts
+import { robotsRoute } from '@profullstack/x402-gateway/next';
+import { gateway } from '../../proxy';
+export const GET = robotsRoute(gateway, { disallow: ['/login', '/api/'] });
+```
+
+## Anything else
+
+`gateway.handle(request)` takes a Fetch `Request` and resolves to a `Response` to send, or `null` to carry on. Wrap it in ten lines for whatever you run.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `siteUrl` | required | canonical origin, no trailing slash |
+| `coinpay.apiKey` | | a **scoped** CoinPay key (`cp_live_…`, from the business's API Keys tab) with `payments:create`. The legacy business key is refused by CoinPay's x402 routes. |
+| `payTo` | | EVM address that receives the USDC, on Base, Polygon and Ethereum alike |
+| `priceCents` | `100` | |
+| `passMinutes` | `1440` | a day |
+| `header` | `x-crawl-pass` | where the pass goes; `Authorization: Bearer` works too |
+| `path` | `/crawl` | the sales page |
+| `openPaths` | `[]` | extra paths a refused crawler may read (`robots.txt`, the sales page, `security.txt` and `.well-known/` always are) |
+| `isPaidAgent` | training list | `(userAgent) => boolean` |
+| `training`, `retrieval` | the lists in `./agents` | |
+| `secret` | the CoinPay key | pass signing secret |
+| `page` | built in | `(ctx) => html` |
+| `contact` | | mailto: or URL for bulk deals |
+| `onSale` | | `({ payer, ref, token, expiresAt, userAgent, priceCents, currency }) => …`, for accounting |
+
+Without `coinpay.apiKey` and `payTo` the gateway still answers training crawlers with 402 and the page says payments are off. Nothing is sold, but nothing is given away either.
+
+## How the money moves
+
+The offer is x402 v2 in CoinPay's dialect: USDC under the `exact` scheme on Base, Polygon or Ethereum, EIP-3009 `transferWithAuthorization`. The buyer signs, the gateway sends the proof to CoinPay's `/api/x402/verify` and `/api/x402/settle`, and CoinPay's relayer broadcasts the transfer, paying the gas. The USDC goes straight to `payTo`.
+
+A pass is `cp_<payload>.<hmac>`: its own expiry and the payment's nonce, signed with HMAC-SHA256. Verifying one is a hash, not a query. A proof is single-use; retrying with the same proof returns a pass bounded by the proof's own validity window, so a lost response is not a lost dollar and a replayed header is not a free day.
+
+## Who is on which list
+
+`TRAINING_AGENTS` is the documented corpus-crawl token of each operator; `RETRIEVAL_AGENTS` the search half of the same pairs: GPTBot / OAI-SearchBot, ClaudeBot / Claude-SearchBot, meta-externalagent / Meta-ExternalFetcher, Applebot-Extended / Applebot. Google-Extended stays welcome because Google documents it as also gating Gemini app grounding. Matching is a substring of the user agent, which identifies a self-declared crawler and nothing more: a crawler wearing a browser's user agent walks past this, and that one needs blocking at the edge.
+
+## Licence
+
+MIT

package/index.d.ts

@@ -0,0 +1,133 @@
+/** A Fetch-API request handler that answers, or returns null to let the request through. */
+export type Handle = (request: Request) => Promise<Response | null>;
+
+export interface Sale {
+  payer: string | null;
+  ref: string | null;
+  token: string;
+  expiresAt: string;
+  userAgent: string;
+  priceCents: number;
+  currency: string;
+}
+
+export interface PageContext {
+  siteName: string;
+  siteUrl: string;
+  buyUrl: string;
+  price: string;
+  minutes: number;
+  header: string;
+  enabled: boolean;
+  offer: Offer;
+  training: string[];
+  retrieval: string[];
+  contact: string;
+}
+
+export interface GatewayOptions {
+  /** Canonical origin, no trailing slash. */
+  siteUrl: string;
+  /** Shown on the sales page; defaults to the hostname. */
+  siteName?: string;
+  /** A SCOPED CoinPay key (cp_live_… from the business's API Keys tab) with payments:create. */
+  coinpay?: { apiKey?: string; baseUrl?: string };
+  /** EVM address that receives the USDC. */
+  payTo?: string;
+  /** Default 100 ($1). */
+  priceCents?: number;
+  currency?: string;
+  /** What a payment buys. Default 1440 (a day). */
+  passMinutes?: number;
+  /** Request header the pass is presented in. Default 'x-crawl-pass'. */
+  header?: string;
+  /** The sales page. Default '/crawl'. */
+  path?: string;
+  /** Extra paths a refused crawler may still read. */
+  openPaths?: string[];
+  training?: string[];
+  retrieval?: string[];
+  /** Who is charged. Default: the training list, substring-matched on the user agent. */
+  isPaidAgent?: (userAgent: string) => boolean;
+  /** Pass signing secret. Defaults to the CoinPay key. */
+  secret?: string;
+  page?: (ctx: PageContext) => string;
+  contact?: string;
+  onSale?: (sale: Sale) => void | Promise<void>;
+  fetch?: typeof fetch;
+}
+
+export interface AcceptEntry {
+  scheme: 'exact';
+  network: string;
+  amount: string;
+  asset: string;
+  payTo: string;
+  resource: string;
+  description: string;
+  mimeType: string;
+  maxTimeoutSeconds: number;
+  extra: { name: string; version: string };
+}
+
+export interface Offer {
+  x402Version: 2;
+  accepts: AcceptEntry[];
+}
+
+export interface RobotsOptions {
+  siteUrl?: string;
+  disallow?: string[];
+  allow?: string[];
+  sitemap?: string;
+  path?: string;
+  refused?: string[];
+  training?: string[];
+  retrieval?: string[];
+  comments?: string[];
+}
+
+export interface Gateway {
+  handle: Handle;
+  sell: (request: Request) => Promise<Response>;
+  enabled: boolean;
+  options: Required<Omit<GatewayOptions, 'onSale' | 'fetch' | 'page' | 'isPaidAgent'>> & {
+    onSale: GatewayOptions['onSale'] | null;
+    fetch: typeof fetch;
+    page: (ctx: PageContext) => string;
+    isPaidAgent: (userAgent: string) => boolean;
+  };
+  robotsTxt: (extra?: RobotsOptions) => string;
+  page: () => string;
+}
+
+export function createGateway(options: GatewayOptions): Gateway;
+export function wantsHtml(accept?: string | null): boolean;
+
+export const TRAINING_AGENTS: string[];
+export const RETRIEVAL_AGENTS: string[];
+export function isTrainingAgent(userAgent?: string | null, agents?: string[]): boolean;
+
+export function robotsTxt(options: RobotsOptions & { siteUrl: string }): string;
+export function renderPage(ctx: PageContext): string;
+
+export function mintPass(args: { secret: string; ref: string | null; expiresAt: number; now?: number }): Promise<{ token: string; expiresAt: number; ref: string | null }>;
+export function readPass(token: string, args: { secret: string; now?: number }): Promise<{ exp: number; iat: number | null; ref: string | null } | null>;
+
+export const METHODS: Array<{ key: string; network: string; asset: string; label: string }>;
+export const X402_METHODS: typeof METHODS;
+export function buildOffer(args: { payTo: string; priceCents: number; resource: string; description?: string; maxTimeoutSeconds?: number; methods?: typeof METHODS }): Offer;
+export function decodePayment(header: string | null | undefined): Record<string, unknown> | null;
+export function expectedFor(payment: unknown, offer: Offer): { amount: string; resource: string; payTo: string; asset: string } | null;
+export function verifyAndSettle(
+  payment: unknown,
+  expected: { amount: string; resource: string; payTo: string; asset: string },
+  coinpay: { apiKey: string; baseUrl: string; fetch?: typeof fetch },
+): Promise<{ ok: true; payer: string | null; ref: string | null } | { ok: false; reason: string; replay: boolean }>;
+
+/** ./hono */
+export function x402Gateway(gatewayOrOptions: Gateway | GatewayOptions): (c: { req: { raw: Request } }, next: () => Promise<void>) => Promise<Response | undefined>;
+
+/** ./next */
+export function x402Proxy(gatewayOrOptions: Gateway | GatewayOptions): (request: Request) => Promise<Response | undefined>;
+export function robotsRoute(gateway: Gateway, extra?: RobotsOptions): () => Response;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@profullstack/x402-gateway",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Sell crawl access to AI training crawlers by the day over x402, settled by CoinPay. One middleware: 402 with an offer, a sales page with CLI instructions, signed passes, and a robots.txt that keeps search crawlers welcome.",
+  "keywords": [
+    "x402",
+    "402",
+    "payment-required",
+    "crawler",
+    "ai-crawler",
+    "gptbot",
+    "claudebot",
+    "meta-externalagent",
+    "robots.txt",
+    "coinpay",
+    "usdc",
+    "hono",
+    "nextjs",
+    "middleware",
+    "paywall"
+  ],
+  "repository": { "type": "git", "url": "git+https://github.com/profullstack/x402-gateway.git" },
+  "homepage": "https://github.com/profullstack/x402-gateway#readme",
+  "bugs": { "url": "https://github.com/profullstack/x402-gateway/issues" },
+  "license": "MIT",
+  "author": "Profullstack, LLC",
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./src/index.js" },
+    "./hono": { "types": "./index.d.ts", "import": "./src/hono.js" },
+    "./next": { "types": "./index.d.ts", "import": "./src/next.js" },
+    "./robots": { "types": "./index.d.ts", "import": "./src/robots.js" },
+    "./agents": { "types": "./index.d.ts", "import": "./src/agents.js" }
+  },
+  "types": "./index.d.ts",
+  "files": ["src", "index.d.ts", "README.md", "LICENSE"],
+  "engines": { "node": ">=20.11" },
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/agents.js

@@ -0,0 +1,59 @@
+/**
+ * Which crawlers pay, and which read free.
+ *
+ * Two kinds of AI crawler visit a site and only one of them ever sends a reader
+ * back. RETRIEVAL crawlers feed the live index that ChatGPT search, Perplexity,
+ * Bing and Siri cite from; they are welcome everywhere a reader may go.
+ * TRAINING crawlers copy pages into a corpus that is baked into weights months
+ * later with no link back. Those are the ones robots.txt refuses and the
+ * gateway charges.
+ *
+ * Each entry is the token its operator documents, and the pairs are the point:
+ * GPTBot vs OAI-SearchBot, ClaudeBot vs Claude-SearchBot, meta-externalagent vs
+ * Meta-ExternalFetcher, Applebot-Extended vs Applebot. Refusing the wrong half
+ * of a pair cuts off citations while the corpus crawl carries on.
+ */
+
+/** Training-only crawlers: refused in robots.txt, charged by the gateway. */
+export const TRAINING_AGENTS = [
+  'GPTBot',
+  'ClaudeBot',
+  'anthropic-ai',
+  'CCBot',
+  'meta-externalagent',
+  'FacebookBot',
+  'Bytespider',
+  'Applebot-Extended',
+];
+
+/**
+ * Retrieval crawlers, named in robots.txt so their operators can see they are
+ * welcome. Google-Extended is Google's training token but Google documents it
+ * as also gating grounding in the Gemini app, so it stays on this side.
+ */
+export const RETRIEVAL_AGENTS = [
+  'OAI-SearchBot',
+  'ChatGPT-User',
+  'Claude-SearchBot',
+  'Claude-User',
+  'PerplexityBot',
+  'Perplexity-User',
+  'Google-Extended',
+  'Bingbot',
+];
+
+const lower = (list) => list.map((t) => t.toLowerCase());
+
+/**
+ * Whether a user agent is one of `agents` (default: the training list).
+ *
+ * Substring match on the documented token, which a determined caller can lie
+ * about. That is fine and worth being clear about: this identifies a
+ * self-declared corpus crawler so it can be charged. It does not stop anything
+ * hostile, and a crawler wearing a browser's user agent walks straight past it.
+ */
+export function isTrainingAgent(userAgent = '', agents = TRAINING_AGENTS) {
+  const ua = String(userAgent ?? '').toLowerCase();
+  if (!ua) return false;
+  return lower(agents).some((t) => ua.includes(t));
+}

package/src/hono.js

@@ -0,0 +1,24 @@
+import { createGateway } from './index.js';
+
+/**
+ * The gateway as Hono middleware.
+ *
+ *   import { x402Gateway } from '@profullstack/x402-gateway/hono';
+ *   app.use('*', x402Gateway({ siteUrl, coinpay: { apiKey }, payTo }));
+ *
+ * Register it before the routes and after any outright user-agent block: a
+ * crawler that is refused everywhere should not be sold anything. Takes either
+ * options or a gateway already created with `createGateway`, so an app can
+ * keep the gateway around for `robotsTxt()` and `page()`.
+ */
+export function x402Gateway(gatewayOrOptions) {
+  const gateway =
+    gatewayOrOptions && typeof gatewayOrOptions.handle === 'function'
+      ? gatewayOrOptions
+      : createGateway(gatewayOrOptions);
+  return async (c, next) => {
+    const answer = await gateway.handle(c.req.raw);
+    if (answer) return answer;
+    await next();
+  };
+}

package/src/index.js

@@ -0,0 +1,262 @@
+import { isTrainingAgent, RETRIEVAL_AGENTS, TRAINING_AGENTS } from './agents.js';
+import { renderPage } from './page.js';
+import { mintPass, readPass } from './pass.js';
+import { robotsTxt } from './robots.js';
+import {
+  buildOffer,
+  decodePayment,
+  expectedFor,
+  METHODS,
+  nonceOf,
+  settleAgain,
+  validBeforeOf,
+  verifyAndSettle,
+} from './x402.js';
+
+export { isTrainingAgent, RETRIEVAL_AGENTS, TRAINING_AGENTS } from './agents.js';
+export { renderPage } from './page.js';
+export { mintPass, readPass } from './pass.js';
+export { robotsTxt } from './robots.js';
+export { buildOffer, decodePayment, expectedFor, METHODS, verifyAndSettle } from './x402.js';
+
+/**
+ * A gateway that sells crawl access to training crawlers, by the day, over x402.
+ *
+ * People and search crawlers pass through untouched. A crawler on the training
+ * list is answered with 402 Payment Required carrying an x402 offer -- as JSON,
+ * or as an HTML sales page if it asked for HTML -- on every path but the few it
+ * needs to read to comply. Paying the offer, at the sales page or on any 402'd
+ * URL, returns a signed pass good for `passMinutes`, presented in `header` on
+ * every request after that.
+ *
+ * Framework-agnostic: `handle(request)` takes a Fetch `Request` and resolves to
+ * a `Response` to send, or null to let the request through. The adapters in
+ * ./hono and ./next are one line each on top of it.
+ *
+ * @param {object} options
+ * @param {string} options.siteUrl                 canonical origin, no trailing slash
+ * @param {string} [options.siteName]              for the page; defaults to the hostname
+ * @param {{apiKey: string, baseUrl?: string}} [options.coinpay]  a SCOPED CoinPay key (cp_live_…) with payments:create
+ * @param {string} [options.payTo]                 EVM address that receives the USDC
+ * @param {number} [options.priceCents=100]
+ * @param {string} [options.currency='USD']
+ * @param {number} [options.passMinutes=1440]          a day
+ * @param {string} [options.header='x-crawl-pass']
+ * @param {string} [options.path='/crawl']         the sales page
+ * @param {string[]} [options.openPaths]           extra paths a refused crawler may read
+ * @param {(ua: string) => boolean} [options.isPaidAgent]
+ * @param {string} [options.secret]                pass signing secret; defaults to the CoinPay key
+ * @param {(ctx: object) => string} [options.page] custom sales page renderer
+ * @param {string} [options.contact]               mailto: or URL for bulk deals
+ * @param {(sale: object) => void|Promise<void>} [options.onSale]   accounting hook, never awaited for the answer
+ * @param {typeof fetch} [options.fetch]           for tests
+ */
+export function createGateway(options = {}) {
+  const o = normalise(options);
+  const enabled = Boolean(o.coinpay.apiKey && o.payTo);
+  const secret = o.secret || o.coinpay.apiKey || null;
+
+  const openPaths = ['/robots.txt', o.path, '/security.txt', '/.well-known/', ...o.openPaths];
+  const isOpen = (path) => openPaths.some((p) => (p.endsWith('/') ? path.startsWith(p) : path === p));
+
+  const price = `${(o.priceCents / 100).toFixed(2)} ${o.currency}`;
+  const buyUrl = `${o.siteUrl}${o.path}`;
+
+  const offer = () =>
+    enabled
+      ? buildOffer({
+          payTo: o.payTo,
+          priceCents: o.priceCents,
+          resource: buyUrl,
+          description: `${o.passMinutes} minutes of crawl access to ${o.siteUrl}`,
+        })
+      : { x402Version: 2, accepts: [] };
+
+  const receipt = (extra = {}) => ({
+    ...offer(),
+    pass: { price, minutes: o.passMinutes, header: o.header, buy: buyUrl },
+    ...extra,
+  });
+
+  const noStore = {
+    'cache-control': 'no-store',
+    vary: 'Accept, User-Agent, X-Payment',
+  };
+  const json = (body, status, headers = {}) =>
+    new Response(JSON.stringify(body, null, 2), {
+      status,
+      headers: { 'content-type': 'application/json; charset=utf-8', ...noStore, ...headers },
+    });
+  const html = (body, status) =>
+    new Response(body, { status, headers: { 'content-type': 'text/html; charset=utf-8', ...noStore } });
+
+  const pageCtx = () => ({
+    siteName: o.siteName,
+    siteUrl: o.siteUrl,
+    buyUrl,
+    price,
+    minutes: o.passMinutes,
+    header: o.header,
+    enabled,
+    offer: offer(),
+    training: o.training,
+    retrieval: o.retrieval,
+    contact: o.contact,
+  });
+
+  /** The pass a request presents, from the named header or a bearer token. */
+  const passFrom = (request) => {
+    const direct = request.headers.get(o.header);
+    if (direct) return direct.trim();
+    const m = /^Bearer\s+(cp_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/i.exec(request.headers.get('authorization') ?? '');
+    return m ? m[1] : null;
+  };
+
+  /**
+   * Answer one request with the sale.
+   *
+   * The pass comes back as the BODY of a 200, not as the page that was asked
+   * for: the buyer is a program reading stdout, `coinpay x402 pay` prints the
+   * body and not the headers, and a crawler that wanted the page can fetch it
+   * again a moment later with the pass.
+   */
+  async function sell(request) {
+    const ua = request.headers.get('user-agent') ?? '';
+    const proofHeader = request.headers.get('x-payment');
+
+    if (proofHeader) {
+      if (!enabled) return json(receipt({ error: 'Payments are not switched on here.' }), 402);
+      const payment = decodePayment(proofHeader);
+      if (!payment) return json(receipt({ error: 'X-PAYMENT is not base64 JSON.' }), 402);
+      const current = offer();
+      const expected = expectedFor(payment, current);
+      if (!expected) return json(receipt({ error: 'Proof does not match an offered network.' }), 402);
+
+      const now = Math.floor(Date.now() / 1000);
+      const coinpay = { apiKey: o.coinpay.apiKey, baseUrl: o.coinpay.baseUrl, fetch: o.fetch };
+      const result = await verifyAndSettle(payment, expected, coinpay);
+
+      let expiresAt = null;
+      let replayed = false;
+      if (result.ok) {
+        expiresAt = now + o.passMinutes * 60;
+      } else if (result.replay) {
+        /*
+         * Paid once, lost the answer, asked again with the same proof. Answered
+         * with a pass -- but only if the money really moved, and only within
+         * the proof's own validity window plus one term, so the same header
+         * cannot be replayed for day after day. validBefore is set by the
+         * payer at signing time, typically ten minutes out; nothing else about
+         * "when was this bought" survives without a table.
+         */
+        const paid = await settleAgain(payment, coinpay);
+        const validBefore = validBeforeOf(payment);
+        if (paid && validBefore) {
+          expiresAt = Math.min(now + o.passMinutes * 60, validBefore + o.passMinutes * 60);
+          replayed = true;
+        }
+      }
+      if (!expiresAt || expiresAt <= now) {
+        return json(receipt({ error: result.reason ?? 'Payment could not be settled.' }), 402);
+      }
+
+      const ref = nonceOf(payment) ?? result.ref ?? null;
+      const pass = await mintPass({ secret, ref, expiresAt, now });
+      const expires = new Date(pass.expiresAt * 1000).toISOString();
+      if (o.onSale && !replayed) {
+        try {
+          await o.onSale({
+            payer: result.payer ?? null,
+            ref,
+            token: pass.token,
+            expiresAt: expires,
+            userAgent: ua,
+            priceCents: o.priceCents,
+            currency: o.currency,
+          });
+        } catch {
+          // Accounting must never cost a buyer the pass it paid for.
+        }
+      }
+      return json(
+        {
+          ok: true,
+          pass: pass.token,
+          expires_at: expires,
+          header: o.header,
+          replayed,
+          use: `curl -H "${o.header}: ${pass.token}" ${o.siteUrl}/`,
+        },
+        200,
+        { [o.header]: pass.token, [`${o.header}-expires`]: expires },
+      );
+    }
+
+    if (wantsHtml(request.headers.get('accept'))) return html(o.page(pageCtx()), 402);
+    return json(receipt({ error: `Payment required for training crawlers. Read ${buyUrl} for how.` }), 402);
+  }
+
+  /**
+   * The gate. Null means "not for me, carry on".
+   *
+   * The sales page is answered for EVERYONE, so an operator can read it and a
+   * client can pay at it whatever user agent it wears. Every other decision
+   * starts from the user agent.
+   */
+  async function handle(request) {
+    const path = new URL(request.url).pathname;
+    if (path === o.path) return sell(request);
+    if (!o.isPaidAgent(request.headers.get('user-agent') ?? '')) return null;
+    if (isOpen(path)) return null;
+
+    const token = passFrom(request);
+    if (token && (await readPass(token, { secret }))) return null;
+    return sell(request);
+  }
+
+  return {
+    handle,
+    sell,
+    enabled,
+    options: o,
+    /** robots.txt with this gateway's lists and sales path. */
+    robotsTxt: (extra = {}) =>
+      robotsTxt({ siteUrl: o.siteUrl, path: o.path, training: o.training, retrieval: o.retrieval, ...extra }),
+    /** The sales page as HTML, for a site that mounts it on a route of its own. */
+    page: () => o.page(pageCtx()),
+  };
+}
+
+/** Whether the caller would rather read a page than a JSON offer. */
+export const wantsHtml = (accept = '') => String(accept ?? '').toLowerCase().includes('text/html');
+
+function normalise(options) {
+  const siteUrl = String(options.siteUrl ?? '').replace(/\/+$/, '');
+  if (!siteUrl) throw new Error('createGateway needs siteUrl');
+  const training = options.training ?? TRAINING_AGENTS;
+  return {
+    siteUrl,
+    siteName: options.siteName || new URL(siteUrl).hostname,
+    coinpay: {
+      apiKey: options.coinpay?.apiKey ?? '',
+      baseUrl: (options.coinpay?.baseUrl ?? 'https://coinpayportal.com').replace(/\/+$/, ''),
+    },
+    payTo: options.payTo ?? '',
+    priceCents: Number.isFinite(options.priceCents) ? options.priceCents : 100,
+    currency: options.currency ?? 'USD',
+    passMinutes: Number.isFinite(options.passMinutes) && options.passMinutes > 0 ? options.passMinutes : 1440,
+    header: String(options.header ?? 'x-crawl-pass').toLowerCase(),
+    path: options.path ?? '/crawl',
+    openPaths: options.openPaths ?? [],
+    training,
+    retrieval: options.retrieval ?? RETRIEVAL_AGENTS,
+    isPaidAgent: options.isPaidAgent ?? ((ua) => isTrainingAgent(ua, training)),
+    secret: options.secret ?? '',
+    page: options.page ?? renderPage,
+    contact: options.contact ?? '',
+    onSale: options.onSale ?? null,
+    fetch: options.fetch ?? globalThis.fetch,
+  };
+}
+
+export { METHODS as X402_METHODS };

package/src/next.js

@@ -0,0 +1,36 @@
+import { createGateway } from './index.js';
+
+/**
+ * The gateway for Next.js, in `proxy.ts` (Next 16) or `middleware.ts` (earlier).
+ *
+ *   import { x402Proxy } from '@profullstack/x402-gateway/next';
+ *   export const proxy = x402Proxy({ siteUrl, coinpay: { apiKey }, payTo });
+ *   export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };
+ *
+ * Returning `undefined` from a Next proxy means "carry on", which is what the
+ * gateway's null becomes. When the app already has a proxy for something
+ * else, compose: `const answer = await gate(request); if (answer) return answer;`
+ * and then do whatever it did before. Runs at the edge: nothing here imports
+ * node:, and the pass is verified with Web Crypto rather than a database.
+ */
+export function x402Proxy(gatewayOrOptions) {
+  const gateway =
+    gatewayOrOptions && typeof gatewayOrOptions.handle === 'function'
+      ? gatewayOrOptions
+      : createGateway(gatewayOrOptions);
+  return async (request) => (await gateway.handle(request)) ?? undefined;
+}
+
+/**
+ * A Route Handler for `app/robots.txt/route.js`, so robots.txt and the gateway
+ * are generated from one set of lists.
+ *
+ *   import { robotsRoute } from '@profullstack/x402-gateway/next';
+ *   export const GET = robotsRoute(gateway, { disallow: ['/login', '/api/'] });
+ */
+export function robotsRoute(gateway, extra = {}) {
+  return () =>
+    new Response(gateway.robotsTxt(extra), {
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    });
+}

package/src/page.js

@@ -0,0 +1,133 @@
+/**
+ * The sales page: what a refused crawler is shown, and what its operator reads.
+ *
+ * Plain HTML with no script, because the reader is a program that renders
+ * nothing, or a person who was sent the link by one. Every number on it comes
+ * from the gateway's options; nothing is typed in twice.
+ */
+
+const esc = (s) =>
+  String(s ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+
+const CSS = `
+:root{color-scheme:light dark;--fg:#1a1a1a;--bg:#fff;--mut:#666;--line:#e5e5e5;--code:#f4f4f4;--acc:#0a5}
+@media(prefers-color-scheme:dark){:root{--fg:#eee;--bg:#111;--mut:#aaa;--line:#333;--code:#1c1c1c;--acc:#3c9}}
+body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.55 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}
+main{max-width:44rem;margin:0 auto;padding:2.5rem 1.25rem 4rem}
+h1{font-size:1.8rem;line-height:1.2;margin:0 0 .5rem}h2{font-size:1.15rem;margin:2rem 0 .5rem}
+p{margin:.5rem 0}.mut{color:var(--mut)}
+pre{background:var(--code);border:1px solid var(--line);border-radius:6px;padding:.9rem 1rem;overflow-x:auto;font-size:.88rem;line-height:1.45}
+code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.92em}
+ol,ul{padding-left:1.3rem}li{margin:.3rem 0}
+.price{font-size:2.2rem;font-weight:700;color:var(--acc);margin:.25rem 0}
+table{border-collapse:collapse;margin:.5rem 0;font-size:.95rem}td,th{border-bottom:1px solid var(--line);padding:.35rem .6rem;text-align:left}
+footer{margin-top:3rem;color:var(--mut);font-size:.85rem}
+`;
+
+/**
+ * @param {object} ctx
+ * @param {string} ctx.siteName
+ * @param {string} ctx.siteUrl
+ * @param {string} ctx.buyUrl           the URL to pay at (the sales page itself)
+ * @param {string} ctx.price            e.g. "1.00 USD"
+ * @param {number} ctx.minutes
+ * @param {string} ctx.header           request header the pass goes in
+ * @param {boolean} ctx.enabled         whether a payment can be taken right now
+ * @param {object} ctx.offer            the x402 body, for the curious
+ * @param {string[]} ctx.training       agents charged
+ * @param {string[]} ctx.retrieval      agents welcome free
+ * @param {string} [ctx.contact]        mailto or URL for bulk deals
+ */
+export function renderPage(ctx) {
+  const {
+    siteName,
+    siteUrl,
+    buyUrl,
+    price,
+    minutes,
+    header,
+    enabled,
+    offer,
+    training = [],
+    retrieval = [],
+    contact,
+  } = ctx;
+  const window =
+    minutes === 1440
+      ? 'one day'
+      : minutes % 1440 === 0
+        ? `${minutes / 1440} days`
+        : minutes === 60
+          ? 'one hour'
+          : minutes % 60 === 0
+            ? `${minutes / 60} hours`
+            : `${minutes} minutes`;
+  const networks = (offer?.accepts ?? []).map((a) => a.network).join(', ');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="robots" content="noindex">
+<title>Crawl access · ${esc(siteName)}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<main>
+<h1>Training crawlers pay for access here.</h1>
+<p class="mut">People read <a href="${esc(siteUrl)}">${esc(siteName)}</a> free. So do search engines and the retrieval crawlers behind AI answers, because they send readers back. A crawler that copies pages into a training corpus sends nobody back, so it pays for the time it spends.</p>
+
+<div class="price">${esc(price)} <span class="mut" style="font-size:1rem;font-weight:400">for ${esc(window)} of requests</span></div>
+${
+  enabled
+    ? ''
+    : '<p><strong>Payments are not switched on here yet.</strong> The offer below is empty until the operator configures a payout address, so for now this crawler is simply refused.</p>'
+}
+
+<h2>How it works</h2>
+<ol>
+  <li>Any page you fetch answers <code>402 Payment Required</code>. This page, fetched with <code>Accept: application/json</code>, returns the x402 offer: USDC, <code>exact</code> scheme, on ${esc(networks || 'Base, Polygon or Ethereum')}.</li>
+  <li>Sign the payment and retry with the proof in an <code>X-PAYMENT</code> header. The response is a JSON receipt carrying a pass.</li>
+  <li>Send the pass in <code>${esc(header)}</code> on every request for the next ${esc(window)}. When it expires, buy another. The sale is the pass, not the page: fetch the page again with the pass.</li>
+</ol>
+
+<h2>Pay with the CoinPay CLI</h2>
+<p>Settlement is by CoinPay: the buyer's USDC goes straight to the site's wallet and CoinPay's relayer pays the gas, so you need USDC and nothing else.</p>
+<pre><code>npm install -g @profullstack/coinpay
+coinpay x402 pay ${esc(buyUrl)} --output pass.json</code></pre>
+<p>The command fetches this page, reads the offer, opens a browser tab to approve the payment with the CoinPay Wallet extension or any EIP-6963 wallet (MetaMask, Rabby, Coinbase Wallet), and writes the receipt to <code>pass.json</code>. Then:</p>
+<pre><code>PASS=$(node -p "require('./pass.json').pass")
+curl -H "${esc(header)}: $PASS" ${esc(siteUrl)}/</code></pre>
+
+<h2>Pay from your own x402 client</h2>
+<pre><code>curl -sS -H "Accept: application/json" ${esc(buyUrl)}
+# 402 with { "x402Version": 2, "accepts": [ ... ] }
+# sign an EIP-3009 transferWithAuthorization for one entry, then:
+curl -sS -H "X-PAYMENT: &lt;base64 proof&gt;" ${esc(buyUrl)}
+# 200 with { "ok": true, "pass": "cp_...", "expires_at": "...", "header": "${esc(header)}" }</code></pre>
+<p class="mut">The proof is x402 v2 in CoinPay's dialect: <code>{ x402Version: 2, scheme: "exact", network: "&lt;CAIP-2&gt;", payload: { signature, authorization } }</code>, base64-encoded. A proof is single-use; retrying with the same one returns the same pass, not a second charge.</p>
+
+<h2>Who pays and who does not</h2>
+<table>
+<tr><th>Charged</th><td>${training.map(esc).join(', ')}</td></tr>
+<tr><th>Free, named in robots.txt</th><td>${retrieval.map(esc).join(', ')}</td></tr>
+<tr><th>Free</th><td>Everyone else: people, Googlebot, Applebot, Bingbot and any crawler not on the first line.</td></tr>
+</table>
+<p class="mut">If your crawler is on the first line and you believe it should not be, or you want more than an hour at a time${
+    contact ? `, <a href="${esc(contact)}">get in touch</a>` : ', contact the site'
+  }.</p>
+
+<h2>The offer, verbatim</h2>
+<pre><code>${esc(JSON.stringify(offer, null, 2))}</code></pre>
+
+<footer>Served by @profullstack/x402-gateway. This page is <code>noindex</code> and is the one URL a refused crawler may read.</footer>
+</main>
+</body>
+</html>
+`;
+}

package/src/pass.js

@@ -0,0 +1,89 @@
+/**
+ * Passes: what a payment buys.
+ *
+ * A pass is a signed, self-describing token -- `cp_<payload>.<signature>` --
+ * carrying its own expiry and the reference of the payment that bought it.
+ * There is no table behind it. The gateway runs in front of six sites on two
+ * frameworks, some of them at the edge with no database in reach, and a token
+ * that proves itself needs none of them to agree on a schema.
+ *
+ * HMAC-SHA256 over Web Crypto, which is what Node, Bun and every edge runtime
+ * have in common. The key defaults to the CoinPay API key: it is already the
+ * one secret every deployment holds, and using it as key material never sends
+ * it anywhere.
+ */
+
+const enc = new TextEncoder();
+
+function toBase64Url(bytes) {
+  let bin = '';
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function fromBase64Url(s) {
+  const bin = atob(String(s).replace(/-/g, '+').replace(/_/g, '/'));
+  return Uint8Array.from(bin, (ch) => ch.charCodeAt(0));
+}
+
+async function hmacKey(secret) {
+  return crypto.subtle.importKey('raw', enc.encode(String(secret)), { name: 'HMAC', hash: 'SHA-256' }, false, [
+    'sign',
+    'verify',
+  ]);
+}
+
+async function sign(secret, data) {
+  const key = await hmacKey(secret);
+  const sig = await crypto.subtle.sign('HMAC', key, enc.encode(data));
+  return toBase64Url(new Uint8Array(sig));
+}
+
+/** Constant-time compare of two short strings. */
+function same(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+/**
+ * Mint a pass.
+ *
+ * @param {object} args
+ * @param {string} args.secret
+ * @param {string|null} args.ref   payment reference, for the accounting question
+ * @param {number} args.expiresAt  unix seconds
+ * @param {number} [args.now]      unix seconds, for tests
+ */
+export async function mintPass({ secret, ref, expiresAt, now = Math.floor(Date.now() / 1000) }) {
+  if (!secret) throw new Error('a pass needs a signing secret');
+  if (!Number.isFinite(expiresAt) || expiresAt <= now) throw new Error('a pass needs a future expiry');
+  const payload = toBase64Url(enc.encode(JSON.stringify({ v: 1, iat: now, exp: Math.floor(expiresAt), ref: ref ?? null })));
+  const sig = await sign(secret, payload);
+  return { token: `cp_${payload}.${sig}`, expiresAt: Math.floor(expiresAt), ref: ref ?? null };
+}
+
+/**
+ * Read a pass. Resolves to `{ exp, iat, ref }` when the signature holds and the
+ * pass has not expired, null otherwise. Never throws on garbage input: a token
+ * is untrusted text from a crawler.
+ */
+export async function readPass(token, { secret, now = Math.floor(Date.now() / 1000) }) {
+  if (!secret || typeof token !== 'string' || !token.startsWith('cp_')) return null;
+  const dot = token.indexOf('.');
+  if (dot < 0) return null;
+  const payload = token.slice(3, dot);
+  const sig = token.slice(dot + 1);
+  if (!payload || !sig) return null;
+  try {
+    const expect = await sign(secret, payload);
+    if (!same(expect, sig)) return null;
+    const claims = JSON.parse(new TextDecoder().decode(fromBase64Url(payload)));
+    if (!claims || claims.v !== 1 || !Number.isFinite(claims.exp)) return null;
+    if (claims.exp <= now) return null;
+    return { exp: claims.exp, iat: claims.iat ?? null, ref: claims.ref ?? null };
+  } catch {
+    return null;
+  }
+}

package/src/robots.js

@@ -0,0 +1,64 @@
+import { RETRIEVAL_AGENTS, TRAINING_AGENTS } from './agents.js';
+
+/**
+ * robots.txt with the crawlers sorted the way the gateway sorts them.
+ *
+ * Training crawlers are refused everywhere except the page that sells them a
+ * way in; retrieval crawlers are named so their operators can see they are
+ * welcome; everything else gets the wildcard rules.
+ *
+ * The trap this avoids: a crawler that finds a group matching its own name
+ * obeys THAT group and ignores `User-agent: *` entirely. Naming one and listing
+ * the sign-in page only under the wildcard would invite it straight into the
+ * sign-in page. So every named group repeats the rules, generated rather than
+ * typed.
+ *
+ * @param {object} options
+ * @param {string} options.siteUrl          no trailing slash
+ * @param {string[]} [options.disallow]     paths nobody should index, e.g. ['/login', '/api/']
+ * @param {string[]} [options.allow]        exceptions that beat a disallow by being longer, e.g. ['/api/v1']
+ * @param {string} [options.sitemap]        defaults to `${siteUrl}/sitemap.xml`; '' to omit
+ * @param {string} [options.path]           the sales page training crawlers may still read; default '/crawl'
+ * @param {string[]} [options.refused]      extra agents refused outright, e.g. a rude SEO bot
+ * @param {string[]} [options.training]     override the training list
+ * @param {string[]} [options.retrieval]    override the retrieval list
+ * @param {string[]} [options.comments]     lines written at the top, without the leading '# '
+ */
+export function robotsTxt({
+  siteUrl,
+  disallow = [],
+  allow = [],
+  sitemap,
+  path = '/crawl',
+  refused = [],
+  training = TRAINING_AGENTS,
+  retrieval = RETRIEVAL_AGENTS,
+  comments = [],
+} = {}) {
+  if (!siteUrl) throw new Error('robotsTxt needs siteUrl');
+  const base = siteUrl.replace(/\/+$/, '');
+  const map = sitemap === undefined ? `${base}/sitemap.xml` : sitemap;
+
+  const welcome = (agent) =>
+    [
+      `User-agent: ${agent}`,
+      'Allow: /',
+      ...allow.map((p) => `Allow: ${p}`),
+      ...disallow.map((p) => `Disallow: ${p}`),
+    ].join('\n');
+  const refuse = (agent) => `User-agent: ${agent}\nDisallow: /`;
+  // Longest match wins, so `Allow: /crawl` beats `Disallow: /` for that one page.
+  const charge = (agent) => `${refuse(agent)}\nAllow: ${path}`;
+
+  const lines = [
+    ...comments.map((c) => `# ${c}`),
+    ...(comments.length ? [''] : []),
+    ...refused.map((a) => `${refuse(a)}\n`),
+    ...training.map((a) => `${charge(a)}\n`),
+    ...retrieval.map((a) => `${welcome(a)}\n`),
+    welcome('*'),
+    '',
+  ];
+  if (map) lines.push(`Sitemap: ${map}`, '');
+  return lines.join('\n');
+}

package/src/x402.js

@@ -0,0 +1,178 @@
+/**
+ * x402 v2, in CoinPayPortal's dialect.
+ *
+ * Checked against @profullstack/coinpay/x402-v2 rather than remembered: the 402
+ * body is JSON `{ x402Version: 2, accepts: [...] }`, the proof arrives as base64
+ * JSON in an `X-PAYMENT` request header, and CoinPay's /api/x402/verify then
+ * /api/x402/settle do the cryptography and the on-chain transfer (EIP-3009,
+ * with CoinPay's relayer paying the gas, so the buyer needs no ETH).
+ *
+ * Reimplemented here in a few dozen lines because the SDK also carries the
+ * CLI's interactive-prompt dependency, which a web server has no business
+ * installing, and because a gateway that runs at the edge cannot import node:.
+ */
+
+/**
+ * The three things CoinPay can settle under the `exact` scheme. USDC only:
+ * EIP-3009 is an ERC-20 extension, so native ETH cannot be paid this way.
+ *
+ * CAIP-2 network ids, 6-decimal amounts, and the token's own EIP-712 domain in
+ * `extra`, which is not derivable from the contract and was read over JSON-RPC
+ * once upstream: all three USDC deployments answer "USD Coin" / "2".
+ *
+ * Base first. Merchant order is the payer's preference order, and Base is where
+ * the relayer's gas is cheapest.
+ */
+export const METHODS = [
+  {
+    key: 'usdc_base',
+    network: 'eip155:8453',
+    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    label: 'USDC on Base',
+  },
+  {
+    key: 'usdc_polygon',
+    network: 'eip155:137',
+    asset: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
+    label: 'USDC on Polygon',
+  },
+  {
+    key: 'usdc_eth',
+    network: 'eip155:1',
+    asset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    label: 'USDC on Ethereum',
+  },
+];
+
+const DECIMALS = 6;
+const DOMAIN = { name: 'USD Coin', version: '2' };
+
+/**
+ * A v2 402 body.
+ *
+ * `amount` is the price in the token's smallest unit, rounded UP: a fraction of
+ * a cent rounded down would quote less than the asking price and then verify as
+ * underpayment.
+ */
+export function buildOffer({
+  payTo,
+  priceCents,
+  resource,
+  description = 'Payment required',
+  maxTimeoutSeconds = 300,
+  methods = METHODS,
+}) {
+  if (!payTo) throw new Error('an offer needs a payTo address');
+  const amount = String(Math.ceil((Number(priceCents) / 100) * 10 ** DECIMALS));
+  return {
+    x402Version: 2,
+    accepts: methods.map((m) => ({
+      scheme: 'exact',
+      network: m.network,
+      amount,
+      asset: m.asset,
+      payTo,
+      resource,
+      description,
+      mimeType: 'application/json',
+      maxTimeoutSeconds,
+      extra: { ...DOMAIN },
+    })),
+  };
+}
+
+/** base64 -> utf8, without Buffer, so it runs at the edge. */
+function fromBase64(s) {
+  const bin = atob(String(s).trim().replace(/-/g, '+').replace(/_/g, '/'));
+  const bytes = Uint8Array.from(bin, (ch) => ch.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+
+/** The proof out of an X-PAYMENT header. Null if it is not base64 JSON. */
+export function decodePayment(header) {
+  if (!header) return null;
+  try {
+    const parsed = JSON.parse(fromBase64(header));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What CoinPay must hold the proof to.
+ *
+ * Its v2 verify refuses without all four of amount, resource, payTo and asset,
+ * and takes them from the OFFERED entry for the proof's network -- never from
+ * the proof itself, which is the payer's claim about what it paid.
+ */
+export function expectedFor(payment, offer) {
+  const network = String(payment?.network ?? '').toLowerCase();
+  const entry = (offer?.accepts ?? []).find((a) => a.network.toLowerCase() === network);
+  if (!entry) return null;
+  return { amount: entry.amount, resource: entry.resource, payTo: entry.payTo, asset: entry.asset };
+}
+
+/** The single-use nonce, which is what CoinPay keys replay detection on. */
+export const nonceOf = (payment) => payment?.payload?.authorization?.nonce ?? null;
+
+/** When the payer's signature stops being valid, as a unix timestamp in seconds. */
+export const validBeforeOf = (payment) => {
+  const v = Number(payment?.payload?.authorization?.validBefore);
+  return Number.isFinite(v) && v > 0 ? v : null;
+};
+
+/**
+ * Verify, then settle. Two calls because verify moves no money: it checks the
+ * signature and records the proof, and settle broadcasts the transfer.
+ *
+ * Resolves to `{ ok: true, payer, ref }` or `{ ok: false, reason, replay }`.
+ * `replay` is set when CoinPay has already seen this proof -- the case where a
+ * crawler paid, lost our answer, and is retrying with the same header. The
+ * gateway answers that with a pass rather than a second charge, bounded by the
+ * proof's own validity window so the same header cannot buy hour after hour.
+ */
+export async function verifyAndSettle(payment, expected, { apiKey, baseUrl, fetch: f = globalThis.fetch }) {
+  const call = async (path, body) => {
+    const res = await f(`${baseUrl}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-api-key': apiKey },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(20000),
+    });
+    const text = await res.text();
+    let json = {};
+    try {
+      json = JSON.parse(text);
+    } catch {}
+    return { status: res.status, json };
+  };
+
+  const v = await call('/api/x402/verify', { payment, expected });
+  if (!v.json?.valid) {
+    const reason = String(v.json?.error ?? v.json?.reason ?? `verify failed (${v.status})`);
+    return { ok: false, reason, replay: /already used|replay/i.test(reason) };
+  }
+  const s = await call('/api/x402/settle', { payment });
+  if (!s.json?.settled) {
+    const reason = String(s.json?.error ?? `settle failed (${s.status})`);
+    return { ok: false, reason, replay: /already settled|already being settled/i.test(reason) };
+  }
+  return { ok: true, payer: v.json.payment?.from ?? null, ref: s.json.txHash ?? nonceOf(payment) };
+}
+
+/** Whether the proof has already been paid, when a settle is asked about twice. */
+export async function settleAgain(payment, { apiKey, baseUrl, fetch: f = globalThis.fetch }) {
+  const res = await f(`${baseUrl}/api/x402/settle`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': apiKey },
+    body: JSON.stringify({ payment }),
+    signal: AbortSignal.timeout(20000),
+  });
+  let json = {};
+  try {
+    json = JSON.parse(await res.text());
+  } catch {}
+  const reason = String(json?.error ?? '');
+  return Boolean(json?.settled) || /already settled/i.test(reason);
+}