@piprail/sdk 1.22.1 → 1.24.0

package/dist/index.d.ts

@@ -5204,6 +5204,22 @@ interface RegisterOptions {
      */
     attribution?: boolean;
 }
+/**
+ * The read-+-pay surface an agent toolkit needs — the methods {@link paymentTools}
+ * calls. BOTH {@link PipRailClient} (one chain) and {@link MultiChainPayer} (many
+ * chains, one per wallet) satisfy it, so `paymentTools` wraps either unchanged:
+ * point an MCP/LLM at one wallet or at a whole bundle without touching the tools.
+ */
+interface PayingClient {
+    discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
+    quote(url: string, init?: RequestInit): Promise<PipRailQuote | null>;
+    planPayment(url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+    get(url: string, init?: RequestInit): Promise<Response>;
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
+    spent(): SpendSummary;
+    budget(): SessionBudget;
+}
 declare class PipRailClient {
     private readonly opts;
     private readonly maxRetries;
@@ -5453,11 +5469,188 @@ declare class PipRailClient {
  * A {@link PipRailClient} is bound to one chain (its wallet); give this one client
  * per chain the agent funds and it runs each client's {@link PipRailClient.planPayment}
  * in parallel and merges the rails into one plan, ranked payable-first. `best` is a
- * payable rail; across different native coins there's no oracle to pick the
- * fiat-cheapest, so the tiebreak is the order `clients` were given (the agent's own
- * chain preference). Returns `null` only if the URL isn't gated for any client.
+ * payable rail. Across different native coins there's no oracle to compare gas costs,
+ * so it does NOT rank chains by fee against each other: `best` is the FIRST chain you
+ * pass in `clients` that can settle (your preference order); within a single chain it
+ * still prefers the cheapest-gas rail. Returns `null` only if the URL isn't gated for
+ * any client. Throws only if EVERY client fails to reach the resource (a total outage),
+ * mirroring a single client — a single chain being down just drops that chain.
  */
 declare function planAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+/**
+ * PAY across several single-chain clients — the EXECUTION counterpart to
+ * {@link planAcross}. Plans the URL on every client in parallel (keeping which
+ * client owns which rail), picks the rail `planAcross` names as `best` (the first
+ * funded chain you listed that can settle RIGHT NOW), and pays it on its owning
+ * client. So an agent that holds one wallet
+ * per chain pays whichever chain/token the merchant's 402 asks for — with no
+ * manual routing — while every payment still goes through that client's own
+ * spend policy, `onBeforePay` hook, retries, and replay-protection (this just
+ * calls the chosen client's {@link PipRailClient.fetch}).
+ *
+ * - A URL that needs no payment (no 402) is returned straight through.
+ * - When NO funded chain can settle it, throws {@link PaymentDeclinedError} with a
+ *   merged, per-chain funding hint — BEFORE any on-chain send.
+ *
+ * Selection matches {@link planAcross}: payable-first, and across different native
+ * coins (no price oracle) the FIRST chain you pass in `clients` that can settle wins
+ * (your preference); within a chain, the cheapest-gas rail. It normally pays the rail
+ * `planAcross` reports as `best`, but on a BEST-EFFORT basis — the owning client
+ * re-reads its balances/gas at pay time, so a change between planning and paying (a
+ * concurrent payment, RPC drift, the merchant returning a different 402) can make it
+ * pick another settleable rail ON THE SAME CHAIN, or decline; its spend policy +
+ * `onBeforePay` still gate whatever is actually paid. For the ergonomic object form,
+ * see {@link MultiChainPayer}.
+ *
+ * NOTE: this PROBES the URL with the caller's `init` (method + body) on each client to
+ * read the 402, so prefer it for GET / idempotent requests — a non-idempotent POST is
+ * sent once per client before the pay leg (the x402 gate returns 402 without acting,
+ * but the body is re-sent).
+ */
+declare function fetchAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<Response>;
+
+/**
+ * MultiChainPayer — one buyer, many wallets, pay whatever the merchant asks.
+ *
+ * A {@link PipRailClient} is bound to exactly ONE chain and ONE wallet (an EVM key
+ * can't sign a Solana tx, and vice-versa — that's enforced at bind time). So a
+ * buyer who wants to pay a 402 *whatever chain/token it demands* holds one key per
+ * chain. This is the ergonomic object that carries that bundle: give it a
+ * `{ chain → wallet }` map and it builds one client per chain, then exposes a single
+ * `fetch`/`get`/`post`/`plan`/`quote` that auto-routes to the first funded chain that
+ * can settle — no manual "which client owns this rail?" plumbing.
+ *
+ * It is a thin, chain-agnostic composition over the existing primitives — it adds
+ * NO new payment logic:
+ *   - `planPayment` → {@link planAcross} (merge every chain's plan, payable-first)
+ *   - `fetch`/`get`/`post` → {@link fetchAcross} (pay on the first chain that can settle)
+ * Every payment still runs through its owning client's own spend policy,
+ * `onBeforePay` hook, retries, and replay-protection. There is no cross-chain
+ * custody, no price oracle, and no backend: across chains it pays the FIRST one you
+ * list that can settle (your preference order — gas isn't comparable across coins);
+ * within a chain it picks the cheapest-gas rail.
+ *
+ * Because it implements {@link PayingClient}, the agent toolkit ({@link paymentTools})
+ * and the MCP server wrap it byte-identically to a single client.
+ */
+
+/**
+ * One wallet per chain you fund, keyed by chain selector. The KEY is a chain
+ * string (an EVM preset like `'base'`/`'bnb'`, or a non-EVM family
+ * `'solana'|'ton'|'tron'|'near'|'sui'|'aptos'|'algorand'|'stellar'|'xrpl'`); the
+ * VALUE is that family's {@link WalletInput}:
+ *
+ *   base/bnb/… → { privateKey }   solana → { secretKey }   ton/algorand → { mnemonic }
+ *   stellar → { secret }   xrpl → { seed }   near → { accountId, privateKey }
+ *
+ * One key per family — this map is how a single buyer carries the keys for every
+ * chain it's willing to pay on. (For a CUSTOM EVM chain configured by a viem
+ * `Chain` object, build the {@link PipRailClient} yourself and use
+ * `new MultiChainPayer([...clients])`.)
+ */
+interface MultiChainPayerOptions {
+    /** `{ chain → wallet }`. Iteration order is your chain PREFERENCE: across chains the
+     *  first one that can settle wins (there's no oracle to compare gas across coins). */
+    wallets: Record<string, WalletInput>;
+    /** Spend policy applied to EVERY chain's client. Each client still keeps its own
+     *  per-(network,asset) ledger — there is no cross-token sum (no price oracle). */
+    policy?: PaymentPolicy;
+    /** Per-chain RPC overrides, keyed by the same chain selector as `wallets`. */
+    rpcUrls?: Record<string, string>;
+    /** Which schemes every client may settle. Default `['onchain-proof']` (unchanged). */
+    schemes?: PaymentScheme[];
+    /** Final approval hook applied to every chain's client (fires before any send). */
+    onBeforePay?: (quote: PipRailQuote) => boolean | Promise<boolean>;
+    /** Observability hook applied to every chain's client. */
+    onEvent?: (event: PipRailEvent) => void;
+    /** Retry budget for the post-broadcast leg, per client. Default 3. */
+    maxPaymentRetries?: number;
+    /** Timeout (ms) for the retry leg, per client. Default 30_000. */
+    retryTimeoutMs?: number;
+}
+declare class MultiChainPayer implements PayingClient {
+    private readonly _clients;
+    /**
+     * Wrap an explicit, ordered set of single-chain clients — use this when a client
+     * needs full control (e.g. a custom EVM chain configured by a viem `Chain`). The
+     * ORDER is your chain preference: across chains the first that can settle wins. Pass
+     * at MOST one client per chain — two clients on the SAME network would double-count in
+     * `spent()`/`budget()` and waste a plan round-trip (`fromWallets` can't produce this).
+     * For the common case, prefer {@link MultiChainPayer.fromWallets}.
+     */
+    constructor(clients: PipRailClient[]);
+    /**
+     * Build one client per funded chain from a `{ chain → wallet }` map — the
+     * ergonomic path. The shared `policy`/`schemes`/`onBeforePay`/`onEvent` apply to
+     * every client; `rpcUrls` are matched per chain. Iteration order of `wallets` is
+     * the chain preference.
+     *
+     * ```ts
+     * const payer = MultiChainPayer.fromWallets({
+     *   wallets: {
+     *     base:    { privateKey: process.env.EVM_KEY! },
+     *     solana:  { secretKey:  process.env.SOLANA_SECRET! },
+     *     xrpl:    { seed:       process.env.XRPL_SEED! },
+     *   },
+     *   policy: { maxAmount: '1.00', maxTotal: '20.00', tokens: ['USDC', 'USDT'] },
+     * })
+     * const res = await payer.get('https://api.example.com/paid')  // pays on the first funded chain that can settle
+     * ```
+     */
+    static fromWallets(opts: MultiChainPayerOptions): MultiChainPayer;
+    /** The underlying single-chain clients, in preference order. Reach for one of
+     *  these for chain-specific reads (`estimateCost`, `discoverySigner`, per-chain
+     *  `budget()`) that don't make sense merged. */
+    get clients(): readonly PipRailClient[];
+    /** Plan a 402 across every funded chain — merged + ranked payable-first. `null`
+     *  when the URL needs no payment. (Delegates to {@link planAcross}.) */
+    planPayment(url: string, init?: RequestInit): Promise<PaymentPlan | null>;
+    /** Can ANY funded chain settle this URL right now? (A free resource is trivially
+     *  "affordable".) No funds move. */
+    canAfford(url: string, init?: RequestInit): Promise<boolean>;
+    /** Price a gated URL across funded chains — the chosen rail's quote (the first
+     *  funded chain that can settle), else the first offered rail's. `null` when the URL
+     *  needs no payment. When it IS
+     *  gated but none of your chains are offered, surfaces the same informative
+     *  `NoCompatibleAcceptError` a single client would (it names the chains the 402 is
+     *  payable on) rather than a misleading `null`. No funds move. */
+    quote(url: string, init?: RequestInit): Promise<PipRailQuote | null>;
+    /** Pay the first funded chain (in your listed order) that can settle this URL.
+     *  Delegates to {@link fetchAcross} — full policy / approval / retry / replay path on
+     *  the owning client. The owner re-reads balances at pay time, so the rail paid is the
+     *  surfaced `best` on a best-effort basis (it can pick another rail on the SAME chain,
+     *  or decline, if balances shift between plan and pay). PROBES the URL with `init`
+     *  (method + body) per client — prefer GET / idempotent requests. */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** GET that auto-pays across chains. */
+    get(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * POST that auto-pays across chains. `body` is a string/FormData/URLSearchParams/
+     * ArrayBuffer/Blob (sent as-is) or a plain object (serialised as JSON) — mirrors
+     * {@link PipRailClient.post}.
+     */
+    post(url: string, body?: BodyInit | object | undefined, init?: RequestInit): Promise<Response>;
+    /**
+     * Find payable resources across every funded chain. With the default
+     * `network: 'self'`, each chain's own results are merged + deduped by URL (so
+     * "self" means "any chain I can pay"). A network-scoped query (a CAIP-2 id or
+     * `'any'`) is chain-independent, so one client answers it. Never throws for a
+     * read problem; moves no funds.
+     */
+    discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
+    /** List a resource YOU run on the open indexes. Registration is a merchant action
+     *  independent of which chain you pay FROM, so it goes through your first chain's
+     *  client; pass `opts.network` to advertise a specific chain. Moves no funds. */
+    register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
+    /** Aggregate spend across every chain — counts summed; per-(network,asset) rows
+     *  and records concatenated (no cross-chain collisions, never a cross-token sum). */
+    spent(): SpendSummary;
+    /** A merged budget view: every chain's per-(network,asset) remaining rows, plus the
+     *  MOST-RESTRICTIVE session time envelope across chains (the soonest deadline wins).
+     *  Mirrors {@link PipRailClient.budget}'s shape so the agent toolkit reads it
+     *  unchanged; per-chain session detail is on each `clients[i].budget()`. */
+    budget(): SessionBudget;
+}
 
 /**
  * MCP-style tool annotations — optional, advisory hints that let an MCP client or
@@ -5514,7 +5707,7 @@ interface AgentTool {
  * declined? }`) — never a thrown error — so the model reasons about it (and never
  * re-pays a broadcast-but-unconfirmed payment) instead of crashing.
  */
-declare function paymentTools(client: PipRailClient): AgentTool[];
+declare function paymentTools(client: PayingClient): AgentTool[];
 
 /**
  * One line summarising a {@link PaymentPlan} for a model: what's payable, on which
@@ -5538,6 +5731,15 @@ declare function explainDecline(err: unknown): string;
  * convenience, not a durable ledger.
  */
 declare function formatSpendReport(summary: SpendSummary): string;
+/**
+ * One line a human or model can act on for a 402 challenge: what it is, the first
+ * rail's amount/token/chain + recipient, and how to pay it programmatically. Composes
+ * only shipped challenge fields (same `amountFormatted ?? amount` / `symbol ?? asset`
+ * convention as the renderers above) — pure, no I/O. Used as the human `instruction`
+ * inside the self-describe block and as a landing page's headline. An empty `accepts`
+ * (shouldn't happen for a valid v2 challenge) degrades to a generic pointer.
+ */
+declare function describeChallenge(challenge: X402Challenge): string;
 
 /**
  * The PipRail agent contract, distilled into one string an LLM can read once and
@@ -5550,7 +5752,7 @@ declare function formatSpendReport(summary: SpendSummary): 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## 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 two 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, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.\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 scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);\nyou can't enable it yourself, but you can report when a 402 needs it (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\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode 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- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\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## 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 two 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, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.\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 scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);\nyou can't enable it yourself, but you can report when a 402 needs it (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\n(network, asset), plus your spend so far. Read-only; moves no funds. Use it in\nMode 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- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014\n  budgets aren't summed across tokens (no price oracle).\n- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart\n  (a convenience, not a durable ledger).\n";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;
 
@@ -5588,6 +5790,104 @@ declare function classifyChallenge(challenge: X402Challenge, opts: {
     schemes: readonly PaymentScheme[];
 }): ChallengeTriage;
 
+/**
+ * Self-description — make a PipRail 402 announce WHAT it is and HOW to pay it, to
+ * humans, AI agents, and crawlers alike, on BOTH schemes. PURE: a builder that turns
+ * the `accepts[]` a gate already resolved into an inert, additive metadata block; it
+ * does NO I/O and imports NO chain library (protocol layer — STANDARDS §1, viem-free).
+ *
+ * The block rides at `challenge.extensions.piprail`, ALONGSIDE the rejection
+ * `{ code, detail }` (the gate deep-merges so neither clobbers the other). x402 v2
+ * treats `extensions` as an opaque bag a standard client ignores, so this is
+ * purely-additive: the pay path, `accepts[]`, headers, and status stay byte-identical.
+ *
+ * Its whole point: even an `onchain-proof`-only endpoint that a stock x402 client
+ * CANNOT pay is no longer invisible — a stranger reads `sdk.install`, runs
+ * `npm i @piprail/sdk`, pastes the snippet, and pays. For the non-EVM families that
+ * have NO standard `exact` rail, this block is the ENTIRE interop story, so the
+ * `onchain-proof` instruction is deliberately chain-agnostic.
+ *
+ * NOT WIRED here — this is the pure builder (discoverability plan, Phase 1). The gate
+ * wires it into every challenge in Phase 5 (default-on, with a `selfDescribe:false`
+ * opt-out that restores the byte-identical default).
+ */
+
+/**
+ * The canonical PipRail brand strings — the SINGLE source of truth for the install
+ * command, the paste-ready snippet, and the docs links, read by the self-describe
+ * block here, and (later phases) the landing page, the `llms.txt` entry, and the
+ * agent guide. `<your-chain>` / `<this-url>` are deliberate placeholders — never guess
+ * the reader's chain or URL.
+ */
+declare const BRAND: {
+    readonly name: "PipRail";
+    readonly home: "https://piprail.com";
+    readonly docs: "https://docs.piprail.com";
+    readonly payDocs: "https://docs.piprail.com/paying";
+    readonly sdkInstall: "npm i @piprail/sdk";
+    readonly sdkSnippet: string;
+    readonly mcpRun: "npx -y @piprail/mcp";
+};
+/**
+ * One payable rail as the self-describe block presents it — the static, agent- and
+ * human-readable view of an `accepts[]` entry (no nonce; this is long-lived metadata).
+ */
+interface SelfDescribeRail {
+    scheme: 'onchain-proof' | 'exact';
+    network: string;
+    asset: string;
+    payTo: string;
+    /** Amount in the token's base units (already scaled by decimals). */
+    amount: string;
+    /** Human-readable amount, e.g. "0.01", when the gate resolved one. */
+    amountFormatted?: string;
+    symbol?: string;
+    /** A one-line instruction for paying THIS rail — chain-agnostic for `onchain-proof`. */
+    how: string;
+}
+/** The `extensions.piprail` self-description block. Inert, purely-additive metadata. */
+interface SelfDescription {
+    name: 'PipRail';
+    protocol: 'x402';
+    version: '2';
+    /** One sentence: what this endpoint is. */
+    what: string;
+    /** Every rail the 402 offers, in the same order as `accepts[]`. */
+    pay: SelfDescribeRail[];
+    /** How to pay programmatically with the SDK. */
+    sdk: {
+        install: string;
+        snippet: string;
+    };
+    /** How to pay via the MCP server (for AI agents). */
+    mcp: {
+        run: string;
+        tool: string;
+    };
+    docs: {
+        home: string;
+        agents: string;
+        pay: string;
+    };
+    /** Where the open discovery artifacts live on this origin. */
+    discovery: {
+        openapi: string;
+        wellKnown: string;
+    };
+    /** A one-line human summary (the gate sets it from `describeChallenge`). */
+    instruction?: string;
+}
+/**
+ * Build the `extensions.piprail` self-describe block from a challenge's resolved
+ * `accepts[]`. PURE — every rail is derived from data the gate already has (no new
+ * data, no I/O). `instruction` is the optional one-line human summary the gate computes
+ * via `describeChallenge` (in `render.ts`) and passes in.
+ */
+declare function buildSelfDescription(input: {
+    accepts: X402AnyAccept[];
+    instruction?: string;
+}): SelfDescription;
+
 /**
  * Discovery — make a gated resource FINDABLE, by emitting the open-standard
  * artifacts a crawler/index reads. PURE: this file turns the config a gate
@@ -5670,6 +5970,28 @@ interface ManifestInput {
 }
 /** What `x-generator` stamps when attribution is on — see {@link ManifestInput.attribution}. */
 declare const GENERATOR = "@piprail/sdk \u00B7 https://piprail.com";
+/**
+ * The "powered by" marker for the `x-powered-by` HTTP header — the response-side twin of the
+ * `/openapi.json` {@link GENERATOR} stamp. Inert metadata; opt out with `attribution:false`.
+ * **ASCII-only on purpose:** this is an HTTP header value, and Node's `setHeader` writes header
+ * values as latin1 — a non-ASCII separator (e.g. `·` U+00B7) would arrive mangled (`·`) and is
+ * RFC-7230-discouraged. {@link GENERATOR} keeps its `·` because it only lands in UTF-8 JSON bodies.
+ */
+declare const POWERED_BY = "PipRail x402 | https://piprail.com";
+/**
+ * Machine-readable discovery pointers for a gated endpoint's HTTP responses — a `Link` header
+ * (RFC 8288) pointing crawlers/agents at the discovery docs, plus a tasteful `x-powered-by`
+ * marker. Spread the result into BOTH the 402 challenge response AND the 200 settlement
+ * response, so a payer / agent / crawler learns what served them on every hit (this is also
+ * how the 200 "receipt" self-advertises — no change to the `X402Receipt` body needed). PURE —
+ * returns a header bag the merchant sets; the SDK serves nothing. `attribution:false` omits
+ * `x-powered-by` (parity with the `x-generator` opt-out on the OpenAPI doc). If you already set
+ * a `Link` header, comma-merge it with this one rather than blindly spreading (object spread
+ * would replace it).
+ */
+declare function discoveryHeaders(opts?: {
+    attribution?: boolean;
+}): Record<string, string>;
 /** A minimal, valid OpenAPI 3.1 document carrying `x-payment-info` per paid op. */
 interface OpenApiDocument {
     openapi: '3.1.0';
@@ -5940,6 +6262,17 @@ interface RequirePaymentOptions {
      * challenge byte-identical to before.
      */
     discovery?: boolean | DiscoveryDescriptor;
+    /**
+     * Self-describe every 402 — stamp an `extensions.piprail` block (identity · per-rail
+     * how-to-pay · `npm i @piprail/sdk` + snippet · MCP · docs + discovery pointers) so the
+     * instant any human, AI agent, or crawler lands on this endpoint — even the default
+     * `onchain-proof` scheme a stock x402 client can't pay — it knows what it is and how to
+     * pay it. **Default `true`.** It is purely-additive metadata a standard client ignores
+     * (the spec treats `extensions` as opaque), so the pay path, `accepts[]`, headers, and
+     * status are byte-identical. Set `false` to omit the block entirely (the literal
+     * byte-identical default of before this feature). See {@link buildSelfDescription}.
+     */
+    selfDescribe?: boolean;
 }
 type VerifyPaymentResult = {
     kind: 'paid';
@@ -6003,6 +6336,13 @@ interface PaymentGate {
      * discovery metadata is long-lived. Read-only — moves nothing on-chain.
      */
     describe(resourceUrl?: string): Promise<ResourceDescription>;
+    /**
+     * Render a self-describing HTML page for a challenge — for the HUMAN who opens the gated
+     * URL in a browser. Pass the challenge you already built with {@link PaymentGate.challenge};
+     * serve the result with `content-type: text/html` when the request's `Accept` is `text/html`.
+     * The SDK never serves it itself (headless by charter). Agents/crawlers keep the JSON 402.
+     */
+    landingPage(challenge: X402Challenge): string;
 }
 /**
  * Framework-agnostic core. Build one gate per gated resource and reuse it
@@ -6062,6 +6402,28 @@ interface FacilitatorPaymentRequirements {
     maxTimeoutSeconds: number;
     extra: Record<string, unknown>;
 }
+/** One (scheme, network) pair a facilitator's `GET /supported` advertises. */
+interface FacilitatorSupportedKind {
+    scheme: string;
+    /** As the facilitator reports it — a CAIP-2 id or a slug. */
+    network: string;
+    /** The fee-payer pubkey when the kind carries one (SVM rails). */
+    feePayer?: string;
+}
+/**
+ * Parse a facilitator `/supported` body into its advertised (scheme, network) kinds.
+ * PURE + tolerant: a malformed body yields `[]`. Mirrors the `{ kinds: [...] }` shape
+ * {@link fetchFacilitatorFeePayer} reads. Useful for verifying coverage before wiring a gate,
+ * and for generating the coverage doc from live reads.
+ */
+declare function parseFacilitatorSupported(body: unknown): FacilitatorSupportedKind[];
+/**
+ * Read a facilitator's LIVE coverage from `GET /supported`. Best-effort + bounded (an
+ * `AbortController` timeout): NEVER throws — returns `[]` on any failure (same posture as
+ * {@link fetchFacilitatorFeePayer}). Lets an operator/agent ask "does this facilitator
+ * cover my network?" before wiring a gate. Pure `fetch`, no chain libraries (STANDARDS §1).
+ */
+declare function facilitatorCoverage(url: string, timeoutMs?: number): Promise<FacilitatorSupportedKind[]>;
 /** A merchant-chosen facilitator: its base URL + optional per-request auth headers. */
 interface FacilitatorConfig {
     /** Base URL, e.g. 'https://x402.org/facilitator' (trailing slash stripped). */
@@ -6094,6 +6456,51 @@ interface SettleViaFacilitatorInput extends FacilitatorConfig {
  */
 declare function settleViaFacilitator(input: SettleViaFacilitatorInput): Promise<VerifyResult>;
 
+/**
+ * Facilitator coverage — the honest, chain-agnostic DATA map of which third-party x402
+ * facilitators settle the `exact` scheme on which networks. PURE DATA: imports only the
+ * `Caip2` type from `x402.ts` — zero chain libraries (protocol layer, STANDARDS §1).
+ *
+ * Why it exists: the `exact: true` shorthand (discoverability plan, Phase 7) and an
+ * operator picking a facilitator both need to know "is there a known KEYLESS facilitator
+ * for my chain?" — WITHOUT a hosted registry (charter: no backend). This map is the SEED;
+ * the live truth is `facilitatorCoverage(url)` in `facilitator.ts`, which reads a
+ * facilitator's `GET /supported`. The map is grown ONLY from a verified `/supported`
+ * read — every entry carries a dated verification comment, never a guess.
+ */
+
+/** One facilitator known to settle `exact` on a given network. */
+interface KnownFacilitator {
+    /** Base URL (no trailing slash), e.g. `https://facilitator.payai.network`. */
+    url: string;
+    /** True when it needs NO API key — buyer AND merchant pay zero gas (the facilitator sponsors it). */
+    keyless: boolean;
+    /** The x402 schemes it settles (today only `exact`). */
+    schemes: ReadonlyArray<'exact'>;
+    /** The exact transfer methods it can settle on this network. */
+    settles: ReadonlyArray<'eip3009' | 'permit2' | 'svm'>;
+    /** A short human note (who it is / caveat). */
+    note?: string;
+}
+/**
+ * Seed map: CAIP-2 network → facilitators that settle `exact` there. Deliberately
+ * CONSERVATIVE — only endpoint-verified entries. Extend it only after a live
+ * `facilitatorCoverage()` read confirms a new (facilitator, network) pair. A merchant on
+ * a network not listed here passes an explicit `exact: { settle: { facilitator } }`.
+ *
+ * NOTE: `x402.org/facilitator` is intentionally ABSENT — it is a Base **Sepolia** testnet
+ * facilitator (verified), not a mainnet rail; seeding it would be a false coverage claim.
+ */
+declare const KNOWN_FACILITATORS: Readonly<Record<Caip2, ReadonlyArray<KnownFacilitator>>>;
+/** Known facilitators for a network — an empty array when none is seeded. */
+declare function knownFacilitatorsFor(network: Caip2): ReadonlyArray<KnownFacilitator>;
+/**
+ * The first KEYLESS facilitator that settles `exact` on `network` (optionally for a
+ * specific transfer `method`). Returns `undefined` when none is known — the `exact: true`
+ * shorthand branches on that to throw a coverage-specific guidance error.
+ */
+declare function firstKeylessFacilitator(network: Caip2, method?: 'eip3009' | 'permit2' | 'svm'): KnownFacilitator | undefined;
+
 /**
  * Reliable receipt delivery — the durable webhook a stateless gate can't be.
  *
@@ -6793,4 +7200,28 @@ declare const PERMIT2_WITNESS_TYPES: {
     }];
 };
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+/**
+ * Landing page — a tiny, self-contained HTML representation of a 402, for the HUMAN
+ * who opens a gated URL in a browser (agents/crawlers still get the unchanged JSON 402).
+ * PURE string templating; imports only the `SelfDescription` type — zero I/O, zero chain
+ * libraries (protocol layer, STANDARDS §1).
+ *
+ * The SDK NEVER serves this itself (it's headless by charter). The merchant opts in by
+ * branching on the request's `Accept` header in their own handler and returning this
+ * string with `content-type: text/html`. See `gate.landingPage(challenge)`.
+ *
+ * SECURITY: every interpolated field is HTML-escaped (a `payTo` / instruction can be
+ * merchant- or rail-influenced) — global rule: escape all user-/data-influenced content.
+ */
+
+/**
+ * Render a self-describing HTML 402 landing page from a {@link SelfDescription}. Leads with the
+ * one-line instruction and a prominent CAUTION — payment must go through an x402 client; a manual
+ * send to the address won't unlock the resource and isn't matched to the request (it lands in the
+ * merchant's wallet uncredited). Then the primary "How to pay" (the `npm i @piprail/sdk` install +
+ * paste-ready snippet + MCP command), and finally the per-rail "Payment details" table (scheme ·
+ * chain · amount · settles-to) for transparency. Fully static — no script, no external asset.
+ */
+declare function renderLandingPage(sd: SelfDescription): string;
+
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };