@piprail/sdk 1.23.0 → 1.25.0

package/dist/index.d.cts

@@ -5204,6 +5204,22 @@ interface RegisterOptions {
      */
     attribution?: boolean;
 }
+/**
+ * The read-+-pay surface an agent toolkit needs — the methods {@link paymentTools}
+ * calls. BOTH {@link PipRailClient} (one chain) and {@link MultiChainPayer} (many
+ * chains, one per wallet) satisfy it, so `paymentTools` wraps either unchanged:
+ * point an MCP/LLM at one wallet or at a whole bundle without touching the tools.
+ */
+interface PayingClient {
+    discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
+    quote(url: string, init?: RequestInit): Promise<PipRailQuote | null>;
+    planPayment(url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+    get(url: string, init?: RequestInit): Promise<Response>;
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
+    spent(): SpendSummary;
+    budget(): SessionBudget;
+}
 declare class PipRailClient {
     private readonly opts;
     private readonly maxRetries;
@@ -5453,11 +5469,188 @@ declare class PipRailClient {
  * 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.
+ * payable rail. Across different native coins there's no oracle to compare gas costs,
+ * so it does NOT rank chains by fee against each other: `best` is the FIRST chain you
+ * pass in `clients` that can settle (your preference order); within a single chain it
+ * still prefers the cheapest-gas rail. Returns `null` only if the URL isn't gated for
+ * any client. Throws only if EVERY client fails to reach the resource (a total outage),
+ * mirroring a single client — a single chain being down just drops that chain.
  */
 declare function planAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+/**
+ * PAY across several single-chain clients — the EXECUTION counterpart to
+ * {@link planAcross}. Plans the URL on every client in parallel (keeping which
+ * client owns which rail), picks the rail `planAcross` names as `best` (the first
+ * funded chain you listed that can settle RIGHT NOW), and pays it on its owning
+ * client. So an agent that holds one wallet
+ * per chain pays whichever chain/token the merchant's 402 asks for — with no
+ * manual routing — while every payment still goes through that client's own
+ * spend policy, `onBeforePay` hook, retries, and replay-protection (this just
+ * calls the chosen client's {@link PipRailClient.fetch}).
+ *
+ * - A URL that needs no payment (no 402) is returned straight through.
+ * - When NO funded chain can settle it, throws {@link PaymentDeclinedError} with a
+ *   merged, per-chain funding hint — BEFORE any on-chain send.
+ *
+ * Selection matches {@link planAcross}: payable-first, and across different native
+ * coins (no price oracle) the FIRST chain you pass in `clients` that can settle wins
+ * (your preference); within a chain, the cheapest-gas rail. It normally pays the rail
+ * `planAcross` reports as `best`, but on a BEST-EFFORT basis — the owning client
+ * re-reads its balances/gas at pay time, so a change between planning and paying (a
+ * concurrent payment, RPC drift, the merchant returning a different 402) can make it
+ * pick another settleable rail ON THE SAME CHAIN, or decline; its spend policy +
+ * `onBeforePay` still gate whatever is actually paid. For the ergonomic object form,
+ * see {@link MultiChainPayer}.
+ *
+ * NOTE: this PROBES the URL with the caller's `init` (method + body) on each client to
+ * read the 402, so prefer it for GET / idempotent requests — a non-idempotent POST is
+ * sent once per client before the pay leg (the x402 gate returns 402 without acting,
+ * but the body is re-sent).
+ */
+declare function fetchAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<Response>;
+
+/**
+ * MultiChainPayer — one buyer, many wallets, pay whatever the merchant asks.
+ *
+ * A {@link PipRailClient} is bound to exactly ONE chain and ONE wallet (an EVM key
+ * can't sign a Solana tx, and vice-versa — that's enforced at bind time). So a
+ * buyer who wants to pay a 402 *whatever chain/token it demands* holds one key per
+ * chain. This is the ergonomic object that carries that bundle: give it a
+ * `{ chain → wallet }` map and it builds one client per chain, then exposes a single
+ * `fetch`/`get`/`post`/`plan`/`quote` that auto-routes to the first funded chain that
+ * can settle — no manual "which client owns this rail?" plumbing.
+ *
+ * It is a thin, chain-agnostic composition over the existing primitives — it adds
+ * NO new payment logic:
+ *   - `planPayment` → {@link planAcross} (merge every chain's plan, payable-first)
+ *   - `fetch`/`get`/`post` → {@link fetchAcross} (pay on the first chain that can settle)
+ * Every payment still runs through its owning client's own spend policy,
+ * `onBeforePay` hook, retries, and replay-protection. There is no cross-chain
+ * custody, no price oracle, and no backend: across chains it pays the FIRST one you
+ * list that can settle (your preference order — gas isn't comparable across coins);
+ * within a chain it picks the cheapest-gas rail.
+ *
+ * Because it implements {@link PayingClient}, the agent toolkit ({@link paymentTools})
+ * and the MCP server wrap it byte-identically to a single client.
+ */
+
+/**
+ * One wallet per chain you fund, keyed by chain selector. The KEY is a chain
+ * string (an EVM preset like `'base'`/`'bnb'`, or a non-EVM family
+ * `'solana'|'ton'|'tron'|'near'|'sui'|'aptos'|'algorand'|'stellar'|'xrpl'`); the
+ * VALUE is that family's {@link WalletInput}:
+ *
+ *   base/bnb/… → { privateKey }   solana → { secretKey }   ton/algorand → { mnemonic }
+ *   stellar → { secret }   xrpl → { seed }   near → { accountId, privateKey }
+ *
+ * One key per family — this map is how a single buyer carries the keys for every
+ * chain it's willing to pay on. (For a CUSTOM EVM chain configured by a viem
+ * `Chain` object, build the {@link PipRailClient} yourself and use
+ * `new MultiChainPayer([...clients])`.)
+ */
+interface MultiChainPayerOptions {
+    /** `{ chain → wallet }`. Iteration order is your chain PREFERENCE: across chains the
+     *  first one that can settle wins (there's no oracle to compare gas across coins). */
+    wallets: Record<string, WalletInput>;
+    /** Spend policy applied to EVERY chain's client. Each client still keeps its own
+     *  per-(network,asset) ledger — there is no cross-token sum (no price oracle). */
+    policy?: PaymentPolicy;
+    /** Per-chain RPC overrides, keyed by the same chain selector as `wallets`. */
+    rpcUrls?: Record<string, string>;
+    /** Which schemes every client may settle. Default `['onchain-proof']` (unchanged). */
+    schemes?: PaymentScheme[];
+    /** Final approval hook applied to every chain's client (fires before any send). */
+    onBeforePay?: (quote: PipRailQuote) => boolean | Promise<boolean>;
+    /** Observability hook applied to every chain's client. */
+    onEvent?: (event: PipRailEvent) => void;
+    /** Retry budget for the post-broadcast leg, per client. Default 3. */
+    maxPaymentRetries?: number;
+    /** Timeout (ms) for the retry leg, per client. Default 30_000. */
+    retryTimeoutMs?: number;
+}
+declare class MultiChainPayer implements PayingClient {
+    private readonly _clients;
+    /**
+     * Wrap an explicit, ordered set of single-chain clients — use this when a client
+     * needs full control (e.g. a custom EVM chain configured by a viem `Chain`). The
+     * ORDER is your chain preference: across chains the first that can settle wins. Pass
+     * at MOST one client per chain — two clients on the SAME network would double-count in
+     * `spent()`/`budget()` and waste a plan round-trip (`fromWallets` can't produce this).
+     * For the common case, prefer {@link MultiChainPayer.fromWallets}.
+     */
+    constructor(clients: PipRailClient[]);
+    /**
+     * Build one client per funded chain from a `{ chain → wallet }` map — the
+     * ergonomic path. The shared `policy`/`schemes`/`onBeforePay`/`onEvent` apply to
+     * every client; `rpcUrls` are matched per chain. Iteration order of `wallets` is
+     * the chain preference.
+     *
+     * ```ts
+     * const payer = MultiChainPayer.fromWallets({
+     *   wallets: {
+     *     base:    { privateKey: process.env.EVM_KEY! },
+     *     solana:  { secretKey:  process.env.SOLANA_SECRET! },
+     *     xrpl:    { seed:       process.env.XRPL_SEED! },
+     *   },
+     *   policy: { maxAmount: '1.00', maxTotal: '20.00', tokens: ['USDC', 'USDT'] },
+     * })
+     * const res = await payer.get('https://api.example.com/paid')  // pays on the first funded chain that can settle
+     * ```
+     */
+    static fromWallets(opts: MultiChainPayerOptions): MultiChainPayer;
+    /** The underlying single-chain clients, in preference order. Reach for one of
+     *  these for chain-specific reads (`estimateCost`, `discoverySigner`, per-chain
+     *  `budget()`) that don't make sense merged. */
+    get clients(): readonly PipRailClient[];
+    /** Plan a 402 across every funded chain — merged + ranked payable-first. `null`
+     *  when the URL needs no payment. (Delegates to {@link planAcross}.) */
+    planPayment(url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+    /** Can ANY funded chain settle this URL right now? (A free resource is trivially
+     *  "affordable".) No funds move. */
+    canAfford(url: string, init?: RequestInit): Promise<boolean>;
+    /** Price a gated URL across funded chains — the chosen rail's quote (the first
+     *  funded chain that can settle), else the first offered rail's. `null` when the URL
+     *  needs no payment. When it IS
+     *  gated but none of your chains are offered, surfaces the same informative
+     *  `NoCompatibleAcceptError` a single client would (it names the chains the 402 is
+     *  payable on) rather than a misleading `null`. No funds move. */
+    quote(url: string, init?: RequestInit): Promise<PipRailQuote | null>;
+    /** Pay the first funded chain (in your listed order) that can settle this URL.
+     *  Delegates to {@link fetchAcross} — full policy / approval / retry / replay path on
+     *  the owning client. The owner re-reads balances at pay time, so the rail paid is the
+     *  surfaced `best` on a best-effort basis (it can pick another rail on the SAME chain,
+     *  or decline, if balances shift between plan and pay). PROBES the URL with `init`
+     *  (method + body) per client — prefer GET / idempotent requests. */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** GET that auto-pays across chains. */
+    get(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * POST that auto-pays across chains. `body` is a string/FormData/URLSearchParams/
+     * ArrayBuffer/Blob (sent as-is) or a plain object (serialised as JSON) — mirrors
+     * {@link PipRailClient.post}.
+     */
+    post(url: string, body?: BodyInit | object | undefined, init?: RequestInit): Promise<Response>;
+    /**
+     * Find payable resources across every funded chain. With the default
+     * `network: 'self'`, each chain's own results are merged + deduped by URL (so
+     * "self" means "any chain I can pay"). A network-scoped query (a CAIP-2 id or
+     * `'any'`) is chain-independent, so one client answers it. Never throws for a
+     * read problem; moves no funds.
+     */
+    discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
+    /** List a resource YOU run on the open indexes. Registration is a merchant action
+     *  independent of which chain you pay FROM, so it goes through your first chain's
+     *  client; pass `opts.network` to advertise a specific chain. Moves no funds. */
+    register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
+    /** Aggregate spend across every chain — counts summed; per-(network,asset) rows
+     *  and records concatenated (no cross-chain collisions, never a cross-token sum). */
+    spent(): SpendSummary;
+    /** A merged budget view: every chain's per-(network,asset) remaining rows, plus the
+     *  MOST-RESTRICTIVE session time envelope across chains (the soonest deadline wins).
+     *  Mirrors {@link PipRailClient.budget}'s shape so the agent toolkit reads it
+     *  unchanged; per-chain session detail is on each `clients[i].budget()`. */
+    budget(): SessionBudget;
+}
 
 /**
  * MCP-style tool annotations — optional, advisory hints that let an MCP client or
@@ -5514,7 +5707,7 @@ interface AgentTool {
  * declined? }`) — never a thrown error — so the model reasons about it (and never
  * re-pays a broadcast-but-unconfirmed payment) instead of crashing.
  */
-declare function paymentTools(client: PipRailClient): AgentTool[];
+declare function paymentTools(client: PayingClient): AgentTool[];
 
 /**
  * One line summarising a {@link PaymentPlan} for a model: what's payable, on which
@@ -7031,4 +7224,4 @@ declare const PERMIT2_WITNESS_TYPES: {
  */
 declare function renderLandingPage(sd: SelfDescription): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, 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, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, 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, POWERED_BY, 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 SelfDescribeRail, type SelfDescription, 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, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, 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, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type 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 SelfDescribeRail, type SelfDescription, 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, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.d.ts

@@ -5204,6 +5204,22 @@ interface RegisterOptions {
      */
     attribution?: boolean;
 }
+/**
+ * The read-+-pay surface an agent toolkit needs — the methods {@link paymentTools}
+ * calls. BOTH {@link PipRailClient} (one chain) and {@link MultiChainPayer} (many
+ * chains, one per wallet) satisfy it, so `paymentTools` wraps either unchanged:
+ * point an MCP/LLM at one wallet or at a whole bundle without touching the tools.
+ */
+interface PayingClient {
+    discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
+    quote(url: string, init?: RequestInit): Promise<PipRailQuote | null>;
+    planPayment(url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+    get(url: string, init?: RequestInit): Promise<Response>;
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
+    spent(): SpendSummary;
+    budget(): SessionBudget;
+}
 declare class PipRailClient {
     private readonly opts;
     private readonly maxRetries;
@@ -5453,11 +5469,188 @@ declare class PipRailClient {
  * 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.
+ * payable rail. Across different native coins there's no oracle to compare gas costs,
+ * so it does NOT rank chains by fee against each other: `best` is the FIRST chain you
+ * pass in `clients` that can settle (your preference order); within a single chain it
+ * still prefers the cheapest-gas rail. Returns `null` only if the URL isn't gated for
+ * any client. Throws only if EVERY client fails to reach the resource (a total outage),
+ * mirroring a single client — a single chain being down just drops that chain.
  */
 declare function planAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+/**
+ * PAY across several single-chain clients — the EXECUTION counterpart to
+ * {@link planAcross}. Plans the URL on every client in parallel (keeping which
+ * client owns which rail), picks the rail `planAcross` names as `best` (the first
+ * funded chain you listed that can settle RIGHT NOW), and pays it on its owning
+ * client. So an agent that holds one wallet
+ * per chain pays whichever chain/token the merchant's 402 asks for — with no
+ * manual routing — while every payment still goes through that client's own
+ * spend policy, `onBeforePay` hook, retries, and replay-protection (this just
+ * calls the chosen client's {@link PipRailClient.fetch}).
+ *
+ * - A URL that needs no payment (no 402) is returned straight through.
+ * - When NO funded chain can settle it, throws {@link PaymentDeclinedError} with a
+ *   merged, per-chain funding hint — BEFORE any on-chain send.
+ *
+ * Selection matches {@link planAcross}: payable-first, and across different native
+ * coins (no price oracle) the FIRST chain you pass in `clients` that can settle wins
+ * (your preference); within a chain, the cheapest-gas rail. It normally pays the rail
+ * `planAcross` reports as `best`, but on a BEST-EFFORT basis — the owning client
+ * re-reads its balances/gas at pay time, so a change between planning and paying (a
+ * concurrent payment, RPC drift, the merchant returning a different 402) can make it
+ * pick another settleable rail ON THE SAME CHAIN, or decline; its spend policy +
+ * `onBeforePay` still gate whatever is actually paid. For the ergonomic object form,
+ * see {@link MultiChainPayer}.
+ *
+ * NOTE: this PROBES the URL with the caller's `init` (method + body) on each client to
+ * read the 402, so prefer it for GET / idempotent requests — a non-idempotent POST is
+ * sent once per client before the pay leg (the x402 gate returns 402 without acting,
+ * but the body is re-sent).
+ */
+declare function fetchAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<Response>;
+
+/**
+ * MultiChainPayer — one buyer, many wallets, pay whatever the merchant asks.
+ *
+ * A {@link PipRailClient} is bound to exactly ONE chain and ONE wallet (an EVM key
+ * can't sign a Solana tx, and vice-versa — that's enforced at bind time). So a
+ * buyer who wants to pay a 402 *whatever chain/token it demands* holds one key per
+ * chain. This is the ergonomic object that carries that bundle: give it a
+ * `{ chain → wallet }` map and it builds one client per chain, then exposes a single
+ * `fetch`/`get`/`post`/`plan`/`quote` that auto-routes to the first funded chain that
+ * can settle — no manual "which client owns this rail?" plumbing.
+ *
+ * It is a thin, chain-agnostic composition over the existing primitives — it adds
+ * NO new payment logic:
+ *   - `planPayment` → {@link planAcross} (merge every chain's plan, payable-first)
+ *   - `fetch`/`get`/`post` → {@link fetchAcross} (pay on the first chain that can settle)
+ * Every payment still runs through its owning client's own spend policy,
+ * `onBeforePay` hook, retries, and replay-protection. There is no cross-chain
+ * custody, no price oracle, and no backend: across chains it pays the FIRST one you
+ * list that can settle (your preference order — gas isn't comparable across coins);
+ * within a chain it picks the cheapest-gas rail.
+ *
+ * Because it implements {@link PayingClient}, the agent toolkit ({@link paymentTools})
+ * and the MCP server wrap it byte-identically to a single client.
+ */
+
+/**
+ * One wallet per chain you fund, keyed by chain selector. The KEY is a chain
+ * string (an EVM preset like `'base'`/`'bnb'`, or a non-EVM family
+ * `'solana'|'ton'|'tron'|'near'|'sui'|'aptos'|'algorand'|'stellar'|'xrpl'`); the
+ * VALUE is that family's {@link WalletInput}:
+ *
+ *   base/bnb/… → { privateKey }   solana → { secretKey }   ton/algorand → { mnemonic }
+ *   stellar → { secret }   xrpl → { seed }   near → { accountId, privateKey }
+ *
+ * One key per family — this map is how a single buyer carries the keys for every
+ * chain it's willing to pay on. (For a CUSTOM EVM chain configured by a viem
+ * `Chain` object, build the {@link PipRailClient} yourself and use
+ * `new MultiChainPayer([...clients])`.)
+ */
+interface MultiChainPayerOptions {
+    /** `{ chain → wallet }`. Iteration order is your chain PREFERENCE: across chains the
+     *  first one that can settle wins (there's no oracle to compare gas across coins). */
+    wallets: Record<string, WalletInput>;
+    /** Spend policy applied to EVERY chain's client. Each client still keeps its own
+     *  per-(network,asset) ledger — there is no cross-token sum (no price oracle). */
+    policy?: PaymentPolicy;
+    /** Per-chain RPC overrides, keyed by the same chain selector as `wallets`. */
+    rpcUrls?: Record<string, string>;
+    /** Which schemes every client may settle. Default `['onchain-proof']` (unchanged). */
+    schemes?: PaymentScheme[];
+    /** Final approval hook applied to every chain's client (fires before any send). */
+    onBeforePay?: (quote: PipRailQuote) => boolean | Promise<boolean>;
+    /** Observability hook applied to every chain's client. */
+    onEvent?: (event: PipRailEvent) => void;
+    /** Retry budget for the post-broadcast leg, per client. Default 3. */
+    maxPaymentRetries?: number;
+    /** Timeout (ms) for the retry leg, per client. Default 30_000. */
+    retryTimeoutMs?: number;
+}
+declare class MultiChainPayer implements PayingClient {
+    private readonly _clients;
+    /**
+     * Wrap an explicit, ordered set of single-chain clients — use this when a client
+     * needs full control (e.g. a custom EVM chain configured by a viem `Chain`). The
+     * ORDER is your chain preference: across chains the first that can settle wins. Pass
+     * at MOST one client per chain — two clients on the SAME network would double-count in
+     * `spent()`/`budget()` and waste a plan round-trip (`fromWallets` can't produce this).
+     * For the common case, prefer {@link MultiChainPayer.fromWallets}.
+     */
+    constructor(clients: PipRailClient[]);
+    /**
+     * Build one client per funded chain from a `{ chain → wallet }` map — the
+     * ergonomic path. The shared `policy`/`schemes`/`onBeforePay`/`onEvent` apply to
+     * every client; `rpcUrls` are matched per chain. Iteration order of `wallets` is
+     * the chain preference.
+     *
+     * ```ts
+     * const payer = MultiChainPayer.fromWallets({
+     *   wallets: {
+     *     base:    { privateKey: process.env.EVM_KEY! },
+     *     solana:  { secretKey:  process.env.SOLANA_SECRET! },
+     *     xrpl:    { seed:       process.env.XRPL_SEED! },
+     *   },
+     *   policy: { maxAmount: '1.00', maxTotal: '20.00', tokens: ['USDC', 'USDT'] },
+     * })
+     * const res = await payer.get('https://api.example.com/paid')  // pays on the first funded chain that can settle
+     * ```
+     */
+    static fromWallets(opts: MultiChainPayerOptions): MultiChainPayer;
+    /** The underlying single-chain clients, in preference order. Reach for one of
+     *  these for chain-specific reads (`estimateCost`, `discoverySigner`, per-chain
+     *  `budget()`) that don't make sense merged. */
+    get clients(): readonly PipRailClient[];
+    /** Plan a 402 across every funded chain — merged + ranked payable-first. `null`
+     *  when the URL needs no payment. (Delegates to {@link planAcross}.) */
+    planPayment(url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+    /** Can ANY funded chain settle this URL right now? (A free resource is trivially
+     *  "affordable".) No funds move. */
+    canAfford(url: string, init?: RequestInit): Promise<boolean>;
+    /** Price a gated URL across funded chains — the chosen rail's quote (the first
+     *  funded chain that can settle), else the first offered rail's. `null` when the URL
+     *  needs no payment. When it IS
+     *  gated but none of your chains are offered, surfaces the same informative
+     *  `NoCompatibleAcceptError` a single client would (it names the chains the 402 is
+     *  payable on) rather than a misleading `null`. No funds move. */
+    quote(url: string, init?: RequestInit): Promise<PipRailQuote | null>;
+    /** Pay the first funded chain (in your listed order) that can settle this URL.
+     *  Delegates to {@link fetchAcross} — full policy / approval / retry / replay path on
+     *  the owning client. The owner re-reads balances at pay time, so the rail paid is the
+     *  surfaced `best` on a best-effort basis (it can pick another rail on the SAME chain,
+     *  or decline, if balances shift between plan and pay). PROBES the URL with `init`
+     *  (method + body) per client — prefer GET / idempotent requests. */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** GET that auto-pays across chains. */
+    get(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * POST that auto-pays across chains. `body` is a string/FormData/URLSearchParams/
+     * ArrayBuffer/Blob (sent as-is) or a plain object (serialised as JSON) — mirrors
+     * {@link PipRailClient.post}.
+     */
+    post(url: string, body?: BodyInit | object | undefined, init?: RequestInit): Promise<Response>;
+    /**
+     * Find payable resources across every funded chain. With the default
+     * `network: 'self'`, each chain's own results are merged + deduped by URL (so
+     * "self" means "any chain I can pay"). A network-scoped query (a CAIP-2 id or
+     * `'any'`) is chain-independent, so one client answers it. Never throws for a
+     * read problem; moves no funds.
+     */
+    discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
+    /** List a resource YOU run on the open indexes. Registration is a merchant action
+     *  independent of which chain you pay FROM, so it goes through your first chain's
+     *  client; pass `opts.network` to advertise a specific chain. Moves no funds. */
+    register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
+    /** Aggregate spend across every chain — counts summed; per-(network,asset) rows
+     *  and records concatenated (no cross-chain collisions, never a cross-token sum). */
+    spent(): SpendSummary;
+    /** A merged budget view: every chain's per-(network,asset) remaining rows, plus the
+     *  MOST-RESTRICTIVE session time envelope across chains (the soonest deadline wins).
+     *  Mirrors {@link PipRailClient.budget}'s shape so the agent toolkit reads it
+     *  unchanged; per-chain session detail is on each `clients[i].budget()`. */
+    budget(): SessionBudget;
+}
 
 /**
  * MCP-style tool annotations — optional, advisory hints that let an MCP client or
@@ -5514,7 +5707,7 @@ interface AgentTool {
  * declined? }`) — never a thrown error — so the model reasons about it (and never
  * re-pays a broadcast-but-unconfirmed payment) instead of crashing.
  */
-declare function paymentTools(client: PipRailClient): AgentTool[];
+declare function paymentTools(client: PayingClient): AgentTool[];
 
 /**
  * One line summarising a {@link PaymentPlan} for a model: what's payable, on which
@@ -7031,4 +7224,4 @@ declare const PERMIT2_WITNESS_TYPES: {
  */
 declare function renderLandingPage(sd: SelfDescription): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, 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, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, 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, POWERED_BY, 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 SelfDescribeRail, type SelfDescription, 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, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, 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, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type 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 SelfDescribeRail, type SelfDescription, 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, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };