@piprail/sdk 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.18.0] — 2026-06-11 — gasless `exact` on 7 more chains + a Permit2-proxy guard
+
+A minor, fully additive release — defaults byte-identical (`exact` stays opt-in), no new dependency,
+the lazy-chunk invariant holds.
+
+### Added — gasless EIP-3009 `exact` on 7 more EVM chains
+- **Sonic, Linea, Celo, Unichain, World Chain, Sei, HyperEVM** added to `EXACT_NETWORK_SLUGS`. Each
+  ships a **native Circle USDC** whose `transferWithAuthorization` (EIP-3009) was **verified on-chain**
+  (`authorizationState` present), so the buyer pays **gasless, with no approval and no proxy**. This
+  roughly **doubles** PipRail's gasless-EVM footprint (7 → 14 mainnet chains). Live-proven on **HyperEVM
+  mainnet** (a standard `exact` client signed EIP-3009, the gate self-settled — tx `0xe31f92ee…`).
+- (The rail was never gated per-chain in the driver — it's capability-detected at runtime via
+  `exactDomain`. `EXACT_NETWORK_SLUGS` is the public `chainIdForExactNetwork` helper + the advertised
+  list; it had simply drifted behind the real capability. It's now accurate.)
+
+### Hardened — never advertise an unsettleable Permit2 rail
+- The `exact` rail's **Permit2** fallback (for non-EIP-3009 tokens) now checks the **x402ExactPermit2Proxy
+  is deployed** on the chain before advertising it. On a chain with neither an EIP-3009 token nor the
+  proxy (e.g. Mantle/Scroll/Kaia for their tokens), the gate offers `onchain-proof` only instead of a
+  Permit2 rail it could never settle; a forced `method: 'permit2'` there is a clear config error.
+- New driver-contract method `exactPermit2Supported?()` (EVM driver implements it from the verified
+  proxy-chain set). New public exports: **`PERMIT2_PROXY_CHAIN_IDS`**, **`isPermit2ProxyChain`**.
+
+### Docs
+- The chain-specific "Permit2 & BNB Chain" page was consolidated into a comprehensive **Gasless
+  payments** page (what gasless means · `onchain-proof` vs `exact` · EIP-3009 vs Permit2 · a clear
+  per-chain/-token coverage table). Old URL redirects.
+
+### Tests
+- +5 (the 7 new slugs, `isPermit2ProxyChain`, and the proxy-guard: auto-drop, mixed-gate, forced-throw).
+
 ## [1.17.0] — 2026-06-11 — `onPaid` hardening: enriched, isolated, durable receipts
 
 A minor, fully additive release — defaults byte-identical (fire-and-forget stays the default,

package/dist/index.cjs

@@ -516,7 +516,15 @@ var EXACT_NETWORK_SLUGS = {
   polygon: 137,
   avalanche: 43114,
   bnb: 56,
-  bsc: 56
+  bsc: 56,
+  // EIP-3009 USDC verified on-chain (authorizationState present) — gasless, no proxy:
+  sonic: 146,
+  linea: 59144,
+  celo: 42220,
+  unichain: 130,
+  worldchain: 480,
+  sei: 1329,
+  hyperevm: 999
 };
 function chainIdForExactNetwork(slug) {
   return _nullishCoalesce(EXACT_NETWORK_SLUGS[slug], () => ( null));
@@ -930,6 +938,37 @@ async function verifyAndSettleExactEvm(input) {
 
 var PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
 var X402_EXACT_PERMIT2_PROXY = "0x402085c248EeA27D92E8b30b2C58ed07f9E20001";
+var PERMIT2_PROXY_CHAIN_IDS = /* @__PURE__ */ new Set([
+  1,
+  // Ethereum
+  8453,
+  // Base
+  84532,
+  // Base Sepolia
+  42161,
+  // Arbitrum
+  10,
+  // Optimism
+  137,
+  // Polygon
+  43114,
+  // Avalanche
+  56,
+  // BNB
+  42220,
+  // Celo
+  480,
+  // World Chain
+  1329,
+  // Sei
+  999,
+  // HyperEVM
+  143
+  // Monad
+]);
+function isPermit2ProxyChain(chainId) {
+  return PERMIT2_PROXY_CHAIN_IDS.has(chainId);
+}
 var PERMIT2_WITNESS_TYPES = {
   PermitWitnessTransferFrom: [
     { name: "permitted", type: "TokenPermissions" },
@@ -1660,6 +1699,11 @@ function makeEvmNetwork(resolved) {
     async exactDomain(asset) {
       return readExactDomain(publicClient, asset);
     },
+    // Whether the Permit2 transfer method can settle here (proxy deployed). EIP-3009
+    // needs no proxy; this only gates the Permit2 fallback for non-EIP-3009 tokens.
+    exactPermit2Supported() {
+      return isPermit2ProxyChain(resolved.chainId);
+    },
     async settleExactSelf({ relayer, payload, accept }) {
       const a = relayer._native;
       if ("permit2Authorization" in payload) {
@@ -4129,6 +4173,14 @@ function createPaymentGate(options) {
         method = "permit2";
       }
     }
+    if (method === "permit2" && !(_nullishCoalesce(_optionalChain([net, 'access', _64 => _64.exactPermit2Supported, 'optionalCall', _65 => _65()]), () => ( false)))) {
+      if (cfg.method === "permit2") {
+        throw new Error(
+          `requirePayment: exact \`method: 'permit2'\` needs the x402 Permit2 proxy deployed on ${net.network}, but it isn't there. Offer an EIP-3009 token (gasless, no proxy), or drop \`exact\` on this chain. (See PERMIT2_PROXY_CHAIN_IDS.)`
+        );
+      }
+      return void 0;
+    }
     if (cfg.settle === "self") {
       if (cfg.relayer === void 0) {
         throw new Error(
@@ -4214,7 +4266,7 @@ function createPaymentGate(options) {
     const specs = await ready();
     const nonce = genNonce();
     const bazaar = options.discovery ? { bazaar: buildBazaarExtension(options.discovery === true ? {} : options.discovery) } : void 0;
-    const extensions = { ...bazaar, ..._optionalChain([opts, 'optionalAccess', _64 => _64.extensions]) };
+    const extensions = { ...bazaar, ..._optionalChain([opts, 'optionalAccess', _66 => _66.extensions]) };
     const challenge2 = {
       x402Version: 2,
       resource: {
@@ -4222,7 +4274,7 @@ function createPaymentGate(options) {
         ...options.description ? { description: options.description } : {}
       },
       accepts: buildAccepts(specs, nonce),
-      ..._optionalChain([opts, 'optionalAccess', _65 => _65.error]) ? { error: opts.error } : {},
+      ..._optionalChain([opts, 'optionalAccess', _67 => _67.error]) ? { error: opts.error } : {},
       ...Object.keys(extensions).length > 0 ? { extensions } : {}
     };
     return { challenge: challenge2, requiredHeader: buildChallengeHeader(challenge2) };
@@ -4456,7 +4508,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', _66 => _66.crypto, 'optionalAccess', _67 => _67.subtle]);
+  const subtle = _optionalChain([globalThis, 'access', _68 => _68.crypto, 'optionalAccess', _69 => _69.subtle]);
   if (!subtle) return null;
   try {
     const enc = new TextEncoder();
@@ -4526,7 +4578,7 @@ async function deliverReceipt(receipt, options) {
     const retryable = status === void 0 ? true : isRetryableStatus(status);
     const willRetry = !ok && retryable && attempt < maxAttempts;
     try {
-      _optionalChain([onAttempt, 'optionalCall', _68 => _68({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
+      _optionalChain([onAttempt, 'optionalCall', _70 => _70({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
     } catch (e36) {
     }
     if (ok) return { delivered: true, attempts: attempt, status };
@@ -4624,4 +4676,6 @@ async function deliverReceipt(receipt, options) {
 
 
 
-exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkPA6YD3HLcjs.ConfirmationTimeoutError; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkPA6YD3HLcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkPA6YD3HLcjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkPA6YD3HLcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkPA6YD3HLcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkPA6YD3HLcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkPA6YD3HLcjs.NonReplayableBodyError; exports.PERMIT2_ADDRESS = PERMIT2_ADDRESS; exports.PERMIT2_WITNESS_TYPES = PERMIT2_WITNESS_TYPES; exports.PIPRAIL_AGENT_GUIDE = PIPRAIL_AGENT_GUIDE; exports.PaymentDeclinedError = _chunkPA6YD3HLcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkPA6YD3HLcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkPA6YD3HLcjs.PipRailError; exports.RecipientNotReadyError = _chunkPA6YD3HLcjs.RecipientNotReadyError; exports.SettlementError = _chunkPA6YD3HLcjs.SettlementError; exports.UnknownTokenError = _chunkPA6YD3HLcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkPA6YD3HLcjs.UnsupportedNetworkError; exports.UnsupportedSchemeError = _chunkPA6YD3HLcjs.UnsupportedSchemeError; exports.WrongChainError = _chunkPA6YD3HLcjs.WrongChainError; exports.WrongFamilyError = _chunkPA6YD3HLcjs.WrongFamilyError; exports.X402_EXACT_PERMIT2_PROXY = X402_EXACT_PERMIT2_PROXY; exports.agentGuide = agentGuide; exports.buildBazaarExtension = buildBazaarExtension; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildExactSignatureHeader = buildExactSignatureHeader; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.classifyChallenge = classifyChallenge; exports.createPaymentGate = createPaymentGate; exports.decorateOutcome = decorateOutcome; exports.deliverReceipt = deliverReceipt; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.explainDecline = explainDecline; exports.formatSpendReport = formatSpendReport; exports.getDirectoryInfo = getDirectoryInfo; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSettleResponse = parseSettleResponse; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.summarizePlan = summarizePlan; exports.toInsufficientFundsError = _chunkPA6YD3HLcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.verify402IndexDomain = verify402IndexDomain;
+
+
+exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkPA6YD3HLcjs.ConfirmationTimeoutError; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkPA6YD3HLcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkPA6YD3HLcjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkPA6YD3HLcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkPA6YD3HLcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkPA6YD3HLcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkPA6YD3HLcjs.NonReplayableBodyError; exports.PERMIT2_ADDRESS = PERMIT2_ADDRESS; exports.PERMIT2_PROXY_CHAIN_IDS = PERMIT2_PROXY_CHAIN_IDS; exports.PERMIT2_WITNESS_TYPES = PERMIT2_WITNESS_TYPES; exports.PIPRAIL_AGENT_GUIDE = PIPRAIL_AGENT_GUIDE; exports.PaymentDeclinedError = _chunkPA6YD3HLcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkPA6YD3HLcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkPA6YD3HLcjs.PipRailError; exports.RecipientNotReadyError = _chunkPA6YD3HLcjs.RecipientNotReadyError; exports.SettlementError = _chunkPA6YD3HLcjs.SettlementError; exports.UnknownTokenError = _chunkPA6YD3HLcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkPA6YD3HLcjs.UnsupportedNetworkError; exports.UnsupportedSchemeError = _chunkPA6YD3HLcjs.UnsupportedSchemeError; exports.WrongChainError = _chunkPA6YD3HLcjs.WrongChainError; exports.WrongFamilyError = _chunkPA6YD3HLcjs.WrongFamilyError; exports.X402_EXACT_PERMIT2_PROXY = X402_EXACT_PERMIT2_PROXY; exports.agentGuide = agentGuide; exports.buildBazaarExtension = buildBazaarExtension; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildExactSignatureHeader = buildExactSignatureHeader; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.classifyChallenge = classifyChallenge; exports.createPaymentGate = createPaymentGate; exports.decorateOutcome = decorateOutcome; exports.deliverReceipt = deliverReceipt; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.explainDecline = explainDecline; exports.formatSpendReport = formatSpendReport; exports.getDirectoryInfo = getDirectoryInfo; exports.isPermit2ProxyChain = isPermit2ProxyChain; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSettleResponse = parseSettleResponse; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.summarizePlan = summarizePlan; exports.toInsufficientFundsError = _chunkPA6YD3HLcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.verify402IndexDomain = verify402IndexDomain;

package/dist/index.d.cts

@@ -4357,6 +4357,15 @@ interface ResolvedNetwork {
         name: string;
         version: string;
     } | null>;
+    /**
+     * OPTIONAL (EVM-only) — whether this chain can carry the **Permit2** transfer method
+     * of the `exact` scheme: i.e. the canonical Permit2 **and** the `x402ExactPermit2Proxy`
+     * are deployed here. The gate calls it to AVOID advertising a Permit2 `exact` rail it
+     * could never settle (a non-EIP-3009 token on a proxy-less chain — e.g. Binance-Peg
+     * USDC on a chain without the proxy). EIP-3009 needs no proxy, so this gates ONLY the
+     * Permit2 fallback. Omitted (or `false`) ⇒ treat Permit2 as unavailable on this chain.
+     */
+    exactPermit2Supported?(): boolean;
     /**
      * OPTIONAL (EVM-only today) — verify a standard x402 `exact` (EIP-3009) payment
      * locally, then SELF-SETTLE it by broadcasting `transferWithAuthorization` from the
@@ -6356,8 +6365,11 @@ declare class UnsupportedNetworkError extends PipRailError {
 
 /** x402 network slug → EVM chain id, for the chains PipRail ships an exact-payable
  *  stablecoin on — EIP-3009 USDC/EURC on most, and **Permit2** on BNB (Binance-Peg
- *  USDC isn't EIP-3009). Extend as needed; an unknown slug just won't be selected.
- *  (Matching uses CAIP-2 via `net.supports`; this is the public slug helper.) */
+ *  USDC isn't EIP-3009). This is a public REFERENCE/helper, NOT the runtime gate: the
+ *  gate offers `exact` on ANY EVM chain whose token is EIP-3009 (detected live via
+ *  `exactDomain`) or whose chain has the Permit2 proxy — so keep this list in sync with
+ *  what we've VERIFIED, but the rail isn't limited to it. An unknown slug → `null`.
+ *  (Matching uses CAIP-2 via `net.supports`.) */
 declare const EXACT_NETWORK_SLUGS: Readonly<Record<string, number>>;
 /** Resolve an x402 `exact` network slug (e.g. "base") to its EVM chain id. */
 declare function chainIdForExactNetwork(slug: string): number | null;
@@ -6620,10 +6632,20 @@ declare function readExactDomain(publicClient: PublicClient, asset: string): Pro
 
 /** Canonical Permit2 (Uniswap), same address on every EVM chain incl. BNB. */
 declare const PERMIT2_ADDRESS: "0x000000000022D473030F116dDEE9F6B43aC78BA3";
-/** Canonical x402ExactPermit2Proxy (CREATE2), same address on every EVM chain incl. BNB.
- *  It is the `spender` the buyer signs over, and the contract the seller settles through;
- *  it enforces `transferDetails.to == witness.to`, so funds can only reach the signed payTo. */
+/** Canonical x402ExactPermit2Proxy — the SAME CREATE2 address on every chain where it's been
+ *  deployed (see {@link PERMIT2_PROXY_CHAIN_IDS}; it is NOT on every EVM chain). It is the
+ *  `spender` the buyer signs over, and the contract the seller settles through; it enforces
+ *  `transferDetails.to == witness.to`, so funds can only reach the signed payTo. */
 declare const X402_EXACT_PERMIT2_PROXY: "0x402085c248EeA27D92E8b30b2C58ed07f9E20001";
+/** EVM chain ids where BOTH the canonical Permit2 AND the x402ExactPermit2Proxy are deployed —
+ *  i.e. where the **Permit2** transfer method of `exact` can actually settle. Verified on-chain
+ *  (`eth_getCode`, 2026-06-11). EIP-3009 needs NO proxy, so this gates only the Permit2 fallback;
+ *  on a non-EIP-3009 token on a chain absent here, the gate offers `onchain-proof` only rather
+ *  than an unsettleable Permit2 rail. The proxy is a permissionless CREATE2 deploy, so extend
+ *  this as it lands on more chains (re-verify before adding). */
+declare const PERMIT2_PROXY_CHAIN_IDS: ReadonlySet<number>;
+/** Whether a chain has the x402 Permit2 proxy deployed (→ can settle the Permit2 exact method). */
+declare function isPermit2ProxyChain(chainId: number): boolean;
 /**
  * EIP-712 type set for the x402 `permit2` exact method. MUST encode to exactly the type
  * string Permit2 reconstructs for `permitWitnessTransferFrom`:
@@ -6663,4 +6685,4 @@ declare const PERMIT2_WITNESS_TYPES: {
     }];
 };
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.d.ts

@@ -4357,6 +4357,15 @@ interface ResolvedNetwork {
         name: string;
         version: string;
     } | null>;
+    /**
+     * OPTIONAL (EVM-only) — whether this chain can carry the **Permit2** transfer method
+     * of the `exact` scheme: i.e. the canonical Permit2 **and** the `x402ExactPermit2Proxy`
+     * are deployed here. The gate calls it to AVOID advertising a Permit2 `exact` rail it
+     * could never settle (a non-EIP-3009 token on a proxy-less chain — e.g. Binance-Peg
+     * USDC on a chain without the proxy). EIP-3009 needs no proxy, so this gates ONLY the
+     * Permit2 fallback. Omitted (or `false`) ⇒ treat Permit2 as unavailable on this chain.
+     */
+    exactPermit2Supported?(): boolean;
     /**
      * OPTIONAL (EVM-only today) — verify a standard x402 `exact` (EIP-3009) payment
      * locally, then SELF-SETTLE it by broadcasting `transferWithAuthorization` from the
@@ -6356,8 +6365,11 @@ declare class UnsupportedNetworkError extends PipRailError {
 
 /** x402 network slug → EVM chain id, for the chains PipRail ships an exact-payable
  *  stablecoin on — EIP-3009 USDC/EURC on most, and **Permit2** on BNB (Binance-Peg
- *  USDC isn't EIP-3009). Extend as needed; an unknown slug just won't be selected.
- *  (Matching uses CAIP-2 via `net.supports`; this is the public slug helper.) */
+ *  USDC isn't EIP-3009). This is a public REFERENCE/helper, NOT the runtime gate: the
+ *  gate offers `exact` on ANY EVM chain whose token is EIP-3009 (detected live via
+ *  `exactDomain`) or whose chain has the Permit2 proxy — so keep this list in sync with
+ *  what we've VERIFIED, but the rail isn't limited to it. An unknown slug → `null`.
+ *  (Matching uses CAIP-2 via `net.supports`.) */
 declare const EXACT_NETWORK_SLUGS: Readonly<Record<string, number>>;
 /** Resolve an x402 `exact` network slug (e.g. "base") to its EVM chain id. */
 declare function chainIdForExactNetwork(slug: string): number | null;
@@ -6620,10 +6632,20 @@ declare function readExactDomain(publicClient: PublicClient, asset: string): Pro
 
 /** Canonical Permit2 (Uniswap), same address on every EVM chain incl. BNB. */
 declare const PERMIT2_ADDRESS: "0x000000000022D473030F116dDEE9F6B43aC78BA3";
-/** Canonical x402ExactPermit2Proxy (CREATE2), same address on every EVM chain incl. BNB.
- *  It is the `spender` the buyer signs over, and the contract the seller settles through;
- *  it enforces `transferDetails.to == witness.to`, so funds can only reach the signed payTo. */
+/** Canonical x402ExactPermit2Proxy — the SAME CREATE2 address on every chain where it's been
+ *  deployed (see {@link PERMIT2_PROXY_CHAIN_IDS}; it is NOT on every EVM chain). It is the
+ *  `spender` the buyer signs over, and the contract the seller settles through; it enforces
+ *  `transferDetails.to == witness.to`, so funds can only reach the signed payTo. */
 declare const X402_EXACT_PERMIT2_PROXY: "0x402085c248EeA27D92E8b30b2C58ed07f9E20001";
+/** EVM chain ids where BOTH the canonical Permit2 AND the x402ExactPermit2Proxy are deployed —
+ *  i.e. where the **Permit2** transfer method of `exact` can actually settle. Verified on-chain
+ *  (`eth_getCode`, 2026-06-11). EIP-3009 needs NO proxy, so this gates only the Permit2 fallback;
+ *  on a non-EIP-3009 token on a chain absent here, the gate offers `onchain-proof` only rather
+ *  than an unsettleable Permit2 rail. The proxy is a permissionless CREATE2 deploy, so extend
+ *  this as it lands on more chains (re-verify before adding). */
+declare const PERMIT2_PROXY_CHAIN_IDS: ReadonlySet<number>;
+/** Whether a chain has the x402 Permit2 proxy deployed (→ can settle the Permit2 exact method). */
+declare function isPermit2ProxyChain(chainId: number): boolean;
 /**
  * EIP-712 type set for the x402 `permit2` exact method. MUST encode to exactly the type
  * string Permit2 reconstructs for `permitWitnessTransferFrom`:
@@ -6663,4 +6685,4 @@ declare const PERMIT2_WITNESS_TYPES: {
     }];
 };
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.js

@@ -516,7 +516,15 @@ var EXACT_NETWORK_SLUGS = {
   polygon: 137,
   avalanche: 43114,
   bnb: 56,
-  bsc: 56
+  bsc: 56,
+  // EIP-3009 USDC verified on-chain (authorizationState present) — gasless, no proxy:
+  sonic: 146,
+  linea: 59144,
+  celo: 42220,
+  unichain: 130,
+  worldchain: 480,
+  sei: 1329,
+  hyperevm: 999
 };
 function chainIdForExactNetwork(slug) {
   return EXACT_NETWORK_SLUGS[slug] ?? null;
@@ -930,6 +938,37 @@ import {
 } from "viem";
 var PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
 var X402_EXACT_PERMIT2_PROXY = "0x402085c248EeA27D92E8b30b2C58ed07f9E20001";
+var PERMIT2_PROXY_CHAIN_IDS = /* @__PURE__ */ new Set([
+  1,
+  // Ethereum
+  8453,
+  // Base
+  84532,
+  // Base Sepolia
+  42161,
+  // Arbitrum
+  10,
+  // Optimism
+  137,
+  // Polygon
+  43114,
+  // Avalanche
+  56,
+  // BNB
+  42220,
+  // Celo
+  480,
+  // World Chain
+  1329,
+  // Sei
+  999,
+  // HyperEVM
+  143
+  // Monad
+]);
+function isPermit2ProxyChain(chainId) {
+  return PERMIT2_PROXY_CHAIN_IDS.has(chainId);
+}
 var PERMIT2_WITNESS_TYPES = {
   PermitWitnessTransferFrom: [
     { name: "permitted", type: "TokenPermissions" },
@@ -1660,6 +1699,11 @@ function makeEvmNetwork(resolved) {
     async exactDomain(asset) {
       return readExactDomain(publicClient, asset);
     },
+    // Whether the Permit2 transfer method can settle here (proxy deployed). EIP-3009
+    // needs no proxy; this only gates the Permit2 fallback for non-EIP-3009 tokens.
+    exactPermit2Supported() {
+      return isPermit2ProxyChain(resolved.chainId);
+    },
     async settleExactSelf({ relayer, payload, accept }) {
       const a = relayer._native;
       if ("permit2Authorization" in payload) {
@@ -4129,6 +4173,14 @@ function createPaymentGate(options) {
         method = "permit2";
       }
     }
+    if (method === "permit2" && !(net.exactPermit2Supported?.() ?? false)) {
+      if (cfg.method === "permit2") {
+        throw new Error(
+          `requirePayment: exact \`method: 'permit2'\` needs the x402 Permit2 proxy deployed on ${net.network}, but it isn't there. Offer an EIP-3009 token (gasless, no proxy), or drop \`exact\` on this chain. (See PERMIT2_PROXY_CHAIN_IDS.)`
+        );
+      }
+      return void 0;
+    }
     if (cfg.settle === "self") {
       if (cfg.relayer === void 0) {
         throw new Error(
@@ -4566,6 +4618,7 @@ export {
   NoCompatibleAcceptError,
   NonReplayableBodyError,
   PERMIT2_ADDRESS,
+  PERMIT2_PROXY_CHAIN_IDS,
   PERMIT2_WITNESS_TYPES,
   PIPRAIL_AGENT_GUIDE,
   PaymentDeclinedError,
@@ -4602,6 +4655,7 @@ export {
   explainDecline,
   formatSpendReport,
   getDirectoryInfo,
+  isPermit2ProxyChain,
   normalizeNetwork,
   parseChallenge,
   parseExactPaymentHeader,

package/package.json

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