@profullstack/coinpay 0.6.10 → 0.8.0

package/src/wallet.js

@@ -33,6 +33,7 @@ export const WalletChain = {
   USDC_ETH: 'USDC_ETH',
   USDC_POL: 'USDC_POL',
   USDC_SOL: 'USDC_SOL',
+  USDC_BASE: 'USDC_BASE',
   USDT_ETH: 'USDT_ETH',
   USDT_POL: 'USDT_POL',
   USDT_SOL: 'USDT_SOL',
@@ -56,6 +57,7 @@ const COIN_TYPES = {
   USDC_ETH: 60,
   USDC_POL: 60,
   USDC_SOL: 501,
+  USDC_BASE: 60, // Base is EVM, uses ETH path — same address as USDC_ETH
   USDT_ETH: 60,
   USDT_POL: 60,
   USDT_SOL: 501,
@@ -64,7 +66,7 @@ const COIN_TYPES = {
 /**
  * Chains that use secp256k1 curve (vs ed25519 for Solana)
  */
-const SECP256K1_CHAINS = ['BTC', 'BCH', 'ETH', 'POL', 'BNB', 'USDC_ETH', 'USDC_POL', 'USDT_ETH', 'USDT_POL'];
+const SECP256K1_CHAINS = ['BTC', 'BCH', 'ETH', 'POL', 'BNB', 'USDC_ETH', 'USDC_POL', 'USDC_BASE', 'USDT_ETH', 'USDT_POL'];
 
 // ============================================================
 // Address derivation helpers
@@ -305,6 +307,7 @@ export function deriveAddress(seed, chain, index = 0) {
     case 'BNB':
     case 'USDC_ETH':
     case 'USDC_POL':
+    case 'USDC_BASE':
     case 'USDT_ETH':
     case 'USDT_POL':
       return deriveETHAddress(publicKey);
@@ -419,6 +422,160 @@ function signMessage(message, privateKey) {
   return bytesToHex(signature.toCompactRawBytes());
 }
 
+// ================================================================
+// Arbitrary tx / message signing
+// ----------------------------------------------------------------
+// These primitives let callers (like b1dz.com's DEX engine) sign
+// EVM contract calls and Solana transactions that CoinPay's built-in
+// `send` flow doesn't cover (e.g., Uniswap swaps, Jupiter routes).
+//
+// The API intentionally stops at the cryptographic primitive:
+//   - EVM:    caller builds the unsigned tx with their own library
+//             (viem / ethers / ethers-v5), hashes it per EIP-1559 or
+//             EIP-155, hands us the 32-byte digest, gets back a
+//             recoverable signature
+//   - Solana: caller builds the unsigned Transaction / VersionedMessage,
+//             hands us the raw message bytes, gets back an ed25519
+//             signature they can attach to the tx
+//
+// This keeps the crypto surface minimal and correct. We don't try to
+// re-implement RLP, EIP-712, or Solana's transaction encoder inside
+// CoinPay — those live in the caller's toolchain.
+// ================================================================
+
+/** Chains that sign via secp256k1 (32-byte digest → recoverable sig). */
+function isSecp256k1Chain(chain) {
+  return SECP256K1_CHAINS.includes(chain);
+}
+
+/** Chains that sign via ed25519 (arbitrary message bytes → 64-byte sig). */
+function isEd25519Chain(chain) {
+  return chain === 'SOL' || chain === 'USDC_SOL' || chain === 'USDT_SOL';
+}
+
+function normalizeHexInput(hex, label = 'hex') {
+  if (typeof hex !== 'string') throw new Error(`${label} must be a string`);
+  const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (stripped.length === 0) throw new Error(`${label} is empty`);
+  if (stripped.length % 2 !== 0) throw new Error(`${label} has odd length`);
+  if (!/^[0-9a-fA-F]+$/.test(stripped)) throw new Error(`${label} contains non-hex chars`);
+  return hexToBytes(stripped);
+}
+
+/**
+ * Sign a 32-byte digest with a secp256k1 chain's derived key.
+ * Returns a 65-byte recoverable signature formatted as `r(32) || s(32) || v(1)`
+ * where v is the low recovery id (0 or 1). This is the layout every
+ * EVM client (viem, ethers v6) expects for post-typed-transaction
+ * (EIP-1559 / EIP-2930) signatures.
+ *
+ * For legacy / EIP-155 transactions the caller is responsible for
+ * converting v to `chainId * 2 + 35 + recId` after receiving the sig.
+ * For EIP-191 (personal_sign) the caller adds 27.
+ *
+ * @param {Uint8Array} seed - Master seed
+ * @param {string} chain - BIP44 chain code (ETH, POL, BNB, ...)
+ * @param {Uint8Array} digest - Exactly 32 bytes
+ * @returns {string} `0x`-prefixed 65-byte hex signature
+ */
+export function signDigestSecp256k1(seed, chain, digest) {
+  if (!isSecp256k1Chain(chain)) {
+    throw new Error(`chain ${chain} does not use secp256k1`);
+  }
+  if (!(digest instanceof Uint8Array) || digest.length !== 32) {
+    throw new Error('digest must be a 32-byte Uint8Array');
+  }
+  const { privateKey } = deriveKeyPair(seed, chain, 0);
+
+  // noble-curves has two incompatible signing APIs across major versions:
+  //   v1.x: sign(hash, key) → Signature object with .r, .s, .recovery
+  //   v2.x: sign(hash, key, { format: 'recovered' }) → 65-byte Uint8Array
+  //         [recovery, r(32), s(32)]
+  // Detect at runtime so this works with whichever version is pinned.
+  // Requesting 'recovered' on v1 is harmless — v1 ignores the option
+  // and still returns a Signature object.
+  const raw = secp256k1.sign(digest, privateKey, { format: 'recovered' });
+  let r, s, recovery;
+  if (raw instanceof Uint8Array && raw.length === 65) {
+    recovery = raw[0] & 0x01;
+    r = raw.subarray(1, 33);
+    s = raw.subarray(33, 65);
+  } else if (raw && typeof raw === 'object' && 'r' in raw && 's' in raw) {
+    if (typeof raw.recovery !== 'number') {
+      throw new Error('signature missing recovery id');
+    }
+    recovery = raw.recovery & 0x01;
+    r = bigIntToBytes32(raw.r);
+    s = bigIntToBytes32(raw.s);
+  } else {
+    throw new Error(`unexpected signature shape (type=${raw?.constructor?.name})`);
+  }
+
+  const evmSig = new Uint8Array(65);
+  evmSig.set(r, 0);
+  evmSig.set(s, 32);
+  evmSig[64] = recovery;
+  return '0x' + bytesToHex(evmSig);
+}
+
+/** Big-endian 32-byte encoding of a bigint. */
+function bigIntToBytes32(n) {
+  const out = new Uint8Array(32);
+  let x = BigInt(n);
+  for (let i = 31; i >= 0; i--) {
+    out[i] = Number(x & 0xffn);
+    x >>= 8n;
+  }
+  return out;
+}
+
+/**
+ * Sign an EIP-191 "personal_sign" message. Wraps the message with the
+ * `\x19Ethereum Signed Message:\n<length>` prefix, keccak256-hashes,
+ * then signs the digest. Returns a 65-byte sig with v bumped to 27/28
+ * per EIP-191 convention (compatible with Solidity's ecrecover).
+ *
+ * @param {Uint8Array} seed
+ * @param {string} chain
+ * @param {string|Uint8Array} message - UTF-8 string or raw bytes
+ * @returns {string}
+ */
+export function signEip191Message(seed, chain, message) {
+  if (!isSecp256k1Chain(chain)) {
+    throw new Error(`chain ${chain} does not use secp256k1`);
+  }
+  const bytes = typeof message === 'string'
+    ? new TextEncoder().encode(message)
+    : message;
+  const prefix = new TextEncoder().encode(`\x19Ethereum Signed Message:\n${bytes.length}`);
+  const payload = new Uint8Array(prefix.length + bytes.length);
+  payload.set(prefix, 0);
+  payload.set(bytes, prefix.length);
+  const digest = keccak_256(payload);
+  const sig = hexToBytes(signDigestSecp256k1(seed, chain, digest).slice(2));
+  sig[64] = sig[64] + 27; // EIP-191 uses 27/28 for v
+  return '0x' + bytesToHex(sig);
+}
+
+/**
+ * Sign arbitrary Solana transaction message bytes with the derived
+ * ed25519 key. Returns a 64-byte signature that the caller attaches
+ * to the `VersionedTransaction.signatures` array.
+ *
+ * @param {Uint8Array} seed
+ * @param {Uint8Array} messageBytes - The serialized Solana tx message
+ * @param {number} [index=0] - Derivation index
+ * @returns {string} 64-byte hex signature
+ */
+export function signSolanaMessage(seed, messageBytes, index = 0) {
+  if (!(messageBytes instanceof Uint8Array)) {
+    throw new Error('messageBytes must be a Uint8Array');
+  }
+  const { privateKey } = deriveSOLAddress(seed, index);
+  const signature = ed25519.sign(messageBytes, privateKey);
+  return '0x' + bytesToHex(signature);
+}
+
 /**
  * Derive address placeholder - actual address derivation happens on client
  * This returns the public key that the server can use to verify ownership
@@ -864,6 +1021,77 @@ export class WalletClient {
     return broadcastResult;
   }
   
+  // ==========================================================
+  // Arbitrary-transaction signing (PR: arbitrary-tx-signing)
+  //
+  // These methods expose raw cryptographic signing so callers can
+  // use CoinPay as a wallet provider for flows CoinPay itself
+  // doesn't implement (Uniswap swaps, Jupiter routes, EIP-712
+  // typed data, etc.). The caller builds the unsigned tx with
+  // their own library (viem / ethers / @solana/web3.js), passes
+  // the digest or message bytes to CoinPay, and receives the
+  // signature back. CoinPay never learns the tx semantics — it
+  // just produces cryptographic output.
+  //
+  // SECURITY: these methods are intentionally unprivileged from
+  // CoinPay's perspective. If you expose them to untrusted
+  // callers you're handing over signing authority for the wallet.
+  // The CLI `wallet sign-digest` / `sign-message` commands
+  // require the GPG-encrypted wallet to be unlocked, same as
+  // `wallet send`.
+  // ==========================================================
+
+  /**
+   * Sign a 32-byte digest with the wallet's secp256k1 key for the
+   * given EVM chain. Returns a 65-byte recoverable signature laid
+   * out as `r(32) || s(32) || v(1)`, where v is the raw recovery
+   * bit (0 or 1). Suitable for EIP-1559 / EIP-2930 typed txs.
+   *
+   * For legacy EIP-155 signatures the caller converts v to
+   * `chainId * 2 + 35 + v`. For EIP-191 personal_sign, use
+   * `signMessage()` below instead.
+   *
+   * @param {{chain: string, digest: string|Uint8Array}} params
+   * @returns {string} 0x-prefixed 65-byte signature hex
+   */
+  signDigest({ chain, digest }) {
+    if (!this.#seed) throw new Error('Wallet not initialized');
+    const digestBytes = typeof digest === 'string'
+      ? normalizeHexInput(digest, 'digest')
+      : digest;
+    return signDigestSecp256k1(this.#seed, chain, digestBytes);
+  }
+
+  /**
+   * Sign an EIP-191 "personal_sign" message with the wallet's
+   * secp256k1 key. Handles the `\x19Ethereum Signed Message:\n`
+   * prefix internally.
+   *
+   * @param {{chain: string, message: string|Uint8Array}} params
+   * @returns {string} 0x-prefixed 65-byte signature hex
+   */
+  signMessage({ chain, message }) {
+    if (!this.#seed) throw new Error('Wallet not initialized');
+    return signEip191Message(this.#seed, chain, message);
+  }
+
+  /**
+   * Sign raw Solana transaction message bytes with the derived
+   * ed25519 key. Returns a 64-byte signature the caller attaches
+   * to their `VersionedTransaction.signatures` array.
+   *
+   * @param {{message: string|Uint8Array, index?: number}} params
+   *   `message` is either hex-encoded bytes or a raw Uint8Array.
+   * @returns {string} 0x-prefixed 64-byte signature hex
+   */
+  signSolanaMessage({ message, index = 0 }) {
+    if (!this.#seed) throw new Error('Wallet not initialized');
+    const bytes = typeof message === 'string'
+      ? normalizeHexInput(message, 'message')
+      : message;
+    return signSolanaMessage(this.#seed, bytes, index);
+  }
+
   /**
    * Get transaction history
    * @param {Object} [options] - Query options

package/src/webhooks.js

@@ -1,5 +1,19 @@
 /**
  * Webhook utilities for CoinPay SDK
+ *
+ * Contract:
+ *   - Each business has ONE webhook URL + ONE webhook secret. Both crypto
+ *     and card payment events route to the same endpoint, signed with the
+ *     same secret. Distinguish rails via data.metadata.payment_rail
+ *     ("crypto" or "card").
+ *   - Header: X-CoinPay-Signature: t=<unix_seconds>,v1=<hex_hmac>
+ *   - HMAC body: `${timestamp}.${rawBody}`
+ *   - Algorithm: HMAC-SHA256
+ *   - Tolerance: 300 seconds
+ *
+ * The server-side signer (src/lib/webhooks/service.ts) and the d0rz
+ * verifier (lib/coinpay-client.ts) are kept in lockstep with this file
+ * by src/lib/webhooks/contract.test.ts in the main repo. Don't drift.
  */
 
 import { createHmac, timingSafeEqual } from 'crypto';
@@ -44,7 +58,12 @@ export function verifyWebhookSignature({
     const signatureParts = {};
     
     for (const part of parts) {
-      const [key, value] = part.split('=');
+      // Split on the FIRST '=' only. Splitting on every one truncates any value
+      // that legitimately contains '=' (base64 padding, for instance).
+      const separator = part.indexOf('=');
+      if (separator === -1) continue;
+      const key = part.slice(0, separator).trim();
+      const value = part.slice(separator + 1).trim();
       signatureParts[key] = value;
     }
 
@@ -55,8 +74,23 @@ export function verifyWebhookSignature({
       return false;
     }
 
-    // Check timestamp tolerance
-    const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
+    // Check timestamp tolerance.
+    //
+    // parseInt('abc', 10) is NaN, and every comparison against NaN is false —
+    // so `Math.abs(NaN) > tolerance` was false and the freshness check silently
+    // PASSED for any non-numeric timestamp. A security check that no-ops on
+    // malformed input is worse than no check, because it reads as one. Parse
+    // strictly and reject anything that is not a plain integer.
+    if (!/^\d+$/.test(String(timestamp))) {
+      return false;
+    }
+
+    const signedAt = Number(timestamp);
+    if (!Number.isSafeInteger(signedAt) || signedAt <= 0) {
+      return false;
+    }
+
+    const timestampAge = Math.floor(Date.now() / 1000) - signedAt;
     if (Math.abs(timestampAge) > tolerance) {
       return false;
     }

package/src/x402-browser.js

@@ -0,0 +1,318 @@
+/**
+ * Browser-side x402 payer.
+ *
+ * Turns a 402 response into a paid retry, using whatever wallet the visitor
+ * actually has. CoinPay Wallet is preferred when present; otherwise any
+ * injected EIP-1193 wallet — MetaMask, Phantom's EVM provider, Rabby, Coinbase
+ * Wallet — can pay, because what gets signed is the standard EIP-3009
+ * authorization rather than anything CoinPay-specific.
+ *
+ * That interoperability is the whole point of signing the real structure. A
+ * bespoke payload would still be signable by MetaMask, but the resulting
+ * signature would authorise no transfer on-chain and only CoinPayPortal could
+ * interpret it — which is not a wallet integration, it is a lock-in.
+ *
+ * Usage:
+ *   const res = await fetchWithX402('https://api.example.com/premium');
+ *
+ * @module x402-browser
+ */
+
+import {
+  buildAuthorization,
+  buildEip3009Domain,
+  buildExactEvmPayment,
+  encodePaymentHeader,
+  evmChainId,
+  requiredAmount,
+  selectAcceptEntry,
+  toCaip2,
+  TRANSFER_WITH_AUTHORIZATION_TYPES,
+} from './x402-v2.js';
+
+/** How long a discovery sweep waits for EIP-6963 wallets to announce. */
+const EIP6963_ANNOUNCE_MS = 100;
+
+/**
+ * Enumerate injected EVM wallets via EIP-6963.
+ *
+ * Before EIP-6963 every wallet raced to own `window.ethereum`, so with two
+ * installed you got whichever won — the user could not choose, and a site
+ * could not tell which it had. EIP-6963 has each wallet announce itself with
+ * its own provider object instead.
+ *
+ * `window.ethereum` is still included as a last resort, for wallets that have
+ * not adopted the standard.
+ */
+export async function discoverEvmWallets({ timeoutMs = EIP6963_ANNOUNCE_MS } = {}) {
+  const found = new Map();
+
+  if (typeof window === 'undefined') return [];
+
+  const onAnnounce = (event) => {
+    const detail = event.detail;
+    if (!detail?.info?.uuid || !detail.provider) return;
+    found.set(detail.info.uuid, { info: detail.info, provider: detail.provider });
+  };
+
+  window.addEventListener('eip6963:announceProvider', onAnnounce);
+  window.dispatchEvent(new Event('eip6963:requestProvider'));
+  await new Promise((resolve) => setTimeout(resolve, timeoutMs));
+  window.removeEventListener('eip6963:announceProvider', onAnnounce);
+
+  const wallets = [...found.values()].map(({ info, provider }) => ({
+    id: info.rdns || info.uuid,
+    name: info.name,
+    icon: info.icon,
+    provider,
+  }));
+
+  // Legacy fallback: only if nothing announced, so a 6963-aware wallet is not
+  // listed twice under two different identities.
+  if (wallets.length === 0 && window.ethereum) {
+    wallets.push({ id: 'injected', name: detectLegacyName(window.ethereum), provider: window.ethereum });
+  }
+
+  return wallets;
+}
+
+function detectLegacyName(provider) {
+  if (provider.isMetaMask) return 'MetaMask';
+  if (provider.isPhantom) return 'Phantom';
+  if (provider.isCoinbaseWallet) return 'Coinbase Wallet';
+  if (provider.isRabby) return 'Rabby';
+  return 'Injected Wallet';
+}
+
+/**
+ * True when a CoinPay Wallet that can actually pay an x402 invoice is present.
+ *
+ * Checks for the method, not merely for the wallet. `payX402` shipped after
+ * the provider itself, so an installed-but-older extension has `isCoinPay`
+ * and no way to pay — treating that as "CoinPay is here" would hand the
+ * payment to a wallet that cannot take it and throw a TypeError, when the
+ * visitor may well have MetaMask sitting right there.
+ */
+export function hasCoinPayWallet() {
+  return (
+    typeof window !== 'undefined' &&
+    window.coinpay?.isCoinPay === true &&
+    typeof window.coinpay.payX402 === 'function'
+  );
+}
+
+/** True when CoinPay Wallet is installed but predates x402 support. */
+export function hasOutdatedCoinPayWallet() {
+  return (
+    typeof window !== 'undefined' &&
+    window.coinpay?.isCoinPay === true &&
+    typeof window.coinpay.payX402 !== 'function'
+  );
+}
+
+/**
+ * Choose a wallet to pay with.
+ *
+ * CoinPay Wallet first when installed — it is the only one that can pay on
+ * every rail CoinPayPortal accepts, including Bitcoin and Lightning, which no
+ * EVM wallet can touch. Otherwise the first injected EVM wallet, or one named
+ * explicitly by `preferWalletId`.
+ */
+export async function selectWallet({ preferWalletId, allowCoinPay = true } = {}) {
+  if (allowCoinPay && hasCoinPayWallet() && !preferWalletId) {
+    return { kind: 'coinpay', id: 'coinpay', name: 'CoinPay Wallet', provider: window.coinpay };
+  }
+
+  const evm = await discoverEvmWallets();
+  if (evm.length === 0) {
+    if (allowCoinPay && hasCoinPayWallet()) {
+      return { kind: 'coinpay', id: 'coinpay', name: 'CoinPay Wallet', provider: window.coinpay };
+    }
+    return null;
+  }
+
+  const chosen = preferWalletId ? evm.find((w) => w.id === preferWalletId) : evm[0];
+  if (!chosen) return null;
+  return { kind: 'evm', ...chosen };
+}
+
+/** Ask an EIP-1193 provider for the active account, prompting if needed. */
+async function requireEvmAccount(provider) {
+  const accounts = await provider.request({ method: 'eth_requestAccounts' });
+  if (!Array.isArray(accounts) || accounts.length === 0) {
+    throw new Error('Wallet returned no accounts');
+  }
+  return accounts[0];
+}
+
+/**
+ * Put an EIP-1193 wallet on the chain an `accepts` entry requires.
+ *
+ * Signing an EIP-712 payload whose domain names chain X while the wallet is on
+ * chain Y produces a signature that verifies against neither — wallets bind
+ * the domain's chainId to their active chain. So the switch is mandatory, not
+ * a nicety.
+ */
+async function ensureEvmChain(provider, network) {
+  const chainId = evmChainId(network);
+  if (chainId === null) throw new Error(`Not an EVM network: ${network}`);
+  const hexChainId = `0x${chainId.toString(16)}`;
+
+  const current = await provider.request({ method: 'eth_chainId' });
+  if (typeof current === 'string' && current.toLowerCase() === hexChainId) return;
+
+  try {
+    await provider.request({
+      method: 'wallet_switchEthereumChain',
+      params: [{ chainId: hexChainId }],
+    });
+  } catch (err) {
+    // 4902 = chain unknown to the wallet. Adding it needs RPC details we do
+    // not have here, so surface it rather than guessing an RPC URL.
+    if (err?.code === 4902) {
+      throw new Error(
+        `Your wallet does not have chain ${chainId} configured. Add it, then try again.`,
+      );
+    }
+    throw err;
+  }
+}
+
+/**
+ * Sign an EIP-3009 authorization with an EIP-1193 wallet.
+ *
+ * @returns {{signature: string, authorization: object, from: string}}
+ */
+export async function signExactEvm(provider, entry, { from } = {}) {
+  const payer = from ?? (await requireEvmAccount(provider));
+  await ensureEvmChain(provider, entry.network);
+
+  const domain = buildEip3009Domain({
+    network: entry.network,
+    asset: entry.asset,
+    name: entry.extra?.name,
+    version: entry.extra?.version,
+  });
+
+  const authorization = buildAuthorization({
+    from: payer,
+    to: entry.payTo,
+    value: requiredAmount(entry),
+    validForSeconds: entry.maxTimeoutSeconds ?? 600,
+  });
+
+  const typedData = {
+    types: {
+      EIP712Domain: [
+        { name: 'name', type: 'string' },
+        { name: 'version', type: 'string' },
+        { name: 'chainId', type: 'uint256' },
+        { name: 'verifyingContract', type: 'address' },
+      ],
+      ...TRANSFER_WITH_AUTHORIZATION_TYPES,
+    },
+    primaryType: 'TransferWithAuthorization',
+    domain,
+    message: authorization,
+  };
+
+  const signature = await provider.request({
+    method: 'eth_signTypedData_v4',
+    params: [payer, JSON.stringify(typedData)],
+  });
+
+  return { signature, authorization, from: payer };
+}
+
+/**
+ * Produce the `X-PAYMENT` header value for a 402 body.
+ *
+ * @param {object} paymentRequired  the parsed 402 JSON (`{x402Version, accepts}`)
+ * @param {object} [options]
+ * @param {string} [options.preferWalletId]
+ * @param {string[]} [options.capabilities] override which networks to consider
+ */
+export async function createPaymentHeader(paymentRequired, options = {}) {
+  const accepts = paymentRequired?.accepts;
+  if (!Array.isArray(accepts) || accepts.length === 0) {
+    throw new Error('402 response carried no `accepts` options');
+  }
+
+  const wallet = await selectWallet(options);
+  if (!wallet) {
+    if (hasOutdatedCoinPayWallet()) {
+      throw new Error(
+        'Your CoinPay Wallet is too old to pay x402 invoices and no other wallet is ' +
+          'available. Update it, or install MetaMask.',
+      );
+    }
+    throw new Error(
+      'No wallet available to pay. Install CoinPay Wallet, MetaMask, or another EVM wallet.',
+    );
+  }
+
+  if (wallet.kind === 'coinpay') {
+    // The extension picks among the offered options itself — it knows which
+    // chains the user actually holds funds on, which this page does not.
+    const header = await wallet.provider.payX402(paymentRequired);
+    return { header, wallet };
+  }
+
+  // An injected EVM wallet can only pay the EVM entries.
+  const evmCapable = accepts
+    .map((entry) => entry.network)
+    .filter((network) => evmChainId(network) !== null);
+
+  const entry = selectAcceptEntry(accepts, options.capabilities ?? evmCapable);
+  if (!entry) {
+    throw new Error(
+      `${wallet.name} cannot pay any of the offered options ` +
+        `(${accepts.map((a) => toCaip2(a.network)).join(', ')}). ` +
+        'CoinPay Wallet supports Bitcoin, Lightning and card rails as well.',
+    );
+  }
+
+  const { signature, authorization } = await signExactEvm(wallet.provider, entry);
+  const payment = buildExactEvmPayment({
+    network: entry.network,
+    signature,
+    authorization,
+    scheme: entry.scheme ?? 'exact',
+  });
+
+  return { header: encodePaymentHeader(payment), wallet, entry };
+}
+
+/**
+ * `fetch` that pays once if the resource asks for payment.
+ *
+ * Retries exactly one time. A second 402 after paying means the payment was
+ * rejected rather than missing, and retrying again would sign a fresh
+ * authorization for a resource that just refused one — at the user's expense.
+ *
+ * @param {string|URL|Request} input
+ * @param {RequestInit} [init]
+ * @param {object} [options] forwarded to {@link createPaymentHeader}
+ */
+export async function fetchWithX402(input, init = {}, options = {}) {
+  const first = await fetch(input, init);
+  if (first.status !== 402) return first;
+
+  let paymentRequired;
+  try {
+    paymentRequired = await first.clone().json();
+  } catch {
+    throw new Error('Resource returned 402 but its body was not valid x402 JSON');
+  }
+
+  const { header } = await createPaymentHeader(paymentRequired, options);
+
+  const headers = new Headers(init.headers ?? {});
+  headers.set('X-PAYMENT', header);
+
+  const paid = await fetch(input, { ...init, headers });
+  if (paid.status === 402) {
+    throw new Error('Payment was rejected by the resource; not retrying to avoid double-paying');
+  }
+  return paid;
+}