@piprail/sdk 1.3.1 → 1.5.0

package/dist/index.d.cts

@@ -3777,9 +3777,9 @@ declare function resolveChain(input: ChainInput, rpcUrlOverride?: string): Resol
  */
 
 /** The chain families the SDK knows about. */
-type ChainFamily = 'evm' | 'solana' | 'ton' | 'stellar' | 'xrpl' | 'tron' | 'sui' | 'near' | 'aptos';
+type ChainFamily = 'evm' | 'solana' | 'ton' | 'stellar' | 'xrpl' | 'tron' | 'sui' | 'near' | 'aptos' | 'algorand';
 /** What chain to use: an EVM name/Chain/{id,rpcUrl}, or a non-EVM family name. */
-type ChainSelector = ChainInput | 'solana' | 'ton' | 'stellar' | 'xrpl' | 'tron' | 'sui' | 'near' | 'aptos';
+type ChainSelector = ChainInput | 'solana' | 'ton' | 'stellar' | 'xrpl' | 'tron' | 'sui' | 'near' | 'aptos' | 'algorand';
 /** An EVM ERC-20 token, by contract address. */
 interface EvmToken {
     address: `0x${string}`;
@@ -3837,6 +3837,12 @@ interface AptosToken {
     decimals: number;
     symbol?: string;
 }
+/** An Algorand Standard Asset (ASA), by its numeric asset id. */
+interface AlgorandToken {
+    assetId: number;
+    decimals: number;
+    symbol?: string;
+}
 /**
  * What to be paid in. Each driver validates the forms it accepts:
  *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP)
@@ -3850,8 +3856,9 @@ interface AptosToken {
  *   - SuiToken        any coin           (Sui)
  *   - NearToken       any NEP-141        (NEAR)
  *   - AptosToken      any Fungible Asset (Aptos)
+ *   - AlgorandToken   any ASA            (Algorand)
  */
-type TokenInput = 'native' | (string & {}) | EvmToken | SolanaToken | TonToken | StellarToken | XrplToken | TronToken | SuiToken | NearToken | AptosToken;
+type TokenInput = 'native' | (string & {}) | EvmToken | SolanaToken | TonToken | StellarToken | XrplToken | TronToken | SuiToken | NearToken | AptosToken | AlgorandToken;
 /** What a driver resolves a TokenInput into. `asset`: 0x | base58 mint | 'native'. */
 interface ResolvedToken {
     asset: string;
@@ -3885,6 +3892,22 @@ interface CostEstimate {
 interface WalletHandle {
     readonly _native: unknown;
 }
+/**
+ * Why a recipient can't receive an asset yet — the chain's one-time receive
+ * prerequisite, when it has one. Surfaced by {@link ResolvedNetwork.recipientReady}
+ * and relayed by the client's planner so an agent fixes the RECIPIENT (not its own
+ * balance). Families with no prerequisite report `ready: 'n/a'` and no reason.
+ */
+type RecipientReason = 'NO_TRUSTLINE' | 'NOT_REGISTERED' | 'NOT_OPTED_IN' | 'INACTIVE';
+/** What {@link ResolvedNetwork.balanceOf} returns — base-unit balances, or null per
+ *  field when that read was unavailable (transient/RPC), never a false 0. */
+interface WalletBalance {
+    /** The payment token's balance in base units, or null if the read was unavailable. */
+    token: bigint | null;
+    /** The native gas coin's balance in base units, or null if unavailable. For
+     *  `asset === 'native'`, this equals `token`. */
+    native: bigint | null;
+}
 interface ConfirmInfo {
     /** Block number (EVM) or slot (Solana) as a string — numeric-agnostic. */
     height: string;
@@ -3939,6 +3962,31 @@ interface ResolvedNetwork {
     estimateCost(accept: X402AcceptEntry, opts?: {
         from?: string;
     }): Promise<CostEstimate>;
+    /**
+     * Read the BOUND WALLET's own balance of the payment `asset` AND of the native
+     * gas coin, in base units — what the client's `planPayment` checks affordability
+     * against. RPC-read-only and NEVER throws: a field whose read was unavailable
+     * (rate-limited / transient) comes back `null` (unknown), never `0` (which would
+     * falsely read "broke"). For `asset === 'native'`, `token === native`.
+     * Payer-side + informational — the gate never calls this. See {@link WalletBalance}.
+     */
+    balanceOf(wallet: WalletHandle, asset: string): Promise<WalletBalance>;
+    /**
+     * Can `payTo` RECEIVE `asset` on this network right now? Reports the chain's
+     * one-time receive prerequisite (trustline / storage_deposit / ASA opt-in /
+     * activation):
+     *   - `{ ready: 'n/a' }`         the family has NO prerequisite (EVM, Solana, TON,
+     *                                Tron, Sui, Aptos — and every native coin)
+     *   - `{ ready: true }`          the prerequisite is satisfied
+     *   - `{ ready: false, reason }` it's missing (see {@link RecipientReason}) — fix the recipient
+     *   - `{ ready: 'unknown' }`     the probe read failed (transient) — NEVER throws
+     * Re-derives nothing from a client ref; reads only the given `payTo`. Payer-side
+     * pre-flight — the gate never calls this.
+     */
+    recipientReady(payTo: string, asset: string): Promise<{
+        ready: boolean | 'n/a' | 'unknown';
+        reason?: RecipientReason;
+    }>;
     /** Verify `ref` satisfies `accept`, RPC-only, in-process. */
     verify(ref: string, accept: X402AcceptEntry): Promise<VerifyResult>;
 }
@@ -4155,6 +4203,62 @@ interface PipRailCostQuote {
     /** Estimated network fee (gas) in the chain's native coin. */
     cost: CostEstimate;
 }
+/** A hard reason a rail can't be settled right now — each maps to a concrete fix. */
+type PayBlocker = 'INSUFFICIENT_TOKEN' | 'INSUFFICIENT_GAS' | 'RECIPIENT_NOT_READY' | 'OUTSIDE_POLICY';
+/** A soft flag — never blocks, always worth surfacing to the agent. */
+type PayWarning = 'SYMBOL_MISMATCH' | 'BALANCE_UNREADABLE' | 'RECIPIENT_READINESS_UNKNOWN' | 'GAS_HEURISTIC' | 'THIN_GAS_MARGIN';
+/** One offered rail, fully analysed against the bound wallet's own holdings. */
+interface PayOption {
+    /** The rail this analyses (one entry from the 402's accepts[]). */
+    accept: X402AcceptEntry;
+    /** The priced requirement — TRUE decimals/symbol + the policy verdict. */
+    quote: PipRailQuote;
+    /** Estimated native-coin gas to send it (cost.basis surfaced). */
+    cost: CostEstimate;
+    /** The verdict for THIS rail. 'unknown' = a read failed, so payability can't be confirmed. */
+    state: 'payable' | 'blocked' | 'unknown';
+    /** Hard reasons it's blocked (empty when payable). */
+    blockers: PayBlocker[];
+    /** Soft flags (may be present even when payable). */
+    warnings: PayWarning[];
+    /** Live wallet holdings, human units; null = the read was unavailable (NOT zero). */
+    balance: {
+        token: string | null;
+        native: string | null;
+    };
+    /** What this rail needs: the payment amount + the estimated gas, human units. */
+    need: {
+        token: string;
+        native: string;
+    };
+    /** How much MORE is needed to clear a funds blocker, human units (omitted when funded). */
+    shortfall?: {
+        token?: string;
+        native?: string;
+    };
+    /** Can payTo receive this asset right now, and if not, what fixes it. */
+    recipient: {
+        ready: boolean | 'n/a' | 'unknown';
+        reason?: RecipientReason;
+        fix?: string;
+    };
+}
+/** The plan for ONE 402 across every rail this client can pay (its bound network). */
+interface PaymentPlan {
+    url: string;
+    /** The network this client is bound to (the rails it can settle). */
+    network: Caip2;
+    /** Top-level verdict for instant branching. */
+    status: 'ready' | 'blocked' | 'unknown';
+    /** True iff at least one rail is payable now (best !== null). */
+    payable: boolean;
+    /** The rail to use: the cheapest (within native coin) payable option, or null. */
+    best: PayOption | null;
+    /** Every offered+supported rail, ranked: payable → unknown → blocked. */
+    options: PayOption[];
+    /** When NOT payable: one human, actionable sentence on exactly what to do. */
+    fundingHint: string | null;
+}
 interface PipRailClientOptions {
     /** Wallet for the chosen chain family. */
     wallet: WalletInput;
@@ -4193,6 +4297,16 @@ interface PipRailClientOptions {
     maxPaymentRetries?: number;
     /** Timeout (ms) for the retry leg after broadcast. Default 30_000. */
     retryTimeoutMs?: number;
+    /**
+     * Balance-aware routing: when true, `fetch()` runs `planPayment` on a 402 and
+     * pays the cheapest rail the wallet can ACTUALLY settle (token + native gas +
+     * recipient-ready), instead of the first policy-passing accept. If none is
+     * settleable it throws {@link PaymentDeclinedError} carrying the funding hint —
+     * before any send. Default **false** (defaults never change): the zero-config
+     * path keeps its existing selection. Recommended for multi-rail 402s. Override
+     * per call with `fetch(url, { autoRoute: true })`.
+     */
+    autoRoute?: boolean;
     /** Logger hook. Default no-op. */
     onEvent?: (event: PipRailEvent) => void;
 }
@@ -4245,6 +4359,32 @@ declare class PipRailClient {
     /** Aggregated snapshot of every payment this client has settled — total
      *  count, cumulative spend per token, and the individual records. */
     spent(): SpendSummary;
+    /**
+     * Plan a payment for a gated URL — WITHOUT paying. The read-only completion of
+     * the `quote()` → `estimateCost()` → **`planPayment()`** trio: it surveys every
+     * rail the 402 offers on this client's chain against the wallet's OWN holdings —
+     * token balance, native-coin gas, and recipient-readiness (trustline / ATA /
+     * storage_deposit / ASA opt-in) — and returns, crystal-clear:
+     *   - `payable` + `best`   — the cheapest rail the wallet can actually settle
+     *   - `options[]`          — every rail with typed `blockers` + soft `warnings`
+     *   - `fundingHint`        — one human sentence on exactly what to top up
+     *
+     * NEVER throws for a read problem (a transient/RPC failure surfaces as a rail in
+     * `state: 'unknown'` + a warning, never a false "unaffordable"); returns `null`
+     * when the URL isn't payment-gated (no 402); and when the 402 offers no rail on
+     * this client's chain it EXPLAINS that (status `blocked` + a hint), rather than
+     * throwing. Throws `InvalidEnvelopeError` only on an unparseable challenge.
+     *
+     * Then pay the chosen rail with `fetch(url, { autoRoute: true })`, or branch on
+     * the plan yourself. No funds move.
+     */
+    planPayment(url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+    /**
+     * Convenience over {@link planPayment}: can the wallet settle this URL right now?
+     * `true` when at least one rail is payable — or when the URL isn't gated (a free
+     * resource is trivially "affordable"). No funds move.
+     */
+    canAfford(url: string, init?: RequestInit): Promise<boolean>;
     /**
      * Lower-level: drive any HTTP method through the 402 flow.
      *
@@ -4259,6 +4399,14 @@ declare class PipRailClient {
      * `quote()` (read-only) and `fetch()` (which then authorises + pays).
      */
     private resolveChallenge;
+    /** The candidate accepts this client could pay: our scheme, on the bound network. */
+    private gatherCandidates;
+    /** Build the full {@link PaymentPlan} from an already-parsed challenge + bound
+     *  net/wallet. Shared by `planPayment` (read-only) and `fetch`'s autoRoute. */
+    private planFromChallenge;
+    /** Analyse ONE rail against the wallet's holdings — quote (existing) + gas
+     *  (estimateCost, existing) + balanceOf + recipientReady → a {@link PayOption}. */
+    private analyzeRail;
     /** Build the agent-facing quote for an accept: TRUE decimals/symbol (via the
      *  driver's describeAsset) + the policy verdict + a symbol-mismatch flag. */
     private buildQuote;
@@ -4270,6 +4418,16 @@ declare class PipRailClient {
     private payAndConfirm;
     private retryWithProof;
 }
+/**
+ * Plan a payment ACROSS several single-chain clients — the cross-chain brain.
+ * A {@link PipRailClient} is bound to one chain (its wallet); give this one client
+ * per chain the agent funds and it runs each client's {@link PipRailClient.planPayment}
+ * in parallel and merges the rails into one plan, ranked payable-first. `best` is a
+ * payable rail; across different native coins there's no oracle to pick the
+ * fiat-cheapest, so the tiebreak is the order `clients` were given (the agent's own
+ * chain preference). Returns `null` only if the URL isn't gated for any client.
+ */
+declare function planAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<PaymentPlan | null>;
 
 /** A framework-agnostic tool definition an agent runtime can register. */
 interface AgentTool {
@@ -4758,4 +4916,4 @@ declare function encodeXPaymentHeader(input: {
     x402Version?: number;
 }): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, InsufficientFundsError, InvalidEnvelopeError, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPolicy, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletHandle, type WalletInput, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildReceiptHeader, buildSignatureHeader, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, registerDriver, requirePayment, resolveChain, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, InsufficientFundsError, InvalidEnvelopeError, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildReceiptHeader, buildSignatureHeader, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, registerDriver, requirePayment, resolveChain, toInsufficientFundsError, toInvalidBody };

package/dist/index.d.ts

@@ -3777,9 +3777,9 @@ declare function resolveChain(input: ChainInput, rpcUrlOverride?: string): Resol
  */
 
 /** The chain families the SDK knows about. */
-type ChainFamily = 'evm' | 'solana' | 'ton' | 'stellar' | 'xrpl' | 'tron' | 'sui' | 'near' | 'aptos';
+type ChainFamily = 'evm' | 'solana' | 'ton' | 'stellar' | 'xrpl' | 'tron' | 'sui' | 'near' | 'aptos' | 'algorand';
 /** What chain to use: an EVM name/Chain/{id,rpcUrl}, or a non-EVM family name. */
-type ChainSelector = ChainInput | 'solana' | 'ton' | 'stellar' | 'xrpl' | 'tron' | 'sui' | 'near' | 'aptos';
+type ChainSelector = ChainInput | 'solana' | 'ton' | 'stellar' | 'xrpl' | 'tron' | 'sui' | 'near' | 'aptos' | 'algorand';
 /** An EVM ERC-20 token, by contract address. */
 interface EvmToken {
     address: `0x${string}`;
@@ -3837,6 +3837,12 @@ interface AptosToken {
     decimals: number;
     symbol?: string;
 }
+/** An Algorand Standard Asset (ASA), by its numeric asset id. */
+interface AlgorandToken {
+    assetId: number;
+    decimals: number;
+    symbol?: string;
+}
 /**
  * What to be paid in. Each driver validates the forms it accepts:
  *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP)
@@ -3850,8 +3856,9 @@ interface AptosToken {
  *   - SuiToken        any coin           (Sui)
  *   - NearToken       any NEP-141        (NEAR)
  *   - AptosToken      any Fungible Asset (Aptos)
+ *   - AlgorandToken   any ASA            (Algorand)
  */
-type TokenInput = 'native' | (string & {}) | EvmToken | SolanaToken | TonToken | StellarToken | XrplToken | TronToken | SuiToken | NearToken | AptosToken;
+type TokenInput = 'native' | (string & {}) | EvmToken | SolanaToken | TonToken | StellarToken | XrplToken | TronToken | SuiToken | NearToken | AptosToken | AlgorandToken;
 /** What a driver resolves a TokenInput into. `asset`: 0x | base58 mint | 'native'. */
 interface ResolvedToken {
     asset: string;
@@ -3885,6 +3892,22 @@ interface CostEstimate {
 interface WalletHandle {
     readonly _native: unknown;
 }
+/**
+ * Why a recipient can't receive an asset yet — the chain's one-time receive
+ * prerequisite, when it has one. Surfaced by {@link ResolvedNetwork.recipientReady}
+ * and relayed by the client's planner so an agent fixes the RECIPIENT (not its own
+ * balance). Families with no prerequisite report `ready: 'n/a'` and no reason.
+ */
+type RecipientReason = 'NO_TRUSTLINE' | 'NOT_REGISTERED' | 'NOT_OPTED_IN' | 'INACTIVE';
+/** What {@link ResolvedNetwork.balanceOf} returns — base-unit balances, or null per
+ *  field when that read was unavailable (transient/RPC), never a false 0. */
+interface WalletBalance {
+    /** The payment token's balance in base units, or null if the read was unavailable. */
+    token: bigint | null;
+    /** The native gas coin's balance in base units, or null if unavailable. For
+     *  `asset === 'native'`, this equals `token`. */
+    native: bigint | null;
+}
 interface ConfirmInfo {
     /** Block number (EVM) or slot (Solana) as a string — numeric-agnostic. */
     height: string;
@@ -3939,6 +3962,31 @@ interface ResolvedNetwork {
     estimateCost(accept: X402AcceptEntry, opts?: {
         from?: string;
     }): Promise<CostEstimate>;
+    /**
+     * Read the BOUND WALLET's own balance of the payment `asset` AND of the native
+     * gas coin, in base units — what the client's `planPayment` checks affordability
+     * against. RPC-read-only and NEVER throws: a field whose read was unavailable
+     * (rate-limited / transient) comes back `null` (unknown), never `0` (which would
+     * falsely read "broke"). For `asset === 'native'`, `token === native`.
+     * Payer-side + informational — the gate never calls this. See {@link WalletBalance}.
+     */
+    balanceOf(wallet: WalletHandle, asset: string): Promise<WalletBalance>;
+    /**
+     * Can `payTo` RECEIVE `asset` on this network right now? Reports the chain's
+     * one-time receive prerequisite (trustline / storage_deposit / ASA opt-in /
+     * activation):
+     *   - `{ ready: 'n/a' }`         the family has NO prerequisite (EVM, Solana, TON,
+     *                                Tron, Sui, Aptos — and every native coin)
+     *   - `{ ready: true }`          the prerequisite is satisfied
+     *   - `{ ready: false, reason }` it's missing (see {@link RecipientReason}) — fix the recipient
+     *   - `{ ready: 'unknown' }`     the probe read failed (transient) — NEVER throws
+     * Re-derives nothing from a client ref; reads only the given `payTo`. Payer-side
+     * pre-flight — the gate never calls this.
+     */
+    recipientReady(payTo: string, asset: string): Promise<{
+        ready: boolean | 'n/a' | 'unknown';
+        reason?: RecipientReason;
+    }>;
     /** Verify `ref` satisfies `accept`, RPC-only, in-process. */
     verify(ref: string, accept: X402AcceptEntry): Promise<VerifyResult>;
 }
@@ -4155,6 +4203,62 @@ interface PipRailCostQuote {
     /** Estimated network fee (gas) in the chain's native coin. */
     cost: CostEstimate;
 }
+/** A hard reason a rail can't be settled right now — each maps to a concrete fix. */
+type PayBlocker = 'INSUFFICIENT_TOKEN' | 'INSUFFICIENT_GAS' | 'RECIPIENT_NOT_READY' | 'OUTSIDE_POLICY';
+/** A soft flag — never blocks, always worth surfacing to the agent. */
+type PayWarning = 'SYMBOL_MISMATCH' | 'BALANCE_UNREADABLE' | 'RECIPIENT_READINESS_UNKNOWN' | 'GAS_HEURISTIC' | 'THIN_GAS_MARGIN';
+/** One offered rail, fully analysed against the bound wallet's own holdings. */
+interface PayOption {
+    /** The rail this analyses (one entry from the 402's accepts[]). */
+    accept: X402AcceptEntry;
+    /** The priced requirement — TRUE decimals/symbol + the policy verdict. */
+    quote: PipRailQuote;
+    /** Estimated native-coin gas to send it (cost.basis surfaced). */
+    cost: CostEstimate;
+    /** The verdict for THIS rail. 'unknown' = a read failed, so payability can't be confirmed. */
+    state: 'payable' | 'blocked' | 'unknown';
+    /** Hard reasons it's blocked (empty when payable). */
+    blockers: PayBlocker[];
+    /** Soft flags (may be present even when payable). */
+    warnings: PayWarning[];
+    /** Live wallet holdings, human units; null = the read was unavailable (NOT zero). */
+    balance: {
+        token: string | null;
+        native: string | null;
+    };
+    /** What this rail needs: the payment amount + the estimated gas, human units. */
+    need: {
+        token: string;
+        native: string;
+    };
+    /** How much MORE is needed to clear a funds blocker, human units (omitted when funded). */
+    shortfall?: {
+        token?: string;
+        native?: string;
+    };
+    /** Can payTo receive this asset right now, and if not, what fixes it. */
+    recipient: {
+        ready: boolean | 'n/a' | 'unknown';
+        reason?: RecipientReason;
+        fix?: string;
+    };
+}
+/** The plan for ONE 402 across every rail this client can pay (its bound network). */
+interface PaymentPlan {
+    url: string;
+    /** The network this client is bound to (the rails it can settle). */
+    network: Caip2;
+    /** Top-level verdict for instant branching. */
+    status: 'ready' | 'blocked' | 'unknown';
+    /** True iff at least one rail is payable now (best !== null). */
+    payable: boolean;
+    /** The rail to use: the cheapest (within native coin) payable option, or null. */
+    best: PayOption | null;
+    /** Every offered+supported rail, ranked: payable → unknown → blocked. */
+    options: PayOption[];
+    /** When NOT payable: one human, actionable sentence on exactly what to do. */
+    fundingHint: string | null;
+}
 interface PipRailClientOptions {
     /** Wallet for the chosen chain family. */
     wallet: WalletInput;
@@ -4193,6 +4297,16 @@ interface PipRailClientOptions {
     maxPaymentRetries?: number;
     /** Timeout (ms) for the retry leg after broadcast. Default 30_000. */
     retryTimeoutMs?: number;
+    /**
+     * Balance-aware routing: when true, `fetch()` runs `planPayment` on a 402 and
+     * pays the cheapest rail the wallet can ACTUALLY settle (token + native gas +
+     * recipient-ready), instead of the first policy-passing accept. If none is
+     * settleable it throws {@link PaymentDeclinedError} carrying the funding hint —
+     * before any send. Default **false** (defaults never change): the zero-config
+     * path keeps its existing selection. Recommended for multi-rail 402s. Override
+     * per call with `fetch(url, { autoRoute: true })`.
+     */
+    autoRoute?: boolean;
     /** Logger hook. Default no-op. */
     onEvent?: (event: PipRailEvent) => void;
 }
@@ -4245,6 +4359,32 @@ declare class PipRailClient {
     /** Aggregated snapshot of every payment this client has settled — total
      *  count, cumulative spend per token, and the individual records. */
     spent(): SpendSummary;
+    /**
+     * Plan a payment for a gated URL — WITHOUT paying. The read-only completion of
+     * the `quote()` → `estimateCost()` → **`planPayment()`** trio: it surveys every
+     * rail the 402 offers on this client's chain against the wallet's OWN holdings —
+     * token balance, native-coin gas, and recipient-readiness (trustline / ATA /
+     * storage_deposit / ASA opt-in) — and returns, crystal-clear:
+     *   - `payable` + `best`   — the cheapest rail the wallet can actually settle
+     *   - `options[]`          — every rail with typed `blockers` + soft `warnings`
+     *   - `fundingHint`        — one human sentence on exactly what to top up
+     *
+     * NEVER throws for a read problem (a transient/RPC failure surfaces as a rail in
+     * `state: 'unknown'` + a warning, never a false "unaffordable"); returns `null`
+     * when the URL isn't payment-gated (no 402); and when the 402 offers no rail on
+     * this client's chain it EXPLAINS that (status `blocked` + a hint), rather than
+     * throwing. Throws `InvalidEnvelopeError` only on an unparseable challenge.
+     *
+     * Then pay the chosen rail with `fetch(url, { autoRoute: true })`, or branch on
+     * the plan yourself. No funds move.
+     */
+    planPayment(url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+    /**
+     * Convenience over {@link planPayment}: can the wallet settle this URL right now?
+     * `true` when at least one rail is payable — or when the URL isn't gated (a free
+     * resource is trivially "affordable"). No funds move.
+     */
+    canAfford(url: string, init?: RequestInit): Promise<boolean>;
     /**
      * Lower-level: drive any HTTP method through the 402 flow.
      *
@@ -4259,6 +4399,14 @@ declare class PipRailClient {
      * `quote()` (read-only) and `fetch()` (which then authorises + pays).
      */
     private resolveChallenge;
+    /** The candidate accepts this client could pay: our scheme, on the bound network. */
+    private gatherCandidates;
+    /** Build the full {@link PaymentPlan} from an already-parsed challenge + bound
+     *  net/wallet. Shared by `planPayment` (read-only) and `fetch`'s autoRoute. */
+    private planFromChallenge;
+    /** Analyse ONE rail against the wallet's holdings — quote (existing) + gas
+     *  (estimateCost, existing) + balanceOf + recipientReady → a {@link PayOption}. */
+    private analyzeRail;
     /** Build the agent-facing quote for an accept: TRUE decimals/symbol (via the
      *  driver's describeAsset) + the policy verdict + a symbol-mismatch flag. */
     private buildQuote;
@@ -4270,6 +4418,16 @@ declare class PipRailClient {
     private payAndConfirm;
     private retryWithProof;
 }
+/**
+ * Plan a payment ACROSS several single-chain clients — the cross-chain brain.
+ * A {@link PipRailClient} is bound to one chain (its wallet); give this one client
+ * per chain the agent funds and it runs each client's {@link PipRailClient.planPayment}
+ * in parallel and merges the rails into one plan, ranked payable-first. `best` is a
+ * payable rail; across different native coins there's no oracle to pick the
+ * fiat-cheapest, so the tiebreak is the order `clients` were given (the agent's own
+ * chain preference). Returns `null` only if the URL isn't gated for any client.
+ */
+declare function planAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<PaymentPlan | null>;
 
 /** A framework-agnostic tool definition an agent runtime can register. */
 interface AgentTool {
@@ -4758,4 +4916,4 @@ declare function encodeXPaymentHeader(input: {
     x402Version?: number;
 }): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, InsufficientFundsError, InvalidEnvelopeError, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPolicy, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletHandle, type WalletInput, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildReceiptHeader, buildSignatureHeader, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, registerDriver, requirePayment, resolveChain, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, InsufficientFundsError, InvalidEnvelopeError, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildReceiptHeader, buildSignatureHeader, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, registerDriver, requirePayment, resolveChain, toInsufficientFundsError, toInvalidBody };