@piprail/sdk 2.14.2 → 2.15.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.15.0] — 2026-06-24 — merchant on-ramp: presets, adapters, `gate.selfTest()`
+
+### Added — merchant on-ramp (presets, adapters, self-test)
+
+Make the *accept* side as terse as the *pay* side. All additive — the zero-config
+`createPaymentGate` / `requirePayment` / `PipRailClient` paths stay byte-identical.
+
+- **Merchant presets** — `createPaywall` (a fixed price for a resource) and `createTipJar`
+  (pay-what-you-want ≥ a minimum): named sugar over `createPaymentGate` with `token` defaulting to
+  USDC. Each resolves to a standard gate, so its 402 is byte-identical to the hand-written equivalent.
+- **Framework adapters** — `toFetchHandler` (the universal `(request, …) => Response` for Next.js,
+  Netlify, Bun, Deno, Vercel, Hono, Lambda — anything request-in/response-out) and `toWorker` (the
+  `{ fetch }` export for Cloudflare / Service Workers). One call runs the whole read-header →
+  switch-on-`kind` → write-headers contract (502 on a `SettlementError`, never 402) and forwards any
+  extra runtime args (`env`/`ctx`/`params`) to your handler. Express keeps `requirePayment`.
+- **`proxyTo(origin)`** — a ready-made `serve` that forwards a PAID request to an existing backend (any
+  language), untouched, stripping the proof headers; the origin never sees an unpaid request.
+  `toWorker(gate, proxyTo('https://my-api.com'))` puts a paywall in front of a whole API.
+- **`gate.selfTest()`** — a read-only, never-throw config check that resolves the gate's rails and
+  reports `{ ok, rails, warnings }` (or `{ ok:false, error }`) without signing or sending. Powers a
+  merchant's `npm run verify` and a scaffolder's post-deploy smoke step.
+- New exports: `createPaywall`, `createTipJar`, `toFetchHandler`, `toWorker`, `proxyTo`; types
+  `PaywallOptions`, `TipJarOptions`, `Serve`, `GateSelfTest`.
+
 ## [2.14.2] — 2026-06-24 — deeper element-level hardening (the 2.14.1 break-it pass, round two)
 
 A follow-up patch to 2.14.1. A second adversarial smash pass found that 2.14.1 guarded the
@@ -1828,6 +1852,7 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[2.15.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.14.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.13.1]: https://www.npmjs.com/package/@piprail/sdk
 [2.12.0]: https://www.npmjs.com/package/@piprail/sdk

package/README.md

@@ -26,6 +26,8 @@ app.get('/report',
 
 That route now costs **0.05 USDC on Base**, paid straight to your wallet. One parameter picks the chain. Add `onPaid` / `onFailed` to be notified the moment a payment settles or is rejected — both carry the same reason, and the buyer's client is notified too. → [Accepting payments](https://docs.piprail.com/accepting-payments/require-payment-and-gate/)
 
+> **Don't want to wire it by hand?** `npm create piprail@latest` scaffolds a complete, mainnet-ready, deployable merchant (node / Cloudflare / Vercel) — paste a public address, no key, no account. → [Scaffold a merchant](https://docs.piprail.com/getting-started/scaffolder/)
+
 ## Let an agent pay for it
 
 ```ts
@@ -74,7 +76,7 @@ The same app can **take** payments and **make** them. → [Making payments](http
 | | |
 |---|---|
 | **[Getting started](https://docs.piprail.com/getting-started/introduction/)** | Install · quickstart · how it works |
-| **[Accepting payments](https://docs.piprail.com/accepting-payments/require-payment-and-gate/)** | `requirePayment` · `createPaymentGate` · the `exact` rail · the `upto` metered rail |
+| **[Accepting payments](https://docs.piprail.com/accepting-payments/require-payment-and-gate/)** | `requirePayment` · `createPaymentGate` · [presets](https://docs.piprail.com/accepting-payments/merchant-presets/) (`createPaywall` / `createTipJar`) · [framework adapters](https://docs.piprail.com/accepting-payments/framework-adapters/) · the `exact` rail · the `upto` metered rail |
 | **[Making payments](https://docs.piprail.com/making-payments/piprail-client/)** | `PipRailClient` · `quote` · `estimateCost` · `planPayment` · auto-route · `MultiChainPayer` |
 | **[Verifiable receipts](https://docs.piprail.com/accepting-payments/verifiable-receipts/)** | Chain-grounded, anyone-verifiable receipts (no key) · optional EIP-712 attestation |
 | **[Spend controls](https://docs.piprail.com/spend-controls/payment-policy/)** | Per-token + cross-token grand total · payment-count caps · time envelope · durable budget · the spend ledger |

package/dist/index.cjs

@@ -7499,7 +7499,36 @@ function createPaymentGate(options) {
     await settleTx(idKey, result.kind === "paid");
     return result.kind === "paid" ? echoPaymentIdentifier(result, id) : result;
   }
-  return { challenge, verify, verifyObject, describe, landingPage };
+  async function selfTest() {
+    try {
+      const specs = await ready();
+      const warnings = [];
+      const rails = specs.map((s) => {
+        if (!s.symbol) {
+          warnings.push(
+            `${s.asset} on ${s.net.network}: custom token (no built-in symbol) \u2014 double-check the address + decimals.`
+          );
+        }
+        return {
+          network: s.net.network,
+          asset: s.asset,
+          ...s.symbol ? { symbol: s.symbol } : {},
+          decimals: s.decimals,
+          amount: s.amountFormatted,
+          payTo: s.payTo,
+          schemes: [
+            ...s.exact ? ["exact"] : [],
+            ...s.upto ? ["upto"] : [],
+            "onchain-proof"
+          ]
+        };
+      });
+      return { ok: true, rails, warnings };
+    } catch (err) {
+      return { ok: false, rails: [], warnings: [], error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  return { challenge, verify, verifyObject, describe, landingPage, selfTest };
 }
 function requirePayment(options) {
   if (options.upto) {
@@ -7551,6 +7580,87 @@ function normaliseHeader(value) {
   return value;
 }
 
+// src/merchant.ts
+function createPaywall({ token = "USDC", ...rest }) {
+  return createPaymentGate({ token, ...rest });
+}
+function createTipJar({ token = "USDC", min, ...rest }) {
+  return createPaymentGate({ token, amount: min, ...rest });
+}
+
+// src/adapters.ts
+function jsonResponse(body, status, headers) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", ..._nullishCoalesce(headers, () => ( {})) }
+  });
+}
+function withSettlementHeaders(res, receiptHeader) {
+  const headers = new Headers();
+  res.headers.forEach((value, key) => {
+    if (key.toLowerCase() !== "set-cookie") headers.append(key, value);
+  });
+  const src = res.headers;
+  const cookies = typeof src.getSetCookie === "function" ? src.getSetCookie() : (() => {
+    const combined = res.headers.get("set-cookie");
+    return combined ? [combined] : [];
+  })();
+  for (const cookie of cookies) headers.append("set-cookie", cookie);
+  headers.set(HEADER_RESPONSE, receiptHeader);
+  headers.set(HEADER_RESPONSE_V1, receiptHeader);
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+function toFetchHandler(gate, serve) {
+  return async (request, ...rest) => {
+    let result;
+    try {
+      const sig = _nullishCoalesce(_nullishCoalesce(request.headers.get(HEADER_SIGNATURE), () => ( request.headers.get(HEADER_SIGNATURE_V1))), () => ( void 0));
+      result = await gate.verify(sig);
+    } catch (err) {
+      if (err instanceof _chunk3FR22M3Ocjs.SettlementError) {
+        return jsonResponse(
+          {
+            x402Version: 2,
+            error: "settlement_failed",
+            detail: err.message,
+            fallback: "The gasless `exact` settlement failed. This resource also accepts `onchain-proof` \u2014 retry by paying that rail yourself (you broadcast the transfer and pay the gas)."
+          },
+          502
+        );
+      }
+      throw err;
+    }
+    if (result.kind === "paid") {
+      const res = await serve(request, ...rest);
+      return withSettlementHeaders(res, result.receiptHeader);
+    }
+    return jsonResponse(result.challenge, 402, { [HEADER_REQUIRED]: result.requiredHeader });
+  };
+}
+function toWorker(gate, serve) {
+  return { fetch: toFetchHandler(gate, serve) };
+}
+function proxyTo(origin) {
+  const base2 = origin.replace(/\/+$/, "");
+  return (request) => {
+    const inUrl = new URL(request.url);
+    const target = base2 + inUrl.pathname + inUrl.search;
+    const headers = new Headers(request.headers);
+    headers.delete(HEADER_SIGNATURE);
+    headers.delete(HEADER_SIGNATURE_V1);
+    const init = {
+      method: request.method,
+      headers,
+      redirect: "manual"
+    };
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      init.body = request.body;
+      init.duplex = "half";
+    }
+    return fetch(target, init);
+  };
+}
+
 // src/receipts.ts
 var DEFAULT_RETRIES = 5;
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -8155,4 +8265,9 @@ function createMcpPaymentTool(options) {
 
 
 
-exports.A2A_ERROR_KEY = A2A_ERROR_KEY; exports.A2A_EXTENSIONS_HEADER = A2A_EXTENSIONS_HEADER; exports.A2A_PAYLOAD_KEY = A2A_PAYLOAD_KEY; exports.A2A_RECEIPTS_KEY = A2A_RECEIPTS_KEY; exports.A2A_REQUIRED_KEY = A2A_REQUIRED_KEY; exports.A2A_STATUS_KEY = A2A_STATUS_KEY; exports.A2A_X402_EXTENSION_URI_V01 = A2A_X402_EXTENSION_URI_V01; exports.A2A_X402_EXTENSION_URI_V02 = A2A_X402_EXTENSION_URI_V02; exports.BRAND = BRAND; exports.BUILTIN_DENOMS = BUILTIN_DENOMS; exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunk3FR22M3Ocjs.ConfirmationTimeoutError; exports.DENOM_PRECISION = DENOM_PRECISION; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.EXT_OFFER_RECEIPT = EXT_OFFER_RECEIPT; exports.EXT_PAYMENT_IDENTIFIER = EXT_PAYMENT_IDENTIFIER; 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 = _chunk3FR22M3Ocjs.InsufficientFundsError; exports.InvalidConfigError = _chunk3FR22M3Ocjs.InvalidConfigError; exports.InvalidEnvelopeError = _chunk3FR22M3Ocjs.InvalidEnvelopeError; exports.KNOWN_FACILITATORS = KNOWN_FACILITATORS; exports.MCP_PAYMENT_META_KEY = MCP_PAYMENT_META_KEY; exports.MCP_PAYMENT_RESPONSE_META_KEY = MCP_PAYMENT_RESPONSE_META_KEY; exports.MaxRetriesExceededError = _chunk3FR22M3Ocjs.MaxRetriesExceededError; exports.MissingDriverError = _chunk3FR22M3Ocjs.MissingDriverError; exports.MultiChainPayer = MultiChainPayer; exports.NoCompatibleAcceptError = _chunk3FR22M3Ocjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunk3FR22M3Ocjs.NonReplayableBodyError; exports.PERMIT2_ADDRESS = PERMIT2_ADDRESS; exports.PERMIT2_PROXY_CHAIN_IDS = PERMIT2_PROXY_CHAIN_IDS; exports.PERMIT2_UPTO_WITNESS_TYPES = PERMIT2_UPTO_WITNESS_TYPES; exports.PERMIT2_WITNESS_TYPES = PERMIT2_WITNESS_TYPES; exports.PIPRAIL_AGENT_GUIDE = PIPRAIL_AGENT_GUIDE; exports.POWERED_BY = POWERED_BY; exports.PaymentDeclinedError = _chunk3FR22M3Ocjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunk3FR22M3Ocjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunk3FR22M3Ocjs.PipRailError; exports.REGISTER_ATTRIBUTION = REGISTER_ATTRIBUTION; exports.RecipientNotReadyError = _chunk3FR22M3Ocjs.RecipientNotReadyError; exports.SettlementError = _chunk3FR22M3Ocjs.SettlementError; exports.SpendLedger = SpendLedger; exports.UPTO_PROXY_CHAIN_IDS = UPTO_PROXY_CHAIN_IDS; exports.UnknownTokenError = _chunk3FR22M3Ocjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunk3FR22M3Ocjs.UnsupportedNetworkError; exports.UnsupportedSchemeError = _chunk3FR22M3Ocjs.UnsupportedSchemeError; exports.VERIFY_CODE_TO_A2A_ERROR = VERIFY_CODE_TO_A2A_ERROR; exports.WalletRequiredError = _chunk3FR22M3Ocjs.WalletRequiredError; exports.WrongChainError = _chunk3FR22M3Ocjs.WrongChainError; exports.WrongFamilyError = _chunk3FR22M3Ocjs.WrongFamilyError; exports.X402_EXACT_PERMIT2_PROXY = X402_EXACT_PERMIT2_PROXY; exports.X402_UPTO_PERMIT2_PROXY = X402_UPTO_PERMIT2_PROXY; exports.agentGuide = agentGuide; exports.appendAttribution = appendAttribution; exports.appendKeywords = appendKeywords; exports.buildBazaarExtension = buildBazaarExtension; exports.buildChallengeHeader = buildChallengeHeader; exports.buildEndpointInfo = buildEndpointInfo; exports.buildExactAuthorization = buildExactAuthorization; exports.buildExactSignatureHeader = buildExactSignatureHeader; exports.buildMcpPaymentMeta = buildMcpPaymentMeta; exports.buildOpenApi = buildOpenApi; exports.buildPaymentIdentifierAdvertisement = buildPaymentIdentifierAdvertisement; exports.buildReceiptExtension = buildReceiptExtension; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSelfDescription = buildSelfDescription; exports.buildSignatureHeader = buildSignatureHeader; exports.buildUptoSignatureHeader = buildUptoSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildWellKnownX402Manifest = buildWellKnownX402Manifest; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.classifyChallenge = classifyChallenge; exports.createA2APaymentHandler = createA2APaymentHandler; exports.createMcpPaymentTool = createMcpPaymentTool; exports.createPaymentGate = createPaymentGate; exports.decodeBase64Json = decodeBase64Json; exports.decorateOutcome = decorateOutcome; exports.deliverReceipt = deliverReceipt; exports.denomOf = denomOf; exports.describeChallenge = describeChallenge; exports.discoveryHeaders = discoveryHeaders; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.explainDecline = explainDecline; exports.facilitatorCoverage = facilitatorCoverage; exports.fetchAcross = fetchAcross; exports.firstKeylessFacilitator = firstKeylessFacilitator; exports.formatSpendReport = formatSpendReport; exports.fromA2APaymentPayload = fromA2APaymentPayload; exports.fromA2APaymentRequired = fromA2APaymentRequired; exports.fromMcpPayment = fromMcpPayment; exports.fromMcpPaymentRequired = fromMcpPaymentRequired; exports.fromMcpPaymentResponse = fromMcpPaymentResponse; exports.getDirectoryInfo = getDirectoryInfo; exports.isMcpPaymentRequired = isMcpPaymentRequired; exports.isPermit2ProxyChain = isPermit2ProxyChain; exports.isUptoProxyChain = isUptoProxyChain; exports.knownFacilitatorsFor = knownFacilitatorsFor; exports.memorySpendStore = _chunkO4UQOZ4Zcjs.memorySpendStore; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactObject = parseExactObject; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseFacilitatorSupported = parseFacilitatorSupported; exports.parseReceipt = parseReceipt; exports.parseReceiptExtension = parseReceiptExtension; exports.parseSettleResponse = parseSettleResponse; exports.parseSignatureHeader = parseSignatureHeader; exports.parseSignatureObject = parseSignatureObject; exports.parseUptoObject = parseUptoObject; exports.parseUptoPaymentHeader = parseUptoPaymentHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.rankResources = rankResources; exports.readExactDomain = readExactDomain; exports.readPaymentIdentifier = readPaymentIdentifier; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.renderLandingPage = renderLandingPage; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.scoreResource = scoreResource; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.summarizePlan = summarizePlan; exports.toA2AErrorCode = toA2AErrorCode; exports.toA2APaymentFailed = toA2APaymentFailed; exports.toA2APaymentReceipts = toA2APaymentReceipts; exports.toA2APaymentRequired = toA2APaymentRequired; exports.toInsufficientFundsError = _chunk3FR22M3Ocjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.toMcpPaymentRequired = toMcpPaymentRequired; exports.toMcpPaymentResponse = toMcpPaymentResponse; exports.verify402IndexDomain = verify402IndexDomain;
+
+
+
+
+
+exports.A2A_ERROR_KEY = A2A_ERROR_KEY; exports.A2A_EXTENSIONS_HEADER = A2A_EXTENSIONS_HEADER; exports.A2A_PAYLOAD_KEY = A2A_PAYLOAD_KEY; exports.A2A_RECEIPTS_KEY = A2A_RECEIPTS_KEY; exports.A2A_REQUIRED_KEY = A2A_REQUIRED_KEY; exports.A2A_STATUS_KEY = A2A_STATUS_KEY; exports.A2A_X402_EXTENSION_URI_V01 = A2A_X402_EXTENSION_URI_V01; exports.A2A_X402_EXTENSION_URI_V02 = A2A_X402_EXTENSION_URI_V02; exports.BRAND = BRAND; exports.BUILTIN_DENOMS = BUILTIN_DENOMS; exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunk3FR22M3Ocjs.ConfirmationTimeoutError; exports.DENOM_PRECISION = DENOM_PRECISION; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.EXT_OFFER_RECEIPT = EXT_OFFER_RECEIPT; exports.EXT_PAYMENT_IDENTIFIER = EXT_PAYMENT_IDENTIFIER; 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 = _chunk3FR22M3Ocjs.InsufficientFundsError; exports.InvalidConfigError = _chunk3FR22M3Ocjs.InvalidConfigError; exports.InvalidEnvelopeError = _chunk3FR22M3Ocjs.InvalidEnvelopeError; exports.KNOWN_FACILITATORS = KNOWN_FACILITATORS; exports.MCP_PAYMENT_META_KEY = MCP_PAYMENT_META_KEY; exports.MCP_PAYMENT_RESPONSE_META_KEY = MCP_PAYMENT_RESPONSE_META_KEY; exports.MaxRetriesExceededError = _chunk3FR22M3Ocjs.MaxRetriesExceededError; exports.MissingDriverError = _chunk3FR22M3Ocjs.MissingDriverError; exports.MultiChainPayer = MultiChainPayer; exports.NoCompatibleAcceptError = _chunk3FR22M3Ocjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunk3FR22M3Ocjs.NonReplayableBodyError; exports.PERMIT2_ADDRESS = PERMIT2_ADDRESS; exports.PERMIT2_PROXY_CHAIN_IDS = PERMIT2_PROXY_CHAIN_IDS; exports.PERMIT2_UPTO_WITNESS_TYPES = PERMIT2_UPTO_WITNESS_TYPES; exports.PERMIT2_WITNESS_TYPES = PERMIT2_WITNESS_TYPES; exports.PIPRAIL_AGENT_GUIDE = PIPRAIL_AGENT_GUIDE; exports.POWERED_BY = POWERED_BY; exports.PaymentDeclinedError = _chunk3FR22M3Ocjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunk3FR22M3Ocjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunk3FR22M3Ocjs.PipRailError; exports.REGISTER_ATTRIBUTION = REGISTER_ATTRIBUTION; exports.RecipientNotReadyError = _chunk3FR22M3Ocjs.RecipientNotReadyError; exports.SettlementError = _chunk3FR22M3Ocjs.SettlementError; exports.SpendLedger = SpendLedger; exports.UPTO_PROXY_CHAIN_IDS = UPTO_PROXY_CHAIN_IDS; exports.UnknownTokenError = _chunk3FR22M3Ocjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunk3FR22M3Ocjs.UnsupportedNetworkError; exports.UnsupportedSchemeError = _chunk3FR22M3Ocjs.UnsupportedSchemeError; exports.VERIFY_CODE_TO_A2A_ERROR = VERIFY_CODE_TO_A2A_ERROR; exports.WalletRequiredError = _chunk3FR22M3Ocjs.WalletRequiredError; exports.WrongChainError = _chunk3FR22M3Ocjs.WrongChainError; exports.WrongFamilyError = _chunk3FR22M3Ocjs.WrongFamilyError; exports.X402_EXACT_PERMIT2_PROXY = X402_EXACT_PERMIT2_PROXY; exports.X402_UPTO_PERMIT2_PROXY = X402_UPTO_PERMIT2_PROXY; exports.agentGuide = agentGuide; exports.appendAttribution = appendAttribution; exports.appendKeywords = appendKeywords; exports.buildBazaarExtension = buildBazaarExtension; exports.buildChallengeHeader = buildChallengeHeader; exports.buildEndpointInfo = buildEndpointInfo; exports.buildExactAuthorization = buildExactAuthorization; exports.buildExactSignatureHeader = buildExactSignatureHeader; exports.buildMcpPaymentMeta = buildMcpPaymentMeta; exports.buildOpenApi = buildOpenApi; exports.buildPaymentIdentifierAdvertisement = buildPaymentIdentifierAdvertisement; exports.buildReceiptExtension = buildReceiptExtension; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSelfDescription = buildSelfDescription; exports.buildSignatureHeader = buildSignatureHeader; exports.buildUptoSignatureHeader = buildUptoSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildWellKnownX402Manifest = buildWellKnownX402Manifest; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.classifyChallenge = classifyChallenge; exports.createA2APaymentHandler = createA2APaymentHandler; exports.createMcpPaymentTool = createMcpPaymentTool; exports.createPaymentGate = createPaymentGate; exports.createPaywall = createPaywall; exports.createTipJar = createTipJar; exports.decodeBase64Json = decodeBase64Json; exports.decorateOutcome = decorateOutcome; exports.deliverReceipt = deliverReceipt; exports.denomOf = denomOf; exports.describeChallenge = describeChallenge; exports.discoveryHeaders = discoveryHeaders; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.explainDecline = explainDecline; exports.facilitatorCoverage = facilitatorCoverage; exports.fetchAcross = fetchAcross; exports.firstKeylessFacilitator = firstKeylessFacilitator; exports.formatSpendReport = formatSpendReport; exports.fromA2APaymentPayload = fromA2APaymentPayload; exports.fromA2APaymentRequired = fromA2APaymentRequired; exports.fromMcpPayment = fromMcpPayment; exports.fromMcpPaymentRequired = fromMcpPaymentRequired; exports.fromMcpPaymentResponse = fromMcpPaymentResponse; exports.getDirectoryInfo = getDirectoryInfo; exports.isMcpPaymentRequired = isMcpPaymentRequired; exports.isPermit2ProxyChain = isPermit2ProxyChain; exports.isUptoProxyChain = isUptoProxyChain; exports.knownFacilitatorsFor = knownFacilitatorsFor; exports.memorySpendStore = _chunkO4UQOZ4Zcjs.memorySpendStore; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactObject = parseExactObject; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseFacilitatorSupported = parseFacilitatorSupported; exports.parseReceipt = parseReceipt; exports.parseReceiptExtension = parseReceiptExtension; exports.parseSettleResponse = parseSettleResponse; exports.parseSignatureHeader = parseSignatureHeader; exports.parseSignatureObject = parseSignatureObject; exports.parseUptoObject = parseUptoObject; exports.parseUptoPaymentHeader = parseUptoPaymentHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.proxyTo = proxyTo; exports.rankResources = rankResources; exports.readExactDomain = readExactDomain; exports.readPaymentIdentifier = readPaymentIdentifier; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.renderLandingPage = renderLandingPage; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.scoreResource = scoreResource; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.summarizePlan = summarizePlan; exports.toA2AErrorCode = toA2AErrorCode; exports.toA2APaymentFailed = toA2APaymentFailed; exports.toA2APaymentReceipts = toA2APaymentReceipts; exports.toA2APaymentRequired = toA2APaymentRequired; exports.toFetchHandler = toFetchHandler; exports.toInsufficientFundsError = _chunk3FR22M3Ocjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.toMcpPaymentRequired = toMcpPaymentRequired; exports.toMcpPaymentResponse = toMcpPaymentResponse; exports.toWorker = toWorker; exports.verify402IndexDomain = verify402IndexDomain;

package/dist/index.d.cts

@@ -7169,6 +7169,34 @@ declare function toInvalidBody(result: {
     error: string;
     detail: string;
 }): X402InvalidBody;
+/**
+ * The result of {@link PaymentGate.selfTest} — a read-only config check. NEVER throws, and never
+ * touches the network beyond the same lazy driver/token resolution the first `challenge()` does
+ * (no signing, no sending). `ok:true` with the resolved `rails` when the config is sound; `ok:false`
+ * with a human `error` when something's wrong (no payTo, a malformed address for the family, an
+ * unknown token, an unresolvable chain). Powers a scaffolder's "✅ your endpoint is configured"
+ * step and a merchant's `npm run verify`.
+ */
+interface GateSelfTest {
+    ok: boolean;
+    /** One entry per resolved payment option (empty when `ok:false`). */
+    rails: Array<{
+        /** CAIP-2 network, e.g. `eip155:8453`. */
+        network: string;
+        asset: string;
+        symbol?: string;
+        decimals: number;
+        /** Human amount the gate charges (for a tip jar, the minimum/floor). */
+        amount: string;
+        payTo: AddressId;
+        /** The schemes this rail offers, e.g. `['onchain-proof']` or `['exact', 'onchain-proof']`. */
+        schemes: string[];
+    }>;
+    /** Non-fatal nudges (e.g. a custom token with no built-in symbol to double-check). */
+    warnings: string[];
+    /** Present only when `ok:false` — the human reason the config can't serve a payment. */
+    error?: string;
+}
 interface PaymentGate {
     /** Build a fresh 402 challenge (new nonce) for a resource URL. */
     challenge(resourceUrl?: string): Promise<{
@@ -7203,6 +7231,13 @@ interface PaymentGate {
      * The SDK never serves it itself (headless by charter). Agents/crawlers keep the JSON 402.
      */
     landingPage(challenge: X402Challenge): string;
+    /**
+     * Read-only config check — resolve the gate's rails WITHOUT signing or sending, and report what
+     * it would charge (or why it can't). Never throws; runs the same lazy resolution as the first
+     * `challenge()`. The merchant's "did I wire this right?" and a scaffolder's post-deploy smoke
+     * step. See {@link GateSelfTest}.
+     */
+    selfTest(): Promise<GateSelfTest>;
 }
 declare function createPaymentGate(options: RequirePaymentOptions): PaymentGate;
 interface ExpressLikeRequest {
@@ -7224,6 +7259,110 @@ type ExpressLikeMiddleware = (req: ExpressLikeRequest, res: ExpressLikeResponse,
  */
 declare function requirePayment(options: RequirePaymentOptions): ExpressLikeMiddleware;
 
+/**
+ * The advanced gate options a preset forwards verbatim — every {@link RequirePaymentOptions} field
+ * EXCEPT the `chain`/`token`/`amount`/`payTo` quartet (each preset re-declares those with its own
+ * shape) and the multi-chain `accept` array (use {@link createPaymentGate} directly for a multi-rail
+ * gate). So `onPaid`, `exact`, `receipts`, `discovery`, `isUsed`/`markUsed`, … all pass through.
+ */
+type GateExtras = Omit<RequirePaymentOptions, 'chain' | 'token' | 'amount' | 'payTo' | 'accept'>;
+/** Options for {@link createPaywall}. */
+interface PaywallOptions extends GateExtras {
+    /** Which chain to be paid on. EVM (`'base'`|`'bnb'`|…) or a non-EVM family name. */
+    chain: ChainSelector;
+    /** Token to charge in. Defaults to **USDC**. */
+    token?: TokenInput;
+    /** The fixed price, human-readable, e.g. `'0.05'`. */
+    amount: string;
+    /** Your receiving wallet address — no private key (receiving needs only the address). */
+    payTo: AddressId;
+}
+/**
+ * Gate one resource behind a fixed price — the API / SaaS / premium-content case. Sugar over
+ * {@link createPaymentGate} with `token` defaulting to USDC; every other gate option is forwarded
+ * unchanged, so the resulting gate (and its 402) is identical to the hand-written equivalent.
+ */
+declare function createPaywall({ token, ...rest }: PaywallOptions): PaymentGate;
+/** Options for {@link createTipJar}. */
+interface TipJarOptions extends GateExtras {
+    /** Which chain to be paid on. */
+    chain: ChainSelector;
+    /** Token to accept. Defaults to **USDC**. */
+    token?: TokenInput;
+    /**
+     * The MINIMUM tip, human-readable, e.g. `'1.00'`. The gate accepts any payment **≥ min** — the
+     * on-chain verify rejects only an under-payment (`amount_too_low`), so a payer can always give
+     * more. There is no upper bound; the minimum is a floor, not a fixed price.
+     */
+    min: string;
+    /** Your receiving wallet address. */
+    payTo: AddressId;
+}
+/**
+ * An open "pay what you want (≥ a minimum)" gate — the creator / tip / donation case. Sugar over
+ * {@link createPaymentGate} that sets the challenge `amount` to `min`; because the gate accepts an
+ * over-payment, the minimum is a floor. Everything else (`onPaid`, etc.) forwards unchanged.
+ */
+declare function createTipJar({ token, min, ...rest }: TipJarOptions): PaymentGate;
+
+/**
+ * Built-in framework adapters — turn a {@link PaymentGate} into a request handler for any
+ * WHATWG-`fetch` runtime. There are only TWO real shapes among fetch runtimes, so there are two
+ * adapters: a plain handler **function** (Next.js, Netlify, Bun, Deno, Vercel Edge, Hono, Lambda),
+ * and the `{ fetch }` **export object** (Cloudflare / Service Workers). Both run the same contract:
+ * read the proof header, switch on the {@link VerifyPaymentResult} `kind`, write the right status +
+ * headers back out — so a merchant's route is a single call instead of a switch.
+ *
+ *   import { createPaywall, toFetchHandler, toWorker } from '@piprail/sdk'
+ *   const gate = createPaywall({ chain: 'base', amount: '0.05', payTo: '0xYourWallet' })
+ *
+ *   export const GET = toFetchHandler(gate, () => Response.json({ secret: 42 }))  // Next / Netlify / Bun / Deno / Hono …
+ *   export default  toWorker(gate, () => Response.json({ secret: 42 }))           // a Cloudflare Worker
+ *
+ * Pure + browser-safe — Web `Request`/`Response`/`Headers` only (no viem, no `node:`). Express keeps
+ * its dedicated {@link requirePayment} middleware; a Node-native framework with its own `req`/`reply`
+ * (Fastify, …) drives `gate.verify()` directly (see the framework-adapters docs). {@link proxyTo} is a
+ * ready-made `serve` that forwards paid requests to an existing backend — gate any API, any language.
+ */
+
+/**
+ * What to serve once a payment is verified — your protected resource, as a Web `Response`. It
+ * receives the original `request` **plus whatever extra arguments the runtime passed the handler**
+ * (a Cloudflare Worker's `env`/`ctx`, a Next.js route `context` with `params`, …), forwarded
+ * untouched — so a protected handler can reach framework context without a second wrapper.
+ */
+type Serve = (request: Request, ...rest: unknown[]) => Response | Promise<Response>;
+/**
+ * The universal adapter: wrap a gate as a `fetch` handler `(request, ...rest) => Response`. Drop the
+ * result into **any** runtime that hands a handler a `Request` and wants a `Response` back — Next.js
+ * route handlers (`export const GET = …`), Netlify Functions, `Bun.serve({ fetch })`,
+ * `Deno.serve(…)`, Vercel Edge, Hono (`(c) => handler(c.req.raw)`), an AWS Lambda Web adapter, Fastly
+ * Compute. Any extra runtime arguments are forwarded to `serve` untouched.
+ *
+ * - **settled payment** → calls `serve`, returns its `Response` with the `payment-response` headers (v2 + v1) added;
+ * - **missing / rejected proof** → a conformant `402` carrying the full challenge (so a standard x402 client can retry);
+ * - **server-side settle failure** ({@link SettlementError}) → `502` — NEVER `402` (the buyer's authorization is still valid + unused).
+ */
+declare function toFetchHandler(gate: PaymentGate, serve: Serve): (request: Request, ...rest: unknown[]) => Promise<Response>;
+/**
+ * The `{ fetch }` export object for runtimes that take one — Cloudflare Workers / Service Workers:
+ * `export default toWorker(gate, serve)`. Identical behaviour to {@link toFetchHandler}; the
+ * runtime's `fetch(request, env, ctx)` arguments are forwarded to `serve` (so it can read bindings /
+ * `ctx.waitUntil`). (Other runtimes that take an object — `Bun.serve`, `Deno.serve` — can use either
+ * this or `toFetchHandler` in their `fetch` field.)
+ */
+declare function toWorker(gate: PaymentGate, serve: Serve): {
+    fetch: (request: Request, ...rest: unknown[]) => Promise<Response>;
+};
+/**
+ * A {@link Serve} that forwards the (already-paid) request to an upstream `origin`, untouched — so you
+ * can put a payment gate in FRONT of an existing API in any language, without changing it. Preserves
+ * the method, path, query, body, and headers; strips the x402 proof headers so they don't leak
+ * upstream. The origin NEVER sees an unpaid request — the gate rejects those before `serve` runs.
+ * Compose with the adapters: `toWorker(gate, proxyTo('https://my-api.example.com'))`.
+ */
+declare function proxyTo(origin: string): Serve;
+
 /**
  * Mode-B settlement: delegate a standard `exact` payment to a THIRD-PARTY x402
  * facilitator the MERCHANT chooses (Coinbase CDP, x402.org, or any). PipRail hosts
@@ -8396,4 +8535,4 @@ interface McpPaymentTool {
  */
 declare function createMcpPaymentTool(options: McpPaymentToolOptions): McpPaymentTool;
 
-export { type A2AArtifact, type A2AExtensionDeclaration, type A2AMessage, type A2AMetadata, type A2APart, type A2APaymentHandler, type A2APaymentHandlerOptions, type A2APaymentStatus, type A2ATask, type A2ATaskRecord, type A2ATaskState, type A2ATaskStore, A2A_ERROR_KEY, A2A_EXTENSIONS_HEADER, A2A_PAYLOAD_KEY, A2A_RECEIPTS_KEY, A2A_REQUIRED_KEY, A2A_STATUS_KEY, A2A_X402_EXTENSION_URI_V01, A2A_X402_EXTENSION_URI_V02, type AcceptOption, AddressId, type AgentTool, type AlgorandToken, type AptosToken, AssetId, BRAND, BUILTIN_DENOMS, type BazaarExtension, type BuildExactParams, CHAINS, Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type CountStatus, DENOM_PRECISION, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DenomRemaining, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, InsufficientFundsError, InvalidConfigError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, MCP_PAYMENT_META_KEY, MCP_PAYMENT_RESPONSE_META_KEY, type ManifestInput, MaxRetriesExceededError, type McpContentBlock, type McpPaymentMeta, type McpPaymentTool, type McpPaymentToolOptions, type McpToolCallParams, type McpToolResult, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_UPTO_WITNESS_TYPES, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, PaidReceipt, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, Permit2UptoPaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, PipRailReceipt, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, type ReceiptInput, type ReceiptOption, type ReceiptVerification, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, SettleOutcome, type SettleViaFacilitatorInput, SettlementError, SignedReceipt, type SolanaToken, SpendLedger, SpendRecord, type SpendRemaining, SpendStore, SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UPTO_PROXY_CHAIN_IDS, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type UptoRailOption, VERIFY_CODE_TO_A2A_ERROR, VerifyErrorCode, type VerifyPaymentResult, VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, type WellKnownX402Item, type WellKnownX402Manifest, WrongChainError, WrongFamilyError, X402AcceptEntry, X402AnyAccept, X402Challenge, type X402DnsRecord, X402ExactAcceptEntry, type X402InvalidBody, X402Receipt, X402UptoAcceptEntry, X402_EXACT_PERMIT2_PROXY, X402_UPTO_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildEndpointInfo, buildExactAuthorization, buildMcpPaymentMeta, buildOpenApi, buildSelfDescription, buildWellKnownX402, buildWellKnownX402Manifest, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createA2APaymentHandler, createMcpPaymentTool, createPaymentGate, decorateOutcome, deliverReceipt, denomOf, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, fromA2APaymentPayload, fromA2APaymentRequired, fromMcpPayment, fromMcpPaymentRequired, fromMcpPaymentResponse, getDirectoryInfo, isMcpPaymentRequired, isPermit2ProxyChain, isUptoProxyChain, knownFacilitatorsFor, normalizeNetwork, parseExactRequirements, parseFacilitatorSupported, paymentTools, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toA2AErrorCode, toA2APaymentFailed, toA2APaymentReceipts, toA2APaymentRequired, toInsufficientFundsError, toInvalidBody, toMcpPaymentRequired, toMcpPaymentResponse, verify402IndexDomain };
+export { type A2AArtifact, type A2AExtensionDeclaration, type A2AMessage, type A2AMetadata, type A2APart, type A2APaymentHandler, type A2APaymentHandlerOptions, type A2APaymentStatus, type A2ATask, type A2ATaskRecord, type A2ATaskState, type A2ATaskStore, A2A_ERROR_KEY, A2A_EXTENSIONS_HEADER, A2A_PAYLOAD_KEY, A2A_RECEIPTS_KEY, A2A_REQUIRED_KEY, A2A_STATUS_KEY, A2A_X402_EXTENSION_URI_V01, A2A_X402_EXTENSION_URI_V02, type AcceptOption, AddressId, type AgentTool, type AlgorandToken, type AptosToken, AssetId, BRAND, BUILTIN_DENOMS, type BazaarExtension, type BuildExactParams, CHAINS, Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type CountStatus, DENOM_PRECISION, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DenomRemaining, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, type GateSelfTest, InsufficientFundsError, InvalidConfigError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, MCP_PAYMENT_META_KEY, MCP_PAYMENT_RESPONSE_META_KEY, type ManifestInput, MaxRetriesExceededError, type McpContentBlock, type McpPaymentMeta, type McpPaymentTool, type McpPaymentToolOptions, type McpToolCallParams, type McpToolResult, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_UPTO_WITNESS_TYPES, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, PaidReceipt, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type PaywallOptions, Permit2UptoPaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, PipRailReceipt, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, type ReceiptInput, type ReceiptOption, type ReceiptVerification, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type Serve, type SessionBudget, SettleOutcome, type SettleViaFacilitatorInput, SettlementError, SignedReceipt, type SolanaToken, SpendLedger, SpendRecord, type SpendRemaining, SpendStore, SpendSummary, type StellarToken, type SuiToken, type TipJarOptions, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UPTO_PROXY_CHAIN_IDS, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type UptoRailOption, VERIFY_CODE_TO_A2A_ERROR, VerifyErrorCode, type VerifyPaymentResult, VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, type WellKnownX402Item, type WellKnownX402Manifest, WrongChainError, WrongFamilyError, X402AcceptEntry, X402AnyAccept, X402Challenge, type X402DnsRecord, X402ExactAcceptEntry, type X402InvalidBody, X402Receipt, X402UptoAcceptEntry, X402_EXACT_PERMIT2_PROXY, X402_UPTO_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildEndpointInfo, buildExactAuthorization, buildMcpPaymentMeta, buildOpenApi, buildSelfDescription, buildWellKnownX402, buildWellKnownX402Manifest, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createA2APaymentHandler, createMcpPaymentTool, createPaymentGate, createPaywall, createTipJar, decorateOutcome, deliverReceipt, denomOf, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, fromA2APaymentPayload, fromA2APaymentRequired, fromMcpPayment, fromMcpPaymentRequired, fromMcpPaymentResponse, getDirectoryInfo, isMcpPaymentRequired, isPermit2ProxyChain, isUptoProxyChain, knownFacilitatorsFor, normalizeNetwork, parseExactRequirements, parseFacilitatorSupported, paymentTools, planAcross, proxyTo, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toA2AErrorCode, toA2APaymentFailed, toA2APaymentReceipts, toA2APaymentRequired, toFetchHandler, toInsufficientFundsError, toInvalidBody, toMcpPaymentRequired, toMcpPaymentResponse, toWorker, verify402IndexDomain };

package/dist/index.d.ts

@@ -7169,6 +7169,34 @@ declare function toInvalidBody(result: {
     error: string;
     detail: string;
 }): X402InvalidBody;
+/**
+ * The result of {@link PaymentGate.selfTest} — a read-only config check. NEVER throws, and never
+ * touches the network beyond the same lazy driver/token resolution the first `challenge()` does
+ * (no signing, no sending). `ok:true` with the resolved `rails` when the config is sound; `ok:false`
+ * with a human `error` when something's wrong (no payTo, a malformed address for the family, an
+ * unknown token, an unresolvable chain). Powers a scaffolder's "✅ your endpoint is configured"
+ * step and a merchant's `npm run verify`.
+ */
+interface GateSelfTest {
+    ok: boolean;
+    /** One entry per resolved payment option (empty when `ok:false`). */
+    rails: Array<{
+        /** CAIP-2 network, e.g. `eip155:8453`. */
+        network: string;
+        asset: string;
+        symbol?: string;
+        decimals: number;
+        /** Human amount the gate charges (for a tip jar, the minimum/floor). */
+        amount: string;
+        payTo: AddressId;
+        /** The schemes this rail offers, e.g. `['onchain-proof']` or `['exact', 'onchain-proof']`. */
+        schemes: string[];
+    }>;
+    /** Non-fatal nudges (e.g. a custom token with no built-in symbol to double-check). */
+    warnings: string[];
+    /** Present only when `ok:false` — the human reason the config can't serve a payment. */
+    error?: string;
+}
 interface PaymentGate {
     /** Build a fresh 402 challenge (new nonce) for a resource URL. */
     challenge(resourceUrl?: string): Promise<{
@@ -7203,6 +7231,13 @@ interface PaymentGate {
      * The SDK never serves it itself (headless by charter). Agents/crawlers keep the JSON 402.
      */
     landingPage(challenge: X402Challenge): string;
+    /**
+     * Read-only config check — resolve the gate's rails WITHOUT signing or sending, and report what
+     * it would charge (or why it can't). Never throws; runs the same lazy resolution as the first
+     * `challenge()`. The merchant's "did I wire this right?" and a scaffolder's post-deploy smoke
+     * step. See {@link GateSelfTest}.
+     */
+    selfTest(): Promise<GateSelfTest>;
 }
 declare function createPaymentGate(options: RequirePaymentOptions): PaymentGate;
 interface ExpressLikeRequest {
@@ -7224,6 +7259,110 @@ type ExpressLikeMiddleware = (req: ExpressLikeRequest, res: ExpressLikeResponse,
  */
 declare function requirePayment(options: RequirePaymentOptions): ExpressLikeMiddleware;
 
+/**
+ * The advanced gate options a preset forwards verbatim — every {@link RequirePaymentOptions} field
+ * EXCEPT the `chain`/`token`/`amount`/`payTo` quartet (each preset re-declares those with its own
+ * shape) and the multi-chain `accept` array (use {@link createPaymentGate} directly for a multi-rail
+ * gate). So `onPaid`, `exact`, `receipts`, `discovery`, `isUsed`/`markUsed`, … all pass through.
+ */
+type GateExtras = Omit<RequirePaymentOptions, 'chain' | 'token' | 'amount' | 'payTo' | 'accept'>;
+/** Options for {@link createPaywall}. */
+interface PaywallOptions extends GateExtras {
+    /** Which chain to be paid on. EVM (`'base'`|`'bnb'`|…) or a non-EVM family name. */
+    chain: ChainSelector;
+    /** Token to charge in. Defaults to **USDC**. */
+    token?: TokenInput;
+    /** The fixed price, human-readable, e.g. `'0.05'`. */
+    amount: string;
+    /** Your receiving wallet address — no private key (receiving needs only the address). */
+    payTo: AddressId;
+}
+/**
+ * Gate one resource behind a fixed price — the API / SaaS / premium-content case. Sugar over
+ * {@link createPaymentGate} with `token` defaulting to USDC; every other gate option is forwarded
+ * unchanged, so the resulting gate (and its 402) is identical to the hand-written equivalent.
+ */
+declare function createPaywall({ token, ...rest }: PaywallOptions): PaymentGate;
+/** Options for {@link createTipJar}. */
+interface TipJarOptions extends GateExtras {
+    /** Which chain to be paid on. */
+    chain: ChainSelector;
+    /** Token to accept. Defaults to **USDC**. */
+    token?: TokenInput;
+    /**
+     * The MINIMUM tip, human-readable, e.g. `'1.00'`. The gate accepts any payment **≥ min** — the
+     * on-chain verify rejects only an under-payment (`amount_too_low`), so a payer can always give
+     * more. There is no upper bound; the minimum is a floor, not a fixed price.
+     */
+    min: string;
+    /** Your receiving wallet address. */
+    payTo: AddressId;
+}
+/**
+ * An open "pay what you want (≥ a minimum)" gate — the creator / tip / donation case. Sugar over
+ * {@link createPaymentGate} that sets the challenge `amount` to `min`; because the gate accepts an
+ * over-payment, the minimum is a floor. Everything else (`onPaid`, etc.) forwards unchanged.
+ */
+declare function createTipJar({ token, min, ...rest }: TipJarOptions): PaymentGate;
+
+/**
+ * Built-in framework adapters — turn a {@link PaymentGate} into a request handler for any
+ * WHATWG-`fetch` runtime. There are only TWO real shapes among fetch runtimes, so there are two
+ * adapters: a plain handler **function** (Next.js, Netlify, Bun, Deno, Vercel Edge, Hono, Lambda),
+ * and the `{ fetch }` **export object** (Cloudflare / Service Workers). Both run the same contract:
+ * read the proof header, switch on the {@link VerifyPaymentResult} `kind`, write the right status +
+ * headers back out — so a merchant's route is a single call instead of a switch.
+ *
+ *   import { createPaywall, toFetchHandler, toWorker } from '@piprail/sdk'
+ *   const gate = createPaywall({ chain: 'base', amount: '0.05', payTo: '0xYourWallet' })
+ *
+ *   export const GET = toFetchHandler(gate, () => Response.json({ secret: 42 }))  // Next / Netlify / Bun / Deno / Hono …
+ *   export default  toWorker(gate, () => Response.json({ secret: 42 }))           // a Cloudflare Worker
+ *
+ * Pure + browser-safe — Web `Request`/`Response`/`Headers` only (no viem, no `node:`). Express keeps
+ * its dedicated {@link requirePayment} middleware; a Node-native framework with its own `req`/`reply`
+ * (Fastify, …) drives `gate.verify()` directly (see the framework-adapters docs). {@link proxyTo} is a
+ * ready-made `serve` that forwards paid requests to an existing backend — gate any API, any language.
+ */
+
+/**
+ * What to serve once a payment is verified — your protected resource, as a Web `Response`. It
+ * receives the original `request` **plus whatever extra arguments the runtime passed the handler**
+ * (a Cloudflare Worker's `env`/`ctx`, a Next.js route `context` with `params`, …), forwarded
+ * untouched — so a protected handler can reach framework context without a second wrapper.
+ */
+type Serve = (request: Request, ...rest: unknown[]) => Response | Promise<Response>;
+/**
+ * The universal adapter: wrap a gate as a `fetch` handler `(request, ...rest) => Response`. Drop the
+ * result into **any** runtime that hands a handler a `Request` and wants a `Response` back — Next.js
+ * route handlers (`export const GET = …`), Netlify Functions, `Bun.serve({ fetch })`,
+ * `Deno.serve(…)`, Vercel Edge, Hono (`(c) => handler(c.req.raw)`), an AWS Lambda Web adapter, Fastly
+ * Compute. Any extra runtime arguments are forwarded to `serve` untouched.
+ *
+ * - **settled payment** → calls `serve`, returns its `Response` with the `payment-response` headers (v2 + v1) added;
+ * - **missing / rejected proof** → a conformant `402` carrying the full challenge (so a standard x402 client can retry);
+ * - **server-side settle failure** ({@link SettlementError}) → `502` — NEVER `402` (the buyer's authorization is still valid + unused).
+ */
+declare function toFetchHandler(gate: PaymentGate, serve: Serve): (request: Request, ...rest: unknown[]) => Promise<Response>;
+/**
+ * The `{ fetch }` export object for runtimes that take one — Cloudflare Workers / Service Workers:
+ * `export default toWorker(gate, serve)`. Identical behaviour to {@link toFetchHandler}; the
+ * runtime's `fetch(request, env, ctx)` arguments are forwarded to `serve` (so it can read bindings /
+ * `ctx.waitUntil`). (Other runtimes that take an object — `Bun.serve`, `Deno.serve` — can use either
+ * this or `toFetchHandler` in their `fetch` field.)
+ */
+declare function toWorker(gate: PaymentGate, serve: Serve): {
+    fetch: (request: Request, ...rest: unknown[]) => Promise<Response>;
+};
+/**
+ * A {@link Serve} that forwards the (already-paid) request to an upstream `origin`, untouched — so you
+ * can put a payment gate in FRONT of an existing API in any language, without changing it. Preserves
+ * the method, path, query, body, and headers; strips the x402 proof headers so they don't leak
+ * upstream. The origin NEVER sees an unpaid request — the gate rejects those before `serve` runs.
+ * Compose with the adapters: `toWorker(gate, proxyTo('https://my-api.example.com'))`.
+ */
+declare function proxyTo(origin: string): Serve;
+
 /**
  * Mode-B settlement: delegate a standard `exact` payment to a THIRD-PARTY x402
  * facilitator the MERCHANT chooses (Coinbase CDP, x402.org, or any). PipRail hosts
@@ -8396,4 +8535,4 @@ interface McpPaymentTool {
  */
 declare function createMcpPaymentTool(options: McpPaymentToolOptions): McpPaymentTool;
 
-export { type A2AArtifact, type A2AExtensionDeclaration, type A2AMessage, type A2AMetadata, type A2APart, type A2APaymentHandler, type A2APaymentHandlerOptions, type A2APaymentStatus, type A2ATask, type A2ATaskRecord, type A2ATaskState, type A2ATaskStore, A2A_ERROR_KEY, A2A_EXTENSIONS_HEADER, A2A_PAYLOAD_KEY, A2A_RECEIPTS_KEY, A2A_REQUIRED_KEY, A2A_STATUS_KEY, A2A_X402_EXTENSION_URI_V01, A2A_X402_EXTENSION_URI_V02, type AcceptOption, AddressId, type AgentTool, type AlgorandToken, type AptosToken, AssetId, BRAND, BUILTIN_DENOMS, type BazaarExtension, type BuildExactParams, CHAINS, Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type CountStatus, DENOM_PRECISION, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DenomRemaining, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, InsufficientFundsError, InvalidConfigError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, MCP_PAYMENT_META_KEY, MCP_PAYMENT_RESPONSE_META_KEY, type ManifestInput, MaxRetriesExceededError, type McpContentBlock, type McpPaymentMeta, type McpPaymentTool, type McpPaymentToolOptions, type McpToolCallParams, type McpToolResult, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_UPTO_WITNESS_TYPES, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, PaidReceipt, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, Permit2UptoPaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, PipRailReceipt, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, type ReceiptInput, type ReceiptOption, type ReceiptVerification, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, SettleOutcome, type SettleViaFacilitatorInput, SettlementError, SignedReceipt, type SolanaToken, SpendLedger, SpendRecord, type SpendRemaining, SpendStore, SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UPTO_PROXY_CHAIN_IDS, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type UptoRailOption, VERIFY_CODE_TO_A2A_ERROR, VerifyErrorCode, type VerifyPaymentResult, VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, type WellKnownX402Item, type WellKnownX402Manifest, WrongChainError, WrongFamilyError, X402AcceptEntry, X402AnyAccept, X402Challenge, type X402DnsRecord, X402ExactAcceptEntry, type X402InvalidBody, X402Receipt, X402UptoAcceptEntry, X402_EXACT_PERMIT2_PROXY, X402_UPTO_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildEndpointInfo, buildExactAuthorization, buildMcpPaymentMeta, buildOpenApi, buildSelfDescription, buildWellKnownX402, buildWellKnownX402Manifest, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createA2APaymentHandler, createMcpPaymentTool, createPaymentGate, decorateOutcome, deliverReceipt, denomOf, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, fromA2APaymentPayload, fromA2APaymentRequired, fromMcpPayment, fromMcpPaymentRequired, fromMcpPaymentResponse, getDirectoryInfo, isMcpPaymentRequired, isPermit2ProxyChain, isUptoProxyChain, knownFacilitatorsFor, normalizeNetwork, parseExactRequirements, parseFacilitatorSupported, paymentTools, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toA2AErrorCode, toA2APaymentFailed, toA2APaymentReceipts, toA2APaymentRequired, toInsufficientFundsError, toInvalidBody, toMcpPaymentRequired, toMcpPaymentResponse, verify402IndexDomain };
+export { type A2AArtifact, type A2AExtensionDeclaration, type A2AMessage, type A2AMetadata, type A2APart, type A2APaymentHandler, type A2APaymentHandlerOptions, type A2APaymentStatus, type A2ATask, type A2ATaskRecord, type A2ATaskState, type A2ATaskStore, A2A_ERROR_KEY, A2A_EXTENSIONS_HEADER, A2A_PAYLOAD_KEY, A2A_RECEIPTS_KEY, A2A_REQUIRED_KEY, A2A_STATUS_KEY, A2A_X402_EXTENSION_URI_V01, A2A_X402_EXTENSION_URI_V02, type AcceptOption, AddressId, type AgentTool, type AlgorandToken, type AptosToken, AssetId, BRAND, BUILTIN_DENOMS, type BazaarExtension, type BuildExactParams, CHAINS, Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type CountStatus, DENOM_PRECISION, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DenomRemaining, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, type GateSelfTest, InsufficientFundsError, InvalidConfigError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, MCP_PAYMENT_META_KEY, MCP_PAYMENT_RESPONSE_META_KEY, type ManifestInput, MaxRetriesExceededError, type McpContentBlock, type McpPaymentMeta, type McpPaymentTool, type McpPaymentToolOptions, type McpToolCallParams, type McpToolResult, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_UPTO_WITNESS_TYPES, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, PaidReceipt, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type PaywallOptions, Permit2UptoPaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, PipRailReceipt, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, type ReceiptInput, type ReceiptOption, type ReceiptVerification, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type Serve, type SessionBudget, SettleOutcome, type SettleViaFacilitatorInput, SettlementError, SignedReceipt, type SolanaToken, SpendLedger, SpendRecord, type SpendRemaining, SpendStore, SpendSummary, type StellarToken, type SuiToken, type TipJarOptions, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UPTO_PROXY_CHAIN_IDS, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type UptoRailOption, VERIFY_CODE_TO_A2A_ERROR, VerifyErrorCode, type VerifyPaymentResult, VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, type WellKnownX402Item, type WellKnownX402Manifest, WrongChainError, WrongFamilyError, X402AcceptEntry, X402AnyAccept, X402Challenge, type X402DnsRecord, X402ExactAcceptEntry, type X402InvalidBody, X402Receipt, X402UptoAcceptEntry, X402_EXACT_PERMIT2_PROXY, X402_UPTO_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildEndpointInfo, buildExactAuthorization, buildMcpPaymentMeta, buildOpenApi, buildSelfDescription, buildWellKnownX402, buildWellKnownX402Manifest, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createA2APaymentHandler, createMcpPaymentTool, createPaymentGate, createPaywall, createTipJar, decorateOutcome, deliverReceipt, denomOf, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, fromA2APaymentPayload, fromA2APaymentRequired, fromMcpPayment, fromMcpPaymentRequired, fromMcpPaymentResponse, getDirectoryInfo, isMcpPaymentRequired, isPermit2ProxyChain, isUptoProxyChain, knownFacilitatorsFor, normalizeNetwork, parseExactRequirements, parseFacilitatorSupported, paymentTools, planAcross, proxyTo, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toA2AErrorCode, toA2APaymentFailed, toA2APaymentReceipts, toA2APaymentRequired, toFetchHandler, toInsufficientFundsError, toInvalidBody, toMcpPaymentRequired, toMcpPaymentResponse, toWorker, verify402IndexDomain };

package/dist/index.js

@@ -7499,7 +7499,36 @@ function createPaymentGate(options) {
     await settleTx(idKey, result.kind === "paid");
     return result.kind === "paid" ? echoPaymentIdentifier(result, id) : result;
   }
-  return { challenge, verify, verifyObject, describe, landingPage };
+  async function selfTest() {
+    try {
+      const specs = await ready();
+      const warnings = [];
+      const rails = specs.map((s) => {
+        if (!s.symbol) {
+          warnings.push(
+            `${s.asset} on ${s.net.network}: custom token (no built-in symbol) \u2014 double-check the address + decimals.`
+          );
+        }
+        return {
+          network: s.net.network,
+          asset: s.asset,
+          ...s.symbol ? { symbol: s.symbol } : {},
+          decimals: s.decimals,
+          amount: s.amountFormatted,
+          payTo: s.payTo,
+          schemes: [
+            ...s.exact ? ["exact"] : [],
+            ...s.upto ? ["upto"] : [],
+            "onchain-proof"
+          ]
+        };
+      });
+      return { ok: true, rails, warnings };
+    } catch (err) {
+      return { ok: false, rails: [], warnings: [], error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  return { challenge, verify, verifyObject, describe, landingPage, selfTest };
 }
 function requirePayment(options) {
   if (options.upto) {
@@ -7551,6 +7580,87 @@ function normaliseHeader(value) {
   return value;
 }
 
+// src/merchant.ts
+function createPaywall({ token = "USDC", ...rest }) {
+  return createPaymentGate({ token, ...rest });
+}
+function createTipJar({ token = "USDC", min, ...rest }) {
+  return createPaymentGate({ token, amount: min, ...rest });
+}
+
+// src/adapters.ts
+function jsonResponse(body, status, headers) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", ...headers ?? {} }
+  });
+}
+function withSettlementHeaders(res, receiptHeader) {
+  const headers = new Headers();
+  res.headers.forEach((value, key) => {
+    if (key.toLowerCase() !== "set-cookie") headers.append(key, value);
+  });
+  const src = res.headers;
+  const cookies = typeof src.getSetCookie === "function" ? src.getSetCookie() : (() => {
+    const combined = res.headers.get("set-cookie");
+    return combined ? [combined] : [];
+  })();
+  for (const cookie of cookies) headers.append("set-cookie", cookie);
+  headers.set(HEADER_RESPONSE, receiptHeader);
+  headers.set(HEADER_RESPONSE_V1, receiptHeader);
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+function toFetchHandler(gate, serve) {
+  return async (request, ...rest) => {
+    let result;
+    try {
+      const sig = request.headers.get(HEADER_SIGNATURE) ?? request.headers.get(HEADER_SIGNATURE_V1) ?? void 0;
+      result = await gate.verify(sig);
+    } catch (err) {
+      if (err instanceof SettlementError) {
+        return jsonResponse(
+          {
+            x402Version: 2,
+            error: "settlement_failed",
+            detail: err.message,
+            fallback: "The gasless `exact` settlement failed. This resource also accepts `onchain-proof` \u2014 retry by paying that rail yourself (you broadcast the transfer and pay the gas)."
+          },
+          502
+        );
+      }
+      throw err;
+    }
+    if (result.kind === "paid") {
+      const res = await serve(request, ...rest);
+      return withSettlementHeaders(res, result.receiptHeader);
+    }
+    return jsonResponse(result.challenge, 402, { [HEADER_REQUIRED]: result.requiredHeader });
+  };
+}
+function toWorker(gate, serve) {
+  return { fetch: toFetchHandler(gate, serve) };
+}
+function proxyTo(origin) {
+  const base2 = origin.replace(/\/+$/, "");
+  return (request) => {
+    const inUrl = new URL(request.url);
+    const target = base2 + inUrl.pathname + inUrl.search;
+    const headers = new Headers(request.headers);
+    headers.delete(HEADER_SIGNATURE);
+    headers.delete(HEADER_SIGNATURE_V1);
+    const init = {
+      method: request.method,
+      headers,
+      redirect: "manual"
+    };
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      init.body = request.body;
+      init.duplex = "half";
+    }
+    return fetch(target, init);
+  };
+}
+
 // src/receipts.ts
 var DEFAULT_RETRIES = 5;
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -8092,6 +8202,8 @@ export {
   createA2APaymentHandler,
   createMcpPaymentTool,
   createPaymentGate,
+  createPaywall,
+  createTipJar,
   decodeBase64Json,
   decorateOutcome,
   deliverReceipt,
@@ -8133,6 +8245,7 @@ export {
   paymentTools,
   pickAccept,
   planAcross,
+  proxyTo,
   rankResources,
   readExactDomain,
   readPaymentIdentifier,
@@ -8150,9 +8263,11 @@ export {
   toA2APaymentFailed,
   toA2APaymentReceipts,
   toA2APaymentRequired,
+  toFetchHandler,
   toInsufficientFundsError,
   toInvalidBody,
   toMcpPaymentRequired,
   toMcpPaymentResponse,
+  toWorker,
   verify402IndexDomain
 };

package/package.json

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