@piprail/sdk 2.16.2 → 3.0.0

package/dist/index.d.ts

@@ -1574,7 +1574,9 @@ declare const CHAINS: {
                         authorizationList?: undefined;
                         mint?: undefined;
                         isSystemTx?: undefined;
-                        sourceHash?: undefined;
+                        sourceHash
+                        /** Native coin metadata. Defaults to 18-decimal ETH. */
+                        ? /** Native coin metadata. Defaults to 18-decimal ETH. */: undefined;
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
@@ -2505,7 +2507,9 @@ declare const CHAINS: {
                         yParity: number;
                         l1BatchNumber: bigint | null;
                         l1BatchTxIndex: bigint | null;
-                        gasPrice?: undefined | undefined;
+                        gasPrice
+                        /** Known tokens on this chain (empty for unknown custom chains). */
+                        ? /** Known tokens on this chain (empty for unknown custom chains). */: undefined | undefined;
                         maxFeePerBlobGas?: undefined | undefined;
                         maxFeePerGas: bigint;
                         maxPriorityFeePerGas: bigint;
@@ -3294,15 +3298,7 @@ declare const CHAINS: {
                         maxPriorityFeePerGas: bigint;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
-                        sourceHash
-                        /**
-                         * Normalise a `ChainInput` (+ optional rpc override) into the
-                         * `{ chain, chainId, rpcUrl, tokens }` the wallet and verifier need.
-                         */
-                        ? /**
-                         * Normalise a `ChainInput` (+ optional rpc override) into the
-                         * `{ chain, chainId, rpcUrl, tokens }` the wallet and verifier need.
-                         */: undefined | undefined;
+                        sourceHash?: undefined | undefined;
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
@@ -3680,6 +3676,74 @@ declare const CHAINS: {
             };
         };
     };
+    /**
+     * 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: {
+            blockExplorers: {
+                readonly default: {
+                    readonly name: "Blockscout";
+                    readonly url: "https://robinhoodchain.blockscout.com";
+                };
+            };
+            blockTime?: number | undefined | undefined;
+            contracts?: {
+                [x: string]: viem.ChainContract | {
+                    [sourceId: number]: viem.ChainContract | undefined;
+                } | undefined;
+                ensRegistry?: viem.ChainContract | undefined;
+                ensUniversalResolver?: viem.ChainContract | undefined;
+                multicall3?: viem.ChainContract | undefined;
+                erc6492Verifier?: viem.ChainContract | undefined;
+            } | undefined;
+            ensTlds?: readonly string[] | undefined;
+            id: 4663;
+            name: "Robinhood Chain";
+            nativeCurrency: {
+                readonly name: "Ether";
+                readonly symbol: "ETH";
+                readonly decimals: 18;
+            };
+            experimental_preconfirmationTime?: number | undefined | undefined;
+            rpcUrls: {
+                readonly default: {
+                    readonly http: readonly ["https://rpc.mainnet.chain.robinhood.com"];
+                };
+            };
+            sourceId?: number | undefined | undefined;
+            testnet?: boolean | undefined | undefined;
+            custom?: Record<string, unknown> | undefined;
+            extendSchema?: Record<string, unknown> | undefined;
+            fees?: viem.ChainFees<undefined> | undefined;
+            formatters?: undefined;
+            prepareTransactionRequest?: ((args: viem.PrepareTransactionRequestParameters, options: {
+                client: viem.Client;
+                phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+            }) => Promise<viem.PrepareTransactionRequestParameters>) | [fn: ((args: viem.PrepareTransactionRequestParameters, options: {
+                client: viem.Client;
+                phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+            }) => Promise<viem.PrepareTransactionRequestParameters>) | undefined, options: {
+                runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+            }] | undefined;
+            serializers?: viem.ChainSerializers<undefined, viem.TransactionSerializable> | undefined;
+            verifyHash?: ((client: viem.Client, parameters: viem.VerifyHashActionParameters) => Promise<viem.VerifyHashActionReturnType>) | undefined;
+        };
+        tokens: {
+            USDG: {
+                address: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168";
+                decimals: number;
+                symbol: string;
+            };
+        };
+    };
 };
 /** A built-in EVM chain name. */
 type ChainName = keyof typeof CHAINS;
@@ -3710,6 +3774,232 @@ interface ResolvedChain {
  */
 declare function resolveChain(input: ChainInput, rpcUrlOverride?: string): ResolvedChain;
 
+/**
+ * Swap — the OPTIONAL, opt-in helper for "I hold the wrong token".
+ *
+ * PROTOCOL LAYER — pure types + pure helpers, ZERO chain libraries (STANDARDS §1).
+ * The work happens in the drivers, behind two OPTIONAL contract methods
+ * (`quoteSwap?` / `swap?` on {@link ResolvedNetwork}), so a family that can't swap
+ * simply doesn't implement them and nothing about it changes.
+ *
+ * ── WHY THIS EXISTS ────────────────────────────────────────────────────────────
+ * A 402 names a token. A wallet holds what it holds. Today, holding XLM when the
+ * invoice wants USDC is a dead end: `planPayment()` reports INSUFFICIENT_TOKEN and
+ * stops. This turns that dead end into a suggestion the caller may act on — or
+ * ignore entirely.
+ *
+ * ── IT IS NOT ON BY DEFAULT, AND IT NEVER WILL BE ──────────────────────────────
+ * Nothing here runs unless you call it. `fetch()` never swaps. `planPayment()`
+ * never swaps. There is no `autoSwap` flag, deliberately: moving one asset into
+ * another is a priced, irreversible act, and it is not something a payment library
+ * should ever do on your behalf because it noticed you were short. You ask, or it
+ * doesn't happen. (STANDARDS §0: opt-in, defaults unchanged.)
+ *
+ * ── 🔴 PIPRAIL DOES NOT PRICE ANYTHING ─────────────────────────────────────────
+ * STANDARDS §7 forbids a price oracle, and a swap rate IS a price. So every
+ * {@link SwapQuote} carries a {@link SwapQuoteSource} naming WHO said it. PipRail
+ * relays a rate; it never asserts one. Read `quote.source` before you trust a
+ * number, exactly as you would read which facilitator settled a payment.
+ *
+ * Two tiers ship today, and the type system keeps them apart.
+ *
+ * **Tier 1, `kind: 'protocol'`** — the ledger itself swaps, so there is no third party
+ * at all:
+ *
+ *   - **Stellar** — a `PathPaymentStrictReceive` to your own account. One atomic
+ *     operation, routed by the **Stellar SDEX** across its order books and liquidity pools.
+ *   - **XRPL** — a cross-currency `Payment` to your own address (the ledger permits
+ *     `Account == Destination` precisely for currency conversion), routed by the
+ *     **XRPL DEX + AMM** across the order books and AMM pools, auto-bridging through XRP
+ *     when that is cheaper.
+ *
+ * Both are protocol primitives: no third-party contract, no router to approve, no
+ * solver, no relayer, no API key, and no integrator fee, because there is nowhere to
+ * put one. The funds never leave the user's own account.
+ *
+ * **Tier 2, `kind: 'provider'`** — a named third-party router, used because those
+ * chains have no protocol-level swap:
+ *
+ *   - **Solana** via **Jupiter**, verified keyless with `platformFee: null`.
+ *   - **EVM** (9 live-probed chains) via **KyberSwap**, verified keyless, no integrator fee.
+ *   - **Sui** via **Aftermath**, which returns a complete signable transaction block.
+ *   - **NEAR** via **Ref Finance**, chosen over Intents because Intents re-adds a facilitator.
+ *   - **Algorand** via **Vestige**, whose unsigned group names only you as a signer.
+ *   - **Aptos** via **Hyperion**, which publishes no API at all: the quote and the swap are
+ *     both Move calls straight to the router contract.
+ *   - **TON** via **STON.fi**, whose `reverse_swap` simulation fixes the ask side; the request
+ *     is padded so the router's on-chain floor is at least the invoice.
+ *   - **Tron** via **SunSwap V2**, also called contract-to-contract with no API.
+ *
+ * The first five were adopted only after a plain server-side request returned HTTP 200 with
+ * no key. The last three need no request at all, because they are read straight off the
+ * chain. 0x, 1inch, Odos, OpenOcean, Squid, Rango and thirdweb Bridge all failed that bar
+ * and were rejected. PipRail never sets a platform or integrator fee field on any provider,
+ * so it takes nothing on top, ever.
+ *
+ * ⭐ **Three of them are exact-output natively.** Hyperion, STON.fi and SunSwap V2 take the
+ * invoice amount as the OUTPUT and cap the input on-chain, which is the exact shape of an
+ * x402 quote. Every other route prices an exact input, so the amount is probed and scaled.
+ */
+
+/**
+ * WHO produced a rate. PipRail never asserts a price of its own, so this is
+ * REQUIRED on every quote — there is no anonymous number in this module.
+ *
+ * - `'protocol'` — the chain's own DEX decided it (Stellar SDEX, XRPL order books
+ *   + AMM). No company is involved and no fee is taken by anyone but the pool.
+ * - `'provider'` — a named third party quoted it. Judge it as you would a
+ *   facilitator: it can be down, it can be wrong, and it may take a cut.
+ */
+interface SwapQuoteSource {
+    kind: 'protocol' | 'provider';
+    /** Human name, e.g. `'Stellar SDEX'`, `'XRPL DEX + AMM'`. */
+    name: string;
+    /** Anything the caller should know before trusting the rate (pool fees, caveats). */
+    note?: string;
+}
+/** One side of a swap, in both machine and human units. */
+interface SwapSide {
+    /** Driver-native asset id (`'native'`, `'USDC:GA5Z…'`, an XRPL `CODE.issuer`). */
+    asset: string;
+    symbol: string;
+    decimals: number;
+    /** Base units. */
+    amount: string;
+    /** Human units, for display and for an LLM to reason about. */
+    amountFormatted: string;
+}
+/** What you want swapped. Shaped for the x402 case: an invoice names an exact price. */
+interface SwapRequest {
+    /** The token you HOLD and are willing to spend. */
+    from: TokenInput;
+    /** The token you NEED. */
+    to: TokenInput;
+    /**
+     * How much of `to` you need, in human units (e.g. `'0.50'`). Exact-output, because
+     * that is the shape of an invoice: the amount owed is fixed and the cost floats.
+     */
+    wantAmount: string;
+    /**
+     * Slippage tolerance in basis points, applied to the INPUT side as a hard on-chain
+     * cap (Stellar `sendMax`, XRPL `SendMax`). Default {@link DEFAULT_SLIPPAGE_BPS}.
+     * The cap is enforced by the validators, not by this library: if the market moves
+     * past it the transaction fails rather than overspending.
+     */
+    slippageBps?: number;
+}
+/**
+ * ── AGENT MODE: who is answerable for this wallet ───────────────────────────────────
+ *
+ * The capability an AI agent gets used to depend on which PACKAGE it imported: a model
+ * driving `@piprail/mcp` could never swap, while the same wallet driven through the SDK
+ * could. That is the wrong axis. Whether an agent may move its own funds between
+ * denominations is a question about AUTHORITY, not transport.
+ *
+ * So it is declared, once, by whoever provisions the key:
+ *
+ * - `'supervised'` — a human approves each payment at the moment of spend. The human is
+ *   the policy. (MCP: `PIPRAIL_CONFIRM=1`.)
+ * - `'budgeted'` — **the default.** The `policy` IS the consent: the agent runs free
+ *   inside caps it cannot exceed, with no per-payment prompt. Swapping is withheld,
+ *   because every cap counts PAYMENTS and a swap is not one.
+ * - `'sovereign'` — the agent owns the wallet and answers for it. Swapping is unlocked,
+ *   governed by {@link SwapPolicy} rather than by the payment caps.
+ *
+ * 🔴 **A model can never set its own mode.** It is read at construction from the
+ * environment the operator controls, exactly as an agent cannot grant itself broader
+ * permissions in its host. `client.mode()` reads it back; nothing writes it.
+ *
+ * 🔴 **Sovereign does not mean unguarded.** It means guarded by the RIGHT instrument.
+ * A payment cap cannot bound a swap, so sovereignty ships with `swapPolicy` instead:
+ * a ceiling on what one swap may spend and on the slippage it may accept. Unlocking the
+ * capability without that would repeat the exact mistake the withholding avoided.
+ *
+ * Defaults are unchanged (STANDARDS §0): omit `mode` and everything behaves byte-for-byte
+ * as before, with the same eight tools.
+ */
+type AgentMode = 'supervised' | 'budgeted' | 'sovereign';
+/** The default. Named, so the fallback is never an unexplained string literal. */
+declare const DEFAULT_AGENT_MODE: AgentMode;
+/** Every valid mode, for validation and for surfaces that enumerate them. */
+declare const AGENT_MODES: readonly AgentMode[];
+/**
+ * Guardrails for SWAPPING, the instrument the payment policy cannot be.
+ *
+ * A payment cap counts money leaving for a merchant. A swap moves your own funds between
+ * denominations, so it passes every such cap untouched: a loop of USDC → SOL → USDC bleeds
+ * the pool fee each time while the ledger records no spend at all. These bound the two
+ * things that actually leak value on that path.
+ */
+interface SwapPolicy {
+    /**
+     * The most one swap may SPEND, in human units of the token being sold (e.g. `'25.00'`).
+     * Compared against the quote's on-chain ceiling (`maxSpend`), never the estimate, so a
+     * route that moves against you cannot slip past it.
+     */
+    maxPerSwap?: string;
+    /**
+     * The worst slippage this agent may accept, in basis points. Caps the tolerance a
+     * caller (or a model) may ask for; a request above it is refused rather than clamped,
+     * because silently tightening a number somebody chose is its own surprise.
+     */
+    maxSlippageBps?: number;
+    /**
+     * Optional allowlist of token symbols this agent may swap into. Omit for no restriction.
+     * Useful for "may consolidate into USDC, may not take a position in anything else".
+     */
+    allowTo?: readonly string[];
+}
+/** A priced, executable swap. Read `source` before trusting `maxSpend`. */
+interface SwapQuote {
+    /** 🔴 WHO said this rate. Never absent. */
+    source: SwapQuoteSource;
+    network: Caip2;
+    /** What you'd spend at the quoted rate. */
+    from: SwapSide;
+    /** What you'd receive — exactly `wantAmount`, since these rails are exact-output. */
+    to: SwapSide;
+    /** The most you can possibly spend, base units. Enforced ON-CHAIN, not here. */
+    maxSpend: string;
+    maxSpendFormatted: string;
+    slippageBps: number;
+    /**
+     * Opaque routing data the driver needs to execute (a Stellar path, an XRPL
+     * `Paths` array). Treat it as a token: pass it back, never interpret it.
+     */
+    route: unknown;
+}
+/** Proof that a swap settled. */
+interface SwapReceipt {
+    /** Tx hash / ledger ref, the same shape a payment receipt uses. */
+    transaction: string;
+    network: Caip2;
+    source: SwapQuoteSource;
+    /** What actually left the wallet, when the chain reports it; else the quote. */
+    from: SwapSide;
+    to: SwapSide;
+}
+/** Default slippage tolerance: 0.5%. Conservative, and overridable per request. */
+declare const DEFAULT_SLIPPAGE_BPS = 50;
+/** Basis-point ceiling. 10% — past this, a "swap" is a donation to an arbitrageur. */
+declare const MAX_SLIPPAGE_BPS = 1000;
+/**
+ * Validate and default a slippage setting. Pure. Throws {@link RangeError} rather
+ * than a `PipRailError` because this is a programming mistake in the caller's own
+ * arguments, not a payment condition — see ERRORS.md §1.
+ */
+declare function resolveSlippageBps(bps: number | undefined): number;
+/**
+ * Apply a slippage tolerance to an input amount, rounding UP so the on-chain cap is
+ * never tighter than asked for. Pure integer maths — no floats anywhere near money.
+ */
+declare function applySlippage(amount: bigint, bps: number): bigint;
+/**
+ * One human sentence describing a quote, for a log line or an LLM. Always names the
+ * source, so the "who priced this?" question is answered wherever the quote is shown.
+ */
+declare function summarizeSwap(q: SwapQuote): string;
+
 /**
  * The PaymentDriver contract. Every chain-family section (EVM, Solana, …)
  * implements this and nothing else; the protocol layer (server/client/x402)
@@ -3968,6 +4258,20 @@ interface ResolvedNetwork {
     assertValidPayTo(payTo: string): void;
     /** Validate + wrap the user's wallet config for this family. */
     bindWallet(wallet: unknown): WalletHandle;
+    /**
+     * The bound wallet's OWN address, in this family's canonical form — the answer to
+     * "where do I get paid?".
+     *
+     * Every driver already derives this internally for {@link ResolvedNetwork.balanceOf};
+     * exposing it is what lets a wallet holder RECEIVE rather than only spend. An agent
+     * handed a key it never chose has no other way to learn its own address, so without
+     * this it can pay for things but can never be paid for anything.
+     *
+     * Async only because TON must build the wallet contract before it has an address;
+     * every other family derives it synchronously from the key. Pure — derives from the
+     * key material, reads no RPC, moves nothing.
+     */
+    addressOf(wallet: WalletHandle): Promise<string>;
     /** Broadcast payment for `accept`; return the proof ref (tx hash / signature). */
     send(wallet: WalletHandle, accept: X402AcceptEntry): Promise<string>;
     /** Wait until `ref` reaches minConfirmations (or finality). */
@@ -4202,6 +4506,42 @@ interface ResolvedNetwork {
         accept: X402UptoAcceptEntry;
         settleAmount: bigint;
     }): Promise<VerifyResult>;
+    /**
+     * Price a same-chain swap — "I hold the wrong token". READ-ONLY: no funds move,
+     * nothing is signed.
+     *
+     * OPTIONAL, like every method above it: a family that can't swap omits both this
+     * and {@link ResolvedNetwork.swap}, and the client reports that honestly instead
+     * of pretending. Implemented today where swapping is a PROTOCOL PRIMITIVE —
+     * Stellar path payments and the XRPL DEX/AMM — so no third party, no API key and
+     * no extra dependency is involved.
+     *
+     * NEVER THROWS for a read problem (same posture as `estimateCost`/`balanceOf`):
+     * returns `null` when this pair can't be routed, the market has no liquidity, or
+     * the RPC read failed. `null` means "no quote", never "no funds".
+     *
+     * 🔴 The returned rate is NOT PipRail's opinion — `quote.source` names who
+     * produced it (STANDARDS §7: no price oracle, ever).
+     */
+    quoteSwap?(input: {
+        from: ResolvedToken;
+        to: ResolvedToken;
+        /** Exact output wanted, base units. */
+        wantAmount: bigint;
+        slippageBps: number;
+        /** The wallet that would swap — the driver derives its own address from it. */
+        wallet: WalletHandle;
+    }): Promise<SwapQuote | null>;
+    /**
+     * Execute a swap the caller has already seen and accepted. Signs and broadcasts
+     * one transaction from the user's OWN wallet; the funds never leave their account
+     * (both rails today are a self-transfer that changes denomination).
+     *
+     * Throws {@link InsufficientFundsError} when the wallet can't cover `maxSpend`,
+     * per ERRORS.md §5. The slippage cap rides ON-CHAIN inside the transaction, so a
+     * market that moves past it fails the transaction rather than overspending.
+     */
+    swap?(wallet: WalletHandle, quote: SwapQuote): Promise<SwapReceipt>;
 }
 interface ResolveOptions {
     /** The developer-supplied `chain` selector. */
@@ -5392,6 +5732,18 @@ interface PipRailClientOptions {
      * (unguarded) default. See {@link PaymentPolicy}.
      */
     policy?: PaymentPolicy;
+    /**
+     * Who is answerable for this wallet. Default `'budgeted'`, which is byte-identical to
+     * every release before modes existed. Set `'sovereign'` only when the agent OWNS these
+     * funds: it unlocks the swap tools for a model, governed by {@link swapPolicy}. A model
+     * can never set this for itself. See {@link AgentMode}.
+     */
+    mode?: AgentMode;
+    /**
+     * Guardrails for swapping, used in `'sovereign'` mode. A payment cap counts money going
+     * to a merchant and cannot bound a swap, so this bounds it instead. See {@link SwapPolicy}.
+     */
+    swapPolicy?: SwapPolicy;
     /**
      * Final approval hook, called with the {@link PipRailQuote} after the policy
      * passes but before paying. Return `false` (or a rejected promise resolving
@@ -5399,6 +5751,21 @@ interface PipRailClientOptions {
      * funds move. Use for human-in-the-loop or custom per-payment logic.
      */
     onBeforePay?: (quote: PipRailQuote) => boolean | Promise<boolean>;
+    /**
+     * Approve (or refuse) a SWAP before anything is signed — the swap-side twin of
+     * {@link PipRailClientOptions.onBeforePay}.
+     *
+     * It exists because `onBeforePay` genuinely does not cover swaps: a swap is not a payment,
+     * which is the whole reason `swapPolicy` bounds it instead. But an operator who wired an
+     * approver did not mean "ask me before payments and let value move silently any other way",
+     * and a supervised sovereign agent could swap its whole balance without the human seeing one
+     * prompt. Same fail-safe contract as `onBeforePay`: `false` or a throw refuses, and the
+     * refusal arrives as a {@link PaymentDeclinedError} with `reasonCode: 'APPROVAL'`.
+     *
+     * `@piprail/mcp` wires this alongside `onBeforePay` whenever confirmation is on, so an
+     * operator gets it without asking.
+     */
+    onBeforeSwap?: (quote: SwapQuote) => boolean | Promise<boolean>;
     /**
      * After paying, how many times to re-send the request with proof before
      * giving up. Default 3, with a short backoff between attempts — this
@@ -5581,6 +5948,41 @@ interface PayingClient {
     /** The CONFIGURED spend policy, read back (so an agent can self-check its whole leash
      *  without hitting a decline). `undefined` when no policy is set. */
     policy(): PaymentPolicy | undefined;
+    /** Who is answerable for this wallet. Absent means the default, `'budgeted'`. */
+    mode?(): AgentMode;
+    /** May a MODEL swap on this wallet? True only in `'sovereign'` mode. */
+    canAgentSwap?(): boolean;
+    /** Price a same-chain swap, read-only. Never throws for a read problem. */
+    quoteSwap?(req: SwapRequest): Promise<SwapQuote | null>;
+    /** Execute a quoted swap. Governed by `swapPolicy`, not by the payment caps. */
+    swap?(quote: SwapQuote): Promise<SwapReceipt>;
+    /** This wallet's own address — where it gets paid. `paymentTools()` defaults a
+     *  sold offer's `payTo` to it, so an agent never has to be told its own address. */
+    address?(): Promise<string>;
+    /** May a MODEL sell on this wallet — price offers and collect for them? Sovereign only. */
+    canAgentSell?(): boolean;
+    /** The chain this client is configured for — the default an offer is priced on. */
+    chain?(): ChainSelector;
+    /** What this wallet HOLDS, per asset — the balance sheet, distinct from the budget leash. */
+    balanceOf?(assets?: readonly string[]): Promise<WalletAssetBalance[]>;
+}
+/**
+ * One asset's holding, as {@link PipRailClient.balanceOf} reports it. A `null` amount means the
+ * read was UNAVAILABLE, never zero: an agent has to tell "I hold nothing" apart from "I could
+ * not find out", because acting on the second as if it were the first looks exactly like having
+ * been drained.
+ */
+interface WalletAssetBalance {
+    /** The symbol as the chain resolved it, or as asked for when the chain does not ship it. */
+    symbol: string;
+    /** The on-chain asset id, or `null` when this chain has no such token. */
+    asset: string | null;
+    decimals: number | null;
+    /** False when this chain does not ship this symbol. Reported, never guessed at. */
+    known: boolean;
+    /** Base units, or `null` when the read was unavailable. */
+    amount: string | null;
+    amountFormatted: string | null;
 }
 /**
  * The verdict from {@link PipRailClient.verifyReceipt} — a {@link PipRailReceipt}
@@ -5744,10 +6146,79 @@ declare class PipRailClient {
      *  count, cumulative spend per token, cumulative spend per denomination (the
      *  cross-token grand total), and the individual records. */
     spent(): SpendSummary;
+    /**
+     * 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.
+     */
+    private assertModeIsHonest;
     /** 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(): PaymentPolicy | undefined;
+    /**
+     * 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(): AgentMode;
+    /** The configured swap guardrails, read back unchanged. `undefined` when none is set. */
+    swapPolicy(): SwapPolicy | undefined;
+    /**
+     * 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(): ChainSelector;
+    /**
+     * 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.
+     */
+    balanceOf(assets?: readonly string[]): Promise<WalletAssetBalance[]>;
+    address(): Promise<string>;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
     /**
      * 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.
@@ -5807,6 +6278,43 @@ declare class PipRailClient {
      * resource is trivially "affordable"). No funds move.
      */
     canAfford(url: string, init?: RequestInit): Promise<boolean>;
+    /**
+     * Price a same-chain swap — "I hold the wrong token". READ-ONLY: no funds move,
+     * nothing is signed, nothing is committed to.
+     *
+     * ⚠️ **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".
+     */
+    quoteSwap(req: SwapRequest): Promise<SwapQuote | 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).
+     */
+    swap(quote: SwapQuote): Promise<SwapReceipt>;
     /**
      * Find payable resources on the OPEN x402 indexes — WITHOUT paying. Reads the
      * free indexes (CDP Bazaar + 402 Index by default), merges + dedupes them, and
@@ -6214,6 +6722,19 @@ declare class MultiChainPayer implements PayingClient {
     /** The CONFIGURED spend policy (the shared policy `fromWallets` applies to every chain;
      *  the first client's for the explicit constructor). `undefined` when none is set. */
     policy(): PaymentPolicy | undefined;
+    mode(): AgentMode;
+    canAgentSwap(): boolean;
+    canAgentSell(): boolean;
+    address(): Promise<string>;
+    chain(): ChainSelector;
+    /**
+     * 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?".
+     */
+    balanceOf(assets?: readonly string[]): Promise<WalletAssetBalance[]>;
+    quoteSwap(req: SwapRequest): Promise<SwapQuote | null>;
+    swap(quote: SwapQuote): Promise<SwapReceipt>;
 }
 
 /**
@@ -6320,7 +6841,7 @@ declare function describeChallenge(challenge: X402Challenge): string;
  * literally, so a wrong name or order actively misleads. A test pins the load-
  * bearing phrases.
  */
-declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## Landing cold \u2014 read the self-description\nEvery PipRail 402 self-describes. Read challenge.extensions.piprail for { name, what, pay[]\n(each rail's how-to-pay), sdk.install, mcp, docs } \u2014 never guess what an endpoint is. If your\ntooling can't pay a rail (e.g. a stock x402 client can't pay the onchain-proof scheme), the\nblock says how: install @piprail/sdk (npm i @piprail/sdk) or run the MCP (npx -y @piprail/mcp)\nand pay with the tools below.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to three rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM, Solana, Algorand, Aptos + NEAR, and the on-chain method (EIP-3009 / Permit2 / SVM /\n  Algorand fee-pooled group / Aptos fee-payer / NEAR SignedDelegateAction) is picked automatically.\n  XRPL also supports exact (native XRP), with ONE difference that matters to your budget: there the\n  PAYER pays the network fee, because on the XRP Ledger the fee lives inside the signed transaction.\n  So keep a little XRP for fees on that chain \u2014 everywhere else exact means you need no native coin.\n- upto (the metered/variable x402 rail, opt-in, EVM): the amount you see is a MAXIMUM \u2014 you sign\n  a ceiling, the server meters real usage and settles the ACTUAL (<= the max). BUDGET AGAINST THE MAX:\n  the plan/policy treat the ceiling as the spend (a server may charge up to it), so a payable plan\n  means the MAX fits your budget; the settled actual is recorded for reconciliation.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact/upto schemes are OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact,upto);\nyou can't enable them yourself, but you can report when a 402 needs one (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left: per (network,\nasset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much\nUSD you can still spend across every stablecoin and chain), the payment-count\nleash, the session time envelope, your spend so far, and the configured policy\nread back. Read-only; moves no funds. Use it in Mode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Per-payment + per-(network, asset) caps always apply. A cross-token GRAND TOTAL per\n  denomination (maxTotalPerDenom, e.g. \"$20 across every USD stablecoin + chain\") is\n  OPTIONAL \u2014 it sums tokens declared as one unit, each 1:1; it is NOT a price oracle and\n  never prices a volatile native coin. Payment-COUNT caps (maxPayments / per-window) also\n  span every chain + token.\n- The time envelope lives IN-MEMORY for THIS process (resets on restart). The money + count\n  totals also reset on restart UNLESS a durable spend store is configured \u2014 then they resume.\n- A refusal arrives as declined:true with a reasonCode; 'BUDGET' covers the lifetime, denom,\n  and count caps; 'OUTSIDE_WINDOW' covers both the rolling money and rolling count windows.\n";
+declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## Your tools, and which ones act\nYou always have these eight tools. Six are READ-ONLY and safe to call freely, two change\nsomething, and only ONE spends. In 'sovereign' mode you also hold the swap and seller tools\ndescribed later, so count your OWN list rather than trusting this number:\n- piprail_guide \u2014 this contract. Re-read it if you lose the thread. Read-only.\n- piprail_discover \u2014 find payable resources on the OPEN indexes (a phone book of x402 APIs),\n  without paying. Read-only.\n- piprail_quote_payment \u2014 the price of one URL. Read-only.\n- piprail_plan_payment \u2014 can I afford it NOW, on this wallet. Read-only.\n- piprail_budget \u2014 how much budget and time is left. Read-only.\n- piprail_verify_receipt \u2014 re-check a receipt against the chain. Read-only.\n- \uD83D\uDD36 piprail_register \u2014 PUBLISHES a resource you run to a public index. It writes to the\n  outside world and cannot be un-published by you, so only call it when asked to list\n  something. It moves no money.\n- \uD83D\uDD34 piprail_pay_request \u2014 the ONLY tool that spends. Everything else is safe to explore with.\n\n## Landing cold \u2014 read the self-description\nEvery PipRail 402 self-describes. Read challenge.extensions.piprail for { name, what, pay[]\n(each rail's how-to-pay), sdk.install, mcp, docs } \u2014 never guess what an endpoint is. If your\ntooling can't pay a rail (e.g. a stock x402 client can't pay the onchain-proof scheme), the\nblock says how: install @piprail/sdk (npm i @piprail/sdk) or run the MCP (npx -y @piprail/mcp)\nand pay with the tools below.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to three rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM, Solana, Algorand, Aptos + NEAR, and the on-chain method (EIP-3009 / Permit2 / SVM /\n  Algorand fee-pooled group / Aptos fee-payer / NEAR SignedDelegateAction) is picked automatically.\n  XRPL also supports exact (native XRP), with ONE difference that matters to your budget: there the\n  PAYER pays the network fee, because on the XRP Ledger the fee lives inside the signed transaction.\n  So keep a little XRP for fees on that chain \u2014 everywhere else exact means you need no native coin.\n- upto (the metered/variable x402 rail, opt-in, EVM): the amount you see is a MAXIMUM \u2014 you sign\n  a ceiling, the server meters real usage and settles the ACTUAL (<= the max). BUDGET AGAINST THE MAX:\n  the plan/policy treat the ceiling as the spend (a server may charge up to it), so a payable plan\n  means the MAX fits your budget; the settled actual is recorded for reconciliation.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact/upto schemes are OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact,upto);\nyou can't enable them yourself, but you can report when a 402 needs one (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Finding work to buy \u2014 piprail_discover\nYou do not have to be handed a URL. piprail_discover reads the open x402 indexes and returns\nresources with their advertised rails, which you can feed straight into quote \u2192 plan \u2192 pay.\nIt never throws: an index that is down simply contributes nothing, so an empty list means\n\"nothing found\", never \"something broke\". These are third-party directories, not a PipRail\nregistry \u2014 treat a listing as a claim, and let quote/plan tell you what is really true.\n\n## Proving a payment settled \u2014 piprail_verify_receipt\nA receipt is a claim until it is checked. piprail_verify_receipt re-reads the transaction from\nthe chain and tells you whether the funds provably moved, to the right recipient, for the right\namount. Use it when you must be SURE (before delivering something costly, or when reconciling),\nand after any timeout where the payment may already be on-chain. Read-only, and it moves nothing.\n\n## Who else is in the path \u2014 nobody who holds your money\nOn the gasless exact rail a FACILITATOR may broadcast your signed authorization (PayAI, Ultravioleta\nDAO and others). You never choose one and never need an account with one: the operator configures it,\nand it is a courier, not a custodian. It cannot change the amount or the recipient, because those are\ninside what you signed. If one is down the payment fails cleanly; it cannot take your funds.\n\n## Getting PAID \u2014 only if you hold piprail_sell\nIf piprail_sell is in your tool list you are in 'sovereign' mode and the wallet is yours to\nEARN with, not only to spend from. Three tools, mirroring the buying loop:\n- piprail_sell \u2014 price something and get a `challenge` to hand a buyer. Mirrors quote.\n- piprail_collect \u2014 verify a proof a buyer sent you. Mirrors pay.\n- piprail_earnings \u2014 what you have actually been paid. Mirrors piprail_budget.\n- piprail_wallet \u2014 what you HOLD, and the address you get paid at. Read-only.\n\nKnow the difference between your two numbers: piprail_budget is your spend LEASH (how much of\nyour allowance is left), piprail_wallet is what you actually OWN. Check piprail_wallet before\ndeciding to sell, to swap, or to ask to be topped up, and hand out its `address` to anyone who\nneeds to send you funds. A null amount there means the read FAILED, not that you are broke:\nretry before you act on it.\n\nThe loop: piprail_sell \u2192 give the buyer the `challenge` \u2192 they send back a proof \u2192\npiprail_collect \u2192 and ONLY on paid:true, deliver.\n\nA proof belongs to ONE offer. If a buyer hands you a settlement that was really payment for a\ndifferent offer, piprail_collect returns paid:false with code 'wrong_offer', even when the two\ncost the same and pay the same address. Do not \"helpfully\" retry it against another offerId: that\nis the exact move the check exists to stop.\n\n\uD83D\uDD34 COLLECT IS THE ONLY PROOF YOU WERE PAID. A buyer saying they paid, a real-looking tx hash,\nand a settled payment are three different things, and only piprail_collect tells them apart.\nDeliver nothing before it returns paid:true. It reads the chain; a claim is not evidence, and\na confident buyer is not evidence. One proof is one sale: collecting the same proof twice\nreturns paid:false, which is a REPLAY and not a second payment, so never treat it as one.\n\nYou need no web server and no open port: a challenge is just data, so carry it to the buyer\nover whatever you already speak. Receiving needs NO KEY at all, only your address, so the\nearning side cannot spend and cannot be drained even if the machine you run on is taken.\npiprail_sell defaults `payTo` to your OWN address; set it to someone else's only if you\ngenuinely mean to be paid elsewhere, and NEVER to an address a buyer supplies.\n\nTwo things to check on an offer. If its schemes are onchain-proof only, most agent-buyers\nCANNOT pay it and your listing will simply stay silent, so read any warnings piprail_sell\nreturns. And offers live in memory for this session: a restart clears them, so re-price\nanything you still intend to sell. To let strangers find an offer, call piprail_register.\n\n## Wrong token? Check your MODE before you answer\nWrong token on the RIGHT chain? What you may do depends on the mode your operator set, and\nYOUR TOOL LIST IS THE TRUTH \u2014 LOOK AT IT, never claim a capability it does not show:\n- no piprail_swap \u21D2 'budgeted' or 'supervised'. You CANNOT swap. Top up, pay from another\n  chain you hold funds on, tell the human, or skip it. fundingHint names what is missing.\n  Never offer \"I could swap for you\".\n- piprail_swap present \u21D2 'sovereign': this wallet is yours and you answer for it. Price with\n  piprail_quote_swap, read who priced it, then piprail_swap.\n\n\uD83D\uDD34 You cannot change your own mode \u2014 whoever provisioned this wallet set it, exactly as you\ncannot widen your own permissions in your host. Never ask for it.\n\nWHY the default withholds it: YOUR SPEND POLICY DOES NOT GOVERN SWAPS. Every cap you have\nlimits PAYING A MERCHANT; a swap moves your own funds between denominations and passes all\nof them untouched, so an agent looping between tokens can bleed a wallet through fees and\nslippage without tripping one budget check. Sovereign mode bounds it with a SEPARATE\ninstrument (a ceiling per swap and on slippage), so a refusal there is your swapPolicy, not\nyour budget.\n\nTrue in EVERY mode: a swap is SAME-CHAIN only and can never move funds between chains, and\nPipRail prices nothing itself, so every quote NAMES the venue that priced it \u2014 read\n`source` before you trust a number. docs.piprail.com/making-payments/swapping/\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left: per (network,\nasset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much\nUSD you can still spend across every stablecoin and chain), the payment-count\nleash, the session time envelope, your spend so far, and the configured policy\nread back. Read-only; moves no funds. Use it in Mode A to self-check before paying.\n\n## Two modes of CONSENT \u2014 a different axis from the mode above\nYour 'supervised'/'budgeted'/'sovereign' mode says what you may DO. This says how each\npayment is agreed. Both are in force at once, so read them together:\n- Mode A (headless \u2014 how 'budgeted' and 'sovereign' behave): you run FREE inside a pre-set\n  budget + time envelope. The policy IS the consent, and there is no per-payment prompt.\n  Stay inside it; piprail_budget shows what's left.\n- Mode B (supervised \u2014 how the 'supervised' mode behaves): the host may ask a human to\n  approve each payment. A decline/cancel/timeout comes back as declined:true\n  (reasonCode:'APPROVAL') \u2014 do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Per-payment + per-(network, asset) caps always apply. A cross-token GRAND TOTAL per\n  denomination (maxTotalPerDenom, e.g. \"$20 across every USD stablecoin + chain\") is\n  OPTIONAL \u2014 it sums tokens declared as one unit, each 1:1; it is NOT a price oracle and\n  never prices a volatile native coin. Payment-COUNT caps (maxPayments / per-window) also\n  span every chain + token.\n- The time envelope lives IN-MEMORY for THIS process (resets on restart). The money + count\n  totals also reset on restart UNLESS a durable spend store is configured \u2014 then they resume.\n- A refusal arrives as declined:true with a reasonCode; 'BUDGET' covers the lifetime, denom,\n  and count caps; 'OUTSIDE_WINDOW' covers both the rolling money and rolling count windows.\n";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;
 
@@ -7396,6 +7917,85 @@ declare function toWorker(gate: PaymentGate, serve: Serve): {
  */
 declare function proxyTo(origin: string): Serve;
 
+/**
+ * Swap coverage — the honest, chain-agnostic DATA map of what can swap where, who
+ * routes it, and the real mainnet transaction that proves each one works.
+ *
+ * PURE DATA: imports only the `Caip2` type from `x402.ts` — zero chain libraries
+ * (protocol layer, STANDARDS §1). Deliberately the same shape as `facilitators.ts`,
+ * because it is the same problem: an optional third party the user opts into, which
+ * must be named openly and must never be advertised beyond what we have proven.
+ *
+ * ── THE ADMISSION RULE (this is the whole point) ──────────────────────────────
+ * An entry earns its place ONLY after a real mainnet swap settled through it and the
+ * transaction was read back from a public node. Never seed from a documentation page,
+ * a coverage table, or a successful quote. A quote proves routing; only a transaction
+ * proves settlement.
+ *
+ * This rule exists because the facilitator registry learned it the hard way: it grew
+ * from `/supported` reads, nothing ever re-checked an entry, and on 2026-08-28 two of
+ * eleven seeded facilitators turned out to be dead hosts the SDK was still handing to
+ * callers. Same failure mode, same guard.
+ *
+ * ── TWO TIERS, AND THE DIFFERENCE MATTERS ─────────────────────────────────────
+ * `kind: 'protocol'` — the LEDGER ITSELF swaps. No third party exists to trust, no API
+ * key, no extra dependency, and no integrator fee is even expressible.
+ * `kind: 'provider'` — a named third-party router. Open and keyless, but you are
+ * trusting its contracts and its routing API as well as the chain.
+ *
+ * Never blur them in any surface that renders this data.
+ */
+
+/** A real mainnet swap, verified by reading the transaction back from a public node. */
+interface SwapProof {
+    network: Caip2;
+    /** Full transaction hash / digest. */
+    tx: string;
+    /** ISO date the swap settled. */
+    date: string;
+    /** Human summary, e.g. `'0.2652 XLM → 0.05 USDC'`. */
+    summary: string;
+    /** What this particular proof covers that the others do not. */
+    covers?: string;
+}
+/** One route that can swap, and the evidence that it does. */
+interface SwapProviderEntry {
+    /** Stable slug. Also the logo filename in `site/public/swaps/<id>.<ext>`. */
+    id: string;
+    name: string;
+    /** `'protocol'` = the ledger swaps, no third party. `'provider'` = a named router. */
+    kind: 'protocol' | 'provider';
+    /** Homepage, or the protocol's own documentation for a `'protocol'` entry. */
+    url: string;
+    /** Networks this route covers, every one of them live-probed. */
+    networks: readonly Caip2[];
+    /** True when it needs NO API key. Every shipped entry is keyless; this is asserted. */
+    keyless: boolean;
+    /** What the route costs, stated plainly. PipRail adds nothing on top, ever. */
+    fee: string;
+    /** How the swap actually happens, one line. */
+    mechanism: string;
+    /**
+     * Set ONLY when the route ships without a mainnet proof, naming the reason. Every other
+     * entry carries real transaction hashes; this makes the exception impossible to miss
+     * rather than letting an empty `proofs` array pass for evidence.
+     */
+    unproven?: string;
+    /** Real mainnet proofs. An entry with none must not ship. */
+    proofs: readonly SwapProof[];
+}
+/**
+ * 🔴 THE SOURCE OF TRUTH. The website data and the docs table are derived from this;
+ * nothing below is allowed a hand-maintained second copy (see `npm run sync`).
+ */
+declare const SWAP_PROVIDERS: readonly SwapProviderEntry[];
+/** Every route that can swap on `network`, or an empty array when none is known. */
+declare function swapProvidersFor(network: Caip2): readonly SwapProviderEntry[];
+/** Can PipRail swap on this network at all? */
+declare function canSwapOn(network: Caip2): boolean;
+/** Every network with a proven swap route, deduped and sorted for stable rendering. */
+declare function swappableNetworks(): readonly Caip2[];
+
 /**
  * Mode-B settlement: delegate a standard `exact` payment to a THIRD-PARTY x402
  * facilitator the MERCHANT chooses (Coinbase CDP, x402.org, or any). PipRail hosts
@@ -7477,6 +8077,18 @@ interface SettleViaFacilitatorInput extends FacilitatorConfig {
     };
     /** authorization.from, for the receipt's `payer`. */
     payerHint?: string;
+    /**
+     * The gated resource, from the merchant's own trusted config (never the client echo).
+     * x402 v2 facilitators may require it at the request root — Ultravioleta DAO refuses a
+     * v2 body without it (`data did not match any variant of untagged enum VerifyRequestEnvelope`),
+     * which silently blocked every non-EVM rail it settles. Omitted fields fall back to a
+     * neutral placeholder rather than being dropped, because the field is required, not optional.
+     */
+    resource?: {
+        url?: string;
+        description?: string;
+        mimeType?: string;
+    };
 }
 /**
  * Verify-then-settle a standard `exact` payment through a third-party facilitator.
@@ -8568,4 +9180,4 @@ interface McpPaymentTool {
  */
 declare function createMcpPaymentTool(options: McpPaymentToolOptions): McpPaymentTool;
 
-export { type A2AArtifact, type A2AExtensionDeclaration, type A2AMessage, type A2AMetadata, type A2APart, type A2APaymentHandler, type A2APaymentHandlerOptions, type A2APaymentStatus, type A2ATask, type A2ATaskRecord, type A2ATaskState, type A2ATaskStore, A2A_ERROR_KEY, A2A_EXTENSIONS_HEADER, A2A_PAYLOAD_KEY, A2A_RECEIPTS_KEY, A2A_REQUIRED_KEY, A2A_STATUS_KEY, A2A_X402_EXTENSION_URI_V01, A2A_X402_EXTENSION_URI_V02, type AcceptOption, AddressId, type AgentTool, type AlgorandToken, type AptosToken, AssetId, BRAND, BUILTIN_DENOMS, type BazaarExtension, type BuildExactParams, CHAINS, Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type CountStatus, DENOM_PRECISION, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DenomRemaining, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, type GateSelfTest, InsufficientFundsError, InvalidConfigError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, MCP_PAYMENT_META_KEY, MCP_PAYMENT_RESPONSE_META_KEY, type ManifestInput, MaxRetriesExceededError, type McpContentBlock, type McpPaymentMeta, type McpPaymentTool, type McpPaymentToolOptions, type McpToolCallParams, type McpToolResult, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_UPTO_WITNESS_TYPES, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, PaidReceipt, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type PaywallOptions, Permit2UptoPaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, PipRailReceipt, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, type ReceiptInput, type ReceiptOption, type ReceiptVerification, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type Serve, type SessionBudget, SettleOutcome, type SettleViaFacilitatorInput, SettlementError, SignedReceipt, type SolanaToken, SpendLedger, SpendRecord, type SpendRemaining, SpendStore, SpendSummary, type StellarToken, type SuiToken, type TipJarOptions, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UPTO_PROXY_CHAIN_IDS, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type UptoRailOption, VERIFY_CODE_TO_A2A_ERROR, VerifyErrorCode, type VerifyPaymentResult, VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, type WellKnownX402Item, type WellKnownX402Manifest, WrongChainError, WrongFamilyError, X402AcceptEntry, X402AnyAccept, X402Challenge, type X402DnsRecord, X402ExactAcceptEntry, type X402InvalidBody, X402Receipt, X402UptoAcceptEntry, X402_EXACT_PERMIT2_PROXY, X402_UPTO_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildEndpointInfo, buildExactAuthorization, buildMcpPaymentMeta, buildOpenApi, buildSelfDescription, buildWellKnownX402, buildWellKnownX402Manifest, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createA2APaymentHandler, createMcpPaymentTool, createPaymentGate, createPaywall, createTipJar, decorateOutcome, deliverReceipt, denomOf, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, fromA2APaymentPayload, fromA2APaymentRequired, fromMcpPayment, fromMcpPaymentRequired, fromMcpPaymentResponse, getDirectoryInfo, isMcpPaymentRequired, isPermit2ProxyChain, isUptoProxyChain, knownFacilitatorsFor, normalizeNetwork, parseExactRequirements, parseFacilitatorSupported, paymentTools, planAcross, proxyTo, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toA2AErrorCode, toA2APaymentFailed, toA2APaymentReceipts, toA2APaymentRequired, toFetchHandler, toInsufficientFundsError, toInvalidBody, toMcpPaymentRequired, toMcpPaymentResponse, toWorker, verify402IndexDomain };
+export { type A2AArtifact, type A2AExtensionDeclaration, type A2AMessage, type A2AMetadata, type A2APart, type A2APaymentHandler, type A2APaymentHandlerOptions, type A2APaymentStatus, type A2ATask, type A2ATaskRecord, type A2ATaskState, type A2ATaskStore, A2A_ERROR_KEY, A2A_EXTENSIONS_HEADER, A2A_PAYLOAD_KEY, A2A_RECEIPTS_KEY, A2A_REQUIRED_KEY, A2A_STATUS_KEY, A2A_X402_EXTENSION_URI_V01, A2A_X402_EXTENSION_URI_V02, AGENT_MODES, type AcceptOption, AddressId, type AgentMode, type AgentTool, type AlgorandToken, type AptosToken, AssetId, BRAND, BUILTIN_DENOMS, type BazaarExtension, type BuildExactParams, CHAINS, Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type CountStatus, DEFAULT_AGENT_MODE, DEFAULT_SLIPPAGE_BPS, DENOM_PRECISION, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DenomRemaining, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, type GateSelfTest, InsufficientFundsError, InvalidConfigError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, MAX_SLIPPAGE_BPS, MCP_PAYMENT_META_KEY, MCP_PAYMENT_RESPONSE_META_KEY, type ManifestInput, MaxRetriesExceededError, type McpContentBlock, type McpPaymentMeta, type McpPaymentTool, type McpPaymentToolOptions, type McpToolCallParams, type McpToolResult, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_UPTO_WITNESS_TYPES, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, PaidReceipt, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type PaywallOptions, Permit2UptoPaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, PipRailReceipt, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, type ReceiptInput, type ReceiptOption, type ReceiptVerification, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, SWAP_PROVIDERS, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type Serve, type SessionBudget, SettleOutcome, type SettleViaFacilitatorInput, SettlementError, SignedReceipt, type SolanaToken, SpendLedger, SpendRecord, type SpendRemaining, SpendStore, SpendSummary, type StellarToken, type SuiToken, type SwapPolicy, type SwapProof, type SwapProviderEntry, type SwapQuote, type SwapQuoteSource, type SwapReceipt, type SwapRequest, type SwapSide, type TipJarOptions, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UPTO_PROXY_CHAIN_IDS, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type UptoRailOption, VERIFY_CODE_TO_A2A_ERROR, VerifyErrorCode, type VerifyPaymentResult, VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, type WellKnownX402Item, type WellKnownX402Manifest, WrongChainError, WrongFamilyError, X402AcceptEntry, X402AnyAccept, X402Challenge, type X402DnsRecord, X402ExactAcceptEntry, type X402InvalidBody, X402Receipt, X402UptoAcceptEntry, X402_EXACT_PERMIT2_PROXY, X402_UPTO_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, applySlippage, buildBazaarExtension, buildEndpointInfo, buildExactAuthorization, buildMcpPaymentMeta, buildOpenApi, buildSelfDescription, buildWellKnownX402, buildWellKnownX402Manifest, buildX402DnsTxt, canSwapOn, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createA2APaymentHandler, createMcpPaymentTool, createPaymentGate, createPaywall, createTipJar, decorateOutcome, deliverReceipt, denomOf, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, fromA2APaymentPayload, fromA2APaymentRequired, fromMcpPayment, fromMcpPaymentRequired, fromMcpPaymentResponse, getDirectoryInfo, isMcpPaymentRequired, isPermit2ProxyChain, isUptoProxyChain, knownFacilitatorsFor, normalizeNetwork, parseExactRequirements, parseFacilitatorSupported, paymentTools, planAcross, proxyTo, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, resolveSlippageBps, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, summarizeSwap, swapProvidersFor, swappableNetworks, toA2AErrorCode, toA2APaymentFailed, toA2APaymentReceipts, toA2APaymentRequired, toFetchHandler, toInsufficientFundsError, toInvalidBody, toMcpPaymentRequired, toMcpPaymentResponse, toWorker, verify402IndexDomain };