@profullstack/coinpay 0.6.11 → 0.8.0

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);
+}

package/src/x402.js

@@ -8,6 +8,8 @@
  * @module x402
  */
 
+import { buildPaymentRequiredV2 } from './x402-v2.js';
+
 /**
  * All supported payment methods with their network/asset metadata.
  * 
@@ -331,6 +333,82 @@ function _networkToMethodKey(network) {
   return map[network] || network;
 }
 
+/**
+ * Decode an X-PAYMENT header without verifying it.
+ *
+ * Returns null on anything malformed — the caller treats that as "no usable
+ * proof", and the facilitator remains the only thing that decides validity.
+ */
+function decodePaymentHeader(paymentHeader) {
+  try {
+    return JSON.parse(Buffer.from(paymentHeader, 'base64').toString('utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Work out what this proof was supposed to pay, by finding the offer entry for
+ * the method the payer chose.
+ *
+ * The price comes from the offer the server just built — never from the proof
+ * itself, which is the payer's word for what they owe.
+ *
+ * @returns {{amount: string, resource: string, payTo?: string, asset?: string}|null}
+ *   null if the proof matches no advertised method, in which case there is no
+ *   price to hold it to.
+ */
+export function expectedForProof(paymentHeader, offer, resource) {
+  const payment = decodePaymentHeader(paymentHeader);
+  if (!payment?.payload) return null;
+
+  // A v2 proof describes itself differently: the network sits at the top level
+  // and the payload holds a signed authorization rather than loose fields.
+  // Matching it against the offer the same way as v1 would find nothing and
+  // report "no price to check against" for a perfectly good payment.
+  const authorization = payment.payload.authorization;
+  if (authorization) {
+    const entries = offer?.accepts || [];
+    const match =
+      entries.find((e) => e.network === payment.network && e.payTo === authorization.to) ||
+      entries.find((e) => e.network === payment.network);
+
+    if (!match) return null;
+
+    return {
+      amount: match.amount ?? match.maxAmountRequired,
+      resource,
+      // v2 verification needs both: an EIP-3009 signature says nothing about
+      // which token it is denominated in, so without the asset there is no
+      // domain to check it against.
+      payTo: match.payTo,
+      asset: match.asset,
+    };
+  }
+
+  const { network, asset } = payment.payload;
+  const methodKey = payment.payload.methodKey || payment.payload.extra?.methodKey;
+
+  const entries = offer?.accepts || [];
+
+  // Prefer an exact method match: a network alone is ambiguous, since e.g.
+  // ethereum offers both ETH and USDC at very different smallest-unit prices.
+  let match = methodKey
+    ? entries.find((e) => e.extra?.methodKey === methodKey)
+    : undefined;
+
+  if (!match && network) {
+    const sameNetwork = entries.filter((e) => e.network === network);
+    match =
+      sameNetwork.find((e) => e.asset === asset) ||
+      (sameNetwork.length === 1 ? sameNetwork[0] : undefined);
+  }
+
+  if (!match) return null;
+
+  return { amount: match.maxAmountRequired, resource };
+}
+
 /**
  * Create Express/Next.js middleware that gates routes behind x402 payments.
  * 
@@ -373,9 +451,23 @@ export function createX402Middleware(globalOptions) {
     description = 'Payment required',
     facilitatorUrl = DEFAULT_FACILITATOR_URL,
     apiBaseUrl = 'https://coinpayportal.com',
+    allowPendingConfirmation: globalAllowPendingConfirmation = false,
+    /**
+     * Which protocol version to quote in the 402.
+     *
+     * Defaults to 1 so existing integrations keep the offer they have today —
+     * their payers only understand our dialect, and switching the quote out
+     * from under them would break every one at once. Set to 2 to advertise the
+     * real protocol, which is what any standard wallet (MetaMask, Phantom) can
+     * actually pay.
+     */
+    x402Version: protocolVersion = 1,
   } = globalOptions;
 
   if (!apiKey) throw new Error('x402 middleware requires an apiKey');
+  if (protocolVersion !== 1 && protocolVersion !== 2) {
+    throw new Error(`Unsupported x402Version: ${protocolVersion} (expected 1 or 2)`);
+  }
   if (!payTo) throw new Error('x402 middleware requires a payTo address');
 
   // Mutable rates cache — can be updated externally or via ratesEndpoint
@@ -408,6 +500,8 @@ export function createX402Middleware(globalOptions) {
     const routeAmount = routeOptions.amount;
     const routeDescription = routeOptions.description || description;
     const routeMethods = routeOptions.methods || methods;
+    const allowPendingConfirmation =
+      routeOptions.allowPendingConfirmation ?? globalAllowPendingConfirmation;
 
     if (!routeAmountUsd && !routeAmount) {
       throw new Error('x402 route requires amountUsd or amount');
@@ -415,32 +509,58 @@ export function createX402Middleware(globalOptions) {
 
     return async function x402Middleware(req, res, next) {
       const paymentHeader = req.headers['x-payment'] || req.headers['X-Payment'];
+      const resource = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
+
+      // Build the offer regardless of branch: on a 402 it is the response body,
+      // and on a paid request it is the price the proof has to actually cover.
+      let offer;
+      try {
+        offer =
+          protocolVersion === 2
+            ? buildPaymentRequiredV2({
+                payTo,
+                amountUsd: routeAmountUsd,
+                amount: routeAmount,
+                methods: routeMethods,
+                resource,
+                description: routeDescription,
+              })
+            : buildPaymentRequired({
+                payTo,
+                amountUsd: routeAmountUsd,
+                amount: routeAmount,
+                network: routeOptions.network,
+                rates: currentRates,
+                methods: routeMethods,
+                resource,
+                description: routeDescription,
+                facilitatorUrl,
+              });
+      } catch (err) {
+        return res.status(500).json({ error: 'Failed to build payment options', details: err.message });
+      }
 
       if (!paymentHeader) {
-        const resource = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
-        try {
-          const body = buildPaymentRequired({
-            payTo,
-            amountUsd: routeAmountUsd,
-            amount: routeAmount,
-            network: routeOptions.network,
-            rates: currentRates,
-            methods: routeMethods,
-            resource,
-            description: routeDescription,
-            facilitatorUrl,
-          });
-          return res.status(402).json(body);
-        } catch (err) {
-          return res.status(500).json({ error: 'Failed to build payment options', details: err.message });
-        }
+        return res.status(402).json(offer);
       }
 
       // Verify the payment
       try {
+        // Find the advertised price for the method the payer actually used.
+        // Without this the facilitator has nothing to compare the proof
+        // against, and any proof unlocks any priced route.
+        const expected = expectedForProof(paymentHeader, offer, resource);
+        if (!expected) {
+          return res.status(402).json({
+            error: 'Invalid payment proof',
+            details: 'Proof does not correspond to any offered payment method',
+          });
+        }
+
         const result = await verifyX402Payment(paymentHeader, {
           apiKey,
           apiBaseUrl,
+          expected,
         });
 
         if (!result.valid) {
@@ -450,6 +570,17 @@ export function createX402Middleware(globalOptions) {
           });
         }
 
+        // On non-EVM rails the paid amount is self-reported until settlement
+        // confirms it on-chain, so serving now means serving on trust.
+        if (result.payment?.pendingConfirmation && !allowPendingConfirmation) {
+          return res.status(402).json({
+            error: 'Payment not confirmed',
+            details:
+              'This payment cannot be confirmed until it settles on-chain. ' +
+              'Set allowPendingConfirmation: true to serve on unconfirmed proofs.',
+          });
+        }
+
         // Attach payment info to request for downstream use
         req.x402Payment = result.payment;
         next();
@@ -472,10 +603,13 @@ export function createX402Middleware(globalOptions) {
  * @param {Object} options
  * @param {string} options.apiKey - CoinPayPortal API key
  * @param {string} [options.apiBaseUrl='https://coinpayportal.com'] - API base URL
+ * @param {{amount: string, resource: string}} options.expected - What this
+ *   request is charging, and for what. Required: the facilitator refuses to
+ *   verify a proof it cannot hold to a price.
  * @returns {Promise<{valid: boolean, payment?: Object, reason?: string}>}
  */
 export async function verifyX402Payment(paymentHeader, options = {}) {
-  const { apiKey, apiBaseUrl = 'https://coinpayportal.com' } = options;
+  const { apiKey, apiBaseUrl = 'https://coinpayportal.com', expected } = options;
 
   if (!paymentHeader) {
     return { valid: false, reason: 'Missing payment header' };
@@ -495,6 +629,7 @@ export async function verifyX402Payment(paymentHeader, options = {}) {
     return { valid: false, reason: 'Missing scheme, signature, or payload in payment proof' };
   }
 
+
   // Check expiry if present
   if (payment.payload?.expiresAt) {
     const expiresAt = typeof payment.payload.expiresAt === 'number'
@@ -505,6 +640,16 @@ export async function verifyX402Payment(paymentHeader, options = {}) {
     }
   }
 
+  // A proof is only meaningful against a price. Without one there is nothing
+  // to check it covers, which is exactly how a $0.01 proof used to unlock a
+  // $5.00 resource.
+  if (!expected?.amount || !expected?.resource) {
+    return {
+      valid: false,
+      reason: 'Missing expected amount/resource — refusing to verify a proof with no price to check it against',
+    };
+  }
+
   // Call CoinPayPortal facilitator to verify
   try {
     const response = await fetch(`${apiBaseUrl}/api/x402/verify`, {
@@ -513,7 +658,7 @@ export async function verifyX402Payment(paymentHeader, options = {}) {
         'Content-Type': 'application/json',
         ...(apiKey ? { 'X-API-Key': apiKey } : {}),
       },
-      body: JSON.stringify({ payment }),
+      body: JSON.stringify({ payment, expected }),
     });
 
     const data = await response.json();