@piprail/sdk 2.14.2 → 2.15.1

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 };