@profullstack/coinpay 0.6.10 → 0.8.0

package/src/x402-pay-server.js

@@ -0,0 +1,272 @@
+/**
+ * A one-shot local payment page, for paying an x402 invoice from the CLI.
+ *
+ * A terminal cannot sign with a browser wallet: the extension lives in the
+ * browser process and exposes itself only to pages. So the CLI serves a page on
+ * loopback, opens it, and waits. The page signs with CoinPay Wallet (or
+ * MetaMask, or anything else injected), posts the `X-PAYMENT` header back, and
+ * the CLI retries the original request with it.
+ *
+ * Security posture, because this is a local server that can spend money:
+ *   * bound to 127.0.0.1, never a routable interface
+ *   * every request must carry a single-use token from the URL, so another
+ *     process on the box cannot drive it or read the invoice
+ *   * one payment, then the server closes — it is not a standing service
+ *   * the private key never comes near this process; it stays in the wallet
+ *
+ * @module x402-pay-server
+ */
+
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** SDK modules the page imports. Served from disk so the page can `import` them. */
+const MODULES = {
+  '/x402-browser.js': join(HERE, 'x402-browser.js'),
+  '/x402-v2.js': join(HERE, 'x402-v2.js'),
+};
+
+function renderPage() {
+  // Kept dependency-free and inline: this page is served from a temporary
+  // loopback server, so anything external would simply fail to load.
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>CoinPay — Approve payment</title>
+<style>
+  :root { color-scheme: light dark; --bg:#faf9f7; --fg:#1a1a1a; --muted:#6b6b6b; --card:#fff; --line:#e6e3de; --accent:#2f6f4f; }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg:#141414; --fg:#f2f2f2; --muted:#9a9a9a; --card:#1e1e1e; --line:#333; --accent:#5ea37a; }
+  }
+  * { box-sizing: border-box; }
+  body { margin:0; min-height:100vh; display:grid; place-items:center; padding:24px;
+         background:var(--bg); color:var(--fg);
+         font:16px/1.5 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif; }
+  .card { width:100%; max-width:420px; background:var(--card); border:1px solid var(--line);
+          border-radius:14px; padding:28px; }
+  h1 { margin:0 0 4px; font-size:19px; }
+  .sub { color:var(--muted); font-size:14px; margin:0 0 20px; }
+  dl { display:grid; grid-template-columns:auto 1fr; gap:10px 16px; margin:0 0 22px;
+       padding:16px 0; border-top:1px solid var(--line); border-bottom:1px solid var(--line); }
+  dt { color:var(--muted); font-size:14px; }
+  dd { margin:0; text-align:right; font-variant-numeric:tabular-nums; overflow-wrap:anywhere; }
+  .amount { font-size:22px; font-weight:600; }
+  button { width:100%; padding:13px; font-size:15px; font-weight:600; border:0; border-radius:9px;
+           background:var(--accent); color:#fff; cursor:pointer; }
+  button:disabled { opacity:.55; cursor:default; }
+  .status { margin-top:16px; font-size:14px; color:var(--muted); min-height:1.5em; text-align:center; overflow-wrap:anywhere; }
+  .status.error { color:#b3261e; }
+  @media (prefers-color-scheme: dark) { .status.error { color:#f2b8b5; } }
+  .status.ok { color:var(--accent); }
+  code { font:13px ui-monospace,SFMono-Regular,Menlo,monospace; }
+</style>
+</head>
+<body>
+  <main class="card">
+    <h1>Approve payment</h1>
+    <p class="sub" id="resource"></p>
+    <dl>
+      <dt>Amount</dt><dd class="amount" id="amount">—</dd>
+      <dt>Network</dt><dd id="network">—</dd>
+      <dt>To</dt><dd><code id="payTo">—</code></dd>
+      <dt>Wallet</dt><dd id="wallet">looking…</dd>
+    </dl>
+    <button id="pay" disabled>Pay</button>
+    <p class="status" id="status"></p>
+  </main>
+
+<script type="module">
+import { fetchWithX402, createPaymentHeader, selectWallet } from './x402-browser.js';
+import { requiredAmount, evmChainId, selectAcceptEntry, toCaip2 } from './x402-v2.js';
+
+const token = new URLSearchParams(location.search).get('t') ?? '';
+const $ = (id) => document.getElementById(id);
+
+const setStatus = (text, kind = '') => {
+  $('status').textContent = text;
+  $('status').className = 'status ' + kind;
+};
+
+const CHAIN_NAMES = { 1: 'Ethereum', 137: 'Polygon', 8453: 'Base' };
+
+function scaled(raw, decimals = 6) {
+  const value = BigInt(raw);
+  const div = 10n ** BigInt(decimals);
+  const whole = value / div;
+  const frac = (value % div).toString().padStart(decimals, '0').replace(/0+$/, '');
+  return frac ? \`\${whole}.\${frac}\` : String(whole);
+}
+
+let invoice;
+
+async function init() {
+  const res = await fetch(\`/invoice?t=\${token}\`);
+  if (!res.ok) return setStatus('This payment link is no longer valid.', 'error');
+
+  const data = await res.json();
+  invoice = data.paymentRequired;
+  $('resource').textContent = data.resourceUrl;
+
+  // Show the option a browser wallet would actually take.
+  const evm = (invoice.accepts ?? [])
+    .map((a) => a.network)
+    .filter((n) => evmChainId(n) !== null);
+  const entry = selectAcceptEntry(invoice.accepts ?? [], evm) ?? invoice.accepts?.[0];
+
+  if (entry) {
+    $('amount').textContent = \`\${scaled(requiredAmount(entry))} \${entry.extra?.name ?? ''}\`.trim();
+    $('network').textContent = CHAIN_NAMES[evmChainId(entry.network)] ?? toCaip2(entry.network);
+    $('payTo').textContent = entry.payTo ?? '—';
+  }
+
+  const wallet = await selectWallet();
+  if (!wallet) {
+    $('wallet').textContent = 'none found';
+    return setStatus('No wallet found. Install CoinPay Wallet or MetaMask, then reload.', 'error');
+  }
+  $('wallet').textContent = wallet.name;
+  $('pay').disabled = false;
+  setStatus('');
+}
+
+$('pay').addEventListener('click', async () => {
+  $('pay').disabled = true;
+  setStatus('Waiting for your wallet…');
+  try {
+    const { header, wallet } = await createPaymentHeader(invoice);
+    setStatus('Signed. Handing back to the terminal…');
+    await fetch(\`/payment?t=\${token}\`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ header, wallet: wallet?.name }),
+    });
+    setStatus('Paid. You can close this tab.', 'ok');
+  } catch (err) {
+    $('pay').disabled = false;
+    setStatus(err?.message ?? String(err), 'error');
+  }
+});
+
+init().catch((err) => setStatus(err?.message ?? String(err), 'error'));
+</script>
+</body>
+</html>`;
+}
+
+/**
+ * Serve a one-shot payment page.
+ *
+ * @param {object} options
+ * @param {object} options.paymentRequired  parsed body of the 402 response
+ * @param {string} options.resourceUrl      what is being bought, for display
+ * @param {number} [options.port=0]         0 lets the OS pick a free port
+ * @returns {Promise<{url: string, waitForPayment: () => Promise<string>, close: () => Promise<void>}>}
+ */
+export async function startPaymentServer({ paymentRequired, resourceUrl, port = 0 }) {
+  // A single-use token, so another local process cannot read the invoice or
+  // post a payment into this session.
+  const token = randomBytes(24).toString('hex');
+
+  let resolvePayment;
+  let rejectPayment;
+  const payment = new Promise((resolve, reject) => {
+    resolvePayment = resolve;
+    rejectPayment = reject;
+  });
+
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+
+    const send = (status, body, type = 'text/plain; charset=utf-8') => {
+      res.writeHead(status, {
+        'Content-Type': type,
+        // The page must not be embeddable or reachable cross-origin: it can
+        // authorise a payment.
+        'X-Frame-Options': 'DENY',
+        'Cache-Control': 'no-store',
+      });
+      res.end(body);
+    };
+
+    if (url.pathname === '/' && req.method === 'GET') {
+      // The token is checked on the data routes rather than here, so a
+      // mistyped link shows the page and a clear error instead of a bare 403.
+      return send(200, renderPage(), 'text/html; charset=utf-8');
+    }
+
+    const modulePath = MODULES[url.pathname];
+    if (modulePath && req.method === 'GET') {
+      try {
+        const source = await readFile(modulePath, 'utf-8');
+        return send(200, source, 'text/javascript; charset=utf-8');
+      } catch {
+        return send(404, 'not found');
+      }
+    }
+
+    if (url.searchParams.get('t') !== token) {
+      return send(403, 'forbidden');
+    }
+
+    if (url.pathname === '/invoice' && req.method === 'GET') {
+      return send(200, JSON.stringify({ paymentRequired, resourceUrl }), 'application/json');
+    }
+
+    if (url.pathname === '/payment' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (chunk) => {
+        body += chunk;
+        // A payment header is a few hundred bytes; anything larger is not one.
+        if (body.length > 64_000) req.destroy();
+      });
+      req.on('end', () => {
+        try {
+          const parsed = JSON.parse(body);
+          if (!parsed.header) throw new Error('No payment header supplied');
+          send(200, JSON.stringify({ ok: true }), 'application/json');
+          resolvePayment(parsed.header);
+        } catch (err) {
+          send(400, JSON.stringify({ error: err.message }), 'application/json');
+        }
+      });
+      return;
+    }
+
+    return send(404, 'not found');
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    // Loopback only. Binding 0.0.0.0 would expose a pay-me button to the LAN.
+    server.listen(port, '127.0.0.1', resolve);
+  });
+
+  const address = server.address();
+  const url = `http://127.0.0.1:${address.port}/?t=${token}`;
+
+  const close = () =>
+    new Promise((resolve) => {
+      server.close(() => resolve());
+      // Don't hold the process open on a browser tab that stayed connected.
+      server.closeAllConnections?.();
+    });
+
+  return {
+    url,
+    waitForPayment: (timeoutMs = 5 * 60 * 1000) => {
+      const timer = setTimeout(
+        () => rejectPayment(new Error('Timed out waiting for approval in the browser')),
+        timeoutMs,
+      );
+      return payment.finally(() => clearTimeout(timer));
+    },
+    close,
+  };
+}

package/src/x402-v2.js

@@ -0,0 +1,416 @@
+/**
+ * x402 v2 protocol primitives.
+ *
+ * `x402.js` speaks a dialect only CoinPayPortal understands: `x402Version: 1`,
+ * bare network names like `"base"`, `maxAmountRequired` instead of `amount`,
+ * and an EIP-712 domain of our own invention (`name: 'x402'`). Nothing else in
+ * the ecosystem can read a 402 we emit, and no proof from a standard client
+ * verifies against us.
+ *
+ * That is survivable while CoinPay Wallet is the only payer. It stops being
+ * survivable the moment MetaMask or Phantom is expected to pay, because those
+ * wallets sign standard structures and nothing else: MetaMask will happily
+ * sign our bespoke domain, but the resulting signature authorises nothing
+ * on-chain and only we could ever interpret it.
+ *
+ * This module is the real thing, and is shared by the browser payer and the
+ * facilitator so the two cannot drift.
+ *
+ * Field shapes here were taken from live `/supported` and
+ * `/discovery/resources` responses on facilitator.goplausible.xyz and
+ * Coinbase's facilitator, not from memory of the spec.
+ *
+ * @module x402-v2
+ */
+
+/** The protocol version the ecosystem is actually on. */
+export const X402_VERSION = 2;
+
+/**
+ * CAIP-2 chain identifiers.
+ *
+ * The ecosystem addresses chains as `namespace:reference`, never as a bare
+ * name — `"base"` is meaningless to another facilitator, `eip155:8453` is not.
+ *
+ * `eip155:*` and `solana:*` are verified against live facilitator responses.
+ * Solana's reference is the first 32 characters of the genesis hash, per
+ * CAIP-30.
+ */
+export const CAIP2 = {
+  ethereum: 'eip155:1',
+  polygon: 'eip155:137',
+  base: 'eip155:8453',
+  'base-sepolia': 'eip155:84532',
+  solana: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+  // CAIP-2 namespace for Bitcoin-family chains is `bip122`, referenced by the
+  // genesis block hash. Bitcoin Cash shares Bitcoin's genesis block, so the two
+  // are not distinguishable by CAIP-2 alone; BCH is left out rather than given
+  // an identifier that collides with Bitcoin's.
+  bitcoin: 'bip122:000000000019d6689c085ae165831e93',
+};
+
+/**
+ * Rails CoinPayPortal supports that have no CAIP-2 identity.
+ *
+ * Nobody else's facilitator accepts these, so there is no interoperable name
+ * to use. They keep their legacy identifiers and are flagged here so callers
+ * can tell "not yet mapped" from "deliberately outside CAIP-2".
+ */
+export const NON_CAIP2_NETWORKS = new Set(['bitcoin-cash', 'lightning', 'stripe']);
+
+/** Legacy bare name -> CAIP-2, for translating our own v1 records. */
+export function toCaip2(network) {
+  if (!network) return '';
+  if (network.includes(':')) return network; // already CAIP-2
+  return CAIP2[network] ?? network;
+}
+
+/** CAIP-2 -> legacy bare name, for code that still keys on the old names. */
+export function fromCaip2(caip2) {
+  if (!caip2) return '';
+  if (!caip2.includes(':')) return caip2; // already a bare name
+  const match = Object.entries(CAIP2).find(([, id]) => id === caip2);
+  return match ? match[0] : caip2;
+}
+
+/** Numeric EVM chain id from a CAIP-2 id, or null if it is not an eip155 chain. */
+export function evmChainId(network) {
+  const caip2 = toCaip2(network);
+  const match = /^eip155:(\d+)$/.exec(caip2);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * EIP-712 domains for the tokens we quote, keyed by `chainId:address`.
+ *
+ * A payer cannot sign without `name` and `version`, and they are not derivable:
+ * `version()` is not part of ERC-20 and tokens disagree about the value. So a
+ * v2 `accepts` entry has to carry them, which means the quoting side has to
+ * know them.
+ *
+ * Every entry below was read from the deployed contract — `name()`,
+ * `version()` and `DOMAIN_SEPARATOR()` over JSON-RPC — not copied from
+ * documentation. The Base values additionally match what GoPlausible's
+ * discovery index publishes for the same token.
+ *
+ * A token that is not in this table cannot be quoted for v2, because guessing
+ * its domain produces signatures that recover to the wrong address and fail
+ * verification with no useful diagnostic.
+ */
+export const TOKEN_DOMAINS = {
+  // USDC. All three deployments report the same domain.
+  'eip155:1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48': { name: 'USD Coin', version: '2' },
+  'eip155:137:0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359': { name: 'USD Coin', version: '2' },
+  'eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913': { name: 'USD Coin', version: '2' },
+};
+
+/** The published EIP-712 domain for a token, or null if we do not know it. */
+export function tokenDomain(network, asset) {
+  if (!asset) return null;
+  const caip2 = toCaip2(network);
+  const exact = TOKEN_DOMAINS[`${caip2}:${asset}`];
+  if (exact) return exact;
+
+  // Addresses are case-insensitive, so a caller passing a differently-cased
+  // address must not silently miss.
+  const wanted = `${caip2}:${asset}`.toLowerCase();
+  const match = Object.entries(TOKEN_DOMAINS).find(([key]) => key.toLowerCase() === wanted);
+  return match ? match[1] : null;
+}
+
+/**
+ * The v2-quotable tokens, as `{ methodKey: {network, asset, decimals} }`.
+ *
+ * Only tokens: EIP-3009 is an ERC-20 extension, so native ETH or POL cannot be
+ * paid under the `exact` scheme at all — there is no contract to authorise
+ * against. Quoting native currency as `exact` would advertise something no
+ * wallet can sign.
+ */
+export const V2_METHODS = {
+  usdc_eth: {
+    network: 'eip155:1',
+    asset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    decimals: 6,
+    label: 'USDC on Ethereum',
+  },
+  usdc_polygon: {
+    network: 'eip155:137',
+    asset: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
+    decimals: 6,
+    label: 'USDC on Polygon',
+  },
+  usdc_base: {
+    network: 'eip155:8453',
+    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    decimals: 6,
+    label: 'USDC on Base',
+  },
+};
+
+/**
+ * EIP-3009 `TransferWithAuthorization` type.
+ *
+ * This — not a bespoke `Payment` struct — is what x402's `exact` scheme signs
+ * on EVM. The signature IS the payment: whoever holds it can call
+ * `transferWithAuthorization` on the token and move the funds, which is why
+ * the facilitator can broadcast and pay the gas while the payer needs no
+ * native currency at all.
+ */
+export const TRANSFER_WITH_AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: 'from', type: 'address' },
+    { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+  ],
+};
+
+/**
+ * Build the EIP-712 domain for an EIP-3009 authorization.
+ *
+ * The domain belongs to the TOKEN, not to x402: `verifyingContract` is the
+ * token's own address, and `name`/`version` are the values that token returns
+ * from its own EIP-712 domain. Tokens disagree about `version` ("1" vs "2")
+ * and it is not derivable, which is why a v2 `accepts` entry carries it in
+ * `extra` — that is what `extra: { name: 'USD Coin', version: '2' }` in live
+ * discovery data is for.
+ *
+ * Getting this wrong is not a soft failure: the recovered signer is simply
+ * some other address, so the authorization is void.
+ *
+ * @param {object} args
+ * @param {string} args.network   CAIP-2 id or legacy name
+ * @param {string} args.asset     token contract address
+ * @param {string} args.name      token's EIP-712 domain name
+ * @param {string} args.version   token's EIP-712 domain version
+ */
+export function buildEip3009Domain({ network, asset, name, version }) {
+  const chainId = evmChainId(network);
+  if (chainId === null) {
+    throw new Error(`Not an EVM network, cannot build an EIP-3009 domain: ${network}`);
+  }
+  if (!asset) {
+    throw new Error('EIP-3009 requires the token contract address as verifyingContract');
+  }
+  if (!name || !version) {
+    throw new Error(
+      'EIP-3009 requires the token EIP-712 domain name and version; ' +
+        'a v2 `accepts` entry supplies them in `extra.name` / `extra.version`',
+    );
+  }
+
+  return { name, version, chainId, verifyingContract: asset };
+}
+
+/**
+ * A random 32-byte nonce, hex encoded.
+ *
+ * EIP-3009 nonces are arbitrary bytes32 rather than a sequence — the token
+ * tracks used ones per authorizer, so they need only be unpredictable and not
+ * repeated. Uses WebCrypto, which is present in browsers, Workers and Node 18+.
+ */
+export function randomNonce() {
+  const bytes = new Uint8Array(32);
+  globalThis.crypto.getRandomValues(bytes);
+  return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/**
+ * Build the authorization message to be signed.
+ *
+ * `validAfter` is 0 rather than "now": clocks differ between the payer and the
+ * chain, and a validAfter in the payer's near future makes the authorization
+ * briefly unusable for no benefit.
+ *
+ * @param {object} args
+ * @param {string} args.from            payer address
+ * @param {string} args.to              payee address (`payTo` from `accepts`)
+ * @param {string|bigint} args.value    amount in the token's smallest unit
+ * @param {number} [args.validForSeconds=600]
+ * @param {string} [args.nonce]         defaults to a fresh random nonce
+ */
+export function buildAuthorization({ from, to, value, validForSeconds = 600, nonce }) {
+  if (!from) throw new Error('buildAuthorization requires `from`');
+  if (!to) throw new Error('buildAuthorization requires `to`');
+  if (value === undefined || value === null || value === '') {
+    throw new Error('buildAuthorization requires `value`');
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+
+  return {
+    from,
+    to,
+    value: String(value),
+    validAfter: '0',
+    validBefore: String(now + validForSeconds),
+    nonce: nonce ?? randomNonce(),
+  };
+}
+
+/**
+ * Assemble the payment payload that goes in the `X-PAYMENT` header.
+ *
+ * @param {object} args
+ * @param {string} args.network        CAIP-2 id
+ * @param {string} args.signature      65-byte EIP-712 signature, hex
+ * @param {object} args.authorization  from `buildAuthorization`
+ * @param {string} [args.scheme='exact']
+ */
+export function buildExactEvmPayment({ network, signature, authorization, scheme = 'exact' }) {
+  return {
+    x402Version: X402_VERSION,
+    scheme,
+    network: toCaip2(network),
+    payload: { signature, authorization },
+  };
+}
+
+/**
+ * base64 encoding of a payment payload, as the `X-PAYMENT` header carries it.
+ *
+ * Uses base64url-safe output only where the runtime gives it; the header is
+ * standard base64 in the spec, so plain base64 is what is produced.
+ */
+export function encodePaymentHeader(payment) {
+  const json = JSON.stringify(payment);
+  if (typeof globalThis.btoa === 'function') {
+    // Browsers: btoa is latin1-only, so UTF-8 must be widened first.
+    const bytes = new TextEncoder().encode(json);
+    let binary = '';
+    for (const byte of bytes) binary += String.fromCharCode(byte);
+    return globalThis.btoa(binary);
+  }
+  return Buffer.from(json, 'utf-8').toString('base64');
+}
+
+/** Inverse of {@link encodePaymentHeader}. */
+export function decodePaymentHeader(header) {
+  let json;
+  if (typeof globalThis.atob === 'function') {
+    const binary = globalThis.atob(header);
+    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+    json = new TextDecoder().decode(bytes);
+  } else {
+    json = Buffer.from(header, 'base64').toString('utf-8');
+  }
+  return JSON.parse(json);
+}
+
+/**
+ * Pick the best `accepts` entry a given set of wallets can actually pay.
+ *
+ * A 402 lists several options and the payer must choose one it can sign. The
+ * order of `accepts` is the merchant's preference, so it is honoured rather
+ * than re-ranked — the first entry whose network is supported wins.
+ *
+ * @param {object[]} accepts       the 402's `accepts` array
+ * @param {string[]} capabilities  CAIP-2 ids (or bare names) the payer can sign
+ * @returns {object|null}
+ */
+export function selectAcceptEntry(accepts, capabilities) {
+  if (!Array.isArray(accepts) || accepts.length === 0) return null;
+  const supported = new Set(capabilities.map(toCaip2));
+  return accepts.find((entry) => supported.has(toCaip2(entry?.network))) ?? null;
+}
+
+/**
+ * Build a v2 `402 Payment Required` body.
+ *
+ * `buildPaymentRequired` in x402.js emits our v1 dialect — `x402Version: 1`,
+ * bare network names, `maxAmountRequired` — which no standard payer can read.
+ * A facilitator that verifies v2 but only ever quotes v1 still cannot be paid
+ * by anyone, so this is the other half of speaking the protocol.
+ *
+ * Only tokens with a known EIP-712 domain are quoted. An entry a payer cannot
+ * sign is worse than an absent one: it looks payable, fails at signing time,
+ * and the failure surfaces as an opaque signature error.
+ *
+ * @param {object} options
+ * @param {string|Record<string,string>} options.payTo  merchant address, or per-network map
+ * @param {number} [options.amountUsd]  price in USD (USDC is quoted 1:1)
+ * @param {string} [options.amount]     explicit smallest-unit amount, overrides amountUsd
+ * @param {string[]} [options.methods]  keys from V2_METHODS; defaults to all
+ * @param {string} options.resource     the URL being sold
+ * @param {string} [options.description]
+ * @param {string} [options.mimeType='application/json']
+ * @param {number} [options.maxTimeoutSeconds=300]
+ */
+export function buildPaymentRequiredV2({
+  payTo,
+  amountUsd,
+  amount,
+  methods,
+  resource,
+  description = 'Payment required',
+  mimeType = 'application/json',
+  maxTimeoutSeconds = 300,
+} = {}) {
+  if (!payTo) throw new Error('buildPaymentRequiredV2 requires `payTo`');
+  if (!resource) throw new Error('buildPaymentRequiredV2 requires `resource`');
+  if (amount === undefined && amountUsd === undefined) {
+    throw new Error('buildPaymentRequiredV2 requires `amount` or `amountUsd`');
+  }
+
+  const keys = methods ?? Object.keys(V2_METHODS);
+  const accepts = [];
+
+  for (const key of keys) {
+    const method = V2_METHODS[key];
+    if (!method) continue;
+
+    const domain = tokenDomain(method.network, method.asset);
+    if (!domain) continue; // unsignable — leave it out rather than advertise it
+
+    const address =
+      typeof payTo === 'object' ? (payTo[method.network] ?? payTo[fromCaip2(method.network)] ?? payTo[key]) : payTo;
+    if (!address) continue; // merchant has no address on this chain
+
+    // USDC is a dollar stablecoin with 6 decimals, so a USD price converts
+    // exactly. Rounding up rather than down: rounding a fraction of a cent
+    // down would quote less than the asking price and verify as underpayment.
+    const smallestUnit =
+      amount !== undefined
+        ? String(amount)
+        : String(Math.ceil(amountUsd * 10 ** method.decimals));
+
+    accepts.push({
+      scheme: 'exact',
+      network: method.network,
+      amount: smallestUnit,
+      asset: method.asset,
+      payTo: address,
+      resource,
+      description,
+      mimeType,
+      maxTimeoutSeconds,
+      // The token's EIP-712 domain. Without this the payer cannot construct a
+      // signature at all — it is the whole reason `extra` exists on a v2 entry.
+      extra: { name: domain.name, version: domain.version },
+    });
+  }
+
+  if (accepts.length === 0) {
+    throw new Error(
+      'No payable options could be built. Check `payTo` covers at least one supported chain.',
+    );
+  }
+
+  return { x402Version: X402_VERSION, accepts };
+}
+
+/**
+ * The amount an `accepts` entry asks for, in the asset's smallest unit.
+ *
+ * v2 names this `amount`; our own v1 emitted `maxAmountRequired`. Both are
+ * read so a payer can pay a CoinPayPortal 402 that has not been migrated yet.
+ */
+export function requiredAmount(entry) {
+  const raw = entry?.amount ?? entry?.maxAmountRequired;
+  if (raw === undefined || raw === null || raw === '') {
+    throw new Error('`accepts` entry has neither `amount` nor `maxAmountRequired`');
+  }
+  return String(raw);
+}