@piprail/sdk 1.21.0 → 1.21.1

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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/).
 
+## [1.21.1] — 2026-06-13 — facilitator hardening + gasless auto-routing + agent-facing docs
+
+A correctness/robustness patch over 1.21.0, after a full re-review and **live mainnet tests of the
+facilitator path on both Solana and Base (EVM)**. Opt-in surface unchanged; `onchain-proof` still the
+default everywhere.
+
+### Fixed
+- **Gasless auto-routing now works on Solana.** The Solana driver's `estimateCost` now reports the
+  `exact` rail as **~0 buyer gas** (the fee payer — a facilitator like PayAI, or your relayer —
+  broadcasts and pays the SOL fee), mirroring the EVM driver. Before, it reported the same fee as
+  `onchain-proof`, so `planPayment()`/`fetch({ autoRoute: true })` wouldn't prefer the gasless rail —
+  now they correctly pick it. (Live-proven: autoRoute chooses `exact` even when the buyer holds SOL.)
+- **Buyer EIP-3009 domain read is resilient to a flaky RPC.** `payExactEvm` now retries the on-chain
+  EIP-712 domain read once before concluding a token "isn't EIP-3009", so a rate-limited public RPC can
+  no longer misreport real USDC as un-payable and block an otherwise-valid gasless payment. The error
+  message, if it still fails, now names the transient-RPC possibility instead of asserting non-EIP-3009.
+
+### Changed
+- **Permit2 can't be facilitator-settled — the gate now says so clearly.** A third-party facilitator
+  settles the standard EIP-3009 (EVM) / SVM (Solana) schemes, not PipRail's `x402ExactPermit2Proxy`. A
+  *forced* `exact: { method: 'permit2', settle: { facilitator } }` now throws a clear config error, and
+  an *auto*-selected Permit2 token is dropped to `onchain-proof`-only over a facilitator (rather than
+  advertising a rail it could never settle). Keyed off the resolved method, so Solana (`svm`) is unaffected.
+- **Clearer facilitator-unreachable error.** When a Solana facilitator's `GET /supported` can't be read
+  at challenge time, the gate now explains the real cause (and points at `exact.settle.feePayer` / 
+  `settle: 'self'`) instead of the misleading "none of the offered rails support it".
+- **`PIPRAIL_AGENT_GUIDE` now teaches the gasless `exact` rail** — the two rails, that it's operator-opt-in,
+  that the on-chain method is auto-selected, and that on a timeout the `exact` `.ref` is an authorization
+  **nonce** (re-present the same authorization, never re-sign). Plus docs: the "whole model in 30 seconds"
+  (gas vs `onchain-proof` vs `exact`'s three methods), a "when the facilitator fails" breakdown, and
+  agent-toolkit/MCP gasless guidance.
+
 ## [1.21.0] — 2026-06-13 — standard `exact` rail on Solana (SVM) + fully-gasless facilitator mode
 
 Opt-in, defaults unchanged. `onchain-proof` stays the default on every chain and is byte-identical.

package/dist/index.cjs

@@ -666,10 +666,14 @@ async function payExactEvm(input) {
       `exact buyer rail requires an EOA signer; ${account.address} is a contract / EIP-1271 / EIP-7702-delegated account (no recoverable ECDSA signature). Pay via onchain-proof.`
     );
   }
-  const domain = await readExactDomain(publicClient, accept.asset);
+  let domain = await readExactDomain(publicClient, accept.asset);
+  if (!domain) {
+    await new Promise((r) => setTimeout(r, 300));
+    domain = await readExactDomain(publicClient, accept.asset);
+  }
   if (!domain) {
     throw new (0, _chunkPA6YD3HLcjs.UnsupportedSchemeError)(
-      `exact: ${accept.asset} on ${accept.network} isn't an EIP-3009 token (USDT needs Permit2; native coin and plain ERC-20s aren't exact-payable). Pay via onchain-proof.`
+      `exact: couldn't derive the EIP-712 domain for ${accept.asset} on ${accept.network}. Either it isn't an EIP-3009 token (USDT needs Permit2; native/plain ERC-20 aren't exact-payable) \u2014 pay via onchain-proof \u2014 OR your RPC couldn't read it (transient): if the gate advertised eip3009, pass a reliable rpcUrl and retry.`
     );
   }
   const g = globalThis.crypto;
@@ -1791,7 +1795,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./solana-CCVSMOKS.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./solana-WG7RGDSI.cjs")));
     } catch (cause) {
       throw new (0, _chunkPA6YD3HLcjs.MissingDriverError)(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -3647,6 +3651,18 @@ straight from your wallet to the server; PipRail custodies nothing. Follow this.
    and return the result.
 Always plan before you pay so you never commit to a payment you cannot finish.
 
+## Gasless \u2014 the exact rail (zero gas for you)
+A 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:
+- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas
+  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.
+- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose
+  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It
+  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.
+When the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest
+settleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is
+identical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);
+you can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).
+
 ## Reading a refusal \u2014 never crash, never double-spend
 A failed pay returns a STRUCTURED object, never a thrown error you must catch:
   { ok:false, code, reason, explain, ref?, reasonCode?, declined? }
@@ -3664,9 +3680,13 @@ Branch on \`code\` (always reliable). Key cases:
 - code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.
 - code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the
   payment may ALREADY be on-chain. Recover using the proof on \`.ref\` (re-verify
-  or re-submit it); never re-pay \u2014 a fresh payment would double-spend.
+  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless
+  exact rail \`.ref\` is the authorization NONCE, not a tx hash: re-present the SAME
+  signed authorization, never sign a fresh one (that would risk a double-spend).
 - code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on
   your chain/scheme; \`explain\` says whether it's the wrong chain or a scheme to enable.
+  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes
+  once (enable the exact scheme); report it, don't retry the same call blindly.
 
 ## Knowing your leash \u2014 call piprail_budget
 piprail_budget tells you how much budget and time you have left, per
@@ -4199,6 +4219,7 @@ function createPaymentGate(options) {
     if (resolved) return resolved;
     const p = (async () => {
       const accepts = normaliseAccepts(options);
+      const exactSkips = [];
       const specs = await Promise.all(
         accepts.map(async (a) => {
           const net = await resolveNetwork2({ chain: a.chain, rpcUrl: _nullishCoalesce(a.rpcUrl, () => ( options.rpcUrl)) });
@@ -4212,13 +4233,17 @@ function createPaymentGate(options) {
           const { asset, decimals, symbol } = net.resolveToken(a.token);
           const amountBase = _chunkPA6YD3HLcjs.parseUnits.call(void 0, a.amount, decimals);
           const spec = { net, asset, decimals, symbol, amountBase, amountFormatted: a.amount, payTo };
-          if (options.exact) spec.exact = await resolveExactRail(net, asset);
+          if (options.exact) {
+            const outcome = await resolveExactRail(net, asset);
+            if (outcome.rail) spec.exact = outcome.rail;
+            else if (outcome.skipReason) exactSkips.push(outcome.skipReason);
+          }
           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. 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`."
+          "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`.")
         );
       }
       return specs;
@@ -4231,10 +4256,11 @@ function createPaymentGate(options) {
   }
   async function resolveExactRail(net, asset) {
     const cfg = options.exact;
-    if (!net.resolveExactRail) return void 0;
+    const settle = cfg.settle;
+    if (!net.resolveExactRail) return {};
     let relayer;
     let feePayer;
-    if (cfg.settle === "self") {
+    if (settle === "self") {
       if (cfg.relayer === void 0) {
         throw new Error(
           "requirePayment: exact `settle: 'self'` needs a `relayer` wallet (the gas-paying key that broadcasts the settle), e.g. exact: { settle: 'self', relayer: { privateKey } }."
@@ -4242,21 +4268,36 @@ function createPaymentGate(options) {
       }
       relayer = net.bindWallet(cfg.relayer);
     } else {
-      feePayer = cfg.settle.feePayer;
+      feePayer = settle.feePayer;
     }
     const method = _nullishCoalesce(cfg.method, () => ( "auto"));
     let info = await net.resolveExactRail({ asset, method, relayer, feePayer });
-    if (!info && cfg.settle !== "self" && !feePayer) {
-      const discovered = await fetchFacilitatorFeePayer(cfg.settle.facilitator, net.network);
-      if (discovered) info = await net.resolveExactRail({ asset, method, relayer, feePayer: discovered });
+    if (!info && settle !== "self" && !feePayer && asset !== "native") {
+      const discovered = await fetchFacilitatorFeePayer(settle.facilitator, net.network);
+      if (!discovered) {
+        return {
+          skipReason: `${net.network}: couldn't read a fee payer from the facilitator (${settle.facilitator}/supported) \u2014 it may be down, or may not sponsor this network. Set \`exact.settle.feePayer\` explicitly to remove the runtime dependency, switch to \`settle: 'self'\` with your own relayer, or retry.`
+        };
+      }
+      info = await net.resolveExactRail({ asset, method, relayer, feePayer: discovered });
+    }
+    if (!info) return {};
+    if (settle !== "self" && info.method === "permit2") {
+      if (cfg.method === "permit2") {
+        throw new Error(
+          "requirePayment: exact `method: 'permit2'` can't be settled by a third-party facilitator \u2014 facilitators settle the standard EIP-3009 (EVM) / SVM (Solana) schemes, not PipRail\u2019s Permit2 proxy. Use an EIP-3009 token (USDC / EURC) with the facilitator, or `settle: 'self'` (your own relayer) to settle Permit2 yourself."
+        );
+      }
+      return {
+        skipReason: `${net.network}: this token isn't EIP-3009 (auto-selected Permit2), which a third-party facilitator can't settle \u2014 it would serve onchain-proof only here. Use an EIP-3009 token (USDC / EURC) with the facilitator, or \`settle: 'self'\` to settle Permit2 yourself.`
+      };
     }
-    if (!info) return void 0;
-    const mode = cfg.settle === "self" ? { kind: "self", relayer } : {
+    const mode = settle === "self" ? { kind: "self", relayer } : {
       kind: "facilitator",
-      url: cfg.settle.facilitator,
-      ...cfg.settle.authHeaders ? { authHeaders: cfg.settle.authHeaders } : {}
+      url: settle.facilitator,
+      ...settle.authHeaders ? { authHeaders: settle.authHeaders } : {}
     };
-    return { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode };
+    return { rail: { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode } };
   }
   const hasCustomStore = Boolean(options.isUsed || options.markUsed);
   const localUsed = /* @__PURE__ */ new Map();

package/dist/index.d.cts

@@ -5545,7 +5545,7 @@ declare function formatSpendReport(summary: SpendSummary): string;
  * literally, so a wrong name or order actively misleads. A test pins the load-
  * bearing phrases.
  */
-declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend.\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
+declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);\nyou can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;
 

package/dist/index.d.ts

@@ -5545,7 +5545,7 @@ declare function formatSpendReport(summary: SpendSummary): string;
  * literally, so a wrong name or order actively misleads. A test pins the load-
  * bearing phrases.
  */
-declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend.\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
+declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);\nyou can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;
 

package/dist/index.js

@@ -666,10 +666,14 @@ async function payExactEvm(input) {
       `exact buyer rail requires an EOA signer; ${account.address} is a contract / EIP-1271 / EIP-7702-delegated account (no recoverable ECDSA signature). Pay via onchain-proof.`
     );
   }
-  const domain = await readExactDomain(publicClient, accept.asset);
+  let domain = await readExactDomain(publicClient, accept.asset);
+  if (!domain) {
+    await new Promise((r) => setTimeout(r, 300));
+    domain = await readExactDomain(publicClient, accept.asset);
+  }
   if (!domain) {
     throw new UnsupportedSchemeError(
-      `exact: ${accept.asset} on ${accept.network} isn't an EIP-3009 token (USDT needs Permit2; native coin and plain ERC-20s aren't exact-payable). Pay via onchain-proof.`
+      `exact: couldn't derive the EIP-712 domain for ${accept.asset} on ${accept.network}. Either it isn't an EIP-3009 token (USDT needs Permit2; native/plain ERC-20 aren't exact-payable) \u2014 pay via onchain-proof \u2014 OR your RPC couldn't read it (transient): if the gate advertised eip3009, pass a reliable rpcUrl and retry.`
     );
   }
   const g = globalThis.crypto;
@@ -1791,7 +1795,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-4EMMGGDR.js");
+      mod = await import("./solana-IBVUZS54.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -3647,6 +3651,18 @@ straight from your wallet to the server; PipRail custodies nothing. Follow this.
    and return the result.
 Always plan before you pay so you never commit to a payment you cannot finish.
 
+## Gasless \u2014 the exact rail (zero gas for you)
+A 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:
+- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas
+  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.
+- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose
+  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It
+  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.
+When the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest
+settleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is
+identical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);
+you can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).
+
 ## Reading a refusal \u2014 never crash, never double-spend
 A failed pay returns a STRUCTURED object, never a thrown error you must catch:
   { ok:false, code, reason, explain, ref?, reasonCode?, declined? }
@@ -3664,9 +3680,13 @@ Branch on \`code\` (always reliable). Key cases:
 - code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.
 - code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the
   payment may ALREADY be on-chain. Recover using the proof on \`.ref\` (re-verify
-  or re-submit it); never re-pay \u2014 a fresh payment would double-spend.
+  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless
+  exact rail \`.ref\` is the authorization NONCE, not a tx hash: re-present the SAME
+  signed authorization, never sign a fresh one (that would risk a double-spend).
 - code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on
   your chain/scheme; \`explain\` says whether it's the wrong chain or a scheme to enable.
+  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes
+  once (enable the exact scheme); report it, don't retry the same call blindly.
 
 ## Knowing your leash \u2014 call piprail_budget
 piprail_budget tells you how much budget and time you have left, per
@@ -4199,6 +4219,7 @@ function createPaymentGate(options) {
     if (resolved) return resolved;
     const p = (async () => {
       const accepts = normaliseAccepts(options);
+      const exactSkips = [];
       const specs = await Promise.all(
         accepts.map(async (a) => {
           const net = await resolveNetwork2({ chain: a.chain, rpcUrl: a.rpcUrl ?? options.rpcUrl });
@@ -4212,13 +4233,17 @@ 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) spec.exact = await resolveExactRail(net, asset);
+          if (options.exact) {
+            const outcome = await resolveExactRail(net, asset);
+            if (outcome.rail) spec.exact = outcome.rail;
+            else if (outcome.skipReason) exactSkips.push(outcome.skipReason);
+          }
           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. 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`."
+          "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`.")
         );
       }
       return specs;
@@ -4231,10 +4256,11 @@ function createPaymentGate(options) {
   }
   async function resolveExactRail(net, asset) {
     const cfg = options.exact;
-    if (!net.resolveExactRail) return void 0;
+    const settle = cfg.settle;
+    if (!net.resolveExactRail) return {};
     let relayer;
     let feePayer;
-    if (cfg.settle === "self") {
+    if (settle === "self") {
       if (cfg.relayer === void 0) {
         throw new Error(
           "requirePayment: exact `settle: 'self'` needs a `relayer` wallet (the gas-paying key that broadcasts the settle), e.g. exact: { settle: 'self', relayer: { privateKey } }."
@@ -4242,21 +4268,36 @@ function createPaymentGate(options) {
       }
       relayer = net.bindWallet(cfg.relayer);
     } else {
-      feePayer = cfg.settle.feePayer;
+      feePayer = settle.feePayer;
     }
     const method = cfg.method ?? "auto";
     let info = await net.resolveExactRail({ asset, method, relayer, feePayer });
-    if (!info && cfg.settle !== "self" && !feePayer) {
-      const discovered = await fetchFacilitatorFeePayer(cfg.settle.facilitator, net.network);
-      if (discovered) info = await net.resolveExactRail({ asset, method, relayer, feePayer: discovered });
+    if (!info && settle !== "self" && !feePayer && asset !== "native") {
+      const discovered = await fetchFacilitatorFeePayer(settle.facilitator, net.network);
+      if (!discovered) {
+        return {
+          skipReason: `${net.network}: couldn't read a fee payer from the facilitator (${settle.facilitator}/supported) \u2014 it may be down, or may not sponsor this network. Set \`exact.settle.feePayer\` explicitly to remove the runtime dependency, switch to \`settle: 'self'\` with your own relayer, or retry.`
+        };
+      }
+      info = await net.resolveExactRail({ asset, method, relayer, feePayer: discovered });
+    }
+    if (!info) return {};
+    if (settle !== "self" && info.method === "permit2") {
+      if (cfg.method === "permit2") {
+        throw new Error(
+          "requirePayment: exact `method: 'permit2'` can't be settled by a third-party facilitator \u2014 facilitators settle the standard EIP-3009 (EVM) / SVM (Solana) schemes, not PipRail\u2019s Permit2 proxy. Use an EIP-3009 token (USDC / EURC) with the facilitator, or `settle: 'self'` (your own relayer) to settle Permit2 yourself."
+        );
+      }
+      return {
+        skipReason: `${net.network}: this token isn't EIP-3009 (auto-selected Permit2), which a third-party facilitator can't settle \u2014 it would serve onchain-proof only here. Use an EIP-3009 token (USDC / EURC) with the facilitator, or \`settle: 'self'\` to settle Permit2 yourself.`
+      };
     }
-    if (!info) return void 0;
-    const mode = cfg.settle === "self" ? { kind: "self", relayer } : {
+    const mode = settle === "self" ? { kind: "self", relayer } : {
       kind: "facilitator",
-      url: cfg.settle.facilitator,
-      ...cfg.settle.authHeaders ? { authHeaders: cfg.settle.authHeaders } : {}
+      url: settle.facilitator,
+      ...settle.authHeaders ? { authHeaders: settle.authHeaders } : {}
     };
-    return { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode };
+    return { rail: { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode } };
   }
   const hasCustomStore = Boolean(options.isUsed || options.markUsed);
   const localUsed = /* @__PURE__ */ new Map();

package/dist/{solana-4EMMGGDR.js → solana-IBVUZS54.js}

@@ -624,6 +624,15 @@ function makeSolanaNetwork(preset, rpcUrl) {
       return { height: String(info.slot) };
     },
     async estimateCost(accept) {
+      if (accept.scheme === "exact") {
+        return nativeCost({
+          symbol: "SOL",
+          decimals: SOL_DECIMALS,
+          fee: 0n,
+          basis: "estimated",
+          detail: "gasless \u2014 the fee payer (facilitator/relayer) broadcasts and pays the SOL fee"
+        });
+      }
       const base = 5000n;
       if (accept.asset === "native") {
         return nativeCost({

package/dist/{solana-CCVSMOKS.cjs → solana-WG7RGDSI.cjs}

@@ -624,6 +624,15 @@ function makeSolanaNetwork(preset, rpcUrl) {
       return { height: String(info.slot) };
     },
     async estimateCost(accept) {
+      if (accept.scheme === "exact") {
+        return _chunkPA6YD3HLcjs.nativeCost.call(void 0, {
+          symbol: "SOL",
+          decimals: SOL_DECIMALS,
+          fee: 0n,
+          basis: "estimated",
+          detail: "gasless \u2014 the fee payer (facilitator/relayer) broadcasts and pays the SOL fee"
+        });
+      }
       const base = 5000n;
       if (accept.asset === "native") {
         return _chunkPA6YD3HLcjs.nativeCost.call(void 0, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.21.0",
+  "version": "1.21.1",
   "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",