@piprail/sdk 2.1.1 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,59 @@ 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.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.
+
+### Changed
+
+- **The `exact` buyer matches a rail's network whether it's a CAIP-2 id _or_ a chain slug.** The pay
+  path now normalizes the offered network (`eip155:8453`, `base`, `bsc`, `56`, …) before matching it to
+  the bound chain — the same normalization discovery already used — so a PipRail client interoperates
+  with any x402 server or facilitator regardless of how it labels the network. Strictly additive: a
+  CAIP-2 label behaves exactly as before; only a chain slug that resolves to the **bound** chain becomes
+  newly payable (a different-chain or unrecognized label is never selected, and the trusted EIP-712
+  domain still fixes the chain id at signing). Fixes `exact` rails that some facilitators label by slug
+  being silently unpayable.
+
+### Added
+
+- **`facilitatorCoverage()` / `parseFacilitatorSupported()` surface two optional per-kind fields** —
+  `x402Version` and `assetTransferMethod` (`'eip3009' | 'permit2'`) — when a facilitator's `GET
+  /supported` advertises them, so coverage can tell a v1 rail from a v2 rail and an EIP-3009 kind from a
+  Permit2 one. Omitted entirely when absent (no `undefined` keys), so a facilitator reporting neither
+  parses exactly as before.
+
 ## [2.1.1] — 2026-06-15 — discoverability polish (post-2.1.0 audit)
 
 A consistency patch from a deep docs↔source audit of the 2.1.0 discoverability surface. No
@@ -1196,6 +1249,8 @@ 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
 [2.0.2]: https://www.npmjs.com/package/@piprail/sdk

package/dist/index.cjs

@@ -3220,7 +3220,7 @@ var PipRailClient = (_class2 = class {
     const candidates = this.gatherCandidates(net, challenge, schemes);
     if (candidates.length === 0) {
       const exactOnNet = challenge.accepts.some(
-        (a) => a.scheme === "exact" && net.supports(a.network)
+        (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network)
       );
       if (schemes.includes("exact") && exactOnNet && typeof net.payExact !== "function") {
         throw new (0, _chunkJG6KRAW6cjs.UnsupportedSchemeError)(
@@ -3229,7 +3229,7 @@ var PipRailClient = (_class2 = class {
       }
       if (!schemes.includes("exact") && exactOnNet && typeof net.payExact === "function") {
         const payable = challenge.accepts.some(
-          (a) => a.scheme === "exact" && net.supports(a.network) && net.describeAsset(a.asset) != null
+          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && net.describeAsset(a.asset) != null
         );
         if (payable) {
           throw new (0, _chunkJG6KRAW6cjs.NoCompatibleAcceptError)(
@@ -3249,6 +3249,17 @@ var PipRailClient = (_class2 = class {
     const chosen = _nullishCoalesce(priced.find((p) => p.quote.withinPolicy), () => ( priced[0]));
     return { net, wallet, accept: chosen.accept, challenge, quote: chosen.quote };
   }
+  /** Match a foreign-supplied network string against the bound driver, tolerating a
+   *  SLUG ('bsc', 'base', '56') the SAME way discovery's `railOnNetwork` already does —
+   *  normalize to CAIP-2 first, since a foreign/AEON/community 402 may label the network
+   *  with a slug (AEON serves v1 duplicate kinds '56'/'bsc'). ADDITIVE: a value that's
+   *  already CAIP-2 passes through `normalizeNetwork` UNCHANGED, so every existing
+   *  exact-CAIP-2 match is byte-identical; only slugs resolving to the bound chain become
+   *  newly matchable (an unknown slug stays unresolved → still unmatched; a different
+   *  chain's slug resolves elsewhere → still unmatched). */
+  supportsNetwork(net, network) {
+    return net.supports(normalizeNetwork(network));
+  }
   /** The candidate accepts this client could pay, on the bound network. Always the
    *  backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
    *  enables them AND the driver can settle them (EVM `payExact` + a recognised
@@ -3259,14 +3270,14 @@ var PipRailClient = (_class2 = class {
     if (schemes.includes("onchain-proof")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "onchain-proof" && net.supports(a.network)
+          (a) => a.scheme === "onchain-proof" && this.supportsNetwork(net, a.network)
         )
       );
     }
     if (schemes.includes("exact")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "exact" && net.supports(a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
+          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
           // signing it would build a NaN/garbage validBefore — drop it silently
           // (symmetric with an unrecognised token) rather than leak a raw SyntaxError.
           Number.isInteger(a.maxTimeoutSeconds) && a.maxTimeoutSeconds > 0
@@ -3508,7 +3519,7 @@ var PipRailClient = (_class2 = class {
     );
   }
   async payAndConfirm(net, wallet, accept) {
-    if (!net.supports(accept.network)) {
+    if (!this.supportsNetwork(net, accept.network)) {
       throw new (0, _chunkJG6KRAW6cjs.WrongChainError)(
         `Challenge expects ${accept.network} but client is on ${net.network}.`
       );
@@ -4761,7 +4772,15 @@ function parseFacilitatorSupported(body) {
     const o = k;
     if (typeof o.scheme !== "string" || typeof o.network !== "string") continue;
     const fp = _optionalChain([o, 'access', _77 => _77.extra, 'optionalAccess', _78 => _78.feePayer]);
-    out.push({ scheme: o.scheme, network: o.network, ...typeof fp === "string" ? { feePayer: fp } : {} });
+    const ver = o.x402Version;
+    const method = _optionalChain([o, 'access', _79 => _79.extra, 'optionalAccess', _80 => _80.assetTransferMethod]);
+    out.push({
+      scheme: o.scheme,
+      network: o.network,
+      ...typeof fp === "string" ? { feePayer: fp } : {},
+      ...typeof ver === "number" ? { x402Version: ver } : {},
+      ...typeof method === "string" ? { assetTransferMethod: method } : {}
+    });
   }
   return out;
 }
@@ -4872,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 };
@@ -4892,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;
@@ -4915,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);
@@ -4923,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;
     })();
@@ -4937,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") {
@@ -5067,7 +5170,7 @@ function createPaymentGate(options) {
       instruction: describeChallenge({ x402Version: 2, resource: { url: resourceUrl }, accepts }),
       ...endpointInfo ? { endpoint: endpointInfo } : {}
     });
-    const rejectionExt = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _79 => _79.extensions]), () => ( {}));
+    const rejectionExt = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _87 => _87.extensions]), () => ( {}));
     const rejectionPiprail = _nullishCoalesce(rejectionExt.piprail, () => ( {}));
     const bodyPiprail = { ..._nullishCoalesce(selfDescribe, () => ( {})), ...rejectionPiprail };
     const bodyExtensions = {
@@ -5087,7 +5190,7 @@ function createPaymentGate(options) {
         ...options.mimeType ? { mimeType: options.mimeType } : {}
       },
       accepts,
-      ..._optionalChain([opts, 'optionalAccess', _80 => _80.error]) ? { error: opts.error } : {},
+      ..._optionalChain([opts, 'optionalAccess', _88 => _88.error]) ? { error: opts.error } : {},
       ...Object.keys(bodyExtensions).length > 0 ? { extensions: bodyExtensions } : {}
     };
     const headerChallenge = {
@@ -5311,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);
@@ -5340,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;
@@ -5409,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', _81 => _81.crypto, 'optionalAccess', _82 => _82.subtle]);
+  const subtle = _optionalChain([globalThis, 'access', _89 => _89.crypto, 'optionalAccess', _90 => _90.subtle]);
   if (!subtle) return null;
   try {
     const enc = new TextEncoder();
@@ -5479,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', _83 => _83({ 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

@@ -5562,6 +5562,15 @@ declare class PipRailClient {
      * `quote()` (read-only) and `fetch()` (which then authorises + pays).
      */
     private resolveChallenge;
+    /** Match a foreign-supplied network string against the bound driver, tolerating a
+     *  SLUG ('bsc', 'base', '56') the SAME way discovery's `railOnNetwork` already does —
+     *  normalize to CAIP-2 first, since a foreign/AEON/community 402 may label the network
+     *  with a slug (AEON serves v1 duplicate kinds '56'/'bsc'). ADDITIVE: a value that's
+     *  already CAIP-2 passes through `normalizeNetwork` UNCHANGED, so every existing
+     *  exact-CAIP-2 match is byte-identical; only slugs resolving to the bound chain become
+     *  newly matchable (an unknown slug stays unresolved → still unmatched; a different
+     *  chain's slug resolves elsewhere → still unmatched). */
+    private supportsNetwork;
     /** The candidate accepts this client could pay, on the bound network. Always the
      *  backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
      *  enables them AND the driver can settle them (EVM `payExact` + a recognised
@@ -6361,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
@@ -6453,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,
@@ -6611,6 +6632,14 @@ interface FacilitatorSupportedKind {
     network: string;
     /** The fee-payer pubkey when the kind carries one (SVM rails). */
     feePayer?: string;
+    /** The kind's x402 envelope version when the facilitator reports it per-kind — e.g.
+     *  AEON's `/supported` serves `{ x402Version, scheme, network }`, letting a reader tell
+     *  a v1 from a v2 BNB rail. Optional — absent when the facilitator doesn't advertise it. */
+    x402Version?: number;
+    /** The EVM exact transfer method (`eip3009` / `permit2`) when the facilitator advertises
+     *  it in the kind's `extra` — so coverage can tell whether a BNB exact kind is gasless
+     *  EIP-3009 or Permit2. Optional — most facilitators (AEON included) omit it. */
+    assetTransferMethod?: string;
 }
 /**
  * Parse a facilitator `/supported` body into its advertised (scheme, network) kinds.

package/dist/index.d.ts

@@ -5562,6 +5562,15 @@ declare class PipRailClient {
      * `quote()` (read-only) and `fetch()` (which then authorises + pays).
      */
     private resolveChallenge;
+    /** Match a foreign-supplied network string against the bound driver, tolerating a
+     *  SLUG ('bsc', 'base', '56') the SAME way discovery's `railOnNetwork` already does —
+     *  normalize to CAIP-2 first, since a foreign/AEON/community 402 may label the network
+     *  with a slug (AEON serves v1 duplicate kinds '56'/'bsc'). ADDITIVE: a value that's
+     *  already CAIP-2 passes through `normalizeNetwork` UNCHANGED, so every existing
+     *  exact-CAIP-2 match is byte-identical; only slugs resolving to the bound chain become
+     *  newly matchable (an unknown slug stays unresolved → still unmatched; a different
+     *  chain's slug resolves elsewhere → still unmatched). */
+    private supportsNetwork;
     /** The candidate accepts this client could pay, on the bound network. Always the
      *  backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
      *  enables them AND the driver can settle them (EVM `payExact` + a recognised
@@ -6361,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
@@ -6453,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,
@@ -6611,6 +6632,14 @@ interface FacilitatorSupportedKind {
     network: string;
     /** The fee-payer pubkey when the kind carries one (SVM rails). */
     feePayer?: string;
+    /** The kind's x402 envelope version when the facilitator reports it per-kind — e.g.
+     *  AEON's `/supported` serves `{ x402Version, scheme, network }`, letting a reader tell
+     *  a v1 from a v2 BNB rail. Optional — absent when the facilitator doesn't advertise it. */
+    x402Version?: number;
+    /** The EVM exact transfer method (`eip3009` / `permit2`) when the facilitator advertises
+     *  it in the kind's `extra` — so coverage can tell whether a BNB exact kind is gasless
+     *  EIP-3009 or Permit2. Optional — most facilitators (AEON included) omit it. */
+    assetTransferMethod?: string;
 }
 /**
  * Parse a facilitator `/supported` body into its advertised (scheme, network) kinds.

package/dist/index.js

@@ -3220,7 +3220,7 @@ var PipRailClient = class {
     const candidates = this.gatherCandidates(net, challenge, schemes);
     if (candidates.length === 0) {
       const exactOnNet = challenge.accepts.some(
-        (a) => a.scheme === "exact" && net.supports(a.network)
+        (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network)
       );
       if (schemes.includes("exact") && exactOnNet && typeof net.payExact !== "function") {
         throw new UnsupportedSchemeError(
@@ -3229,7 +3229,7 @@ var PipRailClient = class {
       }
       if (!schemes.includes("exact") && exactOnNet && typeof net.payExact === "function") {
         const payable = challenge.accepts.some(
-          (a) => a.scheme === "exact" && net.supports(a.network) && net.describeAsset(a.asset) != null
+          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && net.describeAsset(a.asset) != null
         );
         if (payable) {
           throw new NoCompatibleAcceptError(
@@ -3249,6 +3249,17 @@ var PipRailClient = class {
     const chosen = priced.find((p) => p.quote.withinPolicy) ?? priced[0];
     return { net, wallet, accept: chosen.accept, challenge, quote: chosen.quote };
   }
+  /** Match a foreign-supplied network string against the bound driver, tolerating a
+   *  SLUG ('bsc', 'base', '56') the SAME way discovery's `railOnNetwork` already does —
+   *  normalize to CAIP-2 first, since a foreign/AEON/community 402 may label the network
+   *  with a slug (AEON serves v1 duplicate kinds '56'/'bsc'). ADDITIVE: a value that's
+   *  already CAIP-2 passes through `normalizeNetwork` UNCHANGED, so every existing
+   *  exact-CAIP-2 match is byte-identical; only slugs resolving to the bound chain become
+   *  newly matchable (an unknown slug stays unresolved → still unmatched; a different
+   *  chain's slug resolves elsewhere → still unmatched). */
+  supportsNetwork(net, network) {
+    return net.supports(normalizeNetwork(network));
+  }
   /** The candidate accepts this client could pay, on the bound network. Always the
    *  backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
    *  enables them AND the driver can settle them (EVM `payExact` + a recognised
@@ -3259,14 +3270,14 @@ var PipRailClient = class {
     if (schemes.includes("onchain-proof")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "onchain-proof" && net.supports(a.network)
+          (a) => a.scheme === "onchain-proof" && this.supportsNetwork(net, a.network)
         )
       );
     }
     if (schemes.includes("exact")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "exact" && net.supports(a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
+          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
           // signing it would build a NaN/garbage validBefore — drop it silently
           // (symmetric with an unrecognised token) rather than leak a raw SyntaxError.
           Number.isInteger(a.maxTimeoutSeconds) && a.maxTimeoutSeconds > 0
@@ -3508,7 +3519,7 @@ var PipRailClient = class {
     );
   }
   async payAndConfirm(net, wallet, accept) {
-    if (!net.supports(accept.network)) {
+    if (!this.supportsNetwork(net, accept.network)) {
       throw new WrongChainError(
         `Challenge expects ${accept.network} but client is on ${net.network}.`
       );
@@ -4761,7 +4772,15 @@ function parseFacilitatorSupported(body) {
     const o = k;
     if (typeof o.scheme !== "string" || typeof o.network !== "string") continue;
     const fp = o.extra?.feePayer;
-    out.push({ scheme: o.scheme, network: o.network, ...typeof fp === "string" ? { feePayer: fp } : {} });
+    const ver = o.x402Version;
+    const method = o.extra?.assetTransferMethod;
+    out.push({
+      scheme: o.scheme,
+      network: o.network,
+      ...typeof fp === "string" ? { feePayer: fp } : {},
+      ...typeof ver === "number" ? { x402Version: ver } : {},
+      ...typeof method === "string" ? { assetTransferMethod: method } : {}
+    });
   }
   return out;
 }
@@ -4872,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 };
@@ -4892,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;
@@ -4915,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);
@@ -4923,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;
     })();
@@ -4937,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") {
@@ -5311,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);
@@ -5340,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.1.1",
+  "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",