@piprail/sdk 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.24.0] — 2026-06-14 — multi-chain buying (one buyer, a wallet per chain)
+
+### Added — pay a 402 on whichever chain it asks for
+
+- **`MultiChainPayer`** — a `PipRailClient` is bound to ONE chain + ONE wallet (an EVM key can't sign a
+  Solana tx). `MultiChainPayer.fromWallets({ wallets: { base: { privateKey }, solana: { secretKey }, … }, policy })`
+  carries one wallet per chain and exposes a single `fetch`/`get`/`post`/`planPayment`/`canAfford`/`quote`/
+  `discover`/`register`/`spent`/`budget`. On a 402 it surveys every funded chain and pays the FIRST chain
+  you listed that can actually settle — through each client's own spend policy, `onBeforePay`, retries, and
+  replay-protection. No price oracle, no backend, no custody; across coins the order you list the chains is
+  the preference (within a chain, the cheapest-gas rail). Also `new MultiChainPayer([...clients])` for full
+  control (e.g. custom-EVM viem `Chain`s). `schemes` (incl. the gasless `exact` rail) propagates to every
+  chain's client.
+- **`fetchAcross(clients, url, init?)`** — the EXECUTION counterpart to `planAcross`: plan across an array
+  of single-chain clients and pay, on its owning client, the rail `planAcross` reports as `best` (the first
+  funded chain that can settle). Throws `PaymentDeclinedError` with a merged, per-chain funding hint when
+  no chain can settle.
+- **`PayingClient`** — the shared read-+-pay interface `paymentTools` now accepts; both `PipRailClient` and
+  `MultiChainPayer` satisfy it, so the agent toolkit (and the MCP) wrap either unchanged.
+- **`piprail_register` agent tool** gains optional `network` + `asset` params, so a multi-chain agent can
+  advertise a listing on a specific chain instead of defaulting to the first wallet's chain.
+
+### Changed
+
+- **Cross-chain `best` selection is now your PREFERENCE order, not raw gas magnitude.** `planAcross` /
+  `fetchAcross` no longer compare gas fees across different native coins (base units aren't comparable —
+  e.g. EVM wei vs Solana lamports — and there's no oracle), which previously let a small-base-unit coin
+  win regardless of real cost. They now pay the FIRST chain you list that can settle (within a chain, the
+  cheapest-gas rail still wins) — matching the documented contract. Single-chain `PipRailClient` ranking is
+  unchanged.
+- **`planAcross` now propagates a TOTAL outage.** If EVERY client fails to reach the resource it throws
+  (like a single client) instead of returning `null` — so `canAfford`/`quote` can't report a false
+  "affordable"/"not-gated". A single chain being down still just drops that chain.
+- **Clearer multi-chain decline message.** When no funded chain can settle, `planAcross`'s `fundingHint`
+  (and the `PaymentDeclinedError` `fetchAcross` throws) now names EVERY funded chain's own blocker — "top up
+  X USDC on base · add ~Y POL gas on polygon" — instead of only the first. Chains the 402 never offered are
+  dropped as noise when another chain is close; if none of your chains are offered, it says where the 402
+  IS payable. Per-rail `blockers`/`warnings` stay machine-readable for agents that branch programmatically.
+
+Single-chain `PipRailClient` behaviour is byte-identical. Examples: `examples/multi-chain` (routing + a
+live gasless-`exact` BNB Permit2 settlement through `MultiChainPayer`).
+
 ## [1.23.0] — 2026-06-14 — self-describing endpoints + discovery reach
 
 ### Added — self-describing, more discoverable endpoints (discoverability plan: Phases 1, 2, 4, 5)
@@ -1022,6 +1064,7 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[1.24.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.15.1]: https://www.npmjs.com/package/@piprail/sdk
 [1.15.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.14.0]: https://www.npmjs.com/package/@piprail/sdk

package/README.md

@@ -36,6 +36,33 @@ const client = new PipRailClient({ chain: 'base', wallet: { privateKey: process.
 const res = await client.fetch('https://api.example.com/report') // hits the 402, pays it, retries with proof
 ```
 
+## Pay across chains — one buyer, a wallet per chain
+
+A client is bound to one chain (an EVM key can't sign a Solana tx). To pay a 402
+on **whatever chain it asks for**, give a `MultiChainPayer` one wallet per chain —
+it surveys every chain you hold and pays the **first one you listed** that can settle
+(your preference; within a chain, the cheapest-gas rail — there's no oracle to compare
+gas across coins):
+
+```ts
+import { MultiChainPayer } from '@piprail/sdk'
+
+const payer = MultiChainPayer.fromWallets({
+  wallets: {
+    base:   { privateKey: process.env.EVM_KEY },     // one EVM key works on every EVM chain
+    solana: { secretKey:  process.env.SOLANA_KEY },
+    xrpl:   { seed:       process.env.XRPL_SEED },
+  },
+  policy: { maxAmount: '1.00', maxTotal: '10.00', tokens: ['USDC', 'USDT'] }, // one budget, every chain
+})
+
+await payer.planPayment(url) // read-only: every chain ranked, payable-first in your listed order
+const res = await payer.get(url) // pays on the first chain that can settle — same spend policy, no manual routing
+```
+
+Built on `planAcross` / `fetchAcross` (the same composable primitives, for when you
+already hold an array of clients). See [`examples/multi-chain`](../examples/multi-chain).
+
 The same app can **take** payments and **make** them. → [Making payments](https://docs.piprail.com/making-payments/piprail-client/)
 
 ---
@@ -46,7 +73,7 @@ The same app can **take** payments and **make** them. → [Making payments](http
 |---|---|
 | **[Getting started](https://docs.piprail.com/getting-started/introduction/)** | Install · quickstart · how it works |
 | **[Accepting payments](https://docs.piprail.com/accepting-payments/require-payment-and-gate/)** | `requirePayment` · `createPaymentGate` · the `exact` rail |
-| **[Making payments](https://docs.piprail.com/making-payments/piprail-client/)** | `PipRailClient` · `quote` · `estimateCost` · `planPayment` · auto-route |
+| **[Making payments](https://docs.piprail.com/making-payments/piprail-client/)** | `PipRailClient` · `quote` · `estimateCost` · `planPayment` · auto-route · `MultiChainPayer` |
 | **[Spend controls](https://docs.piprail.com/spend-controls/payment-policy/)** | Budgets · time envelope · the spend ledger |
 | **[Agent toolkit](https://docs.piprail.com/agent-toolkit/payment-tools/)** | `paymentTools` · the agent guide · NL renderers |
 | **[Discovery](https://docs.piprail.com/discovery/discover-and-register/)** | Find & be found on the open x402 indexes ($0, no backend) |

package/dist/index.cjs

@@ -3493,6 +3493,33 @@ function rankOptions(options) {
     return 0;
   });
 }
+function rankAcross(plans) {
+  const rank = { payable: 0, unknown: 1, blocked: 2 };
+  return plans.flatMap((p) => p.options).sort((a, b) => rank[a.state] - rank[b.state]);
+}
+async function planEachClient(clients, url, init) {
+  const settled = await Promise.allSettled(clients.map((c) => c.planPayment(url, init)));
+  const live = [];
+  let anyReached = false;
+  let firstError;
+  settled.forEach((s, i) => {
+    if (s.status === "fulfilled") {
+      anyReached = true;
+      if (s.value != null) live.push({ client: clients[i], plan: s.value });
+    } else if (firstError === void 0) {
+      firstError = s.reason;
+    }
+  });
+  if (live.length === 0 && !anyReached) {
+    throw _nullishCoalesce(firstError, () => ( new Error("planAcross: every client failed to reach the resource.")));
+  }
+  return live;
+}
+function mergeDeclineHint(plans) {
+  const actionable = plans.filter((p) => p.options.length > 0 && p.fundingHint).map((p) => p.fundingHint);
+  const chosen = actionable.length ? actionable : plans.map((p) => p.fundingHint).filter(Boolean);
+  return chosen.length ? [...new Set(chosen)].join(" \xB7 ") : null;
+}
 function buildFundingHint(options, chainLabel) {
   if (options.length === 0) return null;
   const target = [...options].sort((a, b) => a.blockers.length - b.blockers.length)[0];
@@ -3519,10 +3546,10 @@ function buildFundingHint(options, chainLabel) {
   return parts.length ? `Can't settle on ${chainLabel}: ${parts.join(" and ")} (to pay ${target.quote.amountFormatted} ${sym}).` : `Can't settle on ${chainLabel} for ${target.quote.amountFormatted} ${sym}.`;
 }
 async function planAcross(clients, url, init) {
-  const plans = await Promise.all(clients.map((c) => c.planPayment(url, init).catch(() => null)));
-  const live = plans.filter((p) => p != null);
+  if (clients.length === 0) return null;
+  const live = (await planEachClient(clients, url, init)).map((p) => p.plan);
   if (live.length === 0) return null;
-  const options = rankOptions(live.flatMap((p) => p.options));
+  const options = rankAcross(live);
   const best = _nullishCoalesce(options.find((o) => o.state === "payable"), () => ( null));
   const status = best ? "ready" : options.some((o) => o.state === "unknown") ? "unknown" : "blocked";
   return {
@@ -3532,10 +3559,25 @@ async function planAcross(clients, url, init) {
     payable: best !== null,
     best,
     options,
-    // First non-null hint across clients — each already names its chain.
-    fundingHint: best ? null : _nullishCoalesce(live.map((p) => p.fundingHint).find(Boolean), () => ( null))
+    // Merge EVERY funded chain's blocker into one clear sentence (not just the first) —
+    // see mergeDeclineHint. `null` when a rail is payable.
+    fundingHint: best ? null : mergeDeclineHint(live)
   };
 }
+async function fetchAcross(clients, url, init) {
+  if (clients.length === 0) {
+    throw new TypeError("fetchAcross needs at least one PipRailClient.");
+  }
+  const live = await planEachClient(clients, url, init);
+  if (live.length === 0) return clients[0].fetch(url, init);
+  const best = rankAcross(live.map((p) => p.plan)).find((o) => o.state === "payable");
+  if (!best) {
+    const hint = mergeDeclineHint(live.map((p) => p.plan));
+    throw new (0, _chunkU35MG4TFcjs.PaymentDeclinedError)(hint || "No funded chain can settle this payment right now.");
+  }
+  const owner = live.find((p) => p.plan.options.includes(best)).client;
+  return owner.fetch(url, { ..._nullishCoalesce(init, () => ( {})), autoRoute: true });
+}
 function railOnNetwork(rail, matches) {
   const n = normalizeNetwork(rail.network);
   return !n.includes(":") || matches(n);
@@ -3601,6 +3643,187 @@ async function readInvalidReason(response) {
   return null;
 }
 
+// src/payer.ts
+var MultiChainPayer = class _MultiChainPayer {
+  
+  /**
+   * 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) {
+    if (clients.length === 0) {
+      throw new TypeError("MultiChainPayer needs at least one PipRailClient.");
+    }
+    this._clients = [...clients];
+  }
+  /**
+   * 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) {
+    const entries = Object.entries(opts.wallets);
+    if (entries.length === 0) {
+      throw new TypeError("MultiChainPayer.fromWallets needs at least one wallet.");
+    }
+    const clients = entries.map(
+      ([chain, wallet]) => new PipRailClient({
+        chain,
+        wallet,
+        ...opts.policy ? { policy: opts.policy } : {},
+        ...opts.schemes ? { schemes: opts.schemes } : {},
+        ..._optionalChain([opts, 'access', _64 => _64.rpcUrls, 'optionalAccess', _65 => _65[chain]]) ? { rpcUrl: opts.rpcUrls[chain] } : {},
+        ...opts.onBeforePay ? { onBeforePay: opts.onBeforePay } : {},
+        ...opts.onEvent ? { onEvent: opts.onEvent } : {},
+        ...opts.maxPaymentRetries != null ? { maxPaymentRetries: opts.maxPaymentRetries } : {},
+        ...opts.retryTimeoutMs != null ? { retryTimeoutMs: opts.retryTimeoutMs } : {}
+      })
+    );
+    return new _MultiChainPayer(clients);
+  }
+  /** 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() {
+    return this._clients;
+  }
+  /** Plan a 402 across every funded chain — merged + ranked payable-first. `null`
+   *  when the URL needs no payment. (Delegates to {@link planAcross}.) */
+  planPayment(url, init) {
+    return planAcross(this._clients, url, init);
+  }
+  /** Can ANY funded chain settle this URL right now? (A free resource is trivially
+   *  "affordable".) No funds move. */
+  async canAfford(url, init) {
+    const plan = await this.planPayment(url, init);
+    return plan == null ? true : plan.payable;
+  }
+  /** 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. */
+  async quote(url, init) {
+    const plan = await this.planPayment(url, init);
+    if (plan == null) return null;
+    const opt = _nullishCoalesce(plan.best, () => ( plan.options[0]));
+    if (opt) return opt.quote;
+    return this._clients[0].quote(url, init);
+  }
+  /** 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, init) {
+    return fetchAcross(this._clients, url, init);
+  }
+  /** GET that auto-pays across chains. */
+  get(url, init) {
+    return this.fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: "GET" });
+  }
+  /**
+   * 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, body, init) {
+    const headers = new Headers(_optionalChain([init, 'optionalAccess', _66 => _66.headers]));
+    let payload;
+    if (body === void 0 || body === null) {
+      payload = void 0;
+    } else if (isBodyInit(body)) {
+      payload = body;
+    } else if (typeof body === "object") {
+      payload = JSON.stringify(body);
+      if (!headers.has("content-type")) headers.set("content-type", "application/json");
+    } else {
+      payload = String(body);
+    }
+    return this.fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: "POST", headers, body: payload });
+  }
+  /**
+   * 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.
+   */
+  async discover(opts = {}) {
+    if (opts.network && opts.network !== "self") {
+      return this._clients[0].discover(opts);
+    }
+    const perChain = await Promise.all(
+      this._clients.map((c) => c.discover({ ...opts, network: "self" }).catch(() => []))
+    );
+    const seen = /* @__PURE__ */ new Set();
+    const merged = [];
+    for (const r of perChain.flat()) {
+      if (seen.has(r.resource)) continue;
+      seen.add(r.resource);
+      merged.push(r);
+    }
+    return merged;
+  }
+  /** 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, opts = {}) {
+    return this._clients[0].register(url, opts);
+  }
+  /** Aggregate spend across every chain — counts summed; per-(network,asset) rows
+   *  and records concatenated (no cross-chain collisions, never a cross-token sum). */
+  spent() {
+    const summaries = this._clients.map((c) => c.spent());
+    return {
+      count: summaries.reduce((n, s) => n + s.count, 0),
+      byAsset: summaries.flatMap((s) => s.byAsset),
+      records: summaries.flatMap((s) => s.records)
+    };
+  }
+  /** 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() {
+    const budgets = this._clients.map((c) => c.budget());
+    const session = budgets.map((b) => b.session).reduce((soonest, s) => {
+      if (soonest.secondsRemaining == null) return s;
+      if (s.secondsRemaining == null) return soonest;
+      return s.secondsRemaining < soonest.secondsRemaining ? s : soonest;
+    });
+    return { session, byAsset: budgets.flatMap((b) => b.byAsset) };
+  }
+};
+function isBodyInit(value) {
+  if (typeof value === "string") return true;
+  if (value instanceof ArrayBuffer) return true;
+  if (ArrayBuffer.isView(value)) return true;
+  if (typeof URLSearchParams !== "undefined" && value instanceof URLSearchParams) return true;
+  if (typeof FormData !== "undefined" && value instanceof FormData) return true;
+  if (typeof Blob !== "undefined" && value instanceof Blob) return true;
+  return false;
+}
+
 // src/selfdescribe.ts
 var BRAND = {
   name: "PipRail",
@@ -4003,7 +4226,12 @@ function paymentTools(client) {
           url: { type: "string", description: "Full URL of the resource to list." },
           name: { type: "string", description: "Display name (defaults to the host)." },
           description: { type: "string", description: "What the resource offers." },
-          priceUsd: { type: "number", description: "Advertised price in USD (metadata)." }
+          priceUsd: { type: "number", description: "Advertised price in USD (metadata)." },
+          network: {
+            type: "string",
+            description: "Network slug to advertise, e.g. 'base' (defaults to the paying chain). Set it when registering from a multi-chain wallet so the listing names the right chain."
+          },
+          asset: { type: "string", description: "Payment asset symbol, e.g. 'USDC' (metadata)." }
         },
         required: ["url"],
         additionalProperties: false
@@ -4013,6 +4241,8 @@ function paymentTools(client) {
         if (typeof args.name === "string") opts.name = args.name;
         if (typeof args.description === "string") opts.description = args.description;
         if (typeof args.priceUsd === "number") opts.priceUsd = args.priceUsd;
+        if (typeof args.network === "string") opts.network = args.network;
+        if (typeof args.asset === "string") opts.asset = args.asset;
         const outcomes = await client.register(String(args.url), opts);
         return { outcomes };
       }
@@ -4215,10 +4445,10 @@ async function fetchFacilitatorFeePayer(url, network, timeoutMs = 8e3) {
     const res = await fetch(`${base2}/supported`, { signal: ctrl.signal });
     if (!res.ok) return void 0;
     const body = await res.json();
-    const kinds = Array.isArray(_optionalChain([body, 'optionalAccess', _64 => _64.kinds])) ? body.kinds : [];
+    const kinds = Array.isArray(_optionalChain([body, 'optionalAccess', _67 => _67.kinds])) ? body.kinds : [];
     const want = normalizeNetwork(network);
-    const kind = kinds.find((k) => _optionalChain([k, 'optionalAccess', _65 => _65.scheme]) === "exact" && normalizeNetwork(String(_nullishCoalesce(_optionalChain([k, 'optionalAccess', _66 => _66.network]), () => ( "")))) === want);
-    const fp = _optionalChain([kind, 'optionalAccess', _67 => _67.extra, 'optionalAccess', _68 => _68.feePayer]);
+    const kind = kinds.find((k) => _optionalChain([k, 'optionalAccess', _68 => _68.scheme]) === "exact" && normalizeNetwork(String(_nullishCoalesce(_optionalChain([k, 'optionalAccess', _69 => _69.network]), () => ( "")))) === want);
+    const fp = _optionalChain([kind, 'optionalAccess', _70 => _70.extra, 'optionalAccess', _71 => _71.feePayer]);
     return typeof fp === "string" ? fp : void 0;
   } catch (e32) {
     return void 0;
@@ -4227,14 +4457,14 @@ async function fetchFacilitatorFeePayer(url, network, timeoutMs = 8e3) {
   }
 }
 function parseFacilitatorSupported(body) {
-  const kinds = _optionalChain([body, 'optionalAccess', _69 => _69.kinds]);
+  const kinds = _optionalChain([body, 'optionalAccess', _72 => _72.kinds]);
   if (!Array.isArray(kinds)) return [];
   const out = [];
   for (const k of kinds) {
     if (!k || typeof k !== "object") continue;
     const o = k;
     if (typeof o.scheme !== "string" || typeof o.network !== "string") continue;
-    const fp = _optionalChain([o, 'access', _70 => _70.extra, 'optionalAccess', _71 => _71.feePayer]);
+    const fp = _optionalChain([o, 'access', _73 => _73.extra, 'optionalAccess', _74 => _74.feePayer]);
     out.push({ scheme: o.scheme, network: o.network, ...typeof fp === "string" ? { feePayer: fp } : {} });
   }
   return out;
@@ -4535,7 +4765,7 @@ function createPaymentGate(options) {
       accepts,
       instruction: describeChallenge({ x402Version: 2, resource: { url: resourceUrl }, accepts })
     });
-    const rejectionExt = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _72 => _72.extensions]), () => ( {}));
+    const rejectionExt = _nullishCoalesce(_optionalChain([opts, 'optionalAccess', _75 => _75.extensions]), () => ( {}));
     const rejectionPiprail = _nullishCoalesce(rejectionExt.piprail, () => ( {}));
     const bodyPiprail = { ..._nullishCoalesce(selfDescribe, () => ( {})), ...rejectionPiprail };
     const bodyExtensions = {
@@ -4554,7 +4784,7 @@ function createPaymentGate(options) {
         ...options.description ? { description: options.description } : {}
       },
       accepts,
-      ..._optionalChain([opts, 'optionalAccess', _73 => _73.error]) ? { error: opts.error } : {},
+      ..._optionalChain([opts, 'optionalAccess', _76 => _76.error]) ? { error: opts.error } : {},
       ...Object.keys(bodyExtensions).length > 0 ? { extensions: bodyExtensions } : {}
     };
     const headerChallenge = {
@@ -4851,7 +5081,7 @@ function isRetryableStatus(status) {
 }
 var sleep = (ms) => ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
 async function signBody(secret, body) {
-  const subtle = _optionalChain([globalThis, 'access', _74 => _74.crypto, 'optionalAccess', _75 => _75.subtle]);
+  const subtle = _optionalChain([globalThis, 'access', _77 => _77.crypto, 'optionalAccess', _78 => _78.subtle]);
   if (!subtle) return null;
   try {
     const enc = new TextEncoder();
@@ -4921,7 +5151,7 @@ async function deliverReceipt(receipt, options) {
     const retryable = status === void 0 ? true : isRetryableStatus(status);
     const willRetry = !ok && retryable && attempt < maxAttempts;
     try {
-      _optionalChain([onAttempt, 'optionalCall', _76 => _76({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
+      _optionalChain([onAttempt, 'optionalCall', _79 => _79({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
     } catch (e39) {
     }
     if (ok) return { delivered: true, attempts: attempt, status };
@@ -5035,4 +5265,6 @@ async function deliverReceipt(receipt, options) {
 
 
 
-exports.BRAND = BRAND; exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkU35MG4TFcjs.ConfirmationTimeoutError; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkU35MG4TFcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkU35MG4TFcjs.InvalidEnvelopeError; exports.KNOWN_FACILITATORS = KNOWN_FACILITATORS; exports.MaxRetriesExceededError = _chunkU35MG4TFcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkU35MG4TFcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkU35MG4TFcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkU35MG4TFcjs.NonReplayableBodyError; exports.PERMIT2_ADDRESS = PERMIT2_ADDRESS; exports.PERMIT2_PROXY_CHAIN_IDS = PERMIT2_PROXY_CHAIN_IDS; exports.PERMIT2_WITNESS_TYPES = PERMIT2_WITNESS_TYPES; exports.PIPRAIL_AGENT_GUIDE = PIPRAIL_AGENT_GUIDE; exports.POWERED_BY = POWERED_BY; exports.PaymentDeclinedError = _chunkU35MG4TFcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkU35MG4TFcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkU35MG4TFcjs.PipRailError; exports.REGISTER_ATTRIBUTION = REGISTER_ATTRIBUTION; exports.RecipientNotReadyError = _chunkU35MG4TFcjs.RecipientNotReadyError; exports.SettlementError = _chunkU35MG4TFcjs.SettlementError; exports.UnknownTokenError = _chunkU35MG4TFcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkU35MG4TFcjs.UnsupportedNetworkError; exports.UnsupportedSchemeError = _chunkU35MG4TFcjs.UnsupportedSchemeError; exports.WalletRequiredError = _chunkU35MG4TFcjs.WalletRequiredError; exports.WrongChainError = _chunkU35MG4TFcjs.WrongChainError; exports.WrongFamilyError = _chunkU35MG4TFcjs.WrongFamilyError; exports.X402_EXACT_PERMIT2_PROXY = X402_EXACT_PERMIT2_PROXY; exports.agentGuide = agentGuide; exports.appendAttribution = appendAttribution; exports.buildBazaarExtension = buildBazaarExtension; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildExactSignatureHeader = buildExactSignatureHeader; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSelfDescription = buildSelfDescription; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.classifyChallenge = classifyChallenge; exports.createPaymentGate = createPaymentGate; exports.decorateOutcome = decorateOutcome; exports.deliverReceipt = deliverReceipt; exports.describeChallenge = describeChallenge; exports.discoveryHeaders = discoveryHeaders; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.explainDecline = explainDecline; exports.facilitatorCoverage = facilitatorCoverage; exports.firstKeylessFacilitator = firstKeylessFacilitator; exports.formatSpendReport = formatSpendReport; exports.getDirectoryInfo = getDirectoryInfo; exports.isPermit2ProxyChain = isPermit2ProxyChain; exports.knownFacilitatorsFor = knownFacilitatorsFor; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseFacilitatorSupported = parseFacilitatorSupported; exports.parseReceipt = parseReceipt; exports.parseSettleResponse = parseSettleResponse; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.renderLandingPage = renderLandingPage; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.summarizePlan = summarizePlan; exports.toInsufficientFundsError = _chunkU35MG4TFcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.verify402IndexDomain = verify402IndexDomain;
+
+
+exports.BRAND = BRAND; exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkU35MG4TFcjs.ConfirmationTimeoutError; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkU35MG4TFcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkU35MG4TFcjs.InvalidEnvelopeError; exports.KNOWN_FACILITATORS = KNOWN_FACILITATORS; exports.MaxRetriesExceededError = _chunkU35MG4TFcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkU35MG4TFcjs.MissingDriverError; exports.MultiChainPayer = MultiChainPayer; exports.NoCompatibleAcceptError = _chunkU35MG4TFcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkU35MG4TFcjs.NonReplayableBodyError; exports.PERMIT2_ADDRESS = PERMIT2_ADDRESS; exports.PERMIT2_PROXY_CHAIN_IDS = PERMIT2_PROXY_CHAIN_IDS; exports.PERMIT2_WITNESS_TYPES = PERMIT2_WITNESS_TYPES; exports.PIPRAIL_AGENT_GUIDE = PIPRAIL_AGENT_GUIDE; exports.POWERED_BY = POWERED_BY; exports.PaymentDeclinedError = _chunkU35MG4TFcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkU35MG4TFcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkU35MG4TFcjs.PipRailError; exports.REGISTER_ATTRIBUTION = REGISTER_ATTRIBUTION; exports.RecipientNotReadyError = _chunkU35MG4TFcjs.RecipientNotReadyError; exports.SettlementError = _chunkU35MG4TFcjs.SettlementError; exports.UnknownTokenError = _chunkU35MG4TFcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkU35MG4TFcjs.UnsupportedNetworkError; exports.UnsupportedSchemeError = _chunkU35MG4TFcjs.UnsupportedSchemeError; exports.WalletRequiredError = _chunkU35MG4TFcjs.WalletRequiredError; exports.WrongChainError = _chunkU35MG4TFcjs.WrongChainError; exports.WrongFamilyError = _chunkU35MG4TFcjs.WrongFamilyError; exports.X402_EXACT_PERMIT2_PROXY = X402_EXACT_PERMIT2_PROXY; exports.agentGuide = agentGuide; exports.appendAttribution = appendAttribution; exports.buildBazaarExtension = buildBazaarExtension; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildExactSignatureHeader = buildExactSignatureHeader; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSelfDescription = buildSelfDescription; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.classifyChallenge = classifyChallenge; exports.createPaymentGate = createPaymentGate; exports.decorateOutcome = decorateOutcome; exports.deliverReceipt = deliverReceipt; exports.describeChallenge = describeChallenge; exports.discoveryHeaders = discoveryHeaders; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.explainDecline = explainDecline; exports.facilitatorCoverage = facilitatorCoverage; exports.fetchAcross = fetchAcross; exports.firstKeylessFacilitator = firstKeylessFacilitator; exports.formatSpendReport = formatSpendReport; exports.getDirectoryInfo = getDirectoryInfo; exports.isPermit2ProxyChain = isPermit2ProxyChain; exports.knownFacilitatorsFor = knownFacilitatorsFor; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseFacilitatorSupported = parseFacilitatorSupported; exports.parseReceipt = parseReceipt; exports.parseSettleResponse = parseSettleResponse; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.renderLandingPage = renderLandingPage; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.summarizePlan = summarizePlan; exports.toInsufficientFundsError = _chunkU35MG4TFcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.verify402IndexDomain = verify402IndexDomain;

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

package/dist/index.js

@@ -3493,6 +3493,33 @@ function rankOptions(options) {
     return 0;
   });
 }
+function rankAcross(plans) {
+  const rank = { payable: 0, unknown: 1, blocked: 2 };
+  return plans.flatMap((p) => p.options).sort((a, b) => rank[a.state] - rank[b.state]);
+}
+async function planEachClient(clients, url, init) {
+  const settled = await Promise.allSettled(clients.map((c) => c.planPayment(url, init)));
+  const live = [];
+  let anyReached = false;
+  let firstError;
+  settled.forEach((s, i) => {
+    if (s.status === "fulfilled") {
+      anyReached = true;
+      if (s.value != null) live.push({ client: clients[i], plan: s.value });
+    } else if (firstError === void 0) {
+      firstError = s.reason;
+    }
+  });
+  if (live.length === 0 && !anyReached) {
+    throw firstError ?? new Error("planAcross: every client failed to reach the resource.");
+  }
+  return live;
+}
+function mergeDeclineHint(plans) {
+  const actionable = plans.filter((p) => p.options.length > 0 && p.fundingHint).map((p) => p.fundingHint);
+  const chosen = actionable.length ? actionable : plans.map((p) => p.fundingHint).filter(Boolean);
+  return chosen.length ? [...new Set(chosen)].join(" \xB7 ") : null;
+}
 function buildFundingHint(options, chainLabel) {
   if (options.length === 0) return null;
   const target = [...options].sort((a, b) => a.blockers.length - b.blockers.length)[0];
@@ -3519,10 +3546,10 @@ function buildFundingHint(options, chainLabel) {
   return parts.length ? `Can't settle on ${chainLabel}: ${parts.join(" and ")} (to pay ${target.quote.amountFormatted} ${sym}).` : `Can't settle on ${chainLabel} for ${target.quote.amountFormatted} ${sym}.`;
 }
 async function planAcross(clients, url, init) {
-  const plans = await Promise.all(clients.map((c) => c.planPayment(url, init).catch(() => null)));
-  const live = plans.filter((p) => p != null);
+  if (clients.length === 0) return null;
+  const live = (await planEachClient(clients, url, init)).map((p) => p.plan);
   if (live.length === 0) return null;
-  const options = rankOptions(live.flatMap((p) => p.options));
+  const options = rankAcross(live);
   const best = options.find((o) => o.state === "payable") ?? null;
   const status = best ? "ready" : options.some((o) => o.state === "unknown") ? "unknown" : "blocked";
   return {
@@ -3532,10 +3559,25 @@ async function planAcross(clients, url, init) {
     payable: best !== null,
     best,
     options,
-    // First non-null hint across clients — each already names its chain.
-    fundingHint: best ? null : live.map((p) => p.fundingHint).find(Boolean) ?? null
+    // Merge EVERY funded chain's blocker into one clear sentence (not just the first) —
+    // see mergeDeclineHint. `null` when a rail is payable.
+    fundingHint: best ? null : mergeDeclineHint(live)
   };
 }
+async function fetchAcross(clients, url, init) {
+  if (clients.length === 0) {
+    throw new TypeError("fetchAcross needs at least one PipRailClient.");
+  }
+  const live = await planEachClient(clients, url, init);
+  if (live.length === 0) return clients[0].fetch(url, init);
+  const best = rankAcross(live.map((p) => p.plan)).find((o) => o.state === "payable");
+  if (!best) {
+    const hint = mergeDeclineHint(live.map((p) => p.plan));
+    throw new PaymentDeclinedError(hint || "No funded chain can settle this payment right now.");
+  }
+  const owner = live.find((p) => p.plan.options.includes(best)).client;
+  return owner.fetch(url, { ...init ?? {}, autoRoute: true });
+}
 function railOnNetwork(rail, matches) {
   const n = normalizeNetwork(rail.network);
   return !n.includes(":") || matches(n);
@@ -3601,6 +3643,187 @@ async function readInvalidReason(response) {
   return null;
 }
 
+// src/payer.ts
+var MultiChainPayer = class _MultiChainPayer {
+  _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) {
+    if (clients.length === 0) {
+      throw new TypeError("MultiChainPayer needs at least one PipRailClient.");
+    }
+    this._clients = [...clients];
+  }
+  /**
+   * 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) {
+    const entries = Object.entries(opts.wallets);
+    if (entries.length === 0) {
+      throw new TypeError("MultiChainPayer.fromWallets needs at least one wallet.");
+    }
+    const clients = entries.map(
+      ([chain, wallet]) => new PipRailClient({
+        chain,
+        wallet,
+        ...opts.policy ? { policy: opts.policy } : {},
+        ...opts.schemes ? { schemes: opts.schemes } : {},
+        ...opts.rpcUrls?.[chain] ? { rpcUrl: opts.rpcUrls[chain] } : {},
+        ...opts.onBeforePay ? { onBeforePay: opts.onBeforePay } : {},
+        ...opts.onEvent ? { onEvent: opts.onEvent } : {},
+        ...opts.maxPaymentRetries != null ? { maxPaymentRetries: opts.maxPaymentRetries } : {},
+        ...opts.retryTimeoutMs != null ? { retryTimeoutMs: opts.retryTimeoutMs } : {}
+      })
+    );
+    return new _MultiChainPayer(clients);
+  }
+  /** 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() {
+    return this._clients;
+  }
+  /** Plan a 402 across every funded chain — merged + ranked payable-first. `null`
+   *  when the URL needs no payment. (Delegates to {@link planAcross}.) */
+  planPayment(url, init) {
+    return planAcross(this._clients, url, init);
+  }
+  /** Can ANY funded chain settle this URL right now? (A free resource is trivially
+   *  "affordable".) No funds move. */
+  async canAfford(url, init) {
+    const plan = await this.planPayment(url, init);
+    return plan == null ? true : plan.payable;
+  }
+  /** 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. */
+  async quote(url, init) {
+    const plan = await this.planPayment(url, init);
+    if (plan == null) return null;
+    const opt = plan.best ?? plan.options[0];
+    if (opt) return opt.quote;
+    return this._clients[0].quote(url, init);
+  }
+  /** 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, init) {
+    return fetchAcross(this._clients, url, init);
+  }
+  /** GET that auto-pays across chains. */
+  get(url, init) {
+    return this.fetch(url, { ...init ?? {}, method: "GET" });
+  }
+  /**
+   * 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, body, init) {
+    const headers = new Headers(init?.headers);
+    let payload;
+    if (body === void 0 || body === null) {
+      payload = void 0;
+    } else if (isBodyInit(body)) {
+      payload = body;
+    } else if (typeof body === "object") {
+      payload = JSON.stringify(body);
+      if (!headers.has("content-type")) headers.set("content-type", "application/json");
+    } else {
+      payload = String(body);
+    }
+    return this.fetch(url, { ...init ?? {}, method: "POST", headers, body: payload });
+  }
+  /**
+   * 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.
+   */
+  async discover(opts = {}) {
+    if (opts.network && opts.network !== "self") {
+      return this._clients[0].discover(opts);
+    }
+    const perChain = await Promise.all(
+      this._clients.map((c) => c.discover({ ...opts, network: "self" }).catch(() => []))
+    );
+    const seen = /* @__PURE__ */ new Set();
+    const merged = [];
+    for (const r of perChain.flat()) {
+      if (seen.has(r.resource)) continue;
+      seen.add(r.resource);
+      merged.push(r);
+    }
+    return merged;
+  }
+  /** 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, opts = {}) {
+    return this._clients[0].register(url, opts);
+  }
+  /** Aggregate spend across every chain — counts summed; per-(network,asset) rows
+   *  and records concatenated (no cross-chain collisions, never a cross-token sum). */
+  spent() {
+    const summaries = this._clients.map((c) => c.spent());
+    return {
+      count: summaries.reduce((n, s) => n + s.count, 0),
+      byAsset: summaries.flatMap((s) => s.byAsset),
+      records: summaries.flatMap((s) => s.records)
+    };
+  }
+  /** 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() {
+    const budgets = this._clients.map((c) => c.budget());
+    const session = budgets.map((b) => b.session).reduce((soonest, s) => {
+      if (soonest.secondsRemaining == null) return s;
+      if (s.secondsRemaining == null) return soonest;
+      return s.secondsRemaining < soonest.secondsRemaining ? s : soonest;
+    });
+    return { session, byAsset: budgets.flatMap((b) => b.byAsset) };
+  }
+};
+function isBodyInit(value) {
+  if (typeof value === "string") return true;
+  if (value instanceof ArrayBuffer) return true;
+  if (ArrayBuffer.isView(value)) return true;
+  if (typeof URLSearchParams !== "undefined" && value instanceof URLSearchParams) return true;
+  if (typeof FormData !== "undefined" && value instanceof FormData) return true;
+  if (typeof Blob !== "undefined" && value instanceof Blob) return true;
+  return false;
+}
+
 // src/selfdescribe.ts
 var BRAND = {
   name: "PipRail",
@@ -4003,7 +4226,12 @@ function paymentTools(client) {
           url: { type: "string", description: "Full URL of the resource to list." },
           name: { type: "string", description: "Display name (defaults to the host)." },
           description: { type: "string", description: "What the resource offers." },
-          priceUsd: { type: "number", description: "Advertised price in USD (metadata)." }
+          priceUsd: { type: "number", description: "Advertised price in USD (metadata)." },
+          network: {
+            type: "string",
+            description: "Network slug to advertise, e.g. 'base' (defaults to the paying chain). Set it when registering from a multi-chain wallet so the listing names the right chain."
+          },
+          asset: { type: "string", description: "Payment asset symbol, e.g. 'USDC' (metadata)." }
         },
         required: ["url"],
         additionalProperties: false
@@ -4013,6 +4241,8 @@ function paymentTools(client) {
         if (typeof args.name === "string") opts.name = args.name;
         if (typeof args.description === "string") opts.description = args.description;
         if (typeof args.priceUsd === "number") opts.priceUsd = args.priceUsd;
+        if (typeof args.network === "string") opts.network = args.network;
+        if (typeof args.asset === "string") opts.asset = args.asset;
         const outcomes = await client.register(String(args.url), opts);
         return { outcomes };
       }
@@ -4960,6 +5190,7 @@ export {
   KNOWN_FACILITATORS,
   MaxRetriesExceededError,
   MissingDriverError,
+  MultiChainPayer,
   NoCompatibleAcceptError,
   NonReplayableBodyError,
   PERMIT2_ADDRESS,
@@ -5006,6 +5237,7 @@ export {
   evaluatePolicy,
   explainDecline,
   facilitatorCoverage,
+  fetchAcross,
   firstKeylessFacilitator,
   formatSpendReport,
   getDirectoryInfo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",