@piprail/sdk 1.4.0 → 1.5.1

package/dist/index.d.cts

@@ -3845,7 +3845,7 @@ interface AlgorandToken {
 }
 /**
  * What to be paid in. Each driver validates the forms it accepts:
- *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP)
+ *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP, TRX, NEAR, SUI, APT, ALGO)
  *   - 'USDC' (string) a symbol resolved against the chosen chain
  *   - EvmToken        any ERC-20         (EVM chains)
  *   - SolanaToken     any SPL token      (Solana)
@@ -3892,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;
@@ -3946,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>;
 }
@@ -4089,6 +4130,8 @@ type PipRailEvent = {
  *   - Stellar → `{ secret }` (S… seed) or a ready `{ keypair }`
  *   - XRPL    → `{ seed }` (s… seed) or a ready `{ wallet }`
  *   - NEAR    → `{ accountId, privateKey }` (privateKey = ed25519:… secret)
+ *   - Aptos   → `{ privateKey }` (AIP-80 `ed25519-priv-0x…` / raw `0x…` hex) or `{ account }`
+ *   - Algorand→ `{ mnemonic }` (25 words) or a ready `{ account }`
  */
 type WalletInput = {
     privateKey: string;
@@ -4162,11 +4205,67 @@ 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;
     /** Which chain to pay on. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar',
-     *  'xrpl', 'tron', 'sui', or 'near'. */
+     *  'xrpl', 'tron', 'sui', 'near', 'aptos', or 'algorand'. */
     chain: ChainSelector;
     /** Override the chain's default RPC URL (recommended in production). */
     rpcUrl?: string;
@@ -4200,6 +4299,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;
 }
@@ -4252,6 +4361,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.
      *
@@ -4266,6 +4401,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;
@@ -4277,6 +4420,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 {
@@ -4290,8 +4443,10 @@ interface AgentTool {
     invoke: (args: Record<string, unknown>) => Promise<unknown>;
 }
 /**
- * Two tools wrapping a configured {@link PipRailClient}:
+ * Three tools wrapping a configured {@link PipRailClient}:
  *   - `piprail_quote_payment(url)` — price a gated URL WITHOUT paying.
+ *   - `piprail_plan_payment(url)` — check you CAN pay (balance + gas + recipient
+ *     readiness) across every rail the URL offers, WITHOUT paying.
  *   - `piprail_pay_request(url, method?, body?)` — pay if needed and return the result.
  *
  * A policy/approval refusal comes back as a structured `{ declined: true, reason }`
@@ -4327,7 +4482,7 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
  */
 interface AcceptOption {
     /** Which chain. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar', 'xrpl',
-     *  'tron', 'near', or 'sui'. */
+     *  'tron', 'near', 'sui', 'aptos', or 'algorand'. */
     chain: ChainSelector;
     /** Token to be paid in (symbol / 'native' / custom descriptor). */
     token: TokenInput;
@@ -4341,8 +4496,9 @@ interface AcceptOption {
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
-     * 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', or 'sui'. Provide
-     * `chain` + `token` + `amount`, OR use the multi-chain `accept` array below.
+     * 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', 'sui', 'aptos', or
+     * 'algorand'. Provide `chain` + `token` + `amount`, OR use the multi-chain
+     * `accept` array below.
      */
     chain?: ChainSelector;
     /** Override the chain's default RPC URL (recommended in production). */
@@ -4353,9 +4509,10 @@ interface RequirePaymentOptions {
      * `{ address, decimals }` on EVM/Tron, `{ mint, decimals }` on Solana,
      * `{ master, decimals }` on TON, `{ issuer, code, decimals }` on Stellar,
      * `{ issuer, currencyHex, decimals }` on XRPL, `{ contractId, decimals }` on
-     * NEAR, `{ coinType, decimals }` on Sui. You name the token; the SDK fills in
+     * NEAR, `{ coinType, decimals }` on Sui, `{ metadata, decimals }` on Aptos, or
+     * `{ assetId, decimals }` on Algorand. You name the token; the SDK fills in
      * the contract + decimals for built-in symbols. (Note: native USDC doesn't
-     * exist on TON/Tron — USDT does; NEAR is FT-only, so `'native'` is rejected.)
+     * exist on TON/Tron — USDT does; native NEAR is supported via `'native'`.)
      */
     token?: TokenInput;
     /** Human-readable amount, e.g. "0.05" (single-chain form). */
@@ -4367,8 +4524,8 @@ interface RequirePaymentOptions {
      */
     accept?: AcceptOption[];
     /** Address that receives the payment (0x… EVM/Sui, base58 Solana, EQ…/UQ… TON,
-     *  G… Stellar, r… XRPL, T… Tron, account id on NEAR). Required for the single
-     *  form; the per-option fallback for the multi form. */
+     *  G… Stellar, r… XRPL, T… Tron, account id on NEAR, 0x… Aptos, base32 Algorand).
+     *  Required for the single form; the per-option fallback for the multi form. */
     payTo?: AddressId;
     /** Shown to the agent in the challenge. */
     description?: string;
@@ -4518,7 +4675,7 @@ declare class InsufficientFundsError extends PipRailError {
  * The message states the requirement and the fix in plain language **and echoes
  * the raw chain code** (e.g. `(XRPL: tecNO_DST_INSUF_XRP)`), while the untouched
  * chain error is preserved on `.cause` for deeper debugging. Chains with no
- * receive prerequisite (EVM, Solana, Sui, Tron, and native TON/NEAR) never throw it.
+ * receive prerequisite (EVM, Solana, Sui, Aptos, Tron, and native TON/NEAR) never throw it.
  */
 declare class RecipientNotReadyError extends PipRailError {
     readonly code = "RECIPIENT_NOT_READY";
@@ -4615,7 +4772,7 @@ declare class NonReplayableBodyError extends PipRailError {
 }
 /**
  * The chosen chain belongs to one family (EVM, Solana, TON, Stellar, XRPL, Tron,
- * Sui, NEAR) but the wallet, payTo, or token was given in another family's form
+ * Sui, NEAR, Aptos, Algorand) but the wallet, payTo, or token was given in another family's form
  * (e.g. an `0x…` payTo on Solana, or a `{ mint }` token on a Stellar chain).
  */
 declare class WrongFamilyError extends PipRailError {
@@ -4627,7 +4784,8 @@ declare class WrongFamilyError extends PipRailError {
  * token by full descriptor ({ address, decimals } EVM/Tron · { mint, decimals }
  * Solana · { master, decimals } TON · { issuer, code, decimals } Stellar ·
  * { issuer, currencyHex, decimals } XRPL · { coinType, decimals } Sui ·
- * { contractId, decimals } NEAR).
+ * { contractId, decimals } NEAR · { metadata, decimals } Aptos ·
+ * { assetId, decimals } Algorand).
  */
 declare class UnknownTokenError extends PipRailError {
     readonly code = "UNKNOWN_TOKEN";
@@ -4639,7 +4797,8 @@ declare class UnknownTokenError extends PipRailError {
  * `npm install @ton/ton @ton/core @ton/crypto`; Stellar:
  * `npm install @stellar/stellar-sdk`; XRPL: `npm install xrpl`; Tron:
  * `npm install tronweb`; Sui: `npm install @mysten/sui`; NEAR:
- * `npm install near-api-js`.
+ * `npm install near-api-js`; Aptos: `npm install @aptos-labs/ts-sdk`;
+ * Algorand: `npm install algosdk`.
  */
 declare class MissingDriverError extends PipRailError {
     readonly code = "MISSING_DRIVER";
@@ -4765,4 +4924,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

@@ -3845,7 +3845,7 @@ interface AlgorandToken {
 }
 /**
  * What to be paid in. Each driver validates the forms it accepts:
- *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP)
+ *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP, TRX, NEAR, SUI, APT, ALGO)
  *   - 'USDC' (string) a symbol resolved against the chosen chain
  *   - EvmToken        any ERC-20         (EVM chains)
  *   - SolanaToken     any SPL token      (Solana)
@@ -3892,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;
@@ -3946,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>;
 }
@@ -4089,6 +4130,8 @@ type PipRailEvent = {
  *   - Stellar → `{ secret }` (S… seed) or a ready `{ keypair }`
  *   - XRPL    → `{ seed }` (s… seed) or a ready `{ wallet }`
  *   - NEAR    → `{ accountId, privateKey }` (privateKey = ed25519:… secret)
+ *   - Aptos   → `{ privateKey }` (AIP-80 `ed25519-priv-0x…` / raw `0x…` hex) or `{ account }`
+ *   - Algorand→ `{ mnemonic }` (25 words) or a ready `{ account }`
  */
 type WalletInput = {
     privateKey: string;
@@ -4162,11 +4205,67 @@ 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;
     /** Which chain to pay on. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar',
-     *  'xrpl', 'tron', 'sui', or 'near'. */
+     *  'xrpl', 'tron', 'sui', 'near', 'aptos', or 'algorand'. */
     chain: ChainSelector;
     /** Override the chain's default RPC URL (recommended in production). */
     rpcUrl?: string;
@@ -4200,6 +4299,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;
 }
@@ -4252,6 +4361,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.
      *
@@ -4266,6 +4401,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;
@@ -4277,6 +4420,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 {
@@ -4290,8 +4443,10 @@ interface AgentTool {
     invoke: (args: Record<string, unknown>) => Promise<unknown>;
 }
 /**
- * Two tools wrapping a configured {@link PipRailClient}:
+ * Three tools wrapping a configured {@link PipRailClient}:
  *   - `piprail_quote_payment(url)` — price a gated URL WITHOUT paying.
+ *   - `piprail_plan_payment(url)` — check you CAN pay (balance + gas + recipient
+ *     readiness) across every rail the URL offers, WITHOUT paying.
  *   - `piprail_pay_request(url, method?, body?)` — pay if needed and return the result.
  *
  * A policy/approval refusal comes back as a structured `{ declined: true, reason }`
@@ -4327,7 +4482,7 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
  */
 interface AcceptOption {
     /** Which chain. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar', 'xrpl',
-     *  'tron', 'near', or 'sui'. */
+     *  'tron', 'near', 'sui', 'aptos', or 'algorand'. */
     chain: ChainSelector;
     /** Token to be paid in (symbol / 'native' / custom descriptor). */
     token: TokenInput;
@@ -4341,8 +4496,9 @@ interface AcceptOption {
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
-     * 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', or 'sui'. Provide
-     * `chain` + `token` + `amount`, OR use the multi-chain `accept` array below.
+     * 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', 'sui', 'aptos', or
+     * 'algorand'. Provide `chain` + `token` + `amount`, OR use the multi-chain
+     * `accept` array below.
      */
     chain?: ChainSelector;
     /** Override the chain's default RPC URL (recommended in production). */
@@ -4353,9 +4509,10 @@ interface RequirePaymentOptions {
      * `{ address, decimals }` on EVM/Tron, `{ mint, decimals }` on Solana,
      * `{ master, decimals }` on TON, `{ issuer, code, decimals }` on Stellar,
      * `{ issuer, currencyHex, decimals }` on XRPL, `{ contractId, decimals }` on
-     * NEAR, `{ coinType, decimals }` on Sui. You name the token; the SDK fills in
+     * NEAR, `{ coinType, decimals }` on Sui, `{ metadata, decimals }` on Aptos, or
+     * `{ assetId, decimals }` on Algorand. You name the token; the SDK fills in
      * the contract + decimals for built-in symbols. (Note: native USDC doesn't
-     * exist on TON/Tron — USDT does; NEAR is FT-only, so `'native'` is rejected.)
+     * exist on TON/Tron — USDT does; native NEAR is supported via `'native'`.)
      */
     token?: TokenInput;
     /** Human-readable amount, e.g. "0.05" (single-chain form). */
@@ -4367,8 +4524,8 @@ interface RequirePaymentOptions {
      */
     accept?: AcceptOption[];
     /** Address that receives the payment (0x… EVM/Sui, base58 Solana, EQ…/UQ… TON,
-     *  G… Stellar, r… XRPL, T… Tron, account id on NEAR). Required for the single
-     *  form; the per-option fallback for the multi form. */
+     *  G… Stellar, r… XRPL, T… Tron, account id on NEAR, 0x… Aptos, base32 Algorand).
+     *  Required for the single form; the per-option fallback for the multi form. */
     payTo?: AddressId;
     /** Shown to the agent in the challenge. */
     description?: string;
@@ -4518,7 +4675,7 @@ declare class InsufficientFundsError extends PipRailError {
  * The message states the requirement and the fix in plain language **and echoes
  * the raw chain code** (e.g. `(XRPL: tecNO_DST_INSUF_XRP)`), while the untouched
  * chain error is preserved on `.cause` for deeper debugging. Chains with no
- * receive prerequisite (EVM, Solana, Sui, Tron, and native TON/NEAR) never throw it.
+ * receive prerequisite (EVM, Solana, Sui, Aptos, Tron, and native TON/NEAR) never throw it.
  */
 declare class RecipientNotReadyError extends PipRailError {
     readonly code = "RECIPIENT_NOT_READY";
@@ -4615,7 +4772,7 @@ declare class NonReplayableBodyError extends PipRailError {
 }
 /**
  * The chosen chain belongs to one family (EVM, Solana, TON, Stellar, XRPL, Tron,
- * Sui, NEAR) but the wallet, payTo, or token was given in another family's form
+ * Sui, NEAR, Aptos, Algorand) but the wallet, payTo, or token was given in another family's form
  * (e.g. an `0x…` payTo on Solana, or a `{ mint }` token on a Stellar chain).
  */
 declare class WrongFamilyError extends PipRailError {
@@ -4627,7 +4784,8 @@ declare class WrongFamilyError extends PipRailError {
  * token by full descriptor ({ address, decimals } EVM/Tron · { mint, decimals }
  * Solana · { master, decimals } TON · { issuer, code, decimals } Stellar ·
  * { issuer, currencyHex, decimals } XRPL · { coinType, decimals } Sui ·
- * { contractId, decimals } NEAR).
+ * { contractId, decimals } NEAR · { metadata, decimals } Aptos ·
+ * { assetId, decimals } Algorand).
  */
 declare class UnknownTokenError extends PipRailError {
     readonly code = "UNKNOWN_TOKEN";
@@ -4639,7 +4797,8 @@ declare class UnknownTokenError extends PipRailError {
  * `npm install @ton/ton @ton/core @ton/crypto`; Stellar:
  * `npm install @stellar/stellar-sdk`; XRPL: `npm install xrpl`; Tron:
  * `npm install tronweb`; Sui: `npm install @mysten/sui`; NEAR:
- * `npm install near-api-js`.
+ * `npm install near-api-js`; Aptos: `npm install @aptos-labs/ts-sdk`;
+ * Algorand: `npm install algosdk`.
  */
 declare class MissingDriverError extends PipRailError {
     readonly code = "MISSING_DRIVER";
@@ -4765,4 +4924,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 };