@piprail/sdk 2.16.2 → 3.0.0

package/dist/index.js

@@ -40,7 +40,7 @@ import {
   parseUptoPaymentHeader,
   pickAccept,
   readPaymentIdentifier
-} from "./chunk-C52H5TYB.js";
+} from "./chunk-YXBQKBDH.js";
 import {
   DIRECTORY_INFO,
   REGISTER_ATTRIBUTION,
@@ -56,7 +56,16 @@ import {
   scoreResource,
   searchOpenIndexes,
   verify402IndexDomain
-} from "./chunk-2CX7XRZK.js";
+} from "./chunk-TZDVZCTC.js";
+import {
+  AGENT_MODES,
+  DEFAULT_AGENT_MODE,
+  DEFAULT_SLIPPAGE_BPS,
+  MAX_SLIPPAGE_BPS,
+  applySlippage,
+  resolveSlippageBps,
+  summarizeSwap
+} from "./chunk-GVCGUSTE.js";
 import {
   ConfirmationTimeoutError,
   InsufficientFundsError,
@@ -85,7 +94,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-QU25LSVS.js";
+} from "./chunk-5GRBEMCA.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -330,6 +339,33 @@ var CHAINS = {
     tokens: {
       USDT: { address: "0xd077A400968890Eacc75cdc901F0356c943e4fDb", decimals: 6, symbol: "USDT" }
     }
+  },
+  /**
+   * Robinhood Chain — Arbitrum Orbit L2 for tokenized equities, mainnet since 2026-07-01.
+   * viem ships no preset for it (it is not in chainid.network either), so the chain is
+   * defined inline from the values Robinhood publishes.
+   *
+   * ONE stablecoin on purpose: USDG, the Paxos-issued Global Dollar, which is the asset the
+   * chain's own markets quote against. Circle does NOT issue native USDC here (verified
+   * against Circle's contract list 2026-09-08), so no USDC/USDT preset ships — a bridged
+   * one would break the "issuer-native only" token rule.
+   */
+  robinhood: {
+    chain: defineChain({
+      id: 4663,
+      name: "Robinhood Chain",
+      nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+      rpcUrls: { default: { http: ["https://rpc.mainnet.chain.robinhood.com"] } },
+      blockExplorers: {
+        default: { name: "Blockscout", url: "https://robinhoodchain.blockscout.com" }
+      }
+    }),
+    tokens: {
+      // Paxos Global Dollar. EIP-3009 AND EIP-2612 verified on-chain 2026-09-08 (exact-payable);
+      // the EIP-712 domain name is "Global Dollar" (NOT "USDG") — the buyer re-derives it from
+      // the contract, so the symbol below is display-only, same as Ethereum's EURC.
+      USDG: { address: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", decimals: 6, symbol: "USDG" }
+    }
   }
 };
 function isViemChain(input) {
@@ -383,7 +419,7 @@ import {
   createWalletClient,
   http
 } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
+import { privateKeyToAccount, nonceManager } from "viem/accounts";
 function createWalletAdapter(config, resolved) {
   assertNoLegacyWalletKey(config, "EVM");
   if ("key" in config) {
@@ -396,7 +432,7 @@ function createWalletAdapter(config, resolved) {
     }
     let account;
     try {
-      account = privateKeyToAccount(key);
+      account = privateKeyToAccount(key, { nonceManager });
     } catch (err) {
       throw new WrongFamilyError(
         `chain is EVM; the wallet { key } is not a valid 0x\u2026 32-byte hex private key: ${err instanceof Error ? err.message : String(err)}.`
@@ -446,6 +482,242 @@ async function payEvm(input) {
   });
 }
 
+// src/drivers/evm/swap.ts
+var KYBER_API = "https://aggregator-api.kyberswap.com";
+var KYBER_CHAIN = {
+  1: "ethereum",
+  10: "optimism",
+  56: "bsc",
+  137: "polygon",
+  8453: "base",
+  42161: "arbitrum",
+  43114: "avalanche",
+  59144: "linea",
+  4663: "robinhood"
+};
+var NATIVE_SENTINEL = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+var ERC20_ALLOWANCE_ABI = [
+  {
+    type: "function",
+    name: "allowance",
+    stateMutability: "view",
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" }
+    ],
+    outputs: [{ type: "uint256" }]
+  },
+  {
+    type: "function",
+    name: "approve",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "amount", type: "uint256" }
+    ],
+    outputs: [{ type: "bool" }]
+  }
+];
+function sourceFor(needsApproval, extraFee) {
+  const charged = !!(extraFee?.feeAmount && extraFee.feeAmount !== "0" && extraFee.feeReceiver);
+  return {
+    kind: "provider",
+    name: "KyberSwap",
+    note: "Third-party EVM DEX aggregator (aggregator-api.kyberswap.com), used keyless. It routes; your own wallet calls the router contract directly and nobody takes possession of the funds. " + (charged ? `\u26A0\uFE0F THIS QUOTE CARRIES AN INTEGRATOR FEE: ${extraFee.feeAmount} to ${extraFee.feeReceiver}. PipRail did not set one. ` : "This quote carries no integrator fee, and PipRail adds none. ") + (needsApproval ? "This swap needs TWO transactions: an ERC-20 approve to the router, then the swap." : "Native-in, so no ERC-20 approval is needed.")
+  };
+}
+function addrFor(t) {
+  return t.asset === "native" ? NATIVE_SENTINEL : t.asset;
+}
+function side(t, amount, nativeSymbol) {
+  return {
+    asset: t.asset,
+    symbol: t.symbol ?? (t.asset === "native" ? nativeSymbol : t.asset),
+    decimals: t.decimals,
+    amount: amount.toString(),
+    amountFormatted: formatUnits(amount, t.decimals)
+  };
+}
+async function getJson(url, init) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 12e3);
+  try {
+    const res = await fetch(url, { ...init ?? {}, signal: ctrl.signal });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function quoteEvmSwap(p) {
+  const chainPath = KYBER_CHAIN[p.chainId];
+  if (!chainPath) return null;
+  if (p.wantAmount <= 0n) return null;
+  const tokenIn = addrFor(p.from);
+  const tokenOut = addrFor(p.to);
+  if (tokenIn.toLowerCase() === tokenOut.toLowerCase()) return null;
+  const route = async (amountIn) => getJson(
+    `${KYBER_API}/${chainPath}/api/v1/routes?tokenIn=${tokenIn}&tokenOut=${tokenOut}&amountIn=${amountIn.toString()}`
+  );
+  const probeIn = 10n ** BigInt(Math.max(p.from.decimals - 2, 1));
+  const probe = await route(probeIn);
+  const probeOut = probe?.data?.routeSummary?.amountOut;
+  if (!probeOut) return null;
+  let needIn;
+  try {
+    const out = BigInt(probeOut);
+    if (out <= 0n) return null;
+    needIn = (probeIn * p.wantAmount + out - 1n) / out;
+    needIn = applySlippage(needIn, p.slippageBps);
+  } catch {
+    return null;
+  }
+  const real = await route(needIn);
+  const summary = real?.data?.routeSummary;
+  if (!summary?.amountOut || !real?.data?.routerAddress) return null;
+  try {
+    if (BigInt(summary.amountOut) < p.wantAmount) return null;
+  } catch {
+    return null;
+  }
+  const needsApproval = p.from.asset !== "native";
+  const spend = needIn;
+  return {
+    source: sourceFor(needsApproval, summary.extraFee),
+    network: p.network,
+    from: side(p.from, spend, p.nativeSymbol),
+    // What we will actually receive: at least the invoice amount, usually a little more.
+    to: side(p.to, BigInt(summary.amountOut), p.nativeSymbol),
+    // Exact-in means the input IS the cap: it cannot spend more than this.
+    maxSpend: spend.toString(),
+    maxSpendFormatted: formatUnits(spend, p.from.decimals),
+    slippageBps: p.slippageBps,
+    route: {
+      chainPath,
+      routeSummary: summary,
+      routerAddress: real.data.routerAddress,
+      needsApproval,
+      tokenIn
+    }
+  };
+}
+async function swapEvm(p) {
+  const { publicClient, walletClient, account, chain, quote } = p;
+  const route = quote.route;
+  if (!route?.routerAddress || !route.routeSummary) {
+    throw new Error("EVM: swap quote is missing its routing data \u2014 re-quote before swapping.");
+  }
+  const router = route.routerAddress;
+  const spend = BigInt(quote.maxSpend);
+  if (route.needsApproval) {
+    const token = route.tokenIn;
+    let allowance = 0n;
+    try {
+      allowance = await publicClient.readContract({
+        address: token,
+        abi: ERC20_ALLOWANCE_ABI,
+        functionName: "allowance",
+        args: [account.address, router]
+      });
+    } catch {
+      allowance = 0n;
+    }
+    if (allowance < spend) {
+      if (allowance > 0n) {
+        const resetHash = await walletClient.writeContract({
+          address: token,
+          abi: ERC20_ALLOWANCE_ABI,
+          functionName: "approve",
+          args: [router, 0n],
+          account,
+          chain
+        });
+        await publicClient.waitForTransactionReceipt({ hash: resetHash });
+      }
+      const approveHash = await walletClient.writeContract({
+        address: token,
+        abi: ERC20_ALLOWANCE_ABI,
+        functionName: "approve",
+        args: [router, spend],
+        account,
+        chain
+      });
+      await publicClient.waitForTransactionReceipt({ hash: approveHash });
+    }
+  }
+  const built = await getJson(
+    `${KYBER_API}/${route.chainPath}/api/v1/route/build`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        routeSummary: route.routeSummary,
+        sender: account.address,
+        recipient: account.address,
+        // ← ourselves: the funds never leave the wallet
+        slippageTolerance: quote.slippageBps
+      })
+    }
+  );
+  if (!built?.data?.data) {
+    throw new InsufficientFundsError(
+      "KyberSwap could not build this swap (the route went stale, or the market moved). Nothing was spent \u2014 re-quote and retry."
+    );
+  }
+  const execRouter = built.data.routerAddress ?? router;
+  if (route.needsApproval && execRouter.toLowerCase() !== router.toLowerCase()) {
+    const token = route.tokenIn;
+    const approveHash = await walletClient.writeContract({
+      address: token,
+      abi: ERC20_ALLOWANCE_ABI,
+      functionName: "approve",
+      args: [execRouter, spend],
+      account,
+      chain
+    });
+    await publicClient.waitForTransactionReceipt({ hash: approveHash });
+  }
+  try {
+    const hash = await walletClient.sendTransaction({
+      account,
+      chain,
+      to: execRouter,
+      data: built.data.data,
+      value: route.tokenIn === NATIVE_SENTINEL ? spend : 0n
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    if (receipt.status === "reverted") {
+      throw new InsufficientFundsError(
+        `EVM swap reverted on-chain (tx ${hash}). Nothing was swapped and only gas was spent. The usual cause is the route going stale between the quote and inclusion, so the router's minimum-output check fails. Re-quote and retry; on a fast-block chain a wider \`slippageBps\` helps.`
+      );
+    }
+    return {
+      transaction: hash,
+      network: quote.network,
+      source: quote.source,
+      from: quote.from,
+      to: quote.to
+    };
+  } catch (err) {
+    const msg = String(err?.message ?? err);
+    if (/TRANSFER_FROM_FAILED/i.test(msg)) {
+      throw new InsufficientFundsError(
+        "EVM swap reverted moving the token: the router allowance was rejected or the balance is short. Nothing was swapped. Some tokens refuse a non-zero to non-zero approve; re-quote and retry, which resets the allowance first.",
+        { cause: err }
+      );
+    }
+    if (/insufficient funds|exceeds balance/i.test(msg)) {
+      throw new InsufficientFundsError(
+        `EVM swap failed: the wallet can't cover it (token balance or native gas). (${msg.slice(0, 160)})`,
+        { cause: err }
+      );
+    }
+    throw err;
+  }
+}
+
 // src/drivers/evm/verify.ts
 import {
   decodeEventLog,
@@ -1947,6 +2219,11 @@ function makeEvmNetwork(resolved) {
         });
       }
     },
+    /** The bound wallet's own address — where THIS wallet gets paid. Derived from the key
+     *  material only: no RPC, nothing moved. See {@link ResolvedNetwork.addressOf}. */
+    async addressOf(wallet) {
+      return wallet._native.account.address;
+    },
     async balanceOf(wallet, asset) {
       const owner = wallet._native.account.address;
       const native = await publicClient.getBalance({ address: owner }).catch(() => null);
@@ -1985,6 +2262,31 @@ function makeEvmNetwork(resolved) {
     signReceipt(wallet, input) {
       return signReceiptEvm(wallet, input);
     },
+    /* ---- swap (OPTIONAL, opt-in): via KyberSwap, keyless + no integrator fee. See ./swap.ts ---- */
+    async quoteSwap({ from, to, wantAmount, slippageBps, wallet }) {
+      const a = wallet._native;
+      return quoteEvmSwap({
+        publicClient,
+        chainId: resolved.chainId,
+        network,
+        nativeSymbol: resolved.chain.nativeCurrency?.symbol ?? "ETH",
+        owner: a.account.address,
+        from,
+        to,
+        wantAmount,
+        slippageBps
+      });
+    },
+    async swap(wallet, quote) {
+      const a = wallet._native;
+      return swapEvm({
+        publicClient,
+        walletClient: a.walletClient,
+        account: a.account,
+        chain: resolved.chain,
+        quote
+      });
+    },
     async verify(ref, accept) {
       return verifyEvm({
         publicClient,
@@ -2138,7 +2440,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-HTKDRTD3.js");
+      mod = await import("./solana-O6Q6QILH.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -2150,7 +2452,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-WH2JVQOO.js");
+      mod = await import("./ton-OZKFNRLT.js");
     } catch (cause) {
       throw new MissingDriverError(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
@@ -2162,7 +2464,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-EUFZLX6J.js");
+      mod = await import("./stellar-YF5LOJEM.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -2174,7 +2476,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-RUOB37QH.js");
+      mod = await import("./xrpl-GOVHMYYK.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -2186,7 +2488,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-FXBXDNEY.js");
+      mod = await import("./tron-HG3IOOCG.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -2198,7 +2500,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-KCIITCYH.js");
+      mod = await import("./sui-JFQSDNSZ.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -2210,7 +2512,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-OLKCMTBI.js");
+      mod = await import("./near-5X2CQGML.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -2222,7 +2524,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-SBV6SGDP.js");
+      mod = await import("./aptos-H5VLH2QL.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
@@ -2234,7 +2536,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-25FMBCT3.js");
+      mod = await import("./algorand-HL57PQHE.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -2273,6 +2575,7 @@ var BUILTIN_DENOMS = {
   USDT: "USD",
   USD1: "USD",
   FDUSD: "USD",
+  USDG: "USD",
   U: "USD",
   // United Stables — BNB EIP-3009 stablecoin (1:1 USDC/USDT/USD1-backed)
   RLUSD: "USD",
@@ -2645,6 +2948,299 @@ var SpendLedger = class {
   }
 };
 
+// src/swapProviders.ts
+var SWAP_PROVIDERS = [
+  {
+    id: "stellar-sdex",
+    name: "Stellar SDEX",
+    kind: "protocol",
+    url: "https://developers.stellar.org/docs/build/guides/transactions/path-payments",
+    networks: ["stellar:pubnet"],
+    keyless: true,
+    fee: "No trading fee on the order books (spread only); the protocol liquidity pools charge a fixed 0.30%. Nobody can add an integrator fee, because there is no field for one.",
+    mechanism: "A PathPaymentStrictReceive addressed to your own account: one atomic operation, routed across the order books and liquidity pools.",
+    proofs: [
+      {
+        network: "stellar:pubnet",
+        tx: "f7b784d4758ea83a022921c7202051b4643fefb4fa61530a49010a4a9348a0aa",
+        date: "2026-09-08",
+        summary: "0.2652 XLM \u2192 0.05 USDC",
+        covers: "native in, and the ledger records source and destination as the same account"
+      },
+      {
+        network: "stellar:pubnet",
+        tx: "3aa2ca9e35ff7d7c3d0aaff3b24d53b4d2ea009067debf058c30ed8cad445f03",
+        date: "2026-09-08",
+        summary: "USDC \u2192 0.2 XLM",
+        covers: "the reverse direction, token in"
+      },
+      {
+        network: "stellar:pubnet",
+        tx: "27f50b2c2c57a64a8b50c1b14f310ec99b4ccbbb4bc72c479a5f6f9f1180e385",
+        date: "2026-09-08",
+        summary: "0.1064 XLM \u2192 0.02 USDC",
+        covers: "run straight from the committed example, so the documented flow is proven too"
+      }
+    ]
+  },
+  {
+    id: "xrpl-dex",
+    name: "XRPL DEX + AMM",
+    kind: "protocol",
+    url: "https://xrpl.org/docs/concepts/tokens/decentralized-exchange/automated-market-makers",
+    networks: ["xrpl:0"],
+    keyless: true,
+    fee: "No protocol fee on the order books (spread only); AMM pools charge a per-pool fee set by liquidity providers, 0% to 1%, paid to the pool. No integrator fee is expressible.",
+    mechanism: "A cross-currency Payment addressed to your own account, which the ledger permits precisely for currency conversion. Auto-bridged through XRP where that is cheaper.",
+    proofs: [
+      {
+        network: "xrpl:0",
+        tx: "F703B271E35BD3C2408DB64F693461513DD5166C15EC61DBAB0B2A9F726ED97E",
+        date: "2026-09-08",
+        summary: "0.072 XRP \u2192 0.1 RLUSD",
+        covers: "native in; delivered_amount matched the requested amount exactly"
+      },
+      {
+        network: "xrpl:0",
+        tx: "24EC9DDD2B5D00FD7CD56882999FCF59ABC274AA32E35119EADE397B335EEB63",
+        date: "2026-09-08",
+        summary: "RLUSD \u2192 0.02 XRP",
+        covers: "the reverse direction, token in"
+      }
+    ]
+  },
+  {
+    id: "jupiter",
+    name: "Jupiter",
+    kind: "provider",
+    url: "https://jup.ag",
+    networks: ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
+    keyless: true,
+    fee: "No platform fee. Verified per quote rather than assumed: PipRail never sets platformFeeBps, and every quote is inspected so the note says so if one ever appears.",
+    mechanism: "Jupiter routes and builds a serialized transaction; your own keypair signs it locally and this process broadcasts it. Jupiter never signs and never holds the funds.",
+    proofs: [
+      {
+        network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+        tx: "2rXpQYVerRzrwUfmXMYcm6ijkm8x7LHU91onSZjrng34kr1nfcxZj1A8Ek7inSw7ZBzk3phAaYnvHwdSJTKxJ4rq",
+        date: "2026-09-08",
+        summary: "0.1031 USDC \u2192 0.001 SOL",
+        covers: "token in, exact output"
+      },
+      {
+        network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+        tx: "UEeXBp3sPZgEHmahMasAbFhbTootXGCcpoNh7bN1sWsjoPDc1QE7uGaHjivT3iTroxLVJeWGVp2jZT63d2BVTk5",
+        date: "2026-09-08",
+        summary: "0.000485 SOL \u2192 0.05 USDC",
+        covers: "the reverse direction, native in"
+      }
+    ]
+  },
+  {
+    id: "kyberswap",
+    name: "KyberSwap",
+    kind: "provider",
+    url: "https://kyberswap.com",
+    // Every one live-probed with a real stablecoin route before being listed. Celo and
+    // Scroll are deliberately ABSENT: the API answers but returns no route even for the
+    // most liquid pair, so listing them would advertise a swap that cannot execute.
+    networks: [
+      "eip155:1",
+      "eip155:10",
+      "eip155:56",
+      "eip155:137",
+      "eip155:8453",
+      "eip155:42161",
+      "eip155:43114",
+      "eip155:59144",
+      "eip155:4663"
+    ],
+    keyless: true,
+    fee: "No integrator fee. Verified per quote rather than assumed: PipRail sends no fee parameters, and the returned extraFee block is inspected so the note says so if one ever appears.",
+    mechanism: "KyberSwap routes; your own wallet calls the router contract directly. An ERC-20 swap costs two transactions (an approve, then the swap); a native-in swap costs one.",
+    proofs: [
+      {
+        network: "eip155:56",
+        tx: "0x1748b6b27b1920aafd1d2730d250378b08cd4c0851a29e5e785dea960e0c8d4d",
+        date: "2026-09-08",
+        summary: "0.0101 USDT \u2192 USDC on BNB Chain",
+        covers: "the ERC-20 path, which needs an approval first"
+      },
+      {
+        network: "eip155:4663",
+        tx: "0x424299e67be623313c679e659fbfe9fb8707800fe145cddf7fac5a9bdbb78f10",
+        date: "2026-09-08",
+        summary: "native ETH \u2192 0.360518 USDG on Robinhood Chain",
+        covers: "a 100ms-block chain, where a route goes stale fast: the default 50 bps slippage reverted first, 300 bps cleared"
+      },
+      {
+        network: "eip155:56",
+        tx: "0xe27f957b40285acf0b846aea23808d49cc6a44fccd755aa88656abf31204fb00",
+        date: "2026-09-08",
+        summary: "native BNB \u2192 0.02 USDC",
+        covers: "the native-in path, which needs no approval"
+      },
+      {
+        network: "eip155:8453",
+        tx: "0xb28b802f530945eba1ea1662890792bfa1dfba64f5094caa58297f9693604032",
+        date: "2026-09-08",
+        summary: "0.00117 USDC \u2192 EURC on Base",
+        covers: "a second EVM chain on the same implementation"
+      },
+      {
+        network: "eip155:8453",
+        tx: "0x99a0842cd6c3fb33ddc03ddf776c2981c629debcd8ac47678a2e5e29e4496242",
+        date: "2026-09-08",
+        summary: "EURC \u2192 USDC on Base",
+        covers: "the reverse direction"
+      }
+    ]
+  },
+  {
+    id: "aftermath",
+    name: "Aftermath",
+    kind: "provider",
+    url: "https://aftermath.finance",
+    networks: ["sui:mainnet"],
+    keyless: true,
+    fee: "No fee added by the router: the route reports its own coinIn/coinOut tradeFee as zero, and the only cost is the underlying pool fee (about 0.014% on the probed route). PipRail passes no fee parameter.",
+    mechanism: "Aftermath routes and returns a COMPLETE serialized programmable transaction block; your own keypair signs it locally and this process broadcasts it. It never signs and never holds the funds.",
+    proofs: [
+      {
+        network: "sui:mainnet",
+        tx: "GtykrnLxejyrjmTL8oKVoEtTAiP9eY69CGne7Djw3Cha",
+        date: "2026-09-08",
+        summary: "0.0657 SUI to 0.0505 USDC",
+        covers: "native in; the balance changes on chain match the quote exactly"
+      }
+    ]
+  },
+  {
+    id: "ref-finance",
+    name: "Ref Finance",
+    kind: "provider",
+    url: "https://app.ref.finance",
+    networks: ["near:mainnet"],
+    keyless: true,
+    fee: "The pool's own total_fee, read live per pool (0.01% on the route used). There is no integrator fee for PipRail to set or waive.",
+    mechanism: "One ft_transfer_call receipt chain: token contract to AMM and back to you, inside a single transaction you sign. No solver takes possession, which is exactly why this is used instead of an intent network.",
+    proofs: [
+      {
+        network: "near:mainnet",
+        tx: "FAb28z1tCcecd2teFTxJGkgaLMr1mpctuiFhUeCKjszT",
+        date: "2026-09-08",
+        summary: "0.0505 USDT to 0.05 USDC",
+        covers: "token to token across a stable pool, 14 receipts, all successful"
+      }
+    ]
+  },
+  {
+    id: "vestige",
+    name: "Vestige",
+    kind: "provider",
+    url: "https://vestige.fi",
+    networks: ["algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="],
+    keyless: true,
+    fee: "The pool's own fee (0.30% on the probed route) plus the group's network fee. PipRail sends no fee parameter.",
+    mechanism: "Vestige returns an UNSIGNED atomic transaction group in which every signer is you. The SDK asserts that at runtime before signing anything, then signs locally and submits.",
+    proofs: [
+      {
+        network: "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
+        tx: "5UV7SWSJODHJDGMXODTOMBNXMK4YGZIZKR4VOM6XHML7JS7A32UA",
+        date: "2026-09-08",
+        summary: "0.5094 ALGO to 0.05 USDC",
+        covers: "a four-transaction atomic group, every signer the sender"
+      }
+    ]
+  },
+  {
+    id: "hyperion",
+    name: "Hyperion",
+    kind: "provider",
+    url: "https://hyperion.xyz",
+    networks: ["aptos:1"],
+    keyless: true,
+    fee: "The pool's own fee, read off-chain-state per route (0.01% on the stable pool used here). No API key, no integrator fee: the entry function has no fee parameter to set.",
+    mechanism: "Called contract-to-contract with NO API in the middle: the quote is an on-chain `view` and the swap is a Move entry function your own account signs. Uniquely, `exact_output_swap_entry` takes the amount you want OUT plus an on-chain input cap, so an x402 invoice is priced exactly rather than approximated.",
+    proofs: [
+      {
+        network: "aptos:1",
+        tx: "0x927293cf8584320f1e265c564ab3096262b675a61996e0da955a2b3c27af1adc",
+        date: "2026-09-08",
+        summary: "0.049997 USDC to exactly 0.05 USDT",
+        covers: "the stable pair, and the first swap in this SDK to deliver an EXACT output rather than at-least"
+      },
+      {
+        network: "aptos:1",
+        tx: "0xae849e031cb50a660f8c9f286c1f3a9caeff08b427efd9428154d884f1e3059e",
+        date: "2026-09-08",
+        summary: "0.040012 USDT to exactly 0.04 USDC",
+        covers: "the reverse direction, which takes the opposite on-chain price bound"
+      },
+      {
+        network: "aptos:1",
+        tx: "0x7921118d64ce1e4ebe7911ed22fef2222597e1b9e20caf0fd4f89bce07c07981",
+        date: "2026-09-08",
+        summary: "0.0459 APT to exactly 0.03 USDC",
+        covers: "native APT in, on a different fee tier"
+      },
+      {
+        network: "aptos:1",
+        tx: "0x640bce4b1e5f688d4494d0c343247b2951d22bc26d371b81f7d2c04655a7a707",
+        date: "2026-09-08",
+        summary: "0.012842 USDC to exactly 0.02 APT",
+        covers: "native APT out, where the balance delta nets off gas and only the deposit event proves the exact amount"
+      }
+    ]
+  },
+  {
+    id: "stonfi",
+    name: "STON.fi",
+    kind: "provider",
+    url: "https://ston.fi",
+    networks: ["tvm:-239"],
+    keyless: true,
+    fee: "The pool's own fee, reported per route by the simulation (about 0.10% on the routes used here). No API key and no referral field.",
+    mechanism: "Exact-output route, priced by STON.fi's keyless `reverse_swap` simulation, which fixes the ASK side and returns the offer required. PipRail pads the request so the router's on-chain floor (`min_ask_units`) is at or above the invoice: you may receive slightly more, never less. The swap is one message your own wallet signs to the router the simulation named. TON settles asynchronously, so arrival is a balance check rather than one atomic receipt.",
+    proofs: [
+      {
+        network: "tvm:-239",
+        tx: "1f6d58d073bd988b47272658297ebabc4748725ca919a4a9c863f28cef8eeb3f",
+        date: "2026-09-08",
+        summary: "0.035528 TON for 0.05 USDT",
+        covers: "native TON in, through the pTON proxy jetton, on the v2.2 router. The wallet transaction that STARTED the swap (opcode 0x01f3835d), not the gas refund that lands moments later"
+      },
+      {
+        network: "tvm:-239",
+        tx: "f76ae97e107b7852ea105d3b3b0caf095ec77bd2541f40417303c08566a87947",
+        date: "2026-09-08",
+        summary: "0.028171 USDT for 0.02 TON",
+        covers: "the jetton-to-TON direction, which the simulation routed through a DIFFERENT router version (v2.1). A TEP-74 jetton transfer (opcode 0x0f8a7ea5) carrying the swap as its forward payload"
+      }
+    ]
+  },
+  {
+    id: "sunswap",
+    name: "SunSwap V2",
+    kind: "provider",
+    url: "https://sunswap.com",
+    networks: ["tron:mainnet"],
+    keyless: true,
+    fee: "The pool's own 0.30% constant-product fee. No API key and no integrator fee: the router has no such parameter. Tron's ENERGY charge is the dominant cost, see below.",
+    mechanism: "Called contract-to-contract with NO API: `getAmountsIn` prices an exact output and `swapETHForExactTokens` executes it with the input capped on-chain. Selling native TRX is one transaction; selling a TRC-20 is two, because the router moves the input with `transferFrom` and needs an approval first. SunSwap's own front end uses an undocumented, obfuscated hostname, which a payments SDK should not depend on, so this skips the service entirely.",
+    unproven: "Shipped without a mainnet proof, deliberately and openly. The route is real, and every part of it that can be checked without spending has been: both directions quote live through the SDK, and the approve and the router call both execute cleanly in constant-call simulations against the real contracts. It has NOT been broadcast because Tron charges about 230,629 ENERGY per swap, which without staked energy is roughly 23 TRX (about $7.79) regardless of trade size, plus about 10 TRX more the first time a TRC-20 is approved. The project test wallets hold 8.1 TRX. A user with energy can swap today; we simply have not paid to prove it.",
+    proofs: []
+  }
+];
+function swapProvidersFor(network) {
+  return SWAP_PROVIDERS.filter((p) => p.networks.includes(network));
+}
+function canSwapOn(network) {
+  return swapProvidersFor(network).length > 0;
+}
+function swappableNetworks() {
+  return [...new Set(SWAP_PROVIDERS.flatMap((p) => p.networks))].sort();
+}
+
 // src/util/exactRecovery.ts
 function exactSettleCheckHint(family, payerFrom, nonce) {
   switch (family) {
@@ -2706,6 +3302,7 @@ var PipRailClient = class {
     this.assertPolicyAmountCaps(opts.policy);
     this.assertPolicyTimeOptions(opts.policy);
     this.assertPolicySpendControls(opts.policy);
+    this.assertModeIsHonest(opts);
   }
   /**
    * Fail LOUDLY at construction on a malformed amount cap — a security boundary
@@ -3055,12 +3652,141 @@ var PipRailClient = class {
   spent() {
     return this.ledger.summary();
   }
+  /**
+   * Each mode must be able to KEEP its promise, checked once at construction.
+   *
+   * `'supervised'` means a human approves each payment, and the only thing that can pause a
+   * payment for a human is `onBeforePay`. Without it the mode was a label: the client happily
+   * paid without asking anyone, while the name, the docs and the operator's mental model all
+   * said otherwise. A safety control that silently does nothing is worse than an absent one,
+   * because the operator has already stopped worrying about it.
+   *
+   * The mirror of the sovereign rule, which refuses to unlock swapping without a ceiling. Both
+   * fail at CONSTRUCTION rather than at the first payment, so the mistake surfaces while
+   * somebody is reading their own config instead of mid-spend.
+   */
+  assertModeIsHonest(opts) {
+    const mode = opts.mode ?? DEFAULT_AGENT_MODE;
+    if (mode === "supervised" && typeof opts.onBeforePay !== "function") {
+      throw new TypeError(
+        "mode: 'supervised' needs an `onBeforePay` hook \u2014 it is the only thing that can pause a payment for a human, so without it this client would pay without asking anyone, which is exactly what 'supervised' promises not to do. Add onBeforePay, or use 'budgeted' if the policy is meant to be the consent. (@piprail/mcp wires this for you from PIPRAIL_MODE.)"
+      );
+    }
+    if (mode === "sovereign" && opts.swapPolicy?.maxPerSwap === void 0) {
+      throw new TypeError(
+        "mode: 'sovereign' needs `swapPolicy.maxPerSwap` \u2014 it hands a model the swap tools, and your payment caps do NOT bound a swap (they count payments; a swap is not one), so without a ceiling nothing limits what one swap may spend. Set a ceiling, e.g. swapPolicy: { maxPerSwap: '25.00' }. Selling needs no ceiling: it takes money rather than spending it."
+      );
+    }
+  }
   /** The CONFIGURED spend policy, read back unchanged — so an agent can self-check
    *  its WHOLE leash (caps, allowlists, time, denom + count limits) without hitting a
    *  decline. `undefined` when no policy is set. Pure; never throws. */
   policy() {
     return this.opts.policy;
   }
+  /**
+   * Who is answerable for this wallet: `'supervised'`, `'budgeted'` (default) or
+   * `'sovereign'`. READ-ONLY on purpose. A model asks what authority it has; it can
+   * never grant itself more, exactly as an agent cannot widen its own permissions in
+   * its host. Set once at construction by whoever provisioned the key.
+   */
+  mode() {
+    return this.opts.mode ?? DEFAULT_AGENT_MODE;
+  }
+  /** The configured swap guardrails, read back unchanged. `undefined` when none is set. */
+  swapPolicy() {
+    return this.opts.swapPolicy;
+  }
+  /**
+   * This wallet's OWN address — where it gets paid.
+   *
+   * The receiving half of a wallet, and the one thing an agent handed a key cannot work
+   * out for itself: the key is set by whoever provisioned it, so without this the agent
+   * can spend but can never tell a buyer where to send anything. `sell` defaults its
+   * `payTo` to exactly this.
+   *
+   * Derived from the key, not the network — no RPC read, nothing moved. Throws
+   * {@link WalletRequiredError} on a read-only client (no wallet, no address).
+   */
+  /** The chain this client is configured for, exactly as it was given. A sold offer
+   *  defaults to it, so an agent prices on the chain it actually holds funds on. */
+  chain() {
+    return this.opts.chain;
+  }
+  /**
+   * What this wallet actually HOLDS, per asset — the balance sheet, not the leash.
+   *
+   * `budget()` answers "how much of my allowance is left", a different question and the only
+   * one an agent could previously ask. An agent that OWNS a wallet has to answer "what do I
+   * have?" before it can decide anything: whether to sell, whether to swap, whether it needs
+   * topping up and in which denomination.
+   *
+   * RPC-read-only and never throws for a read problem: an asset whose read was unavailable
+   * comes back `null` (unknown), never `0`, because a rate-limited read that reads as "broke"
+   * would make an agent behave as though it had been drained. A symbol this chain does not ship
+   * is reported as unknown rather than guessed at.
+   */
+  async balanceOf(assets = ["native"]) {
+    const { net, wallet } = await this.ensure();
+    if (!wallet) {
+      throw new WalletRequiredError("balanceOf needs a wallet \u2014 a read-only client holds nothing.");
+    }
+    const out = [];
+    for (const symbol of assets) {
+      let asset;
+      let decimals;
+      let resolvedSymbol;
+      try {
+        const t = net.resolveToken(symbol);
+        asset = t.asset;
+        decimals = t.decimals;
+        resolvedSymbol = t.symbol;
+      } catch {
+        out.push({ symbol, asset: null, decimals: null, known: false, amount: null, amountFormatted: null });
+        continue;
+      }
+      const bal = await net.balanceOf(wallet, asset).catch(() => ({ token: null, native: null }));
+      out.push({
+        symbol: resolvedSymbol ?? symbol,
+        asset,
+        decimals,
+        known: true,
+        amount: bal.token === null ? null : bal.token.toString(),
+        amountFormatted: bal.token === null ? null : formatUnits(bal.token, decimals)
+      });
+    }
+    return out;
+  }
+  async address() {
+    const { net, wallet } = await this.ensure();
+    if (!wallet) {
+      throw new WalletRequiredError(
+        "address() needs a wallet \u2014 a read-only client has no address to be paid at."
+      );
+    }
+    return net.addressOf(wallet);
+  }
+  /**
+   * May a model SELL on this wallet — price its own offers and collect payment for them?
+   * True only in `'sovereign'` mode, the same authority test as {@link canAgentSwap}:
+   * earning is the other half of owning a wallet, and an agent that answers for its own
+   * balance answers for how that balance is filled.
+   *
+   * Taking money is not the risk that gates this. Committing to DELIVER something is, and
+   * so is publishing an address as an open invitation to pay it — neither is a supervised
+   * agent's call to make alone.
+   */
+  canAgentSell() {
+    return this.mode() === "sovereign";
+  }
+  /**
+   * May a model move this wallet's own funds between denominations? True only in
+   * `'sovereign'` mode. The payment tools consult this, so the answer lives in ONE place
+   * rather than being re-derived by every surface that asks.
+   */
+  canAgentSwap() {
+    return this.mode() === "sovereign";
+  }
   /**
    * Read-only budget + time leash for a Mode-A (headless) agent — the policy IS
    * the consent, and this is how the agent SEES what's left of it before paying.
@@ -3210,22 +3936,142 @@ var PipRailClient = class {
     const plan = await this.planPayment(url, init);
     return plan == null ? true : plan.payable;
   }
-  /* ------------------------- discovery (find + list) ------------------------- */
+  /* --------------------------- swap (OPTIONAL helper) --------------------------- */
   /**
-   * Find payable resources on the OPEN x402 indexes — WITHOUT paying. Reads the
-   * free indexes (CDP Bazaar + 402 Index by default), merges + dedupes them, and
-   * by default returns only resources payable on THIS client's chain
-   * (`network: 'self'`). Each result carries its advertised `rails[]`; feed a
-   * chosen `resource` straight into `quote()` → `planPayment()` → `fetch()`.
+   * Price a same-chain swap — "I hold the wrong token". READ-ONLY: no funds move,
+   * nothing is signed, nothing is committed to.
    *
-   * Nothing PipRail-hosted: these are third-party open directories. Never throws
-   * for a read problem — an index that's down or changed simply contributes
-   * nothing. Honest caveats (see {@link DIRECTORY_INFO}):
-   * - Reads **`bazaar` + `402index`** only — **NOT `x402scan`** (its reads are paid). A
-   *   resource you registered on x402scan is live there but will NOT appear here; don't
-   *   read that absence as failure. (Passing `sources:['x402scan']` explicitly yields `[]`.)
-   * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
-   *   before publishing, so retry with a brief backoff if a fresh listing is missing.
+   * ⚠️ **This is a convenience, not part of paying.** Nothing calls it for you.
+   * `fetch()` never swaps, `planPayment()` never swaps, and there is deliberately no
+   * `autoSwap` option: converting one asset into another is a priced, irreversible
+   * act, and a payment library should not do that on your behalf because it noticed
+   * you were short. If you would rather bridge or swap somewhere else entirely, or
+   * just top the wallet up by hand, that is a perfectly good answer and this method
+   * costs you nothing by existing.
+   *
+   * 🔴 **The rate is not PipRail's.** Read `quote.source` — it names who produced the
+   * number. Today both implementations are `kind: 'protocol'`, meaning the chain's
+   * own order books priced it and no company is involved.
+   *
+   * Returns `null` — never throws — when this chain has no swap support, the pair
+   * can't be routed, there's no liquidity, or a read failed. `null` means "no quote",
+   * never "no funds".
+   */
+  async quoteSwap(req) {
+    const slippageBps = resolveSlippageBps(req.slippageBps);
+    const sp = this.opts.swapPolicy;
+    if (sp?.maxSlippageBps !== void 0 && slippageBps > sp.maxSlippageBps) {
+      throw new PaymentDeclinedError(
+        `slippageBps ${slippageBps} exceeds this agent's swapPolicy.maxSlippageBps of ${sp.maxSlippageBps}.`,
+        { reasonCode: "POLICY" }
+      );
+    }
+    const { net, wallet } = await this.ensure();
+    if (!net.quoteSwap || !wallet) return null;
+    let from;
+    let to;
+    let wantAmount;
+    try {
+      from = net.resolveToken(req.from);
+      to = net.resolveToken(req.to);
+      wantAmount = parseUnits(req.wantAmount, to.decimals);
+    } catch {
+      return null;
+    }
+    try {
+      return await net.quoteSwap({ from, to, wantAmount, slippageBps, wallet });
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Execute a swap you have already quoted and chosen to accept. Signs from your own
+   * wallet (one transaction, or two where a token must be approved first); on every route
+   * the funds never leave your account, they just change denomination.
+   *
+   * Pass the {@link SwapQuote} from {@link quoteSwap} unmodified — it carries the
+   * route and the on-chain slippage cap. Re-quote rather than reusing an old one: a
+   * stale route is how you get a worse price than you were shown.
+   *
+   * Throws {@link WalletRequiredError} without a wallet, {@link UnsupportedNetworkError}
+   * when the chain has no swap support, and {@link InsufficientFundsError} when the
+   * wallet can't cover it (which includes the market moving past your slippage cap —
+   * nothing is swapped in that case, though chains that charge for a reverted
+   * transaction, such as EVM, Aptos and Tron, still take the gas).
+   */
+  async swap(quote) {
+    const { net, wallet } = await this.ensure();
+    if (!wallet) {
+      throw new WalletRequiredError(
+        "swap needs a wallet \u2014 it signs a transaction. This client is read-only."
+      );
+    }
+    if (!net.swap) {
+      const venues = SWAP_PROVIDERS.map((p) => p.name).join(", ");
+      throw new UnsupportedNetworkError(
+        `Swapping isn't supported on ${net.network}. PipRail ships swaps only where an OPEN, KEYLESS route exists (${venues}). On other chains, move funds with a tool you choose.`
+      );
+    }
+    if (quote.network !== net.network) {
+      throw new UnsupportedNetworkError(
+        `This swap quote is for ${quote.network} but the client is bound to ${net.network}.`
+      );
+    }
+    const sp = this.opts.swapPolicy;
+    if (sp?.maxPerSwap !== void 0) {
+      const cap = parseUnits(sp.maxPerSwap, quote.from.decimals);
+      if (BigInt(quote.maxSpend) > cap) {
+        throw new PaymentDeclinedError(
+          `This swap could spend up to ${quote.maxSpendFormatted} ${quote.from.symbol}, over this agent's swapPolicy.maxPerSwap of ${sp.maxPerSwap}. Nothing was signed.`,
+          { reasonCode: "POLICY" }
+        );
+      }
+    }
+    if (sp?.allowTo?.length) {
+      const want = quote.to.symbol;
+      if (!sp.allowTo.some((t) => t.toUpperCase() === want.toUpperCase())) {
+        throw new PaymentDeclinedError(
+          `This agent may only swap into ${sp.allowTo.join(", ")}, not ${want}. Nothing was signed.`,
+          { reasonCode: "POLICY" }
+        );
+      }
+    }
+    const approve = this.opts.onBeforeSwap;
+    if (approve) {
+      let okToSwap;
+      try {
+        okToSwap = await approve(quote);
+      } catch (err) {
+        throw new PaymentDeclinedError(
+          "onBeforeSwap threw \u2014 refusing to swap. Nothing was signed.",
+          { reasonCode: "APPROVAL", cause: err }
+        );
+      }
+      if (okToSwap !== true) {
+        throw new PaymentDeclinedError(
+          `onBeforeSwap declined this swap of up to ${quote.maxSpendFormatted} ${quote.from.symbol} for ${quote.to.symbol}. Nothing was signed.`,
+          { reasonCode: "APPROVAL" }
+        );
+      }
+    }
+    return net.swap(wallet, quote);
+  }
+  /* ------------------------- discovery (find + list) ------------------------- */
+  /**
+   * Find payable resources on the OPEN x402 indexes — WITHOUT paying. Reads the
+   * free indexes (CDP Bazaar + 402 Index by default), merges + dedupes them, and
+   * by default returns only resources payable on THIS client's chain
+   * (`network: 'self'`). Each result carries its advertised `rails[]`; feed a
+   * chosen `resource` straight into `quote()` → `planPayment()` → `fetch()`.
+   *
+   * Nothing PipRail-hosted: these are third-party open directories. Never throws
+   * for a read problem — an index that's down or changed simply contributes
+   * nothing. Honest caveats (see {@link DIRECTORY_INFO}):
+   * - Reads **`bazaar` + `402index`** only — **NOT `x402scan`** (its reads are paid). A
+   *   resource you registered on x402scan is live there but will NOT appear here; don't
+   *   read that absence as failure. (Passing `sources:['x402scan']` explicitly yields `[]`.)
+   * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
+   *   before publishing, so retry with a brief backoff if a fresh listing is missing.
    * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
    *   `onchain-proof` rails by default, and standard `exact` rails too once you opt in
    *   with `schemes: ['onchain-proof', 'exact']` (EVM EIP-3009/Permit2 + Solana SVM + Algorand
@@ -4601,6 +5447,71 @@ var MultiChainPayer = class _MultiChainPayer {
   policy() {
     return this._clients[0].policy();
   }
+  /*
+   * ── SWAP, ACROSS A MULTI-CHAIN PAYER ────────────────────────────────────────────
+   *
+   * A swap is SAME-CHAIN by definition, so there is nothing to route: it delegates to the
+   * PRIMARY client, which is the first one given, and the constructor already documents
+   * that order as your chain preference. Without this the MCP could never expose swapping
+   * at all, because it always wraps its accounts in a MultiChainPayer even for one chain.
+   */
+  mode() {
+    return this._clients[0].mode();
+  }
+  canAgentSwap() {
+    return this._clients[0].canAgentSwap();
+  }
+  /*
+   * ── SELLING, ACROSS A MULTI-CHAIN PAYER ─────────────────────────────────────────
+   *
+   * Same reasoning as the swap block above, and the same necessity: the MCP always wraps
+   * its accounts in a MultiChainPayer, so without these the seller tools would be
+   * unreachable through the MCP no matter what mode the operator set.
+   *
+   * The address is the PRIMARY chain's — a wallet has one address per family, not one
+   * overall, so "where do I get paid?" is only answerable per chain. An offer priced on
+   * another chain names its own payTo; this is the default, not the only option.
+   */
+  canAgentSell() {
+    return this._clients[0].canAgentSell();
+  }
+  async address() {
+    return this._clients[0].address();
+  }
+  chain() {
+    return this._clients[0].chain();
+  }
+  /**
+   * Holdings across EVERY chain this payer owns, not just the primary. A multi-chain agent's
+   * balance sheet is the union: reporting only the first chain would tell it it was broke while
+   * it held funds one client along, which is exactly the wrong answer to "what do I have?".
+   */
+  async balanceOf(assets = ["native"]) {
+    const out = [];
+    for (const c of this._clients) {
+      const rows = await c.balanceOf(assets).catch(() => []);
+      for (const r of rows) out.push({ ...r, chain: String(c.chain()) });
+    }
+    return out;
+  }
+  async quoteSwap(req) {
+    return this._clients[0].quoteSwap(req);
+  }
+  async swap(quote) {
+    let firstRefusal;
+    for (const c of this._clients) {
+      try {
+        return await c.swap(quote);
+      } catch (err) {
+        if (err instanceof WrongChainError || err?.name === "UnsupportedNetworkError") {
+          firstRefusal ??= err;
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw firstRefusal ?? new Error("MultiChainPayer: no client could execute this swap quote.");
+  }
 };
 function isBodyInit(value) {
   if (typeof value === "string") return true;
@@ -4741,6 +5652,22 @@ var PIPRAIL_AGENT_GUIDE = `# Paying with PipRail \u2014 the agent contract
 You can pay for x402 "402 Payment Required" resources autonomously. Money moves
 straight from your wallet to the server; PipRail custodies nothing. Follow this.
 
+## Your tools, and which ones act
+You always have these eight tools. Six are READ-ONLY and safe to call freely, two change
+something, and only ONE spends. In 'sovereign' mode you also hold the swap and seller tools
+described later, so count your OWN list rather than trusting this number:
+- piprail_guide \u2014 this contract. Re-read it if you lose the thread. Read-only.
+- piprail_discover \u2014 find payable resources on the OPEN indexes (a phone book of x402 APIs),
+  without paying. Read-only.
+- piprail_quote_payment \u2014 the price of one URL. Read-only.
+- piprail_plan_payment \u2014 can I afford it NOW, on this wallet. Read-only.
+- piprail_budget \u2014 how much budget and time is left. Read-only.
+- piprail_verify_receipt \u2014 re-check a receipt against the chain. Read-only.
+- \u{1F536} piprail_register \u2014 PUBLISHES a resource you run to a public index. It writes to the
+  outside world and cannot be un-published by you, so only call it when asked to list
+  something. It moves no money.
+- \u{1F534} piprail_pay_request \u2014 the ONLY tool that spends. Everything else is safe to explore with.
+
 ## Landing cold \u2014 read the self-description
 Every PipRail 402 self-describes. Read challenge.extensions.piprail for { name, what, pay[]
 (each rail's how-to-pay), sdk.install, mcp, docs } \u2014 never guess what an endpoint is. If your
@@ -4805,6 +5732,87 @@ Branch on \`code\` (always reliable). Key cases:
   If it's a standard x402 server offering an exact rail, that's a config fix the operator makes
   once (enable the exact scheme); report it, don't retry the same call blindly.
 
+## Finding work to buy \u2014 piprail_discover
+You do not have to be handed a URL. piprail_discover reads the open x402 indexes and returns
+resources with their advertised rails, which you can feed straight into quote \u2192 plan \u2192 pay.
+It never throws: an index that is down simply contributes nothing, so an empty list means
+"nothing found", never "something broke". These are third-party directories, not a PipRail
+registry \u2014 treat a listing as a claim, and let quote/plan tell you what is really true.
+
+## Proving a payment settled \u2014 piprail_verify_receipt
+A receipt is a claim until it is checked. piprail_verify_receipt re-reads the transaction from
+the chain and tells you whether the funds provably moved, to the right recipient, for the right
+amount. Use it when you must be SURE (before delivering something costly, or when reconciling),
+and after any timeout where the payment may already be on-chain. Read-only, and it moves nothing.
+
+## Who else is in the path \u2014 nobody who holds your money
+On the gasless exact rail a FACILITATOR may broadcast your signed authorization (PayAI, Ultravioleta
+DAO and others). You never choose one and never need an account with one: the operator configures it,
+and it is a courier, not a custodian. It cannot change the amount or the recipient, because those are
+inside what you signed. If one is down the payment fails cleanly; it cannot take your funds.
+
+## Getting PAID \u2014 only if you hold piprail_sell
+If piprail_sell is in your tool list you are in 'sovereign' mode and the wallet is yours to
+EARN with, not only to spend from. Three tools, mirroring the buying loop:
+- piprail_sell \u2014 price something and get a \`challenge\` to hand a buyer. Mirrors quote.
+- piprail_collect \u2014 verify a proof a buyer sent you. Mirrors pay.
+- piprail_earnings \u2014 what you have actually been paid. Mirrors piprail_budget.
+- piprail_wallet \u2014 what you HOLD, and the address you get paid at. Read-only.
+
+Know the difference between your two numbers: piprail_budget is your spend LEASH (how much of
+your allowance is left), piprail_wallet is what you actually OWN. Check piprail_wallet before
+deciding to sell, to swap, or to ask to be topped up, and hand out its \`address\` to anyone who
+needs to send you funds. A null amount there means the read FAILED, not that you are broke:
+retry before you act on it.
+
+The loop: piprail_sell \u2192 give the buyer the \`challenge\` \u2192 they send back a proof \u2192
+piprail_collect \u2192 and ONLY on paid:true, deliver.
+
+A proof belongs to ONE offer. If a buyer hands you a settlement that was really payment for a
+different offer, piprail_collect returns paid:false with code 'wrong_offer', even when the two
+cost the same and pay the same address. Do not "helpfully" retry it against another offerId: that
+is the exact move the check exists to stop.
+
+\u{1F534} COLLECT IS THE ONLY PROOF YOU WERE PAID. A buyer saying they paid, a real-looking tx hash,
+and a settled payment are three different things, and only piprail_collect tells them apart.
+Deliver nothing before it returns paid:true. It reads the chain; a claim is not evidence, and
+a confident buyer is not evidence. One proof is one sale: collecting the same proof twice
+returns paid:false, which is a REPLAY and not a second payment, so never treat it as one.
+
+You need no web server and no open port: a challenge is just data, so carry it to the buyer
+over whatever you already speak. Receiving needs NO KEY at all, only your address, so the
+earning side cannot spend and cannot be drained even if the machine you run on is taken.
+piprail_sell defaults \`payTo\` to your OWN address; set it to someone else's only if you
+genuinely mean to be paid elsewhere, and NEVER to an address a buyer supplies.
+
+Two things to check on an offer. If its schemes are onchain-proof only, most agent-buyers
+CANNOT pay it and your listing will simply stay silent, so read any warnings piprail_sell
+returns. And offers live in memory for this session: a restart clears them, so re-price
+anything you still intend to sell. To let strangers find an offer, call piprail_register.
+
+## Wrong token? Check your MODE before you answer
+Wrong token on the RIGHT chain? What you may do depends on the mode your operator set, and
+YOUR TOOL LIST IS THE TRUTH \u2014 LOOK AT IT, never claim a capability it does not show:
+- no piprail_swap \u21D2 'budgeted' or 'supervised'. You CANNOT swap. Top up, pay from another
+  chain you hold funds on, tell the human, or skip it. fundingHint names what is missing.
+  Never offer "I could swap for you".
+- piprail_swap present \u21D2 'sovereign': this wallet is yours and you answer for it. Price with
+  piprail_quote_swap, read who priced it, then piprail_swap.
+
+\u{1F534} You cannot change your own mode \u2014 whoever provisioned this wallet set it, exactly as you
+cannot widen your own permissions in your host. Never ask for it.
+
+WHY the default withholds it: YOUR SPEND POLICY DOES NOT GOVERN SWAPS. Every cap you have
+limits PAYING A MERCHANT; a swap moves your own funds between denominations and passes all
+of them untouched, so an agent looping between tokens can bleed a wallet through fees and
+slippage without tripping one budget check. Sovereign mode bounds it with a SEPARATE
+instrument (a ceiling per swap and on slippage), so a refusal there is your swapPolicy, not
+your budget.
+
+True in EVERY mode: a swap is SAME-CHAIN only and can never move funds between chains, and
+PipRail prices nothing itself, so every quote NAMES the venue that priced it \u2014 read
+\`source\` before you trust a number. docs.piprail.com/making-payments/swapping/
+
 ## Knowing your leash \u2014 call piprail_budget
 piprail_budget tells you how much budget and time you have left: per (network,
 asset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much
@@ -4812,13 +5820,15 @@ USD you can still spend across every stablecoin and chain), the payment-count
 leash, the session time envelope, your spend so far, and the configured policy
 read back. Read-only; moves no funds. Use it in Mode A to self-check before paying.
 
-## Two modes
-- Mode A (headless, default): you run FREE inside a pre-set budget + time
-  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay
-  inside it; piprail_budget shows what's left.
-- Mode B (supervised): the host may ask a human to approve each payment. A
-  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014
-  do NOT retry it as if it were a transient error.
+## Two modes of CONSENT \u2014 a different axis from the mode above
+Your 'supervised'/'budgeted'/'sovereign' mode says what you may DO. This says how each
+payment is agreed. Both are in force at once, so read them together:
+- Mode A (headless \u2014 how 'budgeted' and 'sovereign' behave): you run FREE inside a pre-set
+  budget + time envelope. The policy IS the consent, and there is no per-payment prompt.
+  Stay inside it; piprail_budget shows what's left.
+- Mode B (supervised \u2014 how the 'supervised' mode behaves): the host may ask a human to
+  approve each payment. A decline/cancel/timeout comes back as declined:true
+  (reasonCode:'APPROVAL') \u2014 do NOT retry it as if it were a transient error.
 
 ## Hard facts
 - Per-payment + per-(network, asset) caps always apply. A cross-token GRAND TOTAL per
@@ -4835,525 +5845,110 @@ function agentGuide() {
   return PIPRAIL_AGENT_GUIDE;
 }
 
-// src/agent.ts
-var OPEN_OBJECT = { type: "object", additionalProperties: true };
-async function readBody(res) {
-  const text = await res.text();
-  if (!text) return null;
+// src/discovery.ts
+var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
+var POWERED_BY = "PipRail x402 | https://piprail.com";
+function discoveryHeaders(opts = {}) {
+  return {
+    link: '</openapi.json>; rel="service-desc", </.well-known/x402>; rel="x402-discovery"',
+    ...opts.attribution === false ? {} : { "x-powered-by": POWERED_BY }
+  };
+}
+function buildBazaarExtension(descriptor = {}) {
+  const method = (descriptor.method ?? "GET").toUpperCase();
+  const queryParams = descriptor.queryParams ?? {};
+  return {
+    info: {
+      input: { type: "http", method, queryParams },
+      output: descriptor.output ?? { type: "json" }
+    },
+    schema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      properties: {
+        input: {
+          type: "object",
+          properties: {
+            type: { type: "string", const: "http" },
+            method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"] },
+            queryParams: { type: "object", properties: queryParams, additionalProperties: false }
+          },
+          required: ["type", "method"],
+          additionalProperties: false
+        }
+      },
+      required: ["input"]
+    }
+  };
+}
+function pathOf(url) {
   try {
-    return JSON.parse(text);
+    return new URL(url).pathname || "/";
   } catch {
-    return text;
+    return url.startsWith("/") ? url : `/${url}`;
   }
 }
-function toToolError(err) {
-  if (!(err instanceof PipRailError)) throw err;
-  const out = {
-    ok: false,
-    code: err.code,
-    reason: err.message,
-    explain: explainDecline(err)
+function buildOpenApi(input) {
+  assertResourceList(input?.resources, "buildOpenApi");
+  const paths = {};
+  for (const r of input.resources) {
+    const path = pathOf(r.url);
+    const method = (r.method ?? "GET").toLowerCase();
+    const op = {
+      ...r.description ? { summary: r.description } : {},
+      responses: {
+        "200": { description: "Paid \u2014 the resource." },
+        "402": { description: "Payment required (x402)." }
+      },
+      "x-payment-info": {
+        x402Version: 2,
+        accepts: r.accepts
+      }
+    };
+    paths[path] = { ...paths[path] ?? {}, [method]: op };
+  }
+  return {
+    openapi: "3.1.0",
+    info: { title: input.title ?? "PipRail x402 resources", version: input.version ?? "1.0.0" },
+    servers: [{ url: input.origin }],
+    paths,
+    // "Built with @piprail/sdk" — default on (opt out with attribution:false). At the
+    // document ROOT so `info` stays exactly { title, version }.
+    ...input.attribution === false ? {} : { "x-generator": GENERATOR },
+    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { "x-agentcash-provenance": { ownershipProofs: input.ownershipProofs } } : {}
   };
-  if (err instanceof PaymentDeclinedError) {
-    out.declined = true;
-    if (err.reasonCode) out.reasonCode = err.reasonCode;
+}
+function buildWellKnownX402(input) {
+  assertResourceList(input?.resources, "buildWellKnownX402");
+  return {
+    version: 1,
+    resources: input.resources.map((r) => r.url),
+    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { ownershipProofs: input.ownershipProofs } : {}
+  };
+}
+function assertResourceList(resources, fn) {
+  if (!Array.isArray(resources)) {
+    throw new InvalidConfigError(`${fn}: \`resources\` must be an array of ResourceDescription.`);
   }
-  const ref = err.ref;
-  if (typeof ref === "string") out.ref = ref;
-  return out;
+  resources.forEach((r, i) => {
+    if (r === null || typeof r !== "object" || typeof r.url !== "string") {
+      throw new InvalidConfigError(
+        `${fn}: resources[${i}] must be a ResourceDescription with a string \`url\`.`
+      );
+    }
+  });
 }
-function paymentTools(client) {
-  return [
-    {
-      name: "piprail_discover",
-      description: `Find x402 payment-gated resources on the OPEN indexes (a phone book of payable APIs) WITHOUT paying. Use it to answer "what can I buy?" \u2014 search by topic, then quote/plan/pay a chosen one. By default returns only resources payable on your wallet's chain (network='self'); pass 'any' for every chain. Results are cross-scheme: ALWAYS call piprail_quote_payment on a chosen resource (it re-checks the live price) before piprail_pay_request.`,
-      annotations: {
-        title: "Discover payable x402 APIs",
-        readOnlyHint: true,
-        // reads the open indexes only; never pays
-        openWorldHint: true
-        // reaches external indexes (402 Index, CDP Bazaar)
-      },
-      parameters: {
-        type: "object",
-        properties: {
-          query: {
-            type: "string",
-            description: 'Free-text topic to search for (optional). Multi-word queries are fanned out per word and results are ranked by relevance, so "crypto price feed" finds the best matches even when no single listing contains that exact phrase.'
-          },
-          network: {
-            type: "string",
-            description: "CAIP-2 id, 'self' (your chain \u2014 default), or 'any' (all chains)."
-          },
-          category: { type: "string", description: "Keep ONLY this category, e.g. 'ai', 'finance', 'data' (strict)." },
-          asset: { type: "string", description: "Keep only resources paying in this token symbol, e.g. 'USDC'." },
-          maxPrice: { type: "number", description: "Drop results advertised above this USD price." },
-          minReliability: { type: "number", description: "Drop results below this health score (0\u2013100); unscored pass." },
-          verified: { type: "boolean", description: "Prefer verified listings (402 Index)." },
-          sort: {
-            type: "string",
-            enum: ["relevance", "reliability", "price", "uptime", "name"],
-            description: "Ordering. Default 'relevance' with a query, else first-seen."
-          },
-          limit: { type: "number", description: "Max results to fetch per index (default 20)." }
-        },
-        additionalProperties: false
-      },
-      invoke: async (args) => {
-        try {
-          const opts = {};
-          if (typeof args.query === "string") opts.query = args.query;
-          if (typeof args.network === "string") opts.network = args.network;
-          if (typeof args.category === "string") opts.category = args.category;
-          if (typeof args.asset === "string") opts.asset = args.asset;
-          if (typeof args.maxPrice === "number") opts.maxPrice = args.maxPrice;
-          if (typeof args.minReliability === "number") opts.minReliability = args.minReliability;
-          if (typeof args.verified === "boolean") opts.verified = args.verified;
-          if (typeof args.sort === "string") opts.sort = args.sort;
-          if (typeof args.limit === "number") opts.limit = args.limit;
-          const found = await client.discover(opts);
-          return {
-            count: found.length,
-            resources: found.map((r) => ({
-              resource: r.resource,
-              name: r.name,
-              description: r.description,
-              source: r.source,
-              category: r.category,
-              priceUsd: r.priceUsd,
-              reliabilityScore: r.reliabilityScore,
-              health: r.health,
-              verified: r.verified,
-              networks: [...new Set(r.rails.map((rail) => rail.network))]
-            }))
-          };
-        } catch (err) {
-          return toToolError(err);
-        }
-      }
-    },
-    {
-      name: "piprail_quote_payment",
-      description: "Get the price of an x402 payment-gated URL WITHOUT paying. Returns the amount, token, chain, recipient, and whether it is within the spend policy. Returns { gated: false } when the URL needs no payment. Call this first to decide whether a resource is worth buying.",
-      annotations: {
-        title: "Quote an x402 price",
-        readOnlyHint: true,
-        // reads the 402 challenge; never pays
-        openWorldHint: true
-        // fetches an arbitrary URL
-      },
-      parameters: {
-        type: "object",
-        properties: {
-          url: { type: "string", description: "Full URL of the gated resource." }
-        },
-        required: ["url"],
-        additionalProperties: false
-      },
-      outputSchema: OPEN_OBJECT,
-      invoke: async (args) => {
-        try {
-          const quote = await client.quote(String(args.url));
-          return quote ? { gated: true, ...quote } : { gated: false, url: String(args.url) };
-        } catch (err) {
-          return toToolError(err);
-        }
-      }
-    },
-    {
-      name: "piprail_plan_payment",
-      description: "Check whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive \u2014 across every rail the URL offers on your chain \u2014 and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.",
-      annotations: {
-        title: "Plan an x402 payment",
-        readOnlyHint: true,
-        // reads balances + the challenge; never pays
-        openWorldHint: true
-        // fetches a URL and reads chain state
-      },
-      parameters: {
-        type: "object",
-        properties: {
-          url: { type: "string", description: "Full URL of the gated resource." }
-        },
-        required: ["url"],
-        additionalProperties: false
-      },
-      outputSchema: OPEN_OBJECT,
-      invoke: async (args) => {
-        try {
-          const plan = await client.planPayment(String(args.url));
-          if (plan == null) return { gated: false, url: String(args.url) };
-          return {
-            gated: true,
-            payable: plan.payable,
-            status: plan.status,
-            fundingHint: plan.fundingHint,
-            // One model-readable line distilling the whole plan.
-            summary: summarizePlan(plan),
-            best: plan.best ? {
-              network: plan.best.accept.network,
-              symbol: plan.best.quote.symbol,
-              amount: plan.best.quote.amountFormatted,
-              gasCoin: plan.best.cost.feeSymbol,
-              gas: plan.best.cost.feeFormatted
-            } : null,
-            options: plan.options.map((o) => ({
-              network: o.accept.network,
-              symbol: o.quote.symbol,
-              amount: o.quote.amountFormatted,
-              state: o.state,
-              blockers: o.blockers,
-              warnings: o.warnings,
-              recipientReady: o.recipient.ready
-            })),
-            // The session's time leash, present only when a time policy is configured.
-            ...plan.session ? { session: plan.session } : {}
-          };
-        } catch (err) {
-          return toToolError(err);
-        }
-      }
-    },
-    {
-      name: "piprail_pay_request",
-      description: "Fetch an x402 payment-gated URL, automatically making the required payment if needed (subject to the spend policy + approval hook). Pays whichever rail the client is configured for \u2014 PipRail's backendless on-chain rail, or, when enabled, the standard `exact` rail (where the buyer signs and the server settles, so no buyer gas). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
-      annotations: {
-        title: "Pay an x402 request",
-        readOnlyHint: false,
-        // this is the one tool that MOVES FUNDS
-        destructiveHint: true,
-        // a payment is value-moving and not reversible
-        idempotentHint: false,
-        // paying twice = two payments
-        openWorldHint: true
-        // fetches a URL and settles a payment
-      },
-      parameters: {
-        type: "object",
-        properties: {
-          url: { type: "string", description: "Full URL to fetch." },
-          method: { type: "string", description: "HTTP method, default 'GET'." },
-          body: {
-            type: ["object", "string"],
-            description: "Optional request body for POST/PUT (a JSON object or a string)."
-          }
-        },
-        required: ["url"],
-        additionalProperties: false
-      },
-      invoke: async (args) => {
-        const url = String(args.url);
-        const method = (args.method ? String(args.method) : "GET").toUpperCase();
-        try {
-          let res;
-          if (method === "GET") {
-            res = await client.get(url);
-          } else {
-            const headers = {};
-            let body;
-            if (args.body !== void 0 && args.body !== null) {
-              if (typeof args.body === "string") {
-                body = args.body;
-              } else {
-                body = JSON.stringify(args.body);
-                headers["content-type"] = "application/json";
-              }
-            }
-            res = await client.fetch(url, { method, headers, body });
-          }
-          const verifiable = parseReceiptExtension(res);
-          return {
-            status: res.status,
-            ok: res.ok,
-            body: await readBody(res),
-            receipt: parseReceipt(res),
-            ...verifiable ? { verifiableReceipt: { ...verifiable, resource: { url } } } : {}
-          };
-        } catch (err) {
-          if (err instanceof PipRailError) {
-            const out = {
-              ok: false,
-              code: err.code,
-              reason: err.message,
-              explain: explainDecline(err)
-            };
-            if (err instanceof PaymentDeclinedError) {
-              out.declined = true;
-              if (err.reasonCode) out.reasonCode = err.reasonCode;
-            }
-            const ref = err.ref;
-            if (typeof ref === "string") out.ref = ref;
-            return out;
-          }
-          throw err;
-        }
-      }
-    },
-    {
-      name: "piprail_register",
-      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted. NOTE: index/agent payers are overwhelmingly standard `exact` clients \u2014 a default onchain-proof-only gate gets listed but they cannot pay it, so add an `exact` rail (and set the gate's `discovery` option, required for x402scan) to be usefully discoverable AND payable.",
-      annotations: {
-        title: "Register an x402 endpoint",
-        readOnlyHint: false,
-        // writes a listing to an external index
-        destructiveHint: false,
-        // adds a listing; nothing is destroyed and no funds move
-        openWorldHint: true
-        // posts to external indexes (402 Index)
-        // idempotentHint intentionally omitted — index dedup behaviour isn't guaranteed.
-      },
-      parameters: {
-        type: "object",
-        properties: {
-          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. Pack the words agents will search for INTO this text \u2014 index search is literal, so a keyword that isn't in the name/description won't be found."
-          },
-          category: { type: "string", description: "A category, e.g. 'ai', 'finance', 'data' \u2014 the top findability field (most listings have none)." },
-          tags: { type: "array", items: { type: "string" }, description: "Keywords; folded into the description so they're searchable." },
-          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)." },
-          provider: { type: "string", description: "Who runs the resource (provider/org name)." },
-          contactEmail: { type: "string", description: "Contact email for the listing." }
-        },
-        required: ["url"],
-        additionalProperties: false
-      },
-      invoke: async (args) => {
-        try {
-          const opts = {};
-          if (typeof args.name === "string") opts.name = args.name;
-          if (typeof args.description === "string") opts.description = args.description;
-          if (typeof args.category === "string") opts.category = args.category;
-          if (Array.isArray(args.tags)) opts.tags = args.tags.filter((t) => typeof t === "string");
-          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;
-          if (typeof args.provider === "string") opts.provider = args.provider;
-          if (typeof args.contactEmail === "string") opts.contactEmail = args.contactEmail;
-          const outcomes = await client.register(String(args.url), opts);
-          return { outcomes };
-        } catch (err) {
-          return toToolError(err);
-        }
-      }
-    },
-    {
-      name: "piprail_budget",
-      description: "Read how much of your spend budget and time leash is left \u2014 per (network, asset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much USD you can still spend across every stablecoin and chain), the payment-count leash, the session time envelope, and your spend so far. Use it in Mode A (headless) to self-check BEFORE paying, so you never discover the leash by hitting a decline. Read-only; moves no funds. NOTE: the time envelope is in-memory for THIS process; the money/count totals persist only if a spend store is configured.",
-      annotations: {
-        title: "Check remaining budget",
-        readOnlyHint: true,
-        // reads the ledger + policy; never pays
-        idempotentHint: true
-        // a pure read
-      },
-      parameters: { type: "object", properties: {}, additionalProperties: false },
-      outputSchema: OPEN_OBJECT,
-      invoke: async () => {
-        try {
-          const spent = client.spent();
-          const budget = client.budget();
-          return {
-            spent,
-            remaining: budget.byAsset,
-            grandTotal: budget.byDenom,
-            // cross-token spend cap per denomination (USD/EUR/…)
-            counts: budget.counts,
-            // payment-count leash (settled + lifetime/window caps)
-            session: budget.session,
-            policy: client.policy() ?? null,
-            // the configured leash, read back
-            report: formatSpendReport(spent)
-          };
-        } catch (err) {
-          return toToolError(err);
-        }
-      }
-    },
-    {
-      name: "piprail_guide",
-      description: "Read the PipRail agent contract \u2014 the quote \u2192 plan \u2192 pay loop, how to read a refusal (and which declines are TERMINAL), the never-re-pay rule for broadcast-but-unconfirmed payments, and Mode A (headless) vs Mode B (supervised). Read-only; call it once if unsure how to use these tools.",
-      annotations: {
-        title: "How to use PipRail",
-        readOnlyHint: true,
-        idempotentHint: true
-      },
-      parameters: { type: "object", properties: {}, additionalProperties: false },
-      invoke: async () => ({ guide: PIPRAIL_AGENT_GUIDE })
-    },
-    {
-      name: "piprail_verify_receipt",
-      description: "Re-verify a PipRail VERIFIABLE RECEIPT against the chain \u2014 confirm a payment REALLY settled (the funds provably moved to payTo for AT LEAST the stated amount) WITHOUT trusting whoever handed you the receipt. Read-only and WALLET-FREE: pass the PipRailReceipt JSON (from a prior piprail_pay_request `verifiableReceipt`, or any third party). Returns { ok, onChain:{payTo,asset,amount,payer}, matchesClaims, ageSeconds, error? }: `ok` = the chain confirms the settlement; `onChain.payer` is RE-DERIVED from the tx and `matchesClaims:false` means the receipt forged the payer; `amount` is a verified lower bound. Pass `rpcUrl` for a chain outside the common presets.",
-      annotations: {
-        title: "Verify a payment receipt",
-        readOnlyHint: true,
-        // re-reads the chain; moves nothing, needs no wallet
-        idempotentHint: true,
-        openWorldHint: true
-        // reads an on-chain tx via RPC
-      },
-      parameters: {
-        type: "object",
-        properties: {
-          receipt: {
-            type: "object",
-            description: "The PipRailReceipt JSON ({ piprail, receipt, resource, decimals? }) to re-verify."
-          },
-          rpcUrl: {
-            type: "string",
-            description: "Optional RPC URL for the receipt's chain (required for chains outside the common presets)."
-          }
-        },
-        required: ["receipt"],
-        additionalProperties: false
-      },
-      invoke: async (args) => {
-        const receipt = args.receipt;
-        const opts = args.rpcUrl ? { rpcUrl: String(args.rpcUrl) } : void 0;
-        return await PipRailClient.verifyReceipt(receipt, opts);
-      }
-    }
-  ];
-}
-
-// src/classify.ts
-function classifyChallenge(challenge, opts) {
-  try {
-    const accepts = Array.isArray(challenge?.accepts) ? challenge.accepts : [];
-    const network = opts?.network;
-    const schemes = opts?.schemes ?? [];
-    const offeredSchemes = [
-      ...new Set(accepts.map((a) => a?.scheme).filter((s) => s != null))
-    ];
-    const offeredNetworks = [...new Set(accepts.map((a) => a?.network).filter((n) => n != null))];
-    const onClientChain = accepts.some((a) => a?.network === network);
-    const payableScheme = accepts.some(
-      (a) => a?.network === network && schemes.includes(a?.scheme)
-    );
-    const verdict = accepts.length === 0 ? "NO_RAIL" : payableScheme ? "PAYABLE_RAIL" : onClientChain ? "UNPAYABLE_SCHEME" : "WRONG_CHAIN";
-    return { onClientChain, payableScheme, offeredSchemes, offeredNetworks, verdict };
-  } catch {
-    return {
-      onClientChain: false,
-      payableScheme: false,
-      offeredSchemes: [],
-      offeredNetworks: [],
-      verdict: "NO_RAIL"
-    };
-  }
-}
-
-// src/discovery.ts
-var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
-var POWERED_BY = "PipRail x402 | https://piprail.com";
-function discoveryHeaders(opts = {}) {
-  return {
-    link: '</openapi.json>; rel="service-desc", </.well-known/x402>; rel="x402-discovery"',
-    ...opts.attribution === false ? {} : { "x-powered-by": POWERED_BY }
-  };
-}
-function buildBazaarExtension(descriptor = {}) {
-  const method = (descriptor.method ?? "GET").toUpperCase();
-  const queryParams = descriptor.queryParams ?? {};
-  return {
-    info: {
-      input: { type: "http", method, queryParams },
-      output: descriptor.output ?? { type: "json" }
-    },
-    schema: {
-      $schema: "https://json-schema.org/draft/2020-12/schema",
-      type: "object",
-      properties: {
-        input: {
-          type: "object",
-          properties: {
-            type: { type: "string", const: "http" },
-            method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"] },
-            queryParams: { type: "object", properties: queryParams, additionalProperties: false }
-          },
-          required: ["type", "method"],
-          additionalProperties: false
-        }
-      },
-      required: ["input"]
-    }
-  };
-}
-function pathOf(url) {
-  try {
-    return new URL(url).pathname || "/";
-  } catch {
-    return url.startsWith("/") ? url : `/${url}`;
-  }
-}
-function buildOpenApi(input) {
-  assertResourceList(input?.resources, "buildOpenApi");
-  const paths = {};
-  for (const r of input.resources) {
-    const path = pathOf(r.url);
-    const method = (r.method ?? "GET").toLowerCase();
-    const op = {
-      ...r.description ? { summary: r.description } : {},
-      responses: {
-        "200": { description: "Paid \u2014 the resource." },
-        "402": { description: "Payment required (x402)." }
-      },
-      "x-payment-info": {
-        x402Version: 2,
-        accepts: r.accepts
-      }
-    };
-    paths[path] = { ...paths[path] ?? {}, [method]: op };
-  }
-  return {
-    openapi: "3.1.0",
-    info: { title: input.title ?? "PipRail x402 resources", version: input.version ?? "1.0.0" },
-    servers: [{ url: input.origin }],
-    paths,
-    // "Built with @piprail/sdk" — default on (opt out with attribution:false). At the
-    // document ROOT so `info` stays exactly { title, version }.
-    ...input.attribution === false ? {} : { "x-generator": GENERATOR },
-    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { "x-agentcash-provenance": { ownershipProofs: input.ownershipProofs } } : {}
-  };
-}
-function buildWellKnownX402(input) {
-  assertResourceList(input?.resources, "buildWellKnownX402");
-  return {
-    version: 1,
-    resources: input.resources.map((r) => r.url),
-    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { ownershipProofs: input.ownershipProofs } : {}
-  };
-}
-function assertResourceList(resources, fn) {
-  if (!Array.isArray(resources)) {
-    throw new InvalidConfigError(`${fn}: \`resources\` must be an array of ResourceDescription.`);
-  }
-  resources.forEach((r, i) => {
-    if (r === null || typeof r !== "object" || typeof r.url !== "string") {
-      throw new InvalidConfigError(
-        `${fn}: resources[${i}] must be a ResourceDescription with a string \`url\`.`
-      );
-    }
-  });
-}
-function buildWellKnownX402Manifest(input) {
-  assertResourceList(input?.resources, "buildWellKnownX402Manifest");
-  const lastUpdated = typeof input.lastUpdated === "number" && Number.isFinite(input.lastUpdated) ? input.lastUpdated : Math.floor(Date.now() / 1e3);
-  return {
-    x402Version: 2,
-    lastUpdated,
-    items: input.resources.map((r) => ({
-      resource: {
-        url: r.url,
-        ...r.description ? { description: r.description } : {},
-        ...r.mimeType ? { mimeType: r.mimeType } : {}
+function buildWellKnownX402Manifest(input) {
+  assertResourceList(input?.resources, "buildWellKnownX402Manifest");
+  const lastUpdated = typeof input.lastUpdated === "number" && Number.isFinite(input.lastUpdated) ? input.lastUpdated : Math.floor(Date.now() / 1e3);
+  return {
+    x402Version: 2,
+    lastUpdated,
+    items: input.resources.map((r) => ({
+      resource: {
+        url: r.url,
+        ...r.description ? { description: r.description } : {},
+        ...r.mimeType ? { mimeType: r.mimeType } : {}
       },
       type: "http",
       accepts: r.accepts,
@@ -5506,10 +6101,19 @@ async function post(url, body, headers) {
 }
 async function settleViaFacilitator(input) {
   const base2 = input.url.replace(/\/+$/, "");
+  const v2 = input.x402Version >= 2;
   const body = {
     x402Version: input.x402Version,
     paymentPayload: input.paymentPayload,
-    paymentRequirements: input.paymentRequirements
+    paymentRequirements: input.paymentRequirements,
+    ...v2 ? {
+      accepted: input.paymentRequirements,
+      resource: {
+        url: input.resource?.url || "https://piprail.com/x402/resource",
+        description: input.resource?.description || "Paid resource",
+        mimeType: input.resource?.mimeType || "application/json"
+      }
+    } : {}
   };
   const auth = input.authHeaders ? await input.authHeaders() : {};
   let verify;
@@ -5775,6 +6379,13 @@ var KNOWN_FACILITATORS = {
       schemes: ["exact"],
       settles: ["eip3009"],
       note: "Dexter: keyless, sponsors gas (no floor hit at $0.001 here). LIVE-settled on Avalanche 2026-06-18 (tx 0xb2263e9a4ea3917eee6acabcb454d42a50264fdd69a0781ed8fcaec5590e264b)."
+    },
+    {
+      url: "https://facilitator.ultravioletadao.xyz",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["eip3009"],
+      note: "Ultravioleta DAO: keyless, 100% gas-sponsored (Avalanche native USDC EIP-3009). LIVE-settled on Avalanche 2026-09-07 (tx 0xe9a88e4fa978a16599b6188444d87ea63d43122e5fad16493568c2a596a79436): the buyer held ZERO AVAX and the payment still landed, replay rejected."
     }
   ],
   // Sei (eip155:1329) — PayAI (the only keyless facilitator that lists Sei).
@@ -5813,6 +6424,27 @@ var KNOWN_FACILITATORS = {
       note: "GoPlausible: keyless, 100% gas-sponsored (Algorand USDCa, atomic-group fee pooling; both buyer AND merchant pay 0 ALGO). LIVE-settled on Algorand mainnet 2026-06-17 (tx PDVDVRFGJAG2K6AJ7L26OTSCSRL7AURVKEX4D4KHBAOLNSCYENXA). The only keyless Algorand x402 facilitator."
     }
   ],
+  // Robinhood Chain (eip155:4663) — the tokenized-equity Arbitrum Orbit L2, mainnet since
+  // 2026-07-01. Both facilitators settle the `exact` rail in USDG (Paxos Global Dollar), the
+  // asset the chain's own markets quote against; the address below matched our on-chain read
+  // and Paxos's published list exactly. USDG is EIP-3009 AND EIP-2612 (verified on-chain
+  // 2026-09-08), so the gasless rail is real rather than inferred from the chain being an L2.
+  "eip155:4663": [
+    {
+      url: "https://facilitator.ultravioletadao.xyz",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["eip3009"],
+      note: "Ultravioleta DAO: keyless, 100% gas-sponsored (Robinhood USDG EIP-3009). LIVE-settled on Robinhood mainnet 2026-09-08 (tx 0x35361e5713918e4ca76c8cf9c25fe118d6473b36db19cde3e00ed2f43f990a88): buyer AND merchant both paid 0 ETH, replay rejected."
+    },
+    {
+      url: "https://x402.dexter.cash",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["permit2"],
+      note: 'Dexter: keyless, gas-sponsored. Robinhood USDG (EIP-712 domain name "Global Dollar" version "1", which matches the on-chain DOMAIN_SEPARATOR we recomputed). Enforces a ~$0.0066 dynamic floor (minPaymentAmountAtomic 6554), so a sub-cent payment is rejected. LIVE-settled on Robinhood mainnet 2026-09-08 (tx 0x1ba66e3dfd60e1d32fe4e38b68368a064a20b57858d6311feb08b4d0ba988d99): buyer and merchant paid 0 ETH, replay rejected. A 2nd keyless Robinhood facilitator (failover for UVD).'
+    }
+  ],
   // Solana (mainnet-beta). Keyless fee-payer sponsors for the SVM exact rail, each LIVE-settled
   // by us (a real SPL TransferChecked, buyer paid zero SOL) on the dated day — beyond a /supported
   // read. Daydreams + Questflow are intentionally ABSENT: their /supported is public but /verify
@@ -5839,18 +6471,26 @@ var KNOWN_FACILITATORS = {
       settles: ["svm"],
       note: "GoPlausible: keyless fee-payer sponsor (Solana SPL SVM). LIVE-settled on Solana mainnet 2026-09-06 (tx 3DEGg6Lue8471meBH8hbLxV1bLmZGKvmvmSY3tjg7tQFnxzE9GQXUXokjQnZgTqaEU4SaXuY9F7v3m7JsX5xDgrZ): buyer paid 0 SOL, GoPlausible's sponsor 8a8fFNfk\u2026 paid the 10,001-lamport fee, replay rejected."
     }
+  ],
+  // NEAR (near:mainnet) — the first keyless facilitator settlement on NEAR.
+  //
+  // 🔴 A CORRECTION, kept here because the wrong conclusion was recorded for months. This entry
+  // read "DELIBERATELY UNSEEDED — UVD's /verify 400s on near:mainnet, so the listing is aspirational,
+  // not settle-capable (2026-06-18)". That was OUR bug, not theirs. The 400 was
+  // `data did not match any variant of untagged enum VerifyRequestEnvelope`: PipRail sent an x402 v2
+  // body carrying only the v1 `paymentRequirements` key, and a strict v2 facilitator needs `accepted`
+  // and `resource` at the root. We read a deserialization error as a missing chain implementation.
+  // Fixed in facilitator.ts (a v2 body now carries both spellings); NEAR settled first time after.
+  // The lesson: a 400 from a facilitator is a claim about the REQUEST until you have read its body.
+  "near:mainnet": [
+    {
+      url: "https://facilitator.ultravioletadao.xyz",
+      keyless: true,
+      schemes: ["exact"],
+      settles: ["near"],
+      note: "Ultravioleta DAO: keyless fee-payer sponsor (NEAR NEP-141 USDC, NEP-366 meta-transaction). LIVE-settled on NEAR mainnet 2026-09-07 (tx 8pVe4oeykCT2WpCwToNbkxjdgSvwNNtJUrGezDCHKDda): buyer paid 0 NEAR, replay rejected. The first keyless x402 facilitator settlement on NEAR."
+    }
   ]
-  // NEAR (near:mainnet) — DELIBERATELY UNSEEDED: no x402 facilitator settles NEAR yet.
-  // The NEAR `exact` BUYER payload PipRail builds (drivers/near/exact.ts) is LIVE-PROVEN on mainnet —
-  // a real NEP-366 meta-transaction settles a USDC/USDT ft_transfer gaslessly (buyer 0 NEAR, single-use
-  // via the access-key nonce; relay txs CMnQJzrLvwk… USDT + BCCnVHbSCMY… USDC, 2026-06-18). What's
-  // missing is the FACILITATOR side: the public x402-rs (which Ultravioleta DAO runs) has NO NEAR chain
-  // crate (only eip155/solana/aptos), and UVD's `/verify` 400s on a near:mainnet request even though its
-  // `/supported` ADVERTISES `near:mainnet` + feePayer `uvd-facilitator.near` — i.e. the listing is
-  // aspirational, not settle-capable (verified 2026-06-18). So `exact: true` must NOT auto-pick a NEAR
-  // facilitator. Seed here ONLY after a real keyless settle through a facilitator that actually
-  // implements scheme_exact_near.md (THE RULE). Merchants can still pass an explicit
-  // `exact: { settle: { facilitator } }` for any facilitator they've confirmed settles near:mainnet.
 };
 function knownFacilitatorsFor(network) {
   return KNOWN_FACILITATORS[network] ?? [];
@@ -6225,520 +6865,1354 @@ function createPaymentGate(options) {
       amountFormatted = formatUnits(BigInt(receipt.amount), spec.decimals);
     } catch {
     }
-    return {
-      ...receipt,
-      decimals: spec.decimals,
-      ...spec.symbol ? { symbol: spec.symbol } : {},
-      amountFormatted,
-      idempotencyKey: receipt.transaction
-    };
-  }
-  function reportOnPaidError(error, receipt) {
-    if (!options.onPaidError) return;
-    try {
-      options.onPaidError(error, receipt);
-    } catch {
+    return {
+      ...receipt,
+      decimals: spec.decimals,
+      ...spec.symbol ? { symbol: spec.symbol } : {},
+      amountFormatted,
+      idempotencyKey: receipt.transaction
+    };
+  }
+  function reportOnPaidError(error, receipt) {
+    if (!options.onPaidError) return;
+    try {
+      options.onPaidError(error, receipt);
+    } catch {
+    }
+  }
+  function fireOnPaid(receipt) {
+    if (!options.onPaid) return;
+    let outcome;
+    try {
+      outcome = options.onPaid(receipt);
+    } catch (err) {
+      reportOnPaidError(err, receipt);
+      return;
+    }
+    if (outcome != null && typeof outcome.then === "function") {
+      return Promise.resolve(outcome).catch((err) => reportOnPaidError(err, receipt));
+    }
+  }
+  async function deliverOnPaid(spec, receipt) {
+    const paid = enrichReceipt(spec, receipt);
+    if (options.awaitOnPaid) await fireOnPaid(paid);
+    else void fireOnPaid(paid);
+  }
+  async function buildPaidResult(spec, receipt, nonce) {
+    if (!receiptsOn) {
+      return { kind: "paid", receipt, receiptHeader: buildReceiptHeader(receipt) };
+    }
+    try {
+      const stamped = {
+        ...receipt,
+        ...nonce ? { nonce } : {},
+        // §5.3: a suppressed tx is the empty string on the wire, never a missing key.
+        ...receiptIncludeTxHash ? {} : { transaction: "" }
+      };
+      const attestation = await maybeSignAttestation(spec, stamped);
+      const extensions = buildReceiptExtension({
+        receipt: stamped,
+        resource: { url: receiptResourceUrl },
+        decimals: spec.decimals,
+        ...attestation ? { attestation } : {}
+      });
+      return { kind: "paid", receipt: stamped, receiptHeader: buildReceiptHeader(stamped, extensions) };
+    } catch {
+      return { kind: "paid", receipt, receiptHeader: buildReceiptHeader(receipt) };
+    }
+  }
+  async function maybeSignAttestation(spec, stamped) {
+    if (attestJws) {
+      warnAttestDegrade("JWS attestation is not yet implemented (R3)");
+      return void 0;
+    }
+    if (attestWallet === void 0) return void 0;
+    if (typeof spec.net.signReceipt !== "function") {
+      warnAttestDegrade(`is EVM-only; the ${spec.net.family} rail can't sign an EIP-712 attestation`);
+      return void 0;
+    }
+    try {
+      const wallet = spec.net.bindWallet(attestWallet);
+      return await spec.net.signReceipt(wallet, {
+        payTo: spec.payTo,
+        network: spec.net.network,
+        resourceUrl: receiptResourceUrl,
+        payer: stamped.payer,
+        issuedAt: nowUnixSeconds(stamped.verifiedAt),
+        // §5.3: the signed message carries the empty string for a suppressed tx, never omitted.
+        transaction: receiptIncludeTxHash ? stamped.transaction : ""
+      });
+    } catch {
+      warnAttestDegrade("signing failed");
+      return void 0;
+    }
+  }
+  function reportOnFailedError(error, failure) {
+    if (!options.onFailedError) return;
+    try {
+      options.onFailedError(error, failure);
+    } catch {
+    }
+  }
+  function fireOnFailed(failure) {
+    if (!options.onFailed) return;
+    let outcome;
+    try {
+      outcome = options.onFailed(failure);
+    } catch (err) {
+      reportOnFailedError(err, failure);
+      return;
+    }
+    if (outcome != null && typeof outcome.then === "function") {
+      return Promise.resolve(outcome).catch((err) => reportOnFailedError(err, failure));
+    }
+  }
+  async function deliverOnFailed(result) {
+    const code = result.error;
+    const failure = { code, detail: result.detail, transient: TRANSIENT_VERIFY_CODES.has(code) };
+    if (options.awaitOnFailed) await fireOnFailed(failure);
+    else void fireOnFailed(failure);
+  }
+  function railExtra(full) {
+    const out = {};
+    for (const k of ["assetTransferMethod", "facilitatorAddress", "name", "version"]) {
+      const v = full[k];
+      if (v !== void 0 && v !== "") out[k] = v;
+    }
+    return Object.keys(out).length > 0 ? { extra: out } : {};
+  }
+  async function describe(resourceUrl = "") {
+    const specs = await ready();
+    const accepts = [];
+    for (const s of specs) {
+      const base2 = {
+        network: s.net.network,
+        asset: s.asset,
+        payTo: s.payTo,
+        amount: s.amountBase.toString(),
+        amountFormatted: s.amountFormatted,
+        decimals: s.decimals,
+        maxTimeoutSeconds,
+        ...s.symbol ? { symbol: s.symbol } : {}
+      };
+      if (s.exact) accepts.push({ scheme: "exact", ...base2, ...railExtra(buildExactAccept(s).extra ?? {}) });
+      if (s.upto) accepts.push({ scheme: "upto", ...base2, ...railExtra(buildUptoAccept(s).extra ?? {}) });
+      accepts.push({ scheme: "onchain-proof", ...base2 });
+    }
+    return {
+      url: resourceUrl,
+      ...options.description ? { description: options.description } : {},
+      ...options.mimeType ? { mimeType: options.mimeType } : {},
+      accepts
+    };
+  }
+  async function verifyOnchainProof(sig) {
+    const specs = await ready();
+    const spec = specs.find(
+      (s) => normalizeNetwork(s.net.network) === normalizeNetwork(sig.accepted.network) && s.asset === sig.accepted.asset
+    );
+    if (!spec) {
+      return rejection(
+        "transfer_not_found",
+        `Proof claims ${sig.accepted.asset} on ${sig.accepted.network}, which this resource doesn't accept (offered: ${specs.map((s) => `${s.asset}@${s.net.network}`).join(", ")}).`
+      );
+    }
+    const ref = typeof sig.payload.txHash === "string" ? sig.payload.txHash.trim() : sig.payload.txHash;
+    if (await claimTx(ref)) return rejection("tx_already_used", `Proof ${ref} was already redeemed.`);
+    let result;
+    try {
+      result = await spec.net.verify(ref, buildAccept(spec, sig.payload.nonce));
+    } catch (err) {
+      await settleTx(ref, false);
+      throw err;
+    }
+    if (!result.ok) {
+      await settleTx(ref, false);
+      return rejection(result.error, result.detail);
+    }
+    const verified = result.receipt.transaction;
+    if (verified && verified !== ref) {
+      if (await claimTx(verified)) {
+        await settleTx(ref, false);
+        return rejection("tx_already_used", `Payment ${verified} was already redeemed.`);
+      }
+      await settleTx(ref, false);
+      await settleTx(verified, true);
+    } else {
+      await settleTx(ref, true);
+    }
+    await deliverOnPaid(spec, result.receipt);
+    return await buildPaidResult(spec, result.receipt, sig.payload.nonce);
+  }
+  async function verifyExact(exact) {
+    const specs = await ready();
+    const exactSpecs = specs.filter((s) => s.exact);
+    if (exactSpecs.length === 0) {
+      return rejection("transfer_not_found", "This resource offers no standard `exact` rail.");
+    }
+    const isCaip = exact.network.includes(":");
+    const wantExactNet = normalizeNetwork(exact.network);
+    let candidates = isCaip ? exactSpecs.filter((s) => normalizeNetwork(s.net.network) === wantExactNet) : exactSpecs;
+    if (exact.asset) {
+      candidates = candidates.filter((s) => s.asset.toLowerCase() === exact.asset.toLowerCase());
+    }
+    let spec = candidates[0];
+    if (!isCaip && !exact.asset && exactSpecs.length > 1) spec = void 0;
+    if (!spec && !isCaip && !exact.asset && exactSpecs.length === 1) spec = exactSpecs[0];
+    if (!spec || !spec.exact) {
+      return rejection(
+        "transfer_not_found",
+        `No \`exact\` rail offered for ${exact.network}${exact.asset ? `/${exact.asset}` : ""} (offered: ${exactSpecs.map((s) => `${s.asset}@${s.net.network}`).join(", ")}).`
+      );
+    }
+    let nonce;
+    let evmAuth = null;
+    if ("senderAuth" in exact.payload && "transaction" in exact.payload) {
+      nonce = [exact.payload.transaction, exact.payload.senderAuth].map((t) => {
+        try {
+          return Buffer.from(t, "base64").toString("base64");
+        } catch {
+          return t;
+        }
+      }).join("|");
+    } else if ("transaction" in exact.payload) {
+      try {
+        nonce = Buffer.from(exact.payload.transaction, "base64").toString("base64");
+      } catch {
+        nonce = exact.payload.transaction;
+      }
+    } else if ("paymentGroup" in exact.payload) {
+      nonce = exact.payload.paymentGroup.map((t) => {
+        try {
+          return Buffer.from(t, "base64").toString("base64");
+        } catch {
+          return t;
+        }
+      }).join("|");
+    } else if ("signedDelegateAction" in exact.payload) {
+      try {
+        nonce = Buffer.from(exact.payload.signedDelegateAction, "base64").toString("base64");
+      } catch {
+        nonce = exact.payload.signedDelegateAction;
+      }
+    } else if ("signedTxBlob" in exact.payload) {
+      nonce = exact.payload.signedTxBlob.trim().toUpperCase();
+    } else if ("permit2Authorization" in exact.payload) {
+      evmAuth = exact.payload.permit2Authorization;
+      nonce = evmAuth.nonce;
+    } else {
+      evmAuth = exact.payload.authorization;
+      nonce = evmAuth.nonce;
     }
-  }
-  function fireOnPaid(receipt) {
-    if (!options.onPaid) return;
-    let outcome;
+    if (await claimTx(nonce)) {
+      return rejection("tx_already_used", `Authorization ${evmAuth ? `nonce ${nonce}` : "transaction"} was already redeemed.`);
+    }
+    const accept = buildExactAccept(spec);
+    const mode = spec.exact.mode;
+    let result;
     try {
-      outcome = options.onPaid(receipt);
+      if (mode.kind === "self") {
+        result = await spec.net.settleExactSelf({ relayer: mode.relayer, payload: exact.payload, accept });
+      } else {
+        const ftMethod = accept.extra?.assetTransferMethod;
+        const needsFeePayer = ftMethod === "svm" || ftMethod === "algorand" || ftMethod === "aptos" || ftMethod === "near";
+        if (needsFeePayer && !accept.extra?.feePayer) {
+          throw new SettlementError(
+            `exact settle: the ${ftMethod} facilitator rail is missing extra.feePayer (the gas sponsor) \u2014 cannot settle.`
+          );
+        }
+        result = await settleViaFacilitator({
+          url: mode.url,
+          ...mode.authHeaders ? { authHeaders: mode.authHeaders } : {},
+          // PipRail always builds a v2-shaped paymentRequirements (CAIP-2 network + `amount`),
+          // so force x402Version:2 — echoing a v1 client's version here would hand the facilitator
+          // a self-inconsistent request (v1 envelope, v2 requirements). The inner payload is
+          // byte-identical across versions, so forwarding it verbatim is fine.
+          x402Version: 2,
+          paymentPayload: exact.raw,
+          paymentRequirements: {
+            scheme: "exact",
+            network: accept.network,
+            asset: accept.asset,
+            amount: accept.amount,
+            payTo: accept.payTo,
+            maxTimeoutSeconds: accept.maxTimeoutSeconds,
+            extra: needsFeePayer ? { feePayer: accept.extra.feePayer } : { name: accept.extra?.name ?? "", version: accept.extra?.version ?? "" }
+          },
+          receipt: { network: accept.network, asset: accept.asset, payTo: accept.payTo, amount: accept.amount },
+          // From the merchant's own config, never the client's echo — same rule as `accept`.
+          resource: {
+            ...receiptResourceUrl ? { url: receiptResourceUrl } : {},
+            ...options.description ? { description: options.description } : {},
+            ...options.mimeType ? { mimeType: options.mimeType } : {}
+          },
+          // The buyer address, for the receipt's `payer` fallback. EVM carries it in the
+          // authorization; SVM doesn't (the facilitator returns the settled payer) → omit it.
+          ...evmAuth ? { payerHint: evmAuth.from } : {}
+        });
+      }
     } catch (err) {
-      reportOnPaidError(err, receipt);
-      return;
+      await settleTx(nonce, false);
+      throw err;
     }
-    if (outcome != null && typeof outcome.then === "function") {
-      return Promise.resolve(outcome).catch((err) => reportOnPaidError(err, receipt));
+    if (!result.ok) {
+      await settleTx(nonce, false);
+      return rejection(result.error, result.detail);
     }
+    await settleTx(nonce, true);
+    await deliverOnPaid(spec, result.receipt);
+    return await buildPaidResult(spec, result.receipt);
   }
-  async function deliverOnPaid(spec, receipt) {
-    const paid = enrichReceipt(spec, receipt);
-    if (options.awaitOnPaid) await fireOnPaid(paid);
-    else void fireOnPaid(paid);
-  }
-  async function buildPaidResult(spec, receipt, nonce) {
-    if (!receiptsOn) {
-      return { kind: "paid", receipt, receiptHeader: buildReceiptHeader(receipt) };
-    }
+  function resolveSettleAmount(raw, maxAmount, decimals) {
+    if (typeof raw === "bigint") return raw < 0n ? null : raw;
+    const s = raw.trim();
+    if (s.length === 0) return null;
     try {
-      const stamped = {
-        ...receipt,
-        ...nonce ? { nonce } : {},
-        // §5.3: a suppressed tx is the empty string on the wire, never a missing key.
-        ...receiptIncludeTxHash ? {} : { transaction: "" }
-      };
-      const attestation = await maybeSignAttestation(spec, stamped);
-      const extensions = buildReceiptExtension({
-        receipt: stamped,
-        resource: { url: receiptResourceUrl },
-        decimals: spec.decimals,
-        ...attestation ? { attestation } : {}
-      });
-      return { kind: "paid", receipt: stamped, receiptHeader: buildReceiptHeader(stamped, extensions) };
+      if (s.endsWith("%")) {
+        const pct = s.slice(0, -1).trim();
+        if (!/^\d+(\.\d+)?$/.test(pct)) return null;
+        const pctScaled = floorUnits(pct, 4);
+        return maxAmount * pctScaled / (100n * 10n ** 4n);
+      }
+      if (s.startsWith("$")) {
+        const amt = s.slice(1).trim();
+        return floorUnits(amt, decimals);
+      }
+      if (/^\d+$/.test(s)) return BigInt(s);
+      return floorUnits(s, decimals);
     } catch {
-      return { kind: "paid", receipt, receiptHeader: buildReceiptHeader(receipt) };
+      return null;
     }
   }
-  async function maybeSignAttestation(spec, stamped) {
-    if (attestJws) {
-      warnAttestDegrade("JWS attestation is not yet implemented (R3)");
-      return void 0;
+  async function verifyUpto(upto) {
+    const specs = await ready();
+    const uptoSpecs = specs.filter((s) => s.upto);
+    if (uptoSpecs.length === 0) {
+      return rejection("transfer_not_found", "This resource offers no standard `upto` (metered) rail.");
     }
-    if (attestWallet === void 0) return void 0;
-    if (typeof spec.net.signReceipt !== "function") {
-      warnAttestDegrade(`is EVM-only; the ${spec.net.family} rail can't sign an EIP-712 attestation`);
-      return void 0;
+    const isCaip = upto.network.includes(":");
+    const wantUptoNet = normalizeNetwork(upto.network);
+    let candidates = isCaip ? uptoSpecs.filter((s) => normalizeNetwork(s.net.network) === wantUptoNet) : uptoSpecs;
+    if (upto.asset) {
+      candidates = candidates.filter((s) => s.asset.toLowerCase() === upto.asset.toLowerCase());
     }
-    try {
-      const wallet = spec.net.bindWallet(attestWallet);
-      return await spec.net.signReceipt(wallet, {
-        payTo: spec.payTo,
-        network: spec.net.network,
-        resourceUrl: receiptResourceUrl,
-        payer: stamped.payer,
-        issuedAt: nowUnixSeconds(stamped.verifiedAt),
-        // §5.3: the signed message carries the empty string for a suppressed tx, never omitted.
-        transaction: receiptIncludeTxHash ? stamped.transaction : ""
-      });
-    } catch {
-      warnAttestDegrade("signing failed");
-      return void 0;
+    let spec = candidates[0];
+    if (!isCaip && !upto.asset && uptoSpecs.length > 1) spec = void 0;
+    if (!spec && !isCaip && !upto.asset && uptoSpecs.length === 1) spec = uptoSpecs[0];
+    if (!spec || !spec.upto) {
+      return rejection(
+        "transfer_not_found",
+        `No \`upto\` rail offered for ${upto.network}${upto.asset ? `/${upto.asset}` : ""} (offered: ${uptoSpecs.map((s) => `${s.asset}@${s.net.network}`).join(", ")}).`
+      );
     }
-  }
-  function reportOnFailedError(error, failure) {
-    if (!options.onFailedError) return;
-    try {
-      options.onFailedError(error, failure);
-    } catch {
+    const nonce = upto.payload.permit2Authorization.nonce;
+    if (await claimTx(nonce)) {
+      return rejection("tx_already_used", `Authorization nonce ${nonce} was already redeemed.`);
     }
-  }
-  function fireOnFailed(failure) {
-    if (!options.onFailed) return;
-    let outcome;
+    const accept = buildUptoAccept(spec);
+    const relayer = spec.upto.relayer;
+    let result;
     try {
-      outcome = options.onFailed(failure);
+      const rawAmount = await options.upto.settleAmount({
+        maxAmount: spec.amountBase,
+        asset: spec.asset,
+        network: spec.net.network,
+        decimals: spec.decimals,
+        ...upto.raw ? { request: upto.raw } : {}
+      });
+      const settleAmount = resolveSettleAmount(rawAmount, spec.amountBase, spec.decimals);
+      if (settleAmount === null) {
+        await settleTx(nonce, false);
+        return rejection(
+          "upto_settle_exceeds_max",
+          `The settleAmount callback returned an unparseable amount (${String(rawAmount)}). Return a bigint, a raw/"NN%"/"$X" string, or 0.`
+        );
+      }
+      result = await spec.net.settleUptoSelf({ relayer, payload: upto.payload, accept, settleAmount });
     } catch (err) {
-      reportOnFailedError(err, failure);
-      return;
+      await settleTx(nonce, false);
+      if (err instanceof SettlementError) throw err;
+      return rejection(
+        "tx_reverted",
+        `upto: metering/settle failed (${err instanceof Error ? err.message : String(err)}).`
+      );
     }
-    if (outcome != null && typeof outcome.then === "function") {
-      return Promise.resolve(outcome).catch((err) => reportOnFailedError(err, failure));
+    if (!result.ok) {
+      await settleTx(nonce, false);
+      return rejection(result.error, result.detail);
     }
+    await settleTx(nonce, true);
+    await deliverOnPaid(spec, result.receipt);
+    return await buildPaidResult(spec, result.receipt);
   }
-  async function deliverOnFailed(result) {
-    const code = result.error;
-    const failure = { code, detail: result.detail, transient: TRANSIENT_VERIFY_CODES.has(code) };
-    if (options.awaitOnFailed) await fireOnFailed(failure);
-    else void fireOnFailed(failure);
+  async function verify(paymentSignature) {
+    const raw = normaliseHeader(paymentSignature);
+    const result = await resolveVerdictObject(raw === void 0 ? void 0 : decodeBase64Json(raw));
+    if (result.kind === "invalid") await deliverOnFailed(result);
+    return result;
+  }
+  async function verifyObject(payload) {
+    const result = await resolveVerdictObject(payload);
+    if (result.kind === "invalid") await deliverOnFailed(result);
+    return result;
   }
-  function railExtra(full) {
-    const out = {};
-    for (const k of ["assetTransferMethod", "facilitatorAddress", "name", "version"]) {
-      const v = full[k];
-      if (v !== void 0 && v !== "") out[k] = v;
+  async function routeVerdictObject(obj) {
+    if (obj === void 0 || obj === null) return asChallenge();
+    const sig = parseSignatureObject(obj);
+    if (sig && sig.accepted && typeof sig.accepted.network === "string" && typeof sig.accepted.asset === "string") {
+      return verifyOnchainProof(sig);
     }
-    return Object.keys(out).length > 0 ? { extra: out } : {};
+    const upto = parseUptoObject(obj);
+    if (upto) return verifyUpto(upto);
+    const exact = parseExactObject(obj);
+    if (exact) return verifyExact(exact);
+    return asChallenge();
   }
-  async function describe(resourceUrl = "") {
-    const specs = await ready();
-    const accepts = [];
-    for (const s of specs) {
-      const base2 = {
-        network: s.net.network,
-        asset: s.asset,
-        payTo: s.payTo,
-        amount: s.amountBase.toString(),
-        amountFormatted: s.amountFormatted,
-        decimals: s.decimals,
-        maxTimeoutSeconds,
-        ...s.symbol ? { symbol: s.symbol } : {}
+  function echoPaymentIdentifier(result, id) {
+    try {
+      const decoded = decodeBase64Json(result.receiptHeader);
+      if (!decoded) return result;
+      const { extensions: existing, ...receiptOnly } = decoded;
+      const merged = {
+        ...existing ?? {},
+        [EXT_PAYMENT_IDENTIFIER]: { info: { required: false, id } }
       };
-      if (s.exact) accepts.push({ scheme: "exact", ...base2, ...railExtra(buildExactAccept(s).extra ?? {}) });
-      if (s.upto) accepts.push({ scheme: "upto", ...base2, ...railExtra(buildUptoAccept(s).extra ?? {}) });
-      accepts.push({ scheme: "onchain-proof", ...base2 });
+      return { ...result, receiptHeader: buildReceiptHeader(receiptOnly, merged) };
+    } catch {
+      return result;
     }
-    return {
-      url: resourceUrl,
-      ...options.description ? { description: options.description } : {},
-      ...options.mimeType ? { mimeType: options.mimeType } : {},
-      accepts
-    };
   }
-  async function verifyOnchainProof(sig) {
-    const specs = await ready();
-    const spec = specs.find(
-      (s) => normalizeNetwork(s.net.network) === normalizeNetwork(sig.accepted.network) && s.asset === sig.accepted.asset
-    );
-    if (!spec) {
+  async function resolveVerdictObject(obj) {
+    if (!options.paymentIdentifier) return routeVerdictObject(obj);
+    const id = readPaymentIdentifier(obj);
+    if (id !== null && typeof id === "object") {
+      return rejection("signature_invalid", `payment-identifier: ${id.invalid}.`);
+    }
+    if (id === null) return routeVerdictObject(obj);
+    const idKey = "pid:" + id;
+    if (await claimTx(idKey)) {
       return rejection(
-        "transfer_not_found",
-        `Proof claims ${sig.accepted.asset} on ${sig.accepted.network}, which this resource doesn't accept (offered: ${specs.map((s) => `${s.asset}@${s.net.network}`).join(", ")}).`
+        "tx_already_used",
+        `Idempotency id "${id}" is already bound to a settled payment; use a fresh id for a new payment.`
       );
     }
-    const ref = typeof sig.payload.txHash === "string" ? sig.payload.txHash.trim() : sig.payload.txHash;
-    if (await claimTx(ref)) return rejection("tx_already_used", `Proof ${ref} was already redeemed.`);
     let result;
     try {
-      result = await spec.net.verify(ref, buildAccept(spec, sig.payload.nonce));
+      result = await routeVerdictObject(obj);
     } catch (err) {
-      await settleTx(ref, false);
+      await settleTx(idKey, false);
       throw err;
     }
-    if (!result.ok) {
-      await settleTx(ref, false);
-      return rejection(result.error, result.detail);
+    await settleTx(idKey, result.kind === "paid");
+    return result.kind === "paid" ? echoPaymentIdentifier(result, id) : result;
+  }
+  async function selfTest() {
+    try {
+      const specs = await ready();
+      const warnings = [];
+      const rails = specs.map((s) => {
+        if (!s.symbol) {
+          warnings.push(
+            `${s.asset} on ${s.net.network}: custom token (no built-in symbol) \u2014 double-check the address + decimals.`
+          );
+        }
+        return {
+          network: s.net.network,
+          asset: s.asset,
+          ...s.symbol ? { symbol: s.symbol } : {},
+          decimals: s.decimals,
+          amount: s.amountFormatted,
+          payTo: s.payTo,
+          schemes: [
+            ...s.exact ? ["exact"] : [],
+            ...s.upto ? ["upto"] : [],
+            "onchain-proof"
+          ]
+        };
+      });
+      return { ok: true, rails, warnings };
+    } catch (err) {
+      return { ok: false, rails: [], warnings: [], error: err instanceof Error ? err.message : String(err) };
     }
-    const verified = result.receipt.transaction;
-    if (verified && verified !== ref) {
-      if (await claimTx(verified)) {
-        await settleTx(ref, false);
-        return rejection("tx_already_used", `Payment ${verified} was already redeemed.`);
+  }
+  return { challenge, verify, verifyObject, describe, landingPage, selfTest };
+}
+function requirePayment(options) {
+  if (options.upto) {
+    throw new class extends PipRailError {
+      code = "UNSUPPORTED_SCHEME";
+    }(
+      "requirePayment: the 'upto' (metered) rail is unsupported through the Express middleware \u2014 it settles before the route handler serves, so metered usage is unknown at settle time. Call gate.verify() directly (createPaymentGate) and meter inside settleAmount; see docs/accepting-payments/upto-rail-seller.md."
+    );
+  }
+  const gate = createPaymentGate(options);
+  return async (req, res, next) => {
+    let result;
+    try {
+      result = await gate.verify(req.headers[HEADER_SIGNATURE] ?? req.headers[HEADER_SIGNATURE_V1]);
+    } catch (err) {
+      if (err instanceof SettlementError) {
+        res.status(502);
+        res.json({
+          x402Version: 2,
+          error: "settlement_failed",
+          detail: err.message,
+          fallback: "The gasless `exact` settlement failed. This resource also accepts the `onchain-proof` scheme \u2014 retry by paying that rail yourself (you broadcast the transfer and pay the gas). It is the fallback when no facilitator can sponsor the gas."
+        });
+        return;
+      }
+      next(err);
+      return;
+    }
+    switch (result.kind) {
+      case "paid":
+        res.setHeader(HEADER_RESPONSE, result.receiptHeader);
+        res.setHeader(HEADER_RESPONSE_V1, result.receiptHeader);
+        return next();
+      case "challenge":
+        res.setHeader(HEADER_REQUIRED, result.requiredHeader);
+        res.status(result.statusCode);
+        res.json(result.challenge);
+        return;
+      case "invalid":
+        res.setHeader(HEADER_REQUIRED, result.requiredHeader);
+        res.status(result.statusCode);
+        res.json(result.challenge);
+        return;
+    }
+  };
+}
+function normaliseHeader(value) {
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+
+// src/agent.ts
+var OPEN_OBJECT = { type: "object", additionalProperties: true };
+async function readBody(res) {
+  const text = await res.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function canSwap(client) {
+  return client.canAgentSwap?.() === true && typeof client.quoteSwap === "function";
+}
+function canSell(client) {
+  return client.canAgentSell?.() === true && typeof client.address === "function";
+}
+function nonceIn(payload) {
+  if (typeof payload !== "object" || payload === null) return void 0;
+  const p = payload;
+  const inner = p.payload;
+  const fromPayload = inner && typeof inner.nonce === "string" ? inner.nonce : void 0;
+  const accepted = p.accepted;
+  const fromAccept = typeof accepted?.extra?.nonce === "string" ? accepted.extra.nonce : void 0;
+  return fromPayload ?? fromAccept;
+}
+function toToolError(err) {
+  if (!(err instanceof PipRailError)) throw err;
+  const out = {
+    ok: false,
+    code: err.code,
+    reason: err.message,
+    explain: explainDecline(err)
+  };
+  if (err instanceof PaymentDeclinedError) {
+    out.declined = true;
+    if (err.reasonCode) out.reasonCode = err.reasonCode;
+  }
+  const ref = err.ref;
+  if (typeof ref === "string") out.ref = ref;
+  return out;
+}
+function paymentTools(client) {
+  const base2 = [
+    {
+      name: "piprail_discover",
+      description: `Find x402 payment-gated resources on the OPEN indexes (a phone book of payable APIs) WITHOUT paying. Use it to answer "what can I buy?" \u2014 search by topic, then quote/plan/pay a chosen one. By default returns only resources payable on your wallet's chain (network='self'); pass 'any' for every chain. Results are cross-scheme: ALWAYS call piprail_quote_payment on a chosen resource (it re-checks the live price) before piprail_pay_request.`,
+      annotations: {
+        title: "Discover payable x402 APIs",
+        readOnlyHint: true,
+        // reads the open indexes only; never pays
+        openWorldHint: true
+        // reaches external indexes (402 Index, CDP Bazaar)
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: 'Free-text topic to search for (optional). Multi-word queries are fanned out per word and results are ranked by relevance, so "crypto price feed" finds the best matches even when no single listing contains that exact phrase.'
+          },
+          network: {
+            type: "string",
+            description: "CAIP-2 id, 'self' (your chain \u2014 default), or 'any' (all chains)."
+          },
+          category: { type: "string", description: "Keep ONLY this category, e.g. 'ai', 'finance', 'data' (strict)." },
+          asset: { type: "string", description: "Keep only resources paying in this token symbol, e.g. 'USDC'." },
+          maxPrice: { type: "number", description: "Drop results advertised above this USD price." },
+          minReliability: { type: "number", description: "Drop results below this health score (0\u2013100); unscored pass." },
+          verified: { type: "boolean", description: "Prefer verified listings (402 Index)." },
+          sort: {
+            type: "string",
+            enum: ["relevance", "reliability", "price", "uptime", "name"],
+            description: "Ordering. Default 'relevance' with a query, else first-seen."
+          },
+          limit: { type: "number", description: "Max results to fetch per index (default 20)." }
+        },
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        try {
+          const opts = {};
+          if (typeof args.query === "string") opts.query = args.query;
+          if (typeof args.network === "string") opts.network = args.network;
+          if (typeof args.category === "string") opts.category = args.category;
+          if (typeof args.asset === "string") opts.asset = args.asset;
+          if (typeof args.maxPrice === "number") opts.maxPrice = args.maxPrice;
+          if (typeof args.minReliability === "number") opts.minReliability = args.minReliability;
+          if (typeof args.verified === "boolean") opts.verified = args.verified;
+          if (typeof args.sort === "string") opts.sort = args.sort;
+          if (typeof args.limit === "number") opts.limit = args.limit;
+          const found = await client.discover(opts);
+          return {
+            count: found.length,
+            resources: found.map((r) => ({
+              resource: r.resource,
+              name: r.name,
+              description: r.description,
+              source: r.source,
+              category: r.category,
+              priceUsd: r.priceUsd,
+              reliabilityScore: r.reliabilityScore,
+              health: r.health,
+              verified: r.verified,
+              networks: [...new Set(r.rails.map((rail) => rail.network))]
+            }))
+          };
+        } catch (err) {
+          return toToolError(err);
+        }
       }
-      await settleTx(ref, false);
-      await settleTx(verified, true);
-    } else {
-      await settleTx(ref, true);
-    }
-    await deliverOnPaid(spec, result.receipt);
-    return await buildPaidResult(spec, result.receipt, sig.payload.nonce);
-  }
-  async function verifyExact(exact) {
-    const specs = await ready();
-    const exactSpecs = specs.filter((s) => s.exact);
-    if (exactSpecs.length === 0) {
-      return rejection("transfer_not_found", "This resource offers no standard `exact` rail.");
-    }
-    const isCaip = exact.network.includes(":");
-    const wantExactNet = normalizeNetwork(exact.network);
-    let candidates = isCaip ? exactSpecs.filter((s) => normalizeNetwork(s.net.network) === wantExactNet) : exactSpecs;
-    if (exact.asset) {
-      candidates = candidates.filter((s) => s.asset.toLowerCase() === exact.asset.toLowerCase());
-    }
-    let spec = candidates[0];
-    if (!isCaip && !exact.asset && exactSpecs.length > 1) spec = void 0;
-    if (!spec && !isCaip && !exact.asset && exactSpecs.length === 1) spec = exactSpecs[0];
-    if (!spec || !spec.exact) {
-      return rejection(
-        "transfer_not_found",
-        `No \`exact\` rail offered for ${exact.network}${exact.asset ? `/${exact.asset}` : ""} (offered: ${exactSpecs.map((s) => `${s.asset}@${s.net.network}`).join(", ")}).`
-      );
-    }
-    let nonce;
-    let evmAuth = null;
-    if ("senderAuth" in exact.payload && "transaction" in exact.payload) {
-      nonce = [exact.payload.transaction, exact.payload.senderAuth].map((t) => {
+    },
+    {
+      name: "piprail_quote_payment",
+      description: "Get the price of an x402 payment-gated URL WITHOUT paying. Returns the amount, token, chain, recipient, and whether it is within the spend policy. Returns { gated: false } when the URL needs no payment. Call this first to decide whether a resource is worth buying.",
+      annotations: {
+        title: "Quote an x402 price",
+        readOnlyHint: true,
+        // reads the 402 challenge; never pays
+        openWorldHint: true
+        // fetches an arbitrary URL
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Full URL of the gated resource." }
+        },
+        required: ["url"],
+        additionalProperties: false
+      },
+      outputSchema: OPEN_OBJECT,
+      invoke: async (args) => {
         try {
-          return Buffer.from(t, "base64").toString("base64");
-        } catch {
-          return t;
+          const quote = await client.quote(String(args.url));
+          return quote ? { gated: true, ...quote } : { gated: false, url: String(args.url) };
+        } catch (err) {
+          return toToolError(err);
         }
-      }).join("|");
-    } else if ("transaction" in exact.payload) {
-      try {
-        nonce = Buffer.from(exact.payload.transaction, "base64").toString("base64");
-      } catch {
-        nonce = exact.payload.transaction;
       }
-    } else if ("paymentGroup" in exact.payload) {
-      nonce = exact.payload.paymentGroup.map((t) => {
+    },
+    {
+      name: "piprail_plan_payment",
+      description: "Check whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive \u2014 across every rail the URL offers on your chain \u2014 and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.",
+      annotations: {
+        title: "Plan an x402 payment",
+        readOnlyHint: true,
+        // reads balances + the challenge; never pays
+        openWorldHint: true
+        // fetches a URL and reads chain state
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Full URL of the gated resource." }
+        },
+        required: ["url"],
+        additionalProperties: false
+      },
+      outputSchema: OPEN_OBJECT,
+      invoke: async (args) => {
         try {
-          return Buffer.from(t, "base64").toString("base64");
-        } catch {
-          return t;
+          const plan = await client.planPayment(String(args.url));
+          if (plan == null) return { gated: false, url: String(args.url) };
+          return {
+            gated: true,
+            payable: plan.payable,
+            status: plan.status,
+            fundingHint: plan.fundingHint,
+            // One model-readable line distilling the whole plan.
+            summary: summarizePlan(plan),
+            best: plan.best ? {
+              network: plan.best.accept.network,
+              symbol: plan.best.quote.symbol,
+              amount: plan.best.quote.amountFormatted,
+              gasCoin: plan.best.cost.feeSymbol,
+              gas: plan.best.cost.feeFormatted
+            } : null,
+            options: plan.options.map((o) => ({
+              network: o.accept.network,
+              symbol: o.quote.symbol,
+              amount: o.quote.amountFormatted,
+              state: o.state,
+              blockers: o.blockers,
+              warnings: o.warnings,
+              recipientReady: o.recipient.ready
+            })),
+            // The session's time leash, present only when a time policy is configured.
+            ...plan.session ? { session: plan.session } : {}
+          };
+        } catch (err) {
+          return toToolError(err);
+        }
+      }
+    },
+    {
+      name: "piprail_pay_request",
+      description: "Fetch an x402 payment-gated URL, automatically making the required payment if needed (subject to the spend policy + approval hook). Pays whichever rail the client is configured for \u2014 PipRail's backendless on-chain rail, or, when enabled, the standard `exact` rail (where the buyer signs and the server settles, so no buyer gas). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
+      annotations: {
+        title: "Pay an x402 request",
+        readOnlyHint: false,
+        // this is the one tool that MOVES FUNDS
+        destructiveHint: true,
+        // a payment is value-moving and not reversible
+        idempotentHint: false,
+        // paying twice = two payments
+        openWorldHint: true
+        // fetches a URL and settles a payment
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Full URL to fetch." },
+          method: { type: "string", description: "HTTP method, default 'GET'." },
+          body: {
+            type: ["object", "string"],
+            description: "Optional request body for POST/PUT (a JSON object or a string)."
+          }
+        },
+        required: ["url"],
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        const url = String(args.url);
+        const method = (args.method ? String(args.method) : "GET").toUpperCase();
+        try {
+          let res;
+          if (method === "GET") {
+            res = await client.get(url);
+          } else {
+            const headers = {};
+            let body;
+            if (args.body !== void 0 && args.body !== null) {
+              if (typeof args.body === "string") {
+                body = args.body;
+              } else {
+                body = JSON.stringify(args.body);
+                headers["content-type"] = "application/json";
+              }
+            }
+            res = await client.fetch(url, { method, headers, body });
+          }
+          const verifiable = parseReceiptExtension(res);
+          return {
+            status: res.status,
+            ok: res.ok,
+            body: await readBody(res),
+            receipt: parseReceipt(res),
+            ...verifiable ? { verifiableReceipt: { ...verifiable, resource: { url } } } : {}
+          };
+        } catch (err) {
+          if (err instanceof PipRailError) {
+            const out = {
+              ok: false,
+              code: err.code,
+              reason: err.message,
+              explain: explainDecline(err)
+            };
+            if (err instanceof PaymentDeclinedError) {
+              out.declined = true;
+              if (err.reasonCode) out.reasonCode = err.reasonCode;
+            }
+            const ref = err.ref;
+            if (typeof ref === "string") out.ref = ref;
+            return out;
+          }
+          throw err;
+        }
+      }
+    },
+    {
+      name: "piprail_register",
+      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted. NOTE: index/agent payers are overwhelmingly standard `exact` clients \u2014 a default onchain-proof-only gate gets listed but they cannot pay it, so add an `exact` rail (and set the gate's `discovery` option, required for x402scan) to be usefully discoverable AND payable.",
+      annotations: {
+        title: "Register an x402 endpoint",
+        readOnlyHint: false,
+        // writes a listing to an external index
+        destructiveHint: false,
+        // adds a listing; nothing is destroyed and no funds move
+        openWorldHint: true
+        // posts to external indexes (402 Index)
+        // idempotentHint intentionally omitted — index dedup behaviour isn't guaranteed.
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          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. Pack the words agents will search for INTO this text \u2014 index search is literal, so a keyword that isn't in the name/description won't be found."
+          },
+          category: { type: "string", description: "A category, e.g. 'ai', 'finance', 'data' \u2014 the top findability field (most listings have none)." },
+          tags: { type: "array", items: { type: "string" }, description: "Keywords; folded into the description so they're searchable." },
+          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)." },
+          provider: { type: "string", description: "Who runs the resource (provider/org name)." },
+          contactEmail: { type: "string", description: "Contact email for the listing." }
+        },
+        required: ["url"],
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        try {
+          const opts = {};
+          if (typeof args.name === "string") opts.name = args.name;
+          if (typeof args.description === "string") opts.description = args.description;
+          if (typeof args.category === "string") opts.category = args.category;
+          if (Array.isArray(args.tags)) opts.tags = args.tags.filter((t) => typeof t === "string");
+          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;
+          if (typeof args.provider === "string") opts.provider = args.provider;
+          if (typeof args.contactEmail === "string") opts.contactEmail = args.contactEmail;
+          const outcomes = await client.register(String(args.url), opts);
+          return { outcomes };
+        } catch (err) {
+          return toToolError(err);
         }
-      }).join("|");
-    } else if ("signedDelegateAction" in exact.payload) {
-      try {
-        nonce = Buffer.from(exact.payload.signedDelegateAction, "base64").toString("base64");
-      } catch {
-        nonce = exact.payload.signedDelegateAction;
       }
-    } else if ("signedTxBlob" in exact.payload) {
-      nonce = exact.payload.signedTxBlob.trim().toUpperCase();
-    } else if ("permit2Authorization" in exact.payload) {
-      evmAuth = exact.payload.permit2Authorization;
-      nonce = evmAuth.nonce;
-    } else {
-      evmAuth = exact.payload.authorization;
-      nonce = evmAuth.nonce;
-    }
-    if (await claimTx(nonce)) {
-      return rejection("tx_already_used", `Authorization ${evmAuth ? `nonce ${nonce}` : "transaction"} was already redeemed.`);
-    }
-    const accept = buildExactAccept(spec);
-    const mode = spec.exact.mode;
-    let result;
-    try {
-      if (mode.kind === "self") {
-        result = await spec.net.settleExactSelf({ relayer: mode.relayer, payload: exact.payload, accept });
-      } else {
-        const ftMethod = accept.extra?.assetTransferMethod;
-        const needsFeePayer = ftMethod === "svm" || ftMethod === "algorand" || ftMethod === "aptos" || ftMethod === "near";
-        if (needsFeePayer && !accept.extra?.feePayer) {
-          throw new SettlementError(
-            `exact settle: the ${ftMethod} facilitator rail is missing extra.feePayer (the gas sponsor) \u2014 cannot settle.`
-          );
+    },
+    {
+      name: "piprail_budget",
+      description: "Read how much of your spend budget and time leash is left \u2014 per (network, asset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much USD you can still spend across every stablecoin and chain), the payment-count leash, the session time envelope, and your spend so far. Use it in Mode A (headless) to self-check BEFORE paying, so you never discover the leash by hitting a decline. Read-only; moves no funds. NOTE: the time envelope is in-memory for THIS process; the money/count totals persist only if a spend store is configured.",
+      annotations: {
+        title: "Check remaining budget",
+        readOnlyHint: true,
+        // reads the ledger + policy; never pays
+        idempotentHint: true
+        // a pure read
+      },
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      outputSchema: OPEN_OBJECT,
+      invoke: async () => {
+        try {
+          const spent = client.spent();
+          const budget = client.budget();
+          return {
+            spent,
+            remaining: budget.byAsset,
+            grandTotal: budget.byDenom,
+            // cross-token spend cap per denomination (USD/EUR/…)
+            counts: budget.counts,
+            // payment-count leash (settled + lifetime/window caps)
+            session: budget.session,
+            policy: client.policy() ?? null,
+            // the configured leash, read back
+            report: formatSpendReport(spent)
+          };
+        } catch (err) {
+          return toToolError(err);
         }
-        result = await settleViaFacilitator({
-          url: mode.url,
-          ...mode.authHeaders ? { authHeaders: mode.authHeaders } : {},
-          // PipRail always builds a v2-shaped paymentRequirements (CAIP-2 network + `amount`),
-          // so force x402Version:2 — echoing a v1 client's version here would hand the facilitator
-          // a self-inconsistent request (v1 envelope, v2 requirements). The inner payload is
-          // byte-identical across versions, so forwarding it verbatim is fine.
-          x402Version: 2,
-          paymentPayload: exact.raw,
-          paymentRequirements: {
-            scheme: "exact",
-            network: accept.network,
-            asset: accept.asset,
-            amount: accept.amount,
-            payTo: accept.payTo,
-            maxTimeoutSeconds: accept.maxTimeoutSeconds,
-            extra: needsFeePayer ? { feePayer: accept.extra.feePayer } : { name: accept.extra?.name ?? "", version: accept.extra?.version ?? "" }
-          },
-          receipt: { network: accept.network, asset: accept.asset, payTo: accept.payTo, amount: accept.amount },
-          // The buyer address, for the receipt's `payer` fallback. EVM carries it in the
-          // authorization; SVM doesn't (the facilitator returns the settled payer) → omit it.
-          ...evmAuth ? { payerHint: evmAuth.from } : {}
-        });
-      }
-    } catch (err) {
-      await settleTx(nonce, false);
-      throw err;
-    }
-    if (!result.ok) {
-      await settleTx(nonce, false);
-      return rejection(result.error, result.detail);
-    }
-    await settleTx(nonce, true);
-    await deliverOnPaid(spec, result.receipt);
-    return await buildPaidResult(spec, result.receipt);
-  }
-  function resolveSettleAmount(raw, maxAmount, decimals) {
-    if (typeof raw === "bigint") return raw < 0n ? null : raw;
-    const s = raw.trim();
-    if (s.length === 0) return null;
-    try {
-      if (s.endsWith("%")) {
-        const pct = s.slice(0, -1).trim();
-        if (!/^\d+(\.\d+)?$/.test(pct)) return null;
-        const pctScaled = floorUnits(pct, 4);
-        return maxAmount * pctScaled / (100n * 10n ** 4n);
-      }
-      if (s.startsWith("$")) {
-        const amt = s.slice(1).trim();
-        return floorUnits(amt, decimals);
-      }
-      if (/^\d+$/.test(s)) return BigInt(s);
-      return floorUnits(s, decimals);
-    } catch {
-      return null;
-    }
-  }
-  async function verifyUpto(upto) {
-    const specs = await ready();
-    const uptoSpecs = specs.filter((s) => s.upto);
-    if (uptoSpecs.length === 0) {
-      return rejection("transfer_not_found", "This resource offers no standard `upto` (metered) rail.");
-    }
-    const isCaip = upto.network.includes(":");
-    const wantUptoNet = normalizeNetwork(upto.network);
-    let candidates = isCaip ? uptoSpecs.filter((s) => normalizeNetwork(s.net.network) === wantUptoNet) : uptoSpecs;
-    if (upto.asset) {
-      candidates = candidates.filter((s) => s.asset.toLowerCase() === upto.asset.toLowerCase());
-    }
-    let spec = candidates[0];
-    if (!isCaip && !upto.asset && uptoSpecs.length > 1) spec = void 0;
-    if (!spec && !isCaip && !upto.asset && uptoSpecs.length === 1) spec = uptoSpecs[0];
-    if (!spec || !spec.upto) {
-      return rejection(
-        "transfer_not_found",
-        `No \`upto\` rail offered for ${upto.network}${upto.asset ? `/${upto.asset}` : ""} (offered: ${uptoSpecs.map((s) => `${s.asset}@${s.net.network}`).join(", ")}).`
-      );
-    }
-    const nonce = upto.payload.permit2Authorization.nonce;
-    if (await claimTx(nonce)) {
-      return rejection("tx_already_used", `Authorization nonce ${nonce} was already redeemed.`);
-    }
-    const accept = buildUptoAccept(spec);
-    const relayer = spec.upto.relayer;
-    let result;
-    try {
-      const rawAmount = await options.upto.settleAmount({
-        maxAmount: spec.amountBase,
-        asset: spec.asset,
-        network: spec.net.network,
-        decimals: spec.decimals,
-        ...upto.raw ? { request: upto.raw } : {}
-      });
-      const settleAmount = resolveSettleAmount(rawAmount, spec.amountBase, spec.decimals);
-      if (settleAmount === null) {
-        await settleTx(nonce, false);
-        return rejection(
-          "upto_settle_exceeds_max",
-          `The settleAmount callback returned an unparseable amount (${String(rawAmount)}). Return a bigint, a raw/"NN%"/"$X" string, or 0.`
-        );
       }
-      result = await spec.net.settleUptoSelf({ relayer, payload: upto.payload, accept, settleAmount });
-    } catch (err) {
-      await settleTx(nonce, false);
-      if (err instanceof SettlementError) throw err;
-      return rejection(
-        "tx_reverted",
-        `upto: metering/settle failed (${err instanceof Error ? err.message : String(err)}).`
-      );
-    }
-    if (!result.ok) {
-      await settleTx(nonce, false);
-      return rejection(result.error, result.detail);
-    }
-    await settleTx(nonce, true);
-    await deliverOnPaid(spec, result.receipt);
-    return await buildPaidResult(spec, result.receipt);
-  }
-  async function verify(paymentSignature) {
-    const raw = normaliseHeader(paymentSignature);
-    const result = await resolveVerdictObject(raw === void 0 ? void 0 : decodeBase64Json(raw));
-    if (result.kind === "invalid") await deliverOnFailed(result);
-    return result;
-  }
-  async function verifyObject(payload) {
-    const result = await resolveVerdictObject(payload);
-    if (result.kind === "invalid") await deliverOnFailed(result);
-    return result;
-  }
-  async function routeVerdictObject(obj) {
-    if (obj === void 0 || obj === null) return asChallenge();
-    const sig = parseSignatureObject(obj);
-    if (sig && sig.accepted && typeof sig.accepted.network === "string" && typeof sig.accepted.asset === "string") {
-      return verifyOnchainProof(sig);
-    }
-    const upto = parseUptoObject(obj);
-    if (upto) return verifyUpto(upto);
-    const exact = parseExactObject(obj);
-    if (exact) return verifyExact(exact);
-    return asChallenge();
-  }
-  function echoPaymentIdentifier(result, id) {
-    try {
-      const decoded = decodeBase64Json(result.receiptHeader);
-      if (!decoded) return result;
-      const { extensions: existing, ...receiptOnly } = decoded;
-      const merged = {
-        ...existing ?? {},
-        [EXT_PAYMENT_IDENTIFIER]: { info: { required: false, id } }
-      };
-      return { ...result, receiptHeader: buildReceiptHeader(receiptOnly, merged) };
-    } catch {
-      return result;
-    }
-  }
-  async function resolveVerdictObject(obj) {
-    if (!options.paymentIdentifier) return routeVerdictObject(obj);
-    const id = readPaymentIdentifier(obj);
-    if (id !== null && typeof id === "object") {
-      return rejection("signature_invalid", `payment-identifier: ${id.invalid}.`);
-    }
-    if (id === null) return routeVerdictObject(obj);
-    const idKey = "pid:" + id;
-    if (await claimTx(idKey)) {
-      return rejection(
-        "tx_already_used",
-        `Idempotency id "${id}" is already bound to a settled payment; use a fresh id for a new payment.`
-      );
-    }
-    let result;
-    try {
-      result = await routeVerdictObject(obj);
-    } catch (err) {
-      await settleTx(idKey, false);
-      throw err;
+    },
+    {
+      name: "piprail_guide",
+      description: "Read the PipRail agent contract \u2014 the quote \u2192 plan \u2192 pay loop, how to read a refusal (and which declines are TERMINAL), the never-re-pay rule for broadcast-but-unconfirmed payments, and Mode A (headless) vs Mode B (supervised). Read-only; call it once if unsure how to use these tools.",
+      annotations: {
+        title: "How to use PipRail",
+        readOnlyHint: true,
+        idempotentHint: true
+      },
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      invoke: async () => ({ guide: PIPRAIL_AGENT_GUIDE })
+    },
+    {
+      name: "piprail_verify_receipt",
+      description: "Re-verify a PipRail VERIFIABLE RECEIPT against the chain \u2014 confirm a payment REALLY settled (the funds provably moved to payTo for AT LEAST the stated amount) WITHOUT trusting whoever handed you the receipt. Read-only and WALLET-FREE: pass the PipRailReceipt JSON (from a prior piprail_pay_request `verifiableReceipt`, or any third party). Returns { ok, onChain:{payTo,asset,amount,payer}, matchesClaims, ageSeconds, error? }: `ok` = the chain confirms the settlement; `onChain.payer` is RE-DERIVED from the tx and `matchesClaims:false` means the receipt forged the payer; `amount` is a verified lower bound. Pass `rpcUrl` for a chain outside the common presets.",
+      annotations: {
+        title: "Verify a payment receipt",
+        readOnlyHint: true,
+        // re-reads the chain; moves nothing, needs no wallet
+        idempotentHint: true,
+        openWorldHint: true
+        // reads an on-chain tx via RPC
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          receipt: {
+            type: "object",
+            description: "The PipRailReceipt JSON ({ piprail, receipt, resource, decimals? }) to re-verify."
+          },
+          rpcUrl: {
+            type: "string",
+            description: "Optional RPC URL for the receipt's chain (required for chains outside the common presets)."
+          }
+        },
+        required: ["receipt"],
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        const receipt = args.receipt;
+        const opts = args.rpcUrl ? { rpcUrl: String(args.rpcUrl) } : void 0;
+        return await PipRailClient.verifyReceipt(receipt, opts);
+      }
     }
-    await settleTx(idKey, result.kind === "paid");
-    return result.kind === "paid" ? echoPaymentIdentifier(result, id) : result;
+  ];
+  const tools = [...base2];
+  if (canSwap(client)) {
+    tools.push(
+      {
+        name: "piprail_quote_swap",
+        description: 'Price a SAME-CHAIN swap of one token into another WITHOUT swapping. Read-only: signs nothing and moves nothing. Use it when a payment is blocked because you hold the wrong token on the RIGHT chain. Returns { ok, from, to, maxSpend, source, slippageBps } where `maxSpend` is the ceiling enforced ON-CHAIN (not an estimate) and `source` NAMES who priced it, because PipRail runs no price oracle. `ok:false` with no quote means no route or no liquidity, never "no funds". This CANNOT cross chains: to pay on a chain you hold nothing on, use a wallet on that chain.',
+        annotations: {
+          title: "Price a token swap",
+          readOnlyHint: true,
+          idempotentHint: true,
+          openWorldHint: true
+        },
+        parameters: {
+          type: "object",
+          properties: {
+            from: { type: "string", description: "Token you HOLD and will spend (symbol, address, or 'native')." },
+            to: { type: "string", description: "Token you NEED (symbol, address, or 'native')." },
+            wantAmount: { type: "string", description: 'How much of `to` you need, in human units (e.g. "0.50").' },
+            slippageBps: {
+              type: "number",
+              description: "Optional tolerance in basis points (default 50 = 0.5%). Refused if above your swapPolicy cap."
+            }
+          },
+          required: ["from", "to", "wantAmount"],
+          additionalProperties: false
+        },
+        invoke: async (args) => {
+          const a = args;
+          try {
+            const quote = await client.quoteSwap?.({
+              from: a.from,
+              to: a.to,
+              wantAmount: a.wantAmount,
+              slippageBps: a.slippageBps
+            });
+            if (!quote) {
+              return {
+                ok: false,
+                reason: "no_route",
+                explain: "No route or no liquidity for that pair on this chain. This is not a funding problem. Try a different pair, or pay from a chain where you already hold the token."
+              };
+            }
+            return {
+              ok: true,
+              from: { symbol: quote.from.symbol, amount: quote.from.amountFormatted },
+              to: { symbol: quote.to.symbol, amount: quote.to.amountFormatted },
+              maxSpend: quote.maxSpendFormatted,
+              slippageBps: quote.slippageBps,
+              source: { kind: quote.source.kind, name: quote.source.name, note: quote.source.note },
+              summary: summarizeSwap(quote),
+              quote
+            };
+          } catch (err) {
+            return toToolError(err);
+          }
+        }
+      },
+      {
+        name: "piprail_swap",
+        description: "\u{1F534} MOVES FUNDS. Execute a swap you already priced with piprail_quote_swap. Pass that tool's `quote` back UNMODIFIED: it carries the route and the on-chain spend ceiling. Re-quote rather than reusing an old one, because a stale route gets you a worse price than you were shown. Your PAYMENT budget does not govern this call; your swapPolicy does. Nothing is swapped if the market moves past the ceiling, though chains that charge for a reverted transaction still take gas.",
+        annotations: {
+          title: "Swap tokens",
+          readOnlyHint: false,
+          destructiveHint: true,
+          idempotentHint: false,
+          openWorldHint: true
+        },
+        parameters: {
+          type: "object",
+          properties: {
+            quote: { type: "object", description: "The `quote` object returned by piprail_quote_swap, unmodified." }
+          },
+          required: ["quote"],
+          additionalProperties: false
+        },
+        invoke: async (args) => {
+          const a = args;
+          try {
+            const receipt = await client.swap?.(a.quote);
+            if (!receipt) return { ok: false, reason: "unsupported", explain: "This client cannot swap." };
+            return {
+              ok: true,
+              transaction: receipt.transaction,
+              network: receipt.network,
+              from: { symbol: receipt.from.symbol, amount: receipt.from.amountFormatted },
+              to: { symbol: receipt.to.symbol, amount: receipt.to.amountFormatted },
+              source: receipt.source.name
+            };
+          } catch (err) {
+            return toToolError(err);
+          }
+        }
+      }
+    );
   }
-  async function selfTest() {
-    try {
-      const specs = await ready();
-      const warnings = [];
-      const rails = specs.map((s) => {
-        if (!s.symbol) {
-          warnings.push(
-            `${s.asset} on ${s.net.network}: custom token (no built-in symbol) \u2014 double-check the address + decimals.`
-          );
+  if (!canSell(client)) return tools;
+  const offers = /* @__PURE__ */ new Map();
+  const spentProofs = /* @__PURE__ */ new Set();
+  const offerOr = (id) => {
+    const found = typeof id === "string" ? offers.get(id) : void 0;
+    return found ?? {
+      ok: false,
+      reason: `no offer ${JSON.stringify(id)}. Offers live in memory for this session only, so a restart clears them \u2014 call piprail_sell again to re-price it.`,
+      offers: [...offers.keys()]
+    };
+  };
+  tools.push(
+    {
+      name: "piprail_sell",
+      description: "Put something up for sale and get the payment challenge to hand a buyer. YOU set the price. Returns an offerId plus a `challenge` object: give that challenge to the buyer over ANY channel (a reply, an A2A task, an MCP result) \u2014 it needs no web server and no open port. When they send back a payment proof, call piprail_collect BEFORE you deliver. Money goes straight to your own address; receiving needs no key, so nothing here can spend. Offers are in-memory for this session. By default the offer carries the standard `exact` rail as well as onchain-proof, so ordinary x402 agent-buyers can pay it \u2014 without `exact` most of them cannot, and a listing they cannot pay earns nothing.",
+      annotations: {
+        title: "Sell something",
+        readOnlyHint: false,
+        // creates an offer in this session and advertises an address to be paid at
+        destructiveHint: false,
+        // moves no funds; receiving cannot spend
+        idempotentHint: false,
+        // each call mints a NEW offer with its own nonce
+        openWorldHint: false
+        // publishes nowhere — piprail_register is what lists an offer publicly
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          description: {
+            type: "string",
+            description: "What the buyer is paying for. They see this in the challenge, and it is what you are promising to deliver \u2014 be specific."
+          },
+          price: { type: "string", description: "The price you are charging, human-readable, e.g. '2.50'." },
+          token: { type: "string", description: "What to be paid in. Defaults to 'USDC'. Use 'native' for the chain's own coin." },
+          chain: { type: "string", description: "Which chain to be paid on. Defaults to the chain this wallet is on." },
+          payTo: {
+            type: "string",
+            description: "Where the money goes. Defaults to YOUR OWN address, which is almost always what you want \u2014 set it only to be paid somewhere else, and never to an address a buyer gave you."
+          },
+          resource: { type: "string", description: "Optional identifier or URL for the thing being sold; a label is minted if omitted." }
+        },
+        required: ["description", "price"],
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        try {
+          const description = typeof args.description === "string" ? args.description.trim() : "";
+          const price = typeof args.price === "string" ? args.price.trim() : "";
+          if (!description) return { ok: false, reason: "sell needs a `description` \u2014 it is what the buyer sees and what you owe them." };
+          if (!price) return { ok: false, reason: "sell needs a `price`, human-readable, e.g. '2.50'." };
+          const token = typeof args.token === "string" && args.token.trim() ? args.token.trim() : "USDC";
+          const chain = typeof args.chain === "string" && args.chain.trim() ? args.chain.trim() : client.chain?.();
+          if (chain === void 0) {
+            return { ok: false, reason: "sell needs a `chain` \u2014 this wallet cannot report one of its own." };
+          }
+          let payTo;
+          if (typeof args.payTo === "string" && args.payTo.trim()) {
+            payTo = args.payTo.trim();
+          } else if (typeof client.address === "function") {
+            payTo = await client.address();
+          } else {
+            return { ok: false, reason: "sell needs a `payTo` \u2014 this wallet cannot report its own address." };
+          }
+          const id = `offer_${crypto.randomUUID().replace(/-/g, "").slice(0, 10)}`;
+          const resource = typeof args.resource === "string" && args.resource.trim() ? args.resource.trim() : `piprail:${id}`;
+          const base3 = { chain, token, amount: price, payTo, description, discovery: true };
+          const railSchemes = (t) => [
+            ...new Set((t.rails ?? []).flatMap((r) => [...r.schemes ?? []]))
+          ];
+          const shared = {
+            isUsed: (ref) => spentProofs.has(ref),
+            markUsed: (ref) => void spentProofs.add(ref)
+          };
+          let gate = createPaymentGate({ ...base3, ...shared, exact: true });
+          let check = await gate.selfTest();
+          const warnings = [];
+          if (!check.ok || !railSchemes(check).includes("exact")) {
+            const why = check.error ?? "it did not resolve on this RPC";
+            gate = createPaymentGate({ ...base3, ...shared });
+            check = await gate.selfTest();
+            warnings.push(
+              `This offer carries onchain-proof ONLY, so a standard x402 agent-buyer cannot pay it. A PipRail buyer (piprail_pay_request) and a human still can. The gasless exact rail was dropped because ${why} Two things cause this: the token or family has no exact scheme (a native coin never does, so price in USDC), or the token domain read failed on a busy public RPC, which is transient. Retrying on a dedicated rpcUrl is worth one attempt before you settle for this.`
+            );
+          }
+          if (!check.ok) {
+            return { ok: false, reason: check.error ?? "this offer could not be priced on that chain.", chain, token };
+          }
+          for (const w of check.warnings ?? []) warnings.push(String(w));
+          const { challenge, requiredHeader } = await gate.challenge(resource);
+          const schemes = railSchemes(check);
+          const nonce = challenge.accepts.find((a) => a.scheme === "onchain-proof")?.extra?.nonce;
+          const offer = {
+            id,
+            nonce: typeof nonce === "string" ? nonce : void 0,
+            gate,
+            description,
+            price,
+            token,
+            chain,
+            payTo,
+            resource,
+            schemes,
+            createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+            earnings: []
+          };
+          offers.set(id, offer);
+          return {
+            ok: true,
+            offerId: id,
+            description,
+            price,
+            token,
+            chain,
+            payTo,
+            paidToYou: payTo === (typeof client.address === "function" ? await client.address().catch(() => void 0) : void 0),
+            schemes,
+            challenge,
+            /*
+             * The header an x402 402 must carry alongside the body. An agent serving its own
+             * offer over HTTP needs BOTH halves, and omitting this quietly left it emitting a
+             * non-conformant 402 that only a lenient buyer would pay.
+             */
+            requiredHeader,
+            next: `Give \`challenge\` to the buyer over any channel you like. Serving it over HTTP? Send it as a 402 body with \`requiredHeader\` as the PAYMENT-REQUIRED header. When they hand back a proof, call piprail_collect with offerId ${id} and DO NOT deliver until it comes back paid:true. To let strangers find this offer, call piprail_register with its URL.`,
+            ...warnings.length ? { warnings } : {}
+          };
+        } catch (err) {
+          return toToolError(err);
+        }
+      }
+    },
+    {
+      name: "piprail_collect",
+      description: "Verify a payment a buyer says they made for one of YOUR offers, against the chain. This is the only thing that proves you were paid \u2014 a buyer claiming to have paid, a plausible-looking tx hash, and a real settlement are three different things, and only this call tells them apart. Returns paid:true with a receipt, or paid:false with the reason and a fresh challenge the buyer can retry against. DELIVER NOTHING UNTIL IT RETURNS paid:true. Each proof can be redeemed once: a replay of an already-collected payment comes back paid:false, never a second sale.",
+      annotations: {
+        title: "Collect a payment",
+        readOnlyHint: false,
+        // burns the proof into the offer's used set, so it cannot be redeemed twice
+        destructiveHint: false,
+        // moves no funds; it only reads the chain and records what it found
+        idempotentHint: false,
+        // deliberately NOT: a second call on the same proof is a replay and is refused
+        openWorldHint: true
+        // reads the settlement via RPC
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          offerId: { type: "string", description: "The offer being paid for, from piprail_sell." },
+          payment: {
+            type: "string",
+            description: "What the buyer sent back: the payment-signature header value, or the payment payload as a JSON string. Pass it through exactly as received."
+          }
+        },
+        required: ["offerId", "payment"],
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        try {
+          const offer = offerOr(args.offerId);
+          if ("ok" in offer) return offer;
+          const raw = typeof args.payment === "string" ? args.payment.trim() : "";
+          if (!raw) return { ok: false, reason: "collect needs the `payment` the buyer sent back." };
+          const asObject = raw.startsWith("{") ? JSON.parse(raw) : void 0;
+          const presented = nonceIn(asObject ?? decodeBase64Json(raw));
+          if (offer.nonce && presented && presented !== offer.nonce) {
+            return {
+              ok: true,
+              paid: false,
+              offerId: offer.id,
+              reason: "this proof was minted for a DIFFERENT offer (its challenge nonce is not this one). A payment for one offer is not payment for another, even at the same price.",
+              code: "wrong_offer",
+              next: "Do NOT deliver. Ask the buyer to pay THIS offer's challenge."
+            };
+          }
+          const result = asObject !== void 0 ? await offer.gate.verifyObject(asObject) : await offer.gate.verify(raw);
+          if (result.kind === "paid") {
+            const r = result.receipt;
+            const entry = {
+              at: (/* @__PURE__ */ new Date()).toISOString(),
+              amount: String(r.amountFormatted ?? offer.price),
+              symbol: String(r.symbol ?? offer.token),
+              ...typeof r.payer === "string" ? { payer: r.payer } : {},
+              ref: String(r.transaction ?? r.reference ?? "")
+            };
+            offer.earnings.push(entry);
+            return {
+              ok: true,
+              paid: true,
+              offerId: offer.id,
+              earned: `${entry.amount} ${entry.symbol}`,
+              receipt: result.receipt,
+              next: `Payment is settled and on-chain. Deliver "${offer.description}" now. This proof is spent and cannot be collected again.`
+            };
+          }
+          if (result.kind === "invalid") {
+            return {
+              ok: true,
+              paid: false,
+              offerId: offer.id,
+              reason: result.detail || result.error,
+              code: result.error,
+              retryChallenge: result.challenge,
+              next: "Do NOT deliver. Give the buyer `retryChallenge` if they want to try again."
+            };
+          }
+          return {
+            ok: true,
+            paid: false,
+            offerId: offer.id,
+            reason: "no payment was presented \u2014 this is a fresh challenge, not a settlement.",
+            retryChallenge: result.challenge,
+            next: "Do NOT deliver. The buyer has not paid yet."
+          };
+        } catch (err) {
+          if (err instanceof SyntaxError) {
+            return { ok: false, reason: "the `payment` looked like JSON but would not parse. Pass the buyer's proof through unchanged." };
+          }
+          return toToolError(err);
+        }
+      }
+    },
+    {
+      name: "piprail_earnings",
+      description: "What you have SOLD and what you have actually been paid this session \u2014 the earning-side mirror of piprail_budget. Counts only payments proven by piprail_collect, never what a buyer claimed. In-memory for this session, so it resets on restart and is a record of this run, not a ledger.",
+      annotations: {
+        title: "Your earnings",
+        readOnlyHint: true,
+        // pure read of this session's collected payments
+        idempotentHint: true,
+        openWorldHint: false
+      },
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      invoke: async () => {
+        const list = [...offers.values()];
+        const byAsset = {};
+        for (const o of list) {
+          for (const e of o.earnings) byAsset[e.symbol] = (byAsset[e.symbol] ?? 0) + Number(e.amount || 0);
         }
+        const collected = list.reduce((n, o) => n + o.earnings.length, 0);
         return {
-          network: s.net.network,
-          asset: s.asset,
-          ...s.symbol ? { symbol: s.symbol } : {},
-          decimals: s.decimals,
-          amount: s.amountFormatted,
-          payTo: s.payTo,
-          schemes: [
-            ...s.exact ? ["exact"] : [],
-            ...s.upto ? ["upto"] : [],
-            "onchain-proof"
-          ]
+          ok: true,
+          offers: list.map((o) => ({
+            offerId: o.id,
+            description: o.description,
+            price: `${o.price} ${o.token}`,
+            chain: o.chain,
+            payTo: o.payTo,
+            schemes: o.schemes,
+            timesPaid: o.earnings.length,
+            earnings: o.earnings
+          })),
+          totals: Object.fromEntries(Object.entries(byAsset).map(([s, n]) => [s, String(n)])),
+          collected,
+          report: list.length === 0 ? "Nothing on sale yet. piprail_sell prices something." : `${list.length} offer(s), ${collected} payment(s) collected: ` + (collected === 0 ? "nothing paid yet." : Object.entries(byAsset).map(([s, n]) => `${n} ${s}`).join(", "))
         };
-      });
-      return { ok: true, rails, warnings };
-    } catch (err) {
-      return { ok: false, rails: [], warnings: [], error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+    {
+      name: "piprail_wallet",
+      description: "What YOU hold, and where you get paid \u2014 your balance sheet, which is a different question from piprail_budget (that is how much of your allowance is left). Returns your own address per chain plus the amount of each asset you actually hold. Use it before deciding to sell, swap or ask to be topped up, and give the address to anyone who needs to send you funds. A null amount means the read was UNAVAILABLE, not zero: do NOT treat it as being broke. Read-only; moves nothing and needs no approval.",
+      annotations: {
+        title: "Your wallet",
+        readOnlyHint: true,
+        // reads addresses and balances; changes nothing
+        idempotentHint: true,
+        openWorldHint: true
+        // balances come from RPC
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          assets: {
+            type: "array",
+            items: { type: "string" },
+            description: "Symbols to report, e.g. ['native','USDC','USDT']. Defaults to your chain's coin and USDC. A symbol your chain does not ship comes back known:false rather than as a zero."
+          }
+        },
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        try {
+          const assets = Array.isArray(args.assets) && args.assets.length ? args.assets.filter((a) => typeof a === "string") : ["native", "USDC"];
+          const address = typeof client.address === "function" ? await client.address().catch(() => null) : null;
+          const holdings = typeof client.balanceOf === "function" ? await client.balanceOf(assets).catch(() => []) : [];
+          const held = holdings.filter((h) => h.known && h.amount !== null && h.amount !== "0");
+          const unknown = holdings.filter((h) => h.known && h.amount === null);
+          return {
+            ok: true,
+            address,
+            chain: typeof client.chain === "function" ? client.chain() : void 0,
+            holdings,
+            report: (held.length ? `You hold ${held.map((h) => `${h.amountFormatted} ${h.symbol}`).join(", ")}.` : "No positive balance in the assets you asked about.") + (unknown.length ? ` Could NOT read ${unknown.map((h) => h.symbol).join(", ")} \u2014 unknown, not zero; retry before concluding you are broke.` : ""),
+            next: "To be paid here, give out `address`. piprail_budget is your spend leash; this is what you own."
+          };
+        } catch (err) {
+          return toToolError(err);
+        }
+      }
     }
-  }
-  return { challenge, verify, verifyObject, describe, landingPage, selfTest };
+  );
+  return tools;
 }
-function requirePayment(options) {
-  if (options.upto) {
-    throw new class extends PipRailError {
-      code = "UNSUPPORTED_SCHEME";
-    }(
-      "requirePayment: the 'upto' (metered) rail is unsupported through the Express middleware \u2014 it settles before the route handler serves, so metered usage is unknown at settle time. Call gate.verify() directly (createPaymentGate) and meter inside settleAmount; see docs/accepting-payments/upto-rail-seller.md."
+
+// src/classify.ts
+function classifyChallenge(challenge, opts) {
+  try {
+    const accepts = Array.isArray(challenge?.accepts) ? challenge.accepts : [];
+    const network = opts?.network;
+    const schemes = opts?.schemes ?? [];
+    const offeredSchemes = [
+      ...new Set(accepts.map((a) => a?.scheme).filter((s) => s != null))
+    ];
+    const offeredNetworks = [...new Set(accepts.map((a) => a?.network).filter((n) => n != null))];
+    const onClientChain = accepts.some((a) => a?.network === network);
+    const payableScheme = accepts.some(
+      (a) => a?.network === network && schemes.includes(a?.scheme)
     );
+    const verdict = accepts.length === 0 ? "NO_RAIL" : payableScheme ? "PAYABLE_RAIL" : onClientChain ? "UNPAYABLE_SCHEME" : "WRONG_CHAIN";
+    return { onClientChain, payableScheme, offeredSchemes, offeredNetworks, verdict };
+  } catch {
+    return {
+      onClientChain: false,
+      payableScheme: false,
+      offeredSchemes: [],
+      offeredNetworks: [],
+      verdict: "NO_RAIL"
+    };
   }
-  const gate = createPaymentGate(options);
-  return async (req, res, next) => {
-    let result;
-    try {
-      result = await gate.verify(req.headers[HEADER_SIGNATURE] ?? req.headers[HEADER_SIGNATURE_V1]);
-    } catch (err) {
-      if (err instanceof SettlementError) {
-        res.status(502);
-        res.json({
-          x402Version: 2,
-          error: "settlement_failed",
-          detail: err.message,
-          fallback: "The gasless `exact` settlement failed. This resource also accepts the `onchain-proof` scheme \u2014 retry by paying that rail yourself (you broadcast the transfer and pay the gas). It is the fallback when no facilitator can sponsor the gas."
-        });
-        return;
-      }
-      next(err);
-      return;
-    }
-    switch (result.kind) {
-      case "paid":
-        res.setHeader(HEADER_RESPONSE, result.receiptHeader);
-        res.setHeader(HEADER_RESPONSE_V1, result.receiptHeader);
-        return next();
-      case "challenge":
-        res.setHeader(HEADER_REQUIRED, result.requiredHeader);
-        res.status(result.statusCode);
-        res.json(result.challenge);
-        return;
-      case "invalid":
-        res.setHeader(HEADER_REQUIRED, result.requiredHeader);
-        res.status(result.statusCode);
-        res.json(result.challenge);
-        return;
-    }
-  };
-}
-function normaliseHeader(value) {
-  if (Array.isArray(value)) return value[0];
-  return value;
 }
 
 // src/merchant.ts
@@ -7287,11 +8761,14 @@ export {
   A2A_STATUS_KEY,
   A2A_X402_EXTENSION_URI_V01,
   A2A_X402_EXTENSION_URI_V02,
+  AGENT_MODES,
   BRAND,
   BUILTIN_DENOMS,
   CHAINS,
   ConfirmationTimeoutError,
+  DEFAULT_AGENT_MODE,
   DEFAULT_EXACT_TRANSFER_METHOD,
+  DEFAULT_SLIPPAGE_BPS,
   DENOM_PRECISION,
   DIRECTORY_INFO,
   EIP3009_TYPES,
@@ -7309,6 +8786,7 @@ export {
   InvalidEnvelopeError,
   KNOWN_EXACT_TRANSFER_METHODS,
   KNOWN_FACILITATORS,
+  MAX_SLIPPAGE_BPS,
   MCP_PAYMENT_META_KEY,
   MCP_PAYMENT_RESPONSE_META_KEY,
   MaxRetriesExceededError,
@@ -7328,6 +8806,7 @@ export {
   PipRailError,
   REGISTER_ATTRIBUTION,
   RecipientNotReadyError,
+  SWAP_PROVIDERS,
   SettlementError,
   SpendLedger,
   UPTO_PROXY_CHAIN_IDS,
@@ -7343,6 +8822,7 @@ export {
   agentGuide,
   appendAttribution,
   appendKeywords,
+  applySlippage,
   buildBazaarExtension,
   buildChallengeHeader,
   buildEndpointInfo,
@@ -7360,6 +8840,7 @@ export {
   buildWellKnownX402,
   buildWellKnownX402Manifest,
   buildX402DnsTxt,
+  canSwapOn,
   chainIdForExactNetwork,
   claim402IndexDomain,
   classifyChallenge,
@@ -7422,10 +8903,14 @@ export {
   renderLandingPage,
   requirePayment,
   resolveChain,
+  resolveSlippageBps,
   scoreResource,
   searchOpenIndexes,
   settleViaFacilitator,
   summarizePlan,
+  summarizeSwap,
+  swapProvidersFor,
+  swappableNetworks,
   toA2AErrorCode,
   toA2APaymentFailed,
   toA2APaymentReceipts,