@piprail/sdk 1.21.0 → 1.22.0

package/dist/index.d.cts

@@ -5079,8 +5079,13 @@ interface SpendRemaining {
     remainingFormatted?: string;
 }
 interface PipRailClientOptions {
-    /** Wallet for the chosen chain family. */
-    wallet: WalletInput;
+    /**
+     * Wallet for the chosen chain family. **Optional** — omit it for a READ-ONLY
+     * client that can `quote`, `discover`, `estimateCost`, and `register` (402 Index)
+     * with no key. Paying, planning, or signing then throws {@link WalletRequiredError}
+     * until a wallet is provided. Supplying a wallet is byte-identical to before.
+     */
+    wallet?: WalletInput;
     /** Which chain to pay on. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar',
      *  'xrpl', 'tron', 'sui', 'near', 'aptos', or 'algorand'. */
     chain: ChainSelector;
@@ -5545,7 +5550,7 @@ declare function formatSpendReport(summary: SpendSummary): string;
  * literally, so a wrong name or order actively misleads. A test pins the load-
  * bearing phrases.
  */
-declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend.\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
+declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);\nyou can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;
 
@@ -6392,6 +6397,14 @@ declare class UnsupportedSchemeError extends PipRailError {
 declare class NonReplayableBodyError extends PipRailError {
     readonly code = "NON_REPLAYABLE_BODY";
 }
+/**
+ * A wallet-bound operation was called on a READ-ONLY client — one built with no
+ * `wallet`. Read-only clients still `quote`, `discover`, and `register` (402 Index);
+ * paying, planning, or signing needs a wallet. Pass `wallet` to enable them.
+ */
+declare class WalletRequiredError extends PipRailError {
+    readonly code = "WALLET_REQUIRED";
+}
 /**
  * The chosen chain belongs to one family (EVM, Solana, TON, Stellar, XRPL, Tron,
  * Sui, NEAR, Aptos, Algorand) but the wallet, payTo, or token was given in another family's form
@@ -6780,4 +6793,4 @@ declare const PERMIT2_WITNESS_TYPES: {
     }];
 };
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.d.ts

@@ -5079,8 +5079,13 @@ interface SpendRemaining {
     remainingFormatted?: string;
 }
 interface PipRailClientOptions {
-    /** Wallet for the chosen chain family. */
-    wallet: WalletInput;
+    /**
+     * Wallet for the chosen chain family. **Optional** — omit it for a READ-ONLY
+     * client that can `quote`, `discover`, `estimateCost`, and `register` (402 Index)
+     * with no key. Paying, planning, or signing then throws {@link WalletRequiredError}
+     * until a wallet is provided. Supplying a wallet is byte-identical to before.
+     */
+    wallet?: WalletInput;
     /** Which chain to pay on. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar',
      *  'xrpl', 'tron', 'sui', 'near', 'aptos', or 'algorand'. */
     chain: ChainSelector;
@@ -5545,7 +5550,7 @@ declare function formatSpendReport(summary: SpendSummary): string;
  * literally, so a wrong name or order actively misleads. A test pins the load-
  * bearing phrases.
  */
-declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend.\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
+declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);\nyou can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left, per\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;
 
@@ -6392,6 +6397,14 @@ declare class UnsupportedSchemeError extends PipRailError {
 declare class NonReplayableBodyError extends PipRailError {
     readonly code = "NON_REPLAYABLE_BODY";
 }
+/**
+ * A wallet-bound operation was called on a READ-ONLY client — one built with no
+ * `wallet`. Read-only clients still `quote`, `discover`, and `register` (402 Index);
+ * paying, planning, or signing needs a wallet. Pass `wallet` to enable them.
+ */
+declare class WalletRequiredError extends PipRailError {
+    readonly code = "WALLET_REQUIRED";
+}
 /**
  * The chosen chain belongs to one family (EVM, Solana, TON, Stellar, XRPL, Tron,
  * Sui, NEAR, Aptos, Algorand) but the wallet, payTo, or token was given in another family's form
@@ -6780,4 +6793,4 @@ declare const PERMIT2_WITNESS_TYPES: {
     }];
 };
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.js

@@ -14,6 +14,7 @@ import {
   UnknownTokenError,
   UnsupportedNetworkError,
   UnsupportedSchemeError,
+  WalletRequiredError,
   WrongChainError,
   WrongFamilyError,
   floorUnits,
@@ -22,7 +23,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-ILPABTI2.js";
+} from "./chunk-L6WQRHEZ.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -666,10 +667,14 @@ async function payExactEvm(input) {
       `exact buyer rail requires an EOA signer; ${account.address} is a contract / EIP-1271 / EIP-7702-delegated account (no recoverable ECDSA signature). Pay via onchain-proof.`
     );
   }
-  const domain = await readExactDomain(publicClient, accept.asset);
+  let domain = await readExactDomain(publicClient, accept.asset);
+  if (!domain) {
+    await new Promise((r) => setTimeout(r, 300));
+    domain = await readExactDomain(publicClient, accept.asset);
+  }
   if (!domain) {
     throw new UnsupportedSchemeError(
-      `exact: ${accept.asset} on ${accept.network} isn't an EIP-3009 token (USDT needs Permit2; native coin and plain ERC-20s aren't exact-payable). Pay via onchain-proof.`
+      `exact: couldn't derive the EIP-712 domain for ${accept.asset} on ${accept.network}. Either it isn't an EIP-3009 token (USDT needs Permit2; native/plain ERC-20 aren't exact-payable) \u2014 pay via onchain-proof \u2014 OR your RPC couldn't read it (transient): if the gate advertised eip3009, pass a reliable rpcUrl and retry.`
     );
   }
   const g = globalThis.crypto;
@@ -1791,7 +1796,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-4EMMGGDR.js");
+      mod = await import("./solana-KWNRY5NR.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -1803,7 +1808,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-CHJ26BVA.js");
+      mod = await import("./ton-QN5GTOCS.js");
     } catch (cause) {
       throw new MissingDriverError(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
@@ -1815,7 +1820,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-FIJPQZVW.js");
+      mod = await import("./stellar-YB7JXKK4.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -1827,7 +1832,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-GTUPP6SK.js");
+      mod = await import("./xrpl-ECHK3GIX.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -1839,7 +1844,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-DD3JDROV.js");
+      mod = await import("./tron-QSNCDYRB.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -1851,7 +1856,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-B7AVN7NK.js");
+      mod = await import("./sui-IODKU2MA.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -1863,7 +1868,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-LM7S3WUD.js");
+      mod = await import("./near-TWA4PYOD.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -1875,7 +1880,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-SUXOVP7B.js");
+      mod = await import("./aptos-3TSKTI4D.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
@@ -1887,7 +1892,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-F3OYB534.js");
+      mod = await import("./algorand-677ILBQS.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -2622,7 +2627,7 @@ var PipRailClient = class {
         chain: this.opts.chain,
         rpcUrl: this.opts.rpcUrl
       });
-      const wallet = net.bindWallet(this.opts.wallet);
+      const wallet = this.opts.wallet !== void 0 ? net.bindWallet(this.opts.wallet) : void 0;
       return { net, wallet };
     })();
   }
@@ -2788,6 +2793,11 @@ var PipRailClient = class {
       throw new InvalidEnvelopeError("402 response did not include a parseable x402 challenge.");
     }
     const { net, wallet } = await this.ensure();
+    if (!wallet) {
+      throw new WalletRequiredError(
+        "planPayment needs a wallet (it checks YOUR balance, gas, and recipient-readiness). This client is read-only \u2014 construct it with a `wallet` to plan or pay."
+      );
+    }
     return this.planFromChallenge(net, wallet, challenge, url, this.resolveSchemes());
   }
   /**
@@ -2939,6 +2949,7 @@ var PipRailClient = class {
    */
   async discoverySigner() {
     const { net, wallet } = await this.ensure();
+    if (!wallet) return null;
     return net.discoverySigner ? net.discoverySigner(wallet) : null;
   }
   /**
@@ -2960,6 +2971,11 @@ var PipRailClient = class {
     const schemes = this.resolveSchemes(init?.schemes);
     const resolved = await this.resolveChallenge(url, firstResponse, schemes);
     const { net, wallet, challenge } = resolved;
+    if (!wallet) {
+      throw new WalletRequiredError(
+        "Paying a 402 needs a wallet to sign + settle. This client is read-only \u2014 construct it with a `wallet` to pay (quote/discover/register still work without one)."
+      );
+    }
     let accept = resolved.accept;
     let quote = resolved.quote;
     const autoRoute = init?.autoRoute ?? this.opts.autoRoute ?? false;
@@ -3647,6 +3663,18 @@ straight from your wallet to the server; PipRail custodies nothing. Follow this.
    and return the result.
 Always plan before you pay so you never commit to a payment you cannot finish.
 
+## Gasless \u2014 the exact rail (zero gas for you)
+A 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:
+- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas
+  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.
+- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose
+  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It
+  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.
+When the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest
+settleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is
+identical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);
+you can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).
+
 ## Reading a refusal \u2014 never crash, never double-spend
 A failed pay returns a STRUCTURED object, never a thrown error you must catch:
   { ok:false, code, reason, explain, ref?, reasonCode?, declined? }
@@ -3664,9 +3692,13 @@ Branch on \`code\` (always reliable). Key cases:
 - code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.
 - code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the
   payment may ALREADY be on-chain. Recover using the proof on \`.ref\` (re-verify
-  or re-submit it); never re-pay \u2014 a fresh payment would double-spend.
+  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless
+  exact rail \`.ref\` is the authorization NONCE, not a tx hash: re-present the SAME
+  signed authorization, never sign a fresh one (that would risk a double-spend).
 - code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on
   your chain/scheme; \`explain\` says whether it's the wrong chain or a scheme to enable.
+  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes
+  once (enable the exact scheme); report it, don't retry the same call blindly.
 
 ## Knowing your leash \u2014 call piprail_budget
 piprail_budget tells you how much budget and time you have left, per
@@ -4199,6 +4231,7 @@ function createPaymentGate(options) {
     if (resolved) return resolved;
     const p = (async () => {
       const accepts = normaliseAccepts(options);
+      const exactSkips = [];
       const specs = await Promise.all(
         accepts.map(async (a) => {
           const net = await resolveNetwork2({ chain: a.chain, rpcUrl: a.rpcUrl ?? options.rpcUrl });
@@ -4212,13 +4245,17 @@ function createPaymentGate(options) {
           const { asset, decimals, symbol } = net.resolveToken(a.token);
           const amountBase = parseUnits(a.amount, decimals);
           const spec = { net, asset, decimals, symbol, amountBase, amountFormatted: a.amount, payTo };
-          if (options.exact) spec.exact = await resolveExactRail(net, asset);
+          if (options.exact) {
+            const outcome = await resolveExactRail(net, asset);
+            if (outcome.rail) spec.exact = outcome.rail;
+            else if (outcome.skipReason) exactSkips.push(outcome.skipReason);
+          }
           return spec;
         })
       );
       if (options.exact && !specs.some((s) => s.exact)) {
         throw new Error(
-          "requirePayment: `exact` was requested but none of the offered rails support it. The standard `exact` rail is EVM ERC-20 (EIP-3009 \u2014 USDC / EURC \u2014 or Permit2, e.g. Binance-Peg USDC on BNB) or a Solana SPL token (SVM) \u2014 NOT native coins, NOT families without a standard `exact` scheme. Offer an EVM ERC-20 / Solana SPL token, or drop `exact`."
+          "requirePayment: `exact` was requested but none of the offered rails support it. " + (exactSkips.length > 0 ? exactSkips.join(" ") : "The standard `exact` rail is EVM ERC-20 (EIP-3009 \u2014 USDC / EURC \u2014 or Permit2, e.g. Binance-Peg USDC on BNB) or a Solana SPL token (SVM) \u2014 NOT native coins, NOT families without a standard `exact` scheme. Offer an EVM ERC-20 / Solana SPL token, or drop `exact`.")
         );
       }
       return specs;
@@ -4231,10 +4268,11 @@ function createPaymentGate(options) {
   }
   async function resolveExactRail(net, asset) {
     const cfg = options.exact;
-    if (!net.resolveExactRail) return void 0;
+    const settle = cfg.settle;
+    if (!net.resolveExactRail) return {};
     let relayer;
     let feePayer;
-    if (cfg.settle === "self") {
+    if (settle === "self") {
       if (cfg.relayer === void 0) {
         throw new Error(
           "requirePayment: exact `settle: 'self'` needs a `relayer` wallet (the gas-paying key that broadcasts the settle), e.g. exact: { settle: 'self', relayer: { privateKey } }."
@@ -4242,21 +4280,36 @@ function createPaymentGate(options) {
       }
       relayer = net.bindWallet(cfg.relayer);
     } else {
-      feePayer = cfg.settle.feePayer;
+      feePayer = settle.feePayer;
     }
     const method = cfg.method ?? "auto";
     let info = await net.resolveExactRail({ asset, method, relayer, feePayer });
-    if (!info && cfg.settle !== "self" && !feePayer) {
-      const discovered = await fetchFacilitatorFeePayer(cfg.settle.facilitator, net.network);
-      if (discovered) info = await net.resolveExactRail({ asset, method, relayer, feePayer: discovered });
+    if (!info && settle !== "self" && !feePayer && asset !== "native") {
+      const discovered = await fetchFacilitatorFeePayer(settle.facilitator, net.network);
+      if (!discovered) {
+        return {
+          skipReason: `${net.network}: couldn't read a fee payer from the facilitator (${settle.facilitator}/supported) \u2014 it may be down, or may not sponsor this network. Set \`exact.settle.feePayer\` explicitly to remove the runtime dependency, switch to \`settle: 'self'\` with your own relayer, or retry.`
+        };
+      }
+      info = await net.resolveExactRail({ asset, method, relayer, feePayer: discovered });
+    }
+    if (!info) return {};
+    if (settle !== "self" && info.method === "permit2") {
+      if (cfg.method === "permit2") {
+        throw new Error(
+          "requirePayment: exact `method: 'permit2'` can't be settled by a third-party facilitator \u2014 facilitators settle the standard EIP-3009 (EVM) / SVM (Solana) schemes, not PipRail\u2019s Permit2 proxy. Use an EIP-3009 token (USDC / EURC) with the facilitator, or `settle: 'self'` (your own relayer) to settle Permit2 yourself."
+        );
+      }
+      return {
+        skipReason: `${net.network}: this token isn't EIP-3009 (auto-selected Permit2), which a third-party facilitator can't settle \u2014 it would serve onchain-proof only here. Use an EIP-3009 token (USDC / EURC) with the facilitator, or \`settle: 'self'\` to settle Permit2 yourself.`
+      };
     }
-    if (!info) return void 0;
-    const mode = cfg.settle === "self" ? { kind: "self", relayer } : {
+    const mode = settle === "self" ? { kind: "self", relayer } : {
       kind: "facilitator",
-      url: cfg.settle.facilitator,
-      ...cfg.settle.authHeaders ? { authHeaders: cfg.settle.authHeaders } : {}
+      url: settle.facilitator,
+      ...settle.authHeaders ? { authHeaders: settle.authHeaders } : {}
     };
-    return { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode };
+    return { rail: { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode } };
   }
   const hasCustomStore = Boolean(options.isUsed || options.markUsed);
   const localUsed = /* @__PURE__ */ new Map();
@@ -4719,6 +4772,7 @@ export {
   UnknownTokenError,
   UnsupportedNetworkError,
   UnsupportedSchemeError,
+  WalletRequiredError,
   WrongChainError,
   WrongFamilyError,
   X402_EXACT_PERMIT2_PROXY,

package/dist/{near-ZJLZE26R.cjs → near-MG256A3E.cjs}

@@ -7,7 +7,7 @@
 
 
 
-var _chunkPA6YD3HLcjs = require('./chunk-PA6YD3HL.cjs');
+var _chunkU35MG4TFcjs = require('./chunk-U35MG4TF.cjs');
 
 // src/drivers/near/index.ts
 var _nearapijs = require('near-api-js');
@@ -53,18 +53,18 @@ async function payNear(params) {
     return res.hash;
   } catch (err) {
     if (isNearRegistrationError(err)) {
-      throw new (0, _chunkPA6YD3HLcjs.RecipientNotReadyError)(
+      throw new (0, _chunkU35MG4TFcjs.RecipientNotReadyError)(
         `NEAR recipient ${accept.payTo} isn't registered on token ${accept.asset} (NEP-145 storage_deposit) \u2014 register it once (\u22480.00125 NEAR) before it can receive. (NEAR: not registered)`,
         { cause: err }
       );
     }
     if (isNearAffordability(err)) {
-      throw new (0, _chunkPA6YD3HLcjs.InsufficientFundsError)(
+      throw new (0, _chunkU35MG4TFcjs.InsufficientFundsError)(
         err instanceof Error ? err.message : "Insufficient NEAR balance for the payment.",
         { cause: err }
       );
     }
-    throw _nullishCoalesce(_chunkPA6YD3HLcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkU35MG4TFcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
   }
 }
 async function payNearNative(params) {
@@ -74,12 +74,12 @@ async function payNearNative(params) {
     return res.hash;
   } catch (err) {
     if (isNearAffordability(err)) {
-      throw new (0, _chunkPA6YD3HLcjs.InsufficientFundsError)(
+      throw new (0, _chunkU35MG4TFcjs.InsufficientFundsError)(
         err instanceof Error ? err.message : "Insufficient NEAR balance for the payment.",
         { cause: err }
       );
     }
-    throw _nullishCoalesce(_chunkPA6YD3HLcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkU35MG4TFcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
   }
 }
 function isNearRegistrationError(err) {
@@ -216,22 +216,22 @@ function txNotFound(hash) {
 
 function assertNearWallet(wallet, network) {
   if (typeof wallet !== "object" || wallet === null) {
-    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
+    throw new (0, _chunkU35MG4TFcjs.WrongFamilyError)(
       `chain ${network} is NEAR; wallet must be { accountId, privateKey } (privateKey = ed25519:\u2026).`
     );
   }
   if ("walletClient" in wallet) {
-    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
+    throw new (0, _chunkU35MG4TFcjs.WrongFamilyError)(
       `chain ${network} is NEAR; a viem { walletClient } can't be used \u2014 pass { accountId, privateKey }.`
     );
   }
   if ("secretKey" in wallet || "signer" in wallet || "mnemonic" in wallet || "keyPair" in wallet || "secret" in wallet || "seed" in wallet || "keypair" in wallet) {
-    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
+    throw new (0, _chunkU35MG4TFcjs.WrongFamilyError)(
       `chain ${network} is NEAR; that looks like another family's wallet \u2014 pass { accountId, privateKey }.`
     );
   }
   if (!("accountId" in wallet) || !("privateKey" in wallet)) {
-    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
+    throw new (0, _chunkU35MG4TFcjs.WrongFamilyError)(
       `chain ${network} is NEAR; wallet must be { accountId, privateKey } (privateKey = ed25519:\u2026).`
     );
   }
@@ -239,13 +239,13 @@ function assertNearWallet(wallet, network) {
 }
 function resolveNearWallet(config) {
   if (!config.accountId || !config.privateKey) {
-    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)("NEAR wallet needs { accountId, privateKey } (privateKey = ed25519:\u2026).");
+    throw new (0, _chunkU35MG4TFcjs.WrongFamilyError)("NEAR wallet needs { accountId, privateKey } (privateKey = ed25519:\u2026).");
   }
   let signer;
   try {
     signer = _nearapijs.KeyPairSigner.fromSecretKey(config.privateKey);
   } catch (cause) {
-    throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)("NEAR wallet { privateKey } is not a valid ed25519:\u2026 secret key.", {
+    throw new (0, _chunkU35MG4TFcjs.WrongFamilyError)("NEAR wallet { privateKey } is not a valid ed25519:\u2026 secret key.", {
       cause
     });
   }
@@ -312,16 +312,16 @@ function makeNearNetwork(preset, rpcUrl) {
         const info = preset.tokens[token.toUpperCase()];
         if (!info) {
           const known = Object.keys(preset.tokens).join(", ") || "(none built in)";
-          throw new (0, _chunkPA6YD3HLcjs.UnknownTokenError)(
+          throw new (0, _chunkU35MG4TFcjs.UnknownTokenError)(
             `token "${token}" isn't built in for NEAR (known: ${known}). Pass { contractId, decimals } for a custom NEP-141.`
           );
         }
         return { asset: info.contractId, decimals: info.decimals, symbol: info.symbol };
       }
-      _chunkPA6YD3HLcjs.rejectForeignToken.call(void 0, token, "near", network);
+      _chunkU35MG4TFcjs.rejectForeignToken.call(void 0, token, "near", network);
       const t = token;
       if (!t.contractId || typeof t.decimals !== "number") {
-        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
+        throw new (0, _chunkU35MG4TFcjs.WrongFamilyError)(
           `chain ${network} is NEAR; a custom token must be { contractId, decimals }.`
         );
       }
@@ -340,12 +340,12 @@ function makeNearNetwork(preset, rpcUrl) {
     },
     assertValidPayTo(payTo) {
       if (payTo.startsWith("0x")) {
-        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
+        throw new (0, _chunkU35MG4TFcjs.WrongFamilyError)(
           `chain ${network} is NEAR, but payTo "${payTo}" looks like an EVM/Sui 0x address.`
         );
       }
       if (!isValidNearAccountId(payTo)) {
-        throw new (0, _chunkPA6YD3HLcjs.WrongFamilyError)(
+        throw new (0, _chunkU35MG4TFcjs.WrongFamilyError)(
           `chain ${network} is NEAR, but payTo "${payTo}" is not a valid NEAR account id.`
         );
       }
@@ -389,10 +389,10 @@ function makeNearNetwork(preset, rpcUrl) {
         if (tx && tx.success) return { height: "0" };
       } catch (e7) {
       }
-      throw new (0, _chunkPA6YD3HLcjs.ConfirmationTimeoutError)(`NEAR tx ${hash} not confirmed in time.`);
+      throw new (0, _chunkU35MG4TFcjs.ConfirmationTimeoutError)(`NEAR tx ${hash} not confirmed in time.`);
     },
     async estimateCost() {
-      return _chunkPA6YD3HLcjs.nativeCost.call(void 0, {
+      return _chunkU35MG4TFcjs.nativeCost.call(void 0, {
         symbol: "NEAR",
         decimals: NEAR_DECIMALS,
         fee: 1500000000000000000000n,

package/dist/{near-LM7S3WUD.js → near-TWA4PYOD.js}

@@ -7,7 +7,7 @@ import {
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-ILPABTI2.js";
+} from "./chunk-L6WQRHEZ.js";
 
 // src/drivers/near/index.ts
 import { JsonRpcProvider, Account, actions } from "near-api-js";

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

@@ -7,7 +7,7 @@ import {
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-ILPABTI2.js";
+} from "./chunk-L6WQRHEZ.js";
 
 // src/drivers/solana/index.ts
 import { Connection, PublicKey as PublicKey3 } from "@solana/web3.js";
@@ -624,6 +624,15 @@ function makeSolanaNetwork(preset, rpcUrl) {
       return { height: String(info.slot) };
     },
     async estimateCost(accept) {
+      if (accept.scheme === "exact") {
+        return nativeCost({
+          symbol: "SOL",
+          decimals: SOL_DECIMALS,
+          fee: 0n,
+          basis: "estimated",
+          detail: "gasless \u2014 the fee payer (facilitator/relayer) broadcasts and pays the SOL fee"
+        });
+      }
       const base = 5000n;
       if (accept.asset === "native") {
         return nativeCost({