@piprail/sdk 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -4,7 +4,36 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
-## [2.2.0] — 2026-06-16 — broader x402 ecosystem interoperability
+## [2.3.0] — 2026-06-17 — `exact: true` zero-config gasless gate
+
+Additive and backward-compatible — defaults and the zero-config 402 stay byte-identical. A new
+opt-in shorthand makes the gasless `exact` rail one line, and it degrades gracefully instead of
+breaking when no facilitator covers a chain.
+
+### Added
+
+- **`exact: true` on `requirePayment` / `createPaymentGate` — zero-config gasless.** Equivalent to
+  `exact: { settle: 'keyless' }`: the gate auto-advertises a gasless `exact` rail and, at settle
+  time, picks the first known **keyless** (no-API-key) facilitator for the chain from the built-in
+  `KNOWN_FACILITATORS` map, so buyers pay no gas and the merchant runs no relayer. One line, no
+  facilitator URL, no relayer key.
+- **`ExactRailOption.settle` accepts `'keyless'`** alongside `'self'` and `{ facilitator }`, and
+  `exact` accepts `boolean | ExactRailOption`. The boolean shorthand normalizes to
+  `{ settle: 'keyless' }`.
+
+### Changed
+
+- **Graceful degrade for the soft path.** When `exact: true` (or `settle: 'keyless'`) is set but no
+  keyless facilitator covers the offered chain, the gate **does not throw** — it logs a clear,
+  production-visible warning and serves the `onchain-proof` floor (buyers pay their own gas), so a
+  resource never goes dark over a coverage gap. An **explicit** `settle: 'self'` or
+  `settle: { facilitator }` still throws on a coverage gap (you asked for a specific rail; a silent
+  fallback would hide a misconfiguration). Suppress the soft-path hints with `PIPRAIL_NO_HINTS=1`.
+- **A failed gasless settlement returns a clear fallback hint.** When a facilitator settle fails at
+  pay time, the 502 body now carries a `fallback` field telling the caller the resource also accepts
+  `onchain-proof` — retry by paying that rail yourself.
+
+
 
 Both changes are additive and backward-compatible — defaults and the zero-config 402 stay
 byte-identical; only previously-skipped cases become newly handled.
@@ -1220,6 +1249,7 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[2.3.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.2.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.1.1]: https://www.npmjs.com/package/@piprail/sdk
 [2.1.0]: https://www.npmjs.com/package/@piprail/sdk

package/dist/index.cjs

@@ -4891,6 +4891,63 @@ async function settleViaFacilitator(input) {
   return { ok: true, receipt };
 }
 
+// src/facilitators.ts
+var KNOWN_FACILITATORS = {
+  // Base (eip155:8453). Every entry is keyless and LIVE-settled by us (a real EIP-3009
+  // exact payment, buyer paid zero ETH) — not just a /supported read — on the dated day.
+  "eip155:8453": [
+    {
+      url: "https://facilitator.payai.network",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["eip3009"],
+      note: "PayAI \u2014 keyless, sponsors gas (Base USDC EIP-3009). Verified 2026-06-14 (/supported + live demo)."
+    },
+    {
+      url: "https://facilitator.xpay.sh",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["eip3009"],
+      note: "xpay \u2014 keyless, zero-fee, sponsors gas. LIVE-settled on Base 2026-06-15 (tx 0x2273d5\u2026)."
+    }
+  ],
+  // Solana (mainnet-beta). Keyless fee-payer sponsors for the SVM exact rail, each LIVE-settled
+  // by us (a real SPL TransferChecked, buyer paid zero SOL) on the dated day — beyond a /supported
+  // read. Daydreams + Questflow are intentionally ABSENT: their /supported is public but /verify
+  // returns 401 (an API key is required), so they are not keyless for settlement.
+  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": [
+    {
+      url: "https://facilitator.payai.network",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["svm"],
+      note: "PayAI \u2014 keyless fee-payer sponsor (Solana SPL SVM). LIVE-settled 2026-06-14 (tx 4dL8jRKH\u2026)."
+    },
+    {
+      url: "https://pay.openfacilitator.io",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["svm"],
+      note: "OpenFacilitator \u2014 keyless (no signup), fee-payer sponsor. LIVE-settled on Solana 2026-06-15 (tx 5BabDtX\u2026)."
+    },
+    {
+      url: "https://facilitator.corbits.dev",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["svm"],
+      note: "Corbits \u2014 keyless, Solana-first fee-payer sponsor. LIVE-settled on Solana 2026-06-15 (tx BCreYer\u2026)."
+    }
+  ]
+};
+function knownFacilitatorsFor(network) {
+  return _nullishCoalesce(KNOWN_FACILITATORS[network], () => ( []));
+}
+function firstKeylessFacilitator(network, method) {
+  return knownFacilitatorsFor(network).find(
+    (f) => f.keyless && f.schemes.includes("exact") && (method === void 0 || f.settles.includes(method))
+  );
+}
+
 // src/server.ts
 function toInvalidBody(result) {
   return { x402Version: 2, status: "invalid", error: result.error, detail: result.detail };
@@ -4911,10 +4968,16 @@ function normaliseAccepts(options) {
     "requirePayment: provide either { chain, token, amount } or a non-empty `accept: [{ chain, token, amount }, \u2026]`."
   );
 }
+function normaliseExactOption(exact) {
+  if (!exact) return void 0;
+  if (exact === true) return { settle: "keyless" };
+  return exact;
+}
 function createPaymentGate(options) {
   const minConfirmations = _nullishCoalesce(options.minConfirmations, () => ( 1));
   const maxTimeoutSeconds = _nullishCoalesce(options.maxTimeoutSeconds, () => ( 600));
   const genNonce = _nullishCoalesce(options.generateNonce, () => ( (() => globalThis.crypto.randomUUID())));
+  const exactOption = normaliseExactOption(options.exact);
   let resolved;
   function ready() {
     if (resolved) return resolved;
@@ -4934,7 +4997,7 @@ function createPaymentGate(options) {
           const { asset, decimals, symbol } = net.resolveToken(a.token);
           const amountBase = _chunkJG6KRAW6cjs.parseUnits.call(void 0, a.amount, decimals);
           const spec = { net, asset, decimals, symbol, amountBase, amountFormatted: a.amount, payTo };
-          if (options.exact) {
+          if (exactOption) {
             const outcome = await resolveExactRail(net, asset);
             if (outcome.rail) spec.exact = outcome.rail;
             else if (outcome.skipReason) exactSkips.push(outcome.skipReason);
@@ -4942,10 +5005,17 @@ function createPaymentGate(options) {
           return spec;
         })
       );
-      if (options.exact && !specs.some((s) => s.exact)) {
-        throw new Error(
-          "requirePayment: `exact` was requested but none of the offered rails support it. " + (exactSkips.length > 0 ? exactSkips.join(" ") : "The standard `exact` rail is EVM ERC-20 (EIP-3009 \u2014 USDC / EURC \u2014 or Permit2, e.g. Binance-Peg USDC on BNB) or a Solana SPL token (SVM) \u2014 NOT native coins, NOT families without a standard `exact` scheme. Offer an EVM ERC-20 / Solana SPL token, or drop `exact`.")
-        );
+      if (exactOption && !specs.some((s) => s.exact)) {
+        const why = exactSkips.length > 0 ? exactSkips.join(" ") : "The standard `exact` rail is EVM ERC-20 (EIP-3009 \u2014 USDC / EURC \u2014 or Permit2, e.g. Binance-Peg USDC on BNB) or a Solana SPL token (SVM) \u2014 NOT native coins, NOT families without a standard `exact` scheme.";
+        if (exactOption.settle === "keyless") {
+          if (typeof process === "undefined" || !_optionalChain([process, 'optionalAccess', _81 => _81.env, 'optionalAccess', _82 => _82.PIPRAIL_NO_HINTS])) {
+            console.warn(
+              `[piprail] exact: true \u2014 no offered chain has a gasless \`exact\` rail available, so this gate serves ONCHAIN-PROOF ONLY (buyers PAY GAS \u2014 the fallback when no facilitator can sponsor). ${why} To be gasless: pin \`exact: { settle: { facilitator } }\` or self-settle \`exact: { settle: 'self', relayer }\`. (Suppress with PIPRAIL_NO_HINTS=1.)`
+            );
+          }
+        } else {
+          throw new Error("requirePayment: `exact` was requested but none of the offered rails support it. " + why);
+        }
       }
       return specs;
     })();
@@ -4956,9 +5026,23 @@ function createPaymentGate(options) {
     return p;
   }
   async function resolveExactRail(net, asset) {
-    const cfg = options.exact;
-    const settle = cfg.settle;
+    const cfg = exactOption;
     if (!net.resolveExactRail) return {};
+    let settle = cfg.settle;
+    if (settle === "keyless") {
+      const picked = firstKeylessFacilitator(net.network);
+      if (!picked) {
+        return {
+          skipReason: `${net.network}: \`exact: true\` found no known keyless facilitator for this network. Pass \`exact: { settle: { facilitator } }\`, \`exact: { settle: 'self', relayer }\`, or see the coverage map (KNOWN_FACILITATORS / docs.piprail.com).`
+        };
+      }
+      if (typeof process === "undefined" || _optionalChain([process, 'optionalAccess', _83 => _83.env, 'optionalAccess', _84 => _84.NODE_ENV]) !== "production" && !_optionalChain([process, 'optionalAccess', _85 => _85.env, 'optionalAccess', _86 => _86.PIPRAIL_NO_HINTS])) {
+        console.warn(
+          `[piprail] exact: keyless rail on ${net.network} auto-settles via ${picked.url} (zero-config; pin \`exact.settle.facilitator\` in production).`
+        );
+      }
+      settle = { facilitator: picked.url };
+    }
     let relayer;
     let feePayer;
     if (settle === "self") {
@@ -5086,7 +5170,7 @@ function createPaymentGate(options) {
       instruction: describeChallenge({ x402Version: 2, resource: { url: resourceUrl }, accepts }),
       ...endpointInfo ? { endpoint: endpointInfo } : {}
     });
-    const rejectionExt = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _81 => _81.extensions]), () => ( {}));
+    const rejectionExt = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _87 => _87.extensions]), () => ( {}));
     const rejectionPiprail = _nullishCoalesce(rejectionExt.piprail, () => ( {}));
     const bodyPiprail = { ..._nullishCoalesce(selfDescribe, () => ( {})), ...rejectionPiprail };
     const bodyExtensions = {
@@ -5106,7 +5190,7 @@ function createPaymentGate(options) {
         ...options.mimeType ? { mimeType: options.mimeType } : {}
       },
       accepts,
-      ..._optionalChain([opts, 'optionalAccess', _82 => _82.error]) ? { error: opts.error } : {},
+      ..._optionalChain([opts, 'optionalAccess', _88 => _88.error]) ? { error: opts.error } : {},
       ...Object.keys(bodyExtensions).length > 0 ? { extensions: bodyExtensions } : {}
     };
     const headerChallenge = {
@@ -5330,7 +5414,12 @@ function requirePayment(options) {
     } catch (err) {
       if (err instanceof _chunkJG6KRAW6cjs.SettlementError) {
         res.status(502);
-        res.json({ x402Version: 2, error: "settlement_failed", detail: err.message });
+        res.json({
+          x402Version: 2,
+          error: "settlement_failed",
+          detail: err.message,
+          fallback: "The gasless `exact` settlement failed. This resource also accepts the `onchain-proof` scheme \u2014 retry by paying that rail yourself (you broadcast the transfer and pay the gas). It is the fallback when no facilitator can sponsor the gas."
+        });
         return;
       }
       next(err);
@@ -5359,63 +5448,6 @@ function normaliseHeader(value) {
   return value;
 }
 
-// src/facilitators.ts
-var KNOWN_FACILITATORS = {
-  // Base (eip155:8453). Every entry is keyless and LIVE-settled by us (a real EIP-3009
-  // exact payment, buyer paid zero ETH) — not just a /supported read — on the dated day.
-  "eip155:8453": [
-    {
-      url: "https://facilitator.payai.network",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["eip3009"],
-      note: "PayAI \u2014 keyless, sponsors gas (Base USDC EIP-3009). Verified 2026-06-14 (/supported + live demo)."
-    },
-    {
-      url: "https://facilitator.xpay.sh",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["eip3009"],
-      note: "xpay \u2014 keyless, zero-fee, sponsors gas. LIVE-settled on Base 2026-06-15 (tx 0x2273d5\u2026)."
-    }
-  ],
-  // Solana (mainnet-beta). Keyless fee-payer sponsors for the SVM exact rail, each LIVE-settled
-  // by us (a real SPL TransferChecked, buyer paid zero SOL) on the dated day — beyond a /supported
-  // read. Daydreams + Questflow are intentionally ABSENT: their /supported is public but /verify
-  // returns 401 (an API key is required), so they are not keyless for settlement.
-  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": [
-    {
-      url: "https://facilitator.payai.network",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["svm"],
-      note: "PayAI \u2014 keyless fee-payer sponsor (Solana SPL SVM). LIVE-settled 2026-06-14 (tx 4dL8jRKH\u2026)."
-    },
-    {
-      url: "https://pay.openfacilitator.io",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["svm"],
-      note: "OpenFacilitator \u2014 keyless (no signup), fee-payer sponsor. LIVE-settled on Solana 2026-06-15 (tx 5BabDtX\u2026)."
-    },
-    {
-      url: "https://facilitator.corbits.dev",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["svm"],
-      note: "Corbits \u2014 keyless, Solana-first fee-payer sponsor. LIVE-settled on Solana 2026-06-15 (tx BCreYer\u2026)."
-    }
-  ]
-};
-function knownFacilitatorsFor(network) {
-  return _nullishCoalesce(KNOWN_FACILITATORS[network], () => ( []));
-}
-function firstKeylessFacilitator(network, method) {
-  return knownFacilitatorsFor(network).find(
-    (f) => f.keyless && f.schemes.includes("exact") && (method === void 0 || f.settles.includes(method))
-  );
-}
-
 // src/receipts.ts
 var DEFAULT_RETRIES = 5;
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -5428,7 +5460,7 @@ function isRetryableStatus(status) {
 }
 var sleep = (ms) => ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
 async function signBody(secret, body) {
-  const subtle = _optionalChain([globalThis, 'access', _83 => _83.crypto, 'optionalAccess', _84 => _84.subtle]);
+  const subtle = _optionalChain([globalThis, 'access', _89 => _89.crypto, 'optionalAccess', _90 => _90.subtle]);
   if (!subtle) return null;
   try {
     const enc = new TextEncoder();
@@ -5498,7 +5530,7 @@ async function deliverReceipt(receipt, options) {
     const retryable = status === void 0 ? true : isRetryableStatus(status);
     const willRetry = !ok && retryable && attempt < maxAttempts;
     try {
-      _optionalChain([onAttempt, 'optionalCall', _85 => _85({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
+      _optionalChain([onAttempt, 'optionalCall', _91 => _91({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
     } catch (e40) {
     }
     if (ok) return { delivered: true, attempts: attempt, status };

package/dist/index.d.cts

@@ -6370,7 +6370,11 @@ interface AcceptOption {
  *     relayer key needed. (EVM facilitators are also the path onto Coinbase's Bazaar directory.)
  */
 interface ExactRailOption {
-    settle: 'self' | {
+    /** How the gate settles an inbound `exact` payment. `'self'` = your own `relayer` broadcasts
+     *  (you pay gas). `'keyless'` = auto-pick a known KEYLESS facilitator for the chain (it sponsors
+     *  gas — zero-config; the same resolution as the top-level `exact: true` shorthand). `{ facilitator }`
+     *  = a specific facilitator you name — pin this in production rather than relying on the auto-pick. */
+    settle: 'self' | 'keyless' | {
         facilitator: string;
         authHeaders?: () => Promise<Record<string, string>>;
         /** Solana only — the facilitator's fee-payer pubkey, if you'd rather set it than have the
@@ -6462,9 +6466,17 @@ interface RequirePaymentOptions {
     /**
      * ALSO advertise a standard x402 `exact` rail so any standard x402 client can pay this
      * gate — opt-in, EVM (EIP-3009/Permit2) + Solana (SVM). See {@link ExactRailOption}.
-     * Omit to keep the gate exactly as today (`onchain-proof` only).
+     * Shorthand **`exact: true`** === `{ settle: 'keyless' }`: the gate auto-picks a known KEYLESS
+     * facilitator for each offered chain (from `KNOWN_FACILITATORS`), so neither buyer nor merchant
+     * pays gas, zero-config. It is a SOFT, best-effort flag — a chain with no available keyless
+     * facilitator DEGRADES GRACEFULLY to the always-present `onchain-proof` rail (the buyer pays gas,
+     * the only option left when no facilitator can sponsor) with a LOUD warning; it never bricks the
+     * gate. For guaranteed gasless, pin `settle: { facilitator }` (recommended in production) or
+     * self-settle `settle: 'self'`; an EXPLICIT `settle` that can't carry exact throws loudly (a config
+     * error you should fix). `false`/omitted keeps the gate exactly as today (`onchain-proof` only —
+     * byte-identical).
      */
-    exact?: ExactRailOption;
+    exact?: boolean | ExactRailOption;
     /**
      * Make this gate's 402 self-describing for the open indexes — **x402scan REQUIRES
      * an input schema or it won't list the resource.** Set `true` for a no-input GET,

package/dist/index.d.ts

@@ -6370,7 +6370,11 @@ interface AcceptOption {
  *     relayer key needed. (EVM facilitators are also the path onto Coinbase's Bazaar directory.)
  */
 interface ExactRailOption {
-    settle: 'self' | {
+    /** How the gate settles an inbound `exact` payment. `'self'` = your own `relayer` broadcasts
+     *  (you pay gas). `'keyless'` = auto-pick a known KEYLESS facilitator for the chain (it sponsors
+     *  gas — zero-config; the same resolution as the top-level `exact: true` shorthand). `{ facilitator }`
+     *  = a specific facilitator you name — pin this in production rather than relying on the auto-pick. */
+    settle: 'self' | 'keyless' | {
         facilitator: string;
         authHeaders?: () => Promise<Record<string, string>>;
         /** Solana only — the facilitator's fee-payer pubkey, if you'd rather set it than have the
@@ -6462,9 +6466,17 @@ interface RequirePaymentOptions {
     /**
      * ALSO advertise a standard x402 `exact` rail so any standard x402 client can pay this
      * gate — opt-in, EVM (EIP-3009/Permit2) + Solana (SVM). See {@link ExactRailOption}.
-     * Omit to keep the gate exactly as today (`onchain-proof` only).
+     * Shorthand **`exact: true`** === `{ settle: 'keyless' }`: the gate auto-picks a known KEYLESS
+     * facilitator for each offered chain (from `KNOWN_FACILITATORS`), so neither buyer nor merchant
+     * pays gas, zero-config. It is a SOFT, best-effort flag — a chain with no available keyless
+     * facilitator DEGRADES GRACEFULLY to the always-present `onchain-proof` rail (the buyer pays gas,
+     * the only option left when no facilitator can sponsor) with a LOUD warning; it never bricks the
+     * gate. For guaranteed gasless, pin `settle: { facilitator }` (recommended in production) or
+     * self-settle `settle: 'self'`; an EXPLICIT `settle` that can't carry exact throws loudly (a config
+     * error you should fix). `false`/omitted keeps the gate exactly as today (`onchain-proof` only —
+     * byte-identical).
      */
-    exact?: ExactRailOption;
+    exact?: boolean | ExactRailOption;
     /**
      * Make this gate's 402 self-describing for the open indexes — **x402scan REQUIRES
      * an input schema or it won't list the resource.** Set `true` for a no-input GET,

package/dist/index.js

@@ -4891,6 +4891,63 @@ async function settleViaFacilitator(input) {
   return { ok: true, receipt };
 }
 
+// src/facilitators.ts
+var KNOWN_FACILITATORS = {
+  // Base (eip155:8453). Every entry is keyless and LIVE-settled by us (a real EIP-3009
+  // exact payment, buyer paid zero ETH) — not just a /supported read — on the dated day.
+  "eip155:8453": [
+    {
+      url: "https://facilitator.payai.network",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["eip3009"],
+      note: "PayAI \u2014 keyless, sponsors gas (Base USDC EIP-3009). Verified 2026-06-14 (/supported + live demo)."
+    },
+    {
+      url: "https://facilitator.xpay.sh",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["eip3009"],
+      note: "xpay \u2014 keyless, zero-fee, sponsors gas. LIVE-settled on Base 2026-06-15 (tx 0x2273d5\u2026)."
+    }
+  ],
+  // Solana (mainnet-beta). Keyless fee-payer sponsors for the SVM exact rail, each LIVE-settled
+  // by us (a real SPL TransferChecked, buyer paid zero SOL) on the dated day — beyond a /supported
+  // read. Daydreams + Questflow are intentionally ABSENT: their /supported is public but /verify
+  // returns 401 (an API key is required), so they are not keyless for settlement.
+  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": [
+    {
+      url: "https://facilitator.payai.network",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["svm"],
+      note: "PayAI \u2014 keyless fee-payer sponsor (Solana SPL SVM). LIVE-settled 2026-06-14 (tx 4dL8jRKH\u2026)."
+    },
+    {
+      url: "https://pay.openfacilitator.io",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["svm"],
+      note: "OpenFacilitator \u2014 keyless (no signup), fee-payer sponsor. LIVE-settled on Solana 2026-06-15 (tx 5BabDtX\u2026)."
+    },
+    {
+      url: "https://facilitator.corbits.dev",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["svm"],
+      note: "Corbits \u2014 keyless, Solana-first fee-payer sponsor. LIVE-settled on Solana 2026-06-15 (tx BCreYer\u2026)."
+    }
+  ]
+};
+function knownFacilitatorsFor(network) {
+  return KNOWN_FACILITATORS[network] ?? [];
+}
+function firstKeylessFacilitator(network, method) {
+  return knownFacilitatorsFor(network).find(
+    (f) => f.keyless && f.schemes.includes("exact") && (method === void 0 || f.settles.includes(method))
+  );
+}
+
 // src/server.ts
 function toInvalidBody(result) {
   return { x402Version: 2, status: "invalid", error: result.error, detail: result.detail };
@@ -4911,10 +4968,16 @@ function normaliseAccepts(options) {
     "requirePayment: provide either { chain, token, amount } or a non-empty `accept: [{ chain, token, amount }, \u2026]`."
   );
 }
+function normaliseExactOption(exact) {
+  if (!exact) return void 0;
+  if (exact === true) return { settle: "keyless" };
+  return exact;
+}
 function createPaymentGate(options) {
   const minConfirmations = options.minConfirmations ?? 1;
   const maxTimeoutSeconds = options.maxTimeoutSeconds ?? 600;
   const genNonce = options.generateNonce ?? (() => globalThis.crypto.randomUUID());
+  const exactOption = normaliseExactOption(options.exact);
   let resolved;
   function ready() {
     if (resolved) return resolved;
@@ -4934,7 +4997,7 @@ function createPaymentGate(options) {
           const { asset, decimals, symbol } = net.resolveToken(a.token);
           const amountBase = parseUnits(a.amount, decimals);
           const spec = { net, asset, decimals, symbol, amountBase, amountFormatted: a.amount, payTo };
-          if (options.exact) {
+          if (exactOption) {
             const outcome = await resolveExactRail(net, asset);
             if (outcome.rail) spec.exact = outcome.rail;
             else if (outcome.skipReason) exactSkips.push(outcome.skipReason);
@@ -4942,10 +5005,17 @@ function createPaymentGate(options) {
           return spec;
         })
       );
-      if (options.exact && !specs.some((s) => s.exact)) {
-        throw new Error(
-          "requirePayment: `exact` was requested but none of the offered rails support it. " + (exactSkips.length > 0 ? exactSkips.join(" ") : "The standard `exact` rail is EVM ERC-20 (EIP-3009 \u2014 USDC / EURC \u2014 or Permit2, e.g. Binance-Peg USDC on BNB) or a Solana SPL token (SVM) \u2014 NOT native coins, NOT families without a standard `exact` scheme. Offer an EVM ERC-20 / Solana SPL token, or drop `exact`.")
-        );
+      if (exactOption && !specs.some((s) => s.exact)) {
+        const why = exactSkips.length > 0 ? exactSkips.join(" ") : "The standard `exact` rail is EVM ERC-20 (EIP-3009 \u2014 USDC / EURC \u2014 or Permit2, e.g. Binance-Peg USDC on BNB) or a Solana SPL token (SVM) \u2014 NOT native coins, NOT families without a standard `exact` scheme.";
+        if (exactOption.settle === "keyless") {
+          if (typeof process === "undefined" || !process?.env?.PIPRAIL_NO_HINTS) {
+            console.warn(
+              `[piprail] exact: true \u2014 no offered chain has a gasless \`exact\` rail available, so this gate serves ONCHAIN-PROOF ONLY (buyers PAY GAS \u2014 the fallback when no facilitator can sponsor). ${why} To be gasless: pin \`exact: { settle: { facilitator } }\` or self-settle \`exact: { settle: 'self', relayer }\`. (Suppress with PIPRAIL_NO_HINTS=1.)`
+            );
+          }
+        } else {
+          throw new Error("requirePayment: `exact` was requested but none of the offered rails support it. " + why);
+        }
       }
       return specs;
     })();
@@ -4956,9 +5026,23 @@ function createPaymentGate(options) {
     return p;
   }
   async function resolveExactRail(net, asset) {
-    const cfg = options.exact;
-    const settle = cfg.settle;
+    const cfg = exactOption;
     if (!net.resolveExactRail) return {};
+    let settle = cfg.settle;
+    if (settle === "keyless") {
+      const picked = firstKeylessFacilitator(net.network);
+      if (!picked) {
+        return {
+          skipReason: `${net.network}: \`exact: true\` found no known keyless facilitator for this network. Pass \`exact: { settle: { facilitator } }\`, \`exact: { settle: 'self', relayer }\`, or see the coverage map (KNOWN_FACILITATORS / docs.piprail.com).`
+        };
+      }
+      if (typeof process === "undefined" || process?.env?.NODE_ENV !== "production" && !process?.env?.PIPRAIL_NO_HINTS) {
+        console.warn(
+          `[piprail] exact: keyless rail on ${net.network} auto-settles via ${picked.url} (zero-config; pin \`exact.settle.facilitator\` in production).`
+        );
+      }
+      settle = { facilitator: picked.url };
+    }
     let relayer;
     let feePayer;
     if (settle === "self") {
@@ -5330,7 +5414,12 @@ function requirePayment(options) {
     } catch (err) {
       if (err instanceof SettlementError) {
         res.status(502);
-        res.json({ x402Version: 2, error: "settlement_failed", detail: err.message });
+        res.json({
+          x402Version: 2,
+          error: "settlement_failed",
+          detail: err.message,
+          fallback: "The gasless `exact` settlement failed. This resource also accepts the `onchain-proof` scheme \u2014 retry by paying that rail yourself (you broadcast the transfer and pay the gas). It is the fallback when no facilitator can sponsor the gas."
+        });
         return;
       }
       next(err);
@@ -5359,63 +5448,6 @@ function normaliseHeader(value) {
   return value;
 }
 
-// src/facilitators.ts
-var KNOWN_FACILITATORS = {
-  // Base (eip155:8453). Every entry is keyless and LIVE-settled by us (a real EIP-3009
-  // exact payment, buyer paid zero ETH) — not just a /supported read — on the dated day.
-  "eip155:8453": [
-    {
-      url: "https://facilitator.payai.network",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["eip3009"],
-      note: "PayAI \u2014 keyless, sponsors gas (Base USDC EIP-3009). Verified 2026-06-14 (/supported + live demo)."
-    },
-    {
-      url: "https://facilitator.xpay.sh",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["eip3009"],
-      note: "xpay \u2014 keyless, zero-fee, sponsors gas. LIVE-settled on Base 2026-06-15 (tx 0x2273d5\u2026)."
-    }
-  ],
-  // Solana (mainnet-beta). Keyless fee-payer sponsors for the SVM exact rail, each LIVE-settled
-  // by us (a real SPL TransferChecked, buyer paid zero SOL) on the dated day — beyond a /supported
-  // read. Daydreams + Questflow are intentionally ABSENT: their /supported is public but /verify
-  // returns 401 (an API key is required), so they are not keyless for settlement.
-  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": [
-    {
-      url: "https://facilitator.payai.network",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["svm"],
-      note: "PayAI \u2014 keyless fee-payer sponsor (Solana SPL SVM). LIVE-settled 2026-06-14 (tx 4dL8jRKH\u2026)."
-    },
-    {
-      url: "https://pay.openfacilitator.io",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["svm"],
-      note: "OpenFacilitator \u2014 keyless (no signup), fee-payer sponsor. LIVE-settled on Solana 2026-06-15 (tx 5BabDtX\u2026)."
-    },
-    {
-      url: "https://facilitator.corbits.dev",
-      keyless: true,
-      schemes: ["exact"],
-      settles: ["svm"],
-      note: "Corbits \u2014 keyless, Solana-first fee-payer sponsor. LIVE-settled on Solana 2026-06-15 (tx BCreYer\u2026)."
-    }
-  ]
-};
-function knownFacilitatorsFor(network) {
-  return KNOWN_FACILITATORS[network] ?? [];
-}
-function firstKeylessFacilitator(network, method) {
-  return knownFacilitatorsFor(network).find(
-    (f) => f.keyless && f.schemes.includes("exact") && (method === void 0 || f.settles.includes(method))
-  );
-}
-
 // src/receipts.ts
 var DEFAULT_RETRIES = 5;
 var DEFAULT_TIMEOUT_MS = 1e4;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",