@piprail/sdk 1.9.0 → 1.11.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as viem_zksync from 'viem/zksync';
 import * as abitype from 'abitype';
 import * as viem_chains from 'viem/chains';
 import * as viem from 'viem';
-import { Chain, Account, Hex } from 'viem';
+import { Chain, Account, Hex, PublicClient } from 'viem';
 
 /**
  * The on-the-wire payment protocol. Self-contained — it runs entirely
@@ -40,6 +40,8 @@ type AddressId = string;
 interface X402ResourceObject {
     url: string;
     description?: string;
+    /** The resource's response content-type, e.g. 'application/json' (v2 ResourceInfo, optional). */
+    mimeType?: string;
 }
 interface X402AcceptEntry {
     scheme: 'onchain-proof';
@@ -63,11 +65,55 @@ interface X402AcceptEntry {
         symbol?: string;
     };
 }
+/**
+ * A standard x402 `exact` rail (EVM / EIP-3009) — the interop rail a PipRail gate
+ * advertises ALONGSIDE its `onchain-proof` rail (dual-advertise) so any standard
+ * x402 client can pay it. Same v2 PaymentRequirements skeleton as
+ * {@link X402AcceptEntry}; only `scheme` and `extra` differ. The `extra` carries
+ * the EIP-712 domain a payer signs over — `name`/`version` are READ from the token
+ * contract by the gate (never assumed), since e.g. USDC's domain name is "USD Coin",
+ * not the "USDC" symbol.
+ */
+interface X402ExactAcceptEntry {
+    scheme: 'exact';
+    network: Caip2;
+    amount: string;
+    asset: AssetId;
+    payTo: AddressId;
+    maxTimeoutSeconds: number;
+    extra: {
+        /** The exact-EVM transfer method. PipRail self-settles EIP-3009 today. */
+        assetTransferMethod: 'eip3009';
+        /** EIP-712 domain name of the token (USDC: "USD Coin"; EURC: "EURC"). Read on-chain. */
+        name: string;
+        /** EIP-712 domain version of the token (USDC/EURC: "2"). Read on-chain. */
+        version: string;
+        /** Confirmations the gate waits for before granting access — mirrors the gate's
+         *  `minConfirmations`, so the exact rail honours the same reorg safety as onchain-proof.
+         *  A PipRail convenience (standard clients ignore unknown keys). */
+        minConfirmations?: number;
+        /** Token decimals — a PipRail convenience (standard clients ignore unknown keys). */
+        decimals?: number;
+        /** Human-readable amount, e.g. "0.05" — a PipRail convenience. */
+        amountFormatted?: string;
+        symbol?: string;
+    };
+}
+/** A challenge `accepts[]` entry — either PipRail's `onchain-proof` rail or a standard `exact` rail. */
+type X402AnyAccept = X402AcceptEntry | X402ExactAcceptEntry;
 interface X402Challenge {
     x402Version: 2;
-    error: string | null;
+    /**
+     * Optional human-readable reason (v2 `error?: string`). PipRail EMITS it only on a
+     * rejected-proof re-challenge (omitted on a fresh challenge). Typed to also tolerate
+     * `null` when PARSING a foreign challenge — some deployed servers send `error: null`.
+     */
+    error?: string | null;
     resource: X402ResourceObject;
-    accepts: X402AcceptEntry[];
+    accepts: X402AnyAccept[];
+    /** v2 optional extensions. PipRail stamps the machine-readable rejection reason here on a
+     *  rejected-proof re-challenge: `{ piprail: { code, detail } }`. Omitted otherwise. */
+    extensions?: Record<string, unknown>;
 }
 interface X402PaymentSignature {
     x402Version: 2;
@@ -86,8 +132,43 @@ interface X402PaymentSignature {
         txHash: string;
     };
 }
+/**
+ * The EIP-3009 authorization a payer signs for a standard `exact` rail. All
+ * numeric fields are DECIMAL strings on the wire (value, validAfter, validBefore);
+ * `nonce` is a 0x-prefixed 32-byte hex. Identical shape across x402 v1 and v2.
+ */
+interface ExactAuthorizationWire {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+/** The `payload` a client sends for an `exact` rail: an EIP-3009 signature + its authorization. */
+interface ExactPaymentPayload {
+    signature: string;
+    authorization: ExactAuthorizationWire;
+}
+/**
+ * What {@link parseExactPaymentHeader} extracts from an inbound `exact` payment,
+ * normalised across the v1 (`X-PAYMENT`, flat `{scheme,network,payload}`, network
+ * slug) and v2 (`PAYMENT-SIGNATURE`, `{accepted,payload}`, CAIP-2 network) wire
+ * shapes. `network`/`asset` are the CLIENT's claim — used only to MATCH an offered
+ * rail; the gate re-derives every verified field from its own trusted rail.
+ */
+interface ParsedExactPayment {
+    x402Version: number;
+    /** The client's claimed network (slug or CAIP-2) — for matching, not trust. */
+    network: string;
+    /** The client's claimed asset, if present (v2 `accepted.asset`). */
+    asset?: string;
+    payload: ExactPaymentPayload;
+    /** The full decoded PaymentPayload, for verbatim forwarding to a facilitator (Mode B). */
+    raw: Record<string, unknown>;
+}
 interface X402Receipt {
-    scheme: 'onchain-proof';
+    scheme: 'onchain-proof' | 'exact';
     /**
      * x402 v2 SettlementResponse: settlement succeeded. Always `true` here — a
      * failed verification returns a 402, never a receipt.
@@ -122,7 +203,7 @@ interface X402Receipt {
  * `maxPaymentRetries` (a short backoff absorbs RPC lag); it does not branch on
  * the code.
  */
-type VerifyErrorCode = 'tx_not_found' | 'insufficient_confirmations' | 'tx_reverted' | 'no_meta' | 'wrong_recipient' | 'amount_too_low' | 'transfer_not_found' | 'payment_expired' | 'tx_already_used';
+type VerifyErrorCode = 'tx_not_found' | 'insufficient_confirmations' | 'tx_reverted' | 'no_meta' | 'wrong_recipient' | 'amount_too_low' | 'transfer_not_found' | 'payment_expired' | 'tx_already_used' | 'signature_invalid';
 /** The shape every driver's `verify()` returns. Shared by drivers + protocol. */
 type VerifyResult = {
     ok: true;
@@ -132,6 +213,11 @@ type VerifyResult = {
     error: VerifyErrorCode;
     detail: string;
 };
+declare const HEADER_REQUIRED = "payment-required";
+declare const HEADER_SIGNATURE = "payment-signature";
+declare const HEADER_RESPONSE = "payment-response";
+declare const HEADER_SIGNATURE_V1 = "x-payment";
+declare const HEADER_RESPONSE_V1 = "x-payment-response";
 declare function buildChallengeHeader(challenge: X402Challenge): string;
 declare function buildReceiptHeader(receipt: X402Receipt): string;
 declare function buildSignatureHeader(signature: X402PaymentSignature): string;
@@ -144,6 +230,15 @@ declare function parseChallenge(response: Response): Promise<X402Challenge | nul
 declare function parseReceipt(response: Response): X402Receipt | null;
 /** Parse a PAYMENT-SIGNATURE header value (server side). */
 declare function parseSignatureHeader(value: string): X402PaymentSignature | null;
+/**
+ * Parse an inbound `exact` payment from a base64 header value (`PAYMENT-SIGNATURE`
+ * v2 or `X-PAYMENT` v1). Tolerant of BOTH wire shapes — the inner
+ * `{ signature, authorization }` payload is identical across versions, so we read
+ * `scheme`/`network` from either the v2 `accepted` object or the v1 flat fields.
+ * Returns null when the value isn't a recognisable `exact` payment (e.g. it's an
+ * `onchain-proof` proof, or malformed).
+ */
+declare function parseExactPaymentHeader(value: string): ParsedExactPayment | null;
 /**
  * Pick the first accepts[] entry on the `onchain-proof` scheme whose network
  * satisfies `matches` (any chain family). Returns null if none match.
@@ -4068,6 +4163,38 @@ interface ResolvedNetwork {
     discoverySigner?(wallet: WalletHandle): DiscoverySigner | null;
     /** Verify `ref` satisfies `accept`, RPC-only, in-process. */
     verify(ref: string, accept: X402AcceptEntry): Promise<VerifyResult>;
+    /**
+     * OPTIONAL (EVM-only today) — the on-chain EIP-712 domain `{ name, version }` of an
+     * EIP-3009 token `asset`, read from the contract (`name()`/`version()`). Returns
+     * `null` when the asset is NOT an EIP-3009 token (no `transferWithAuthorization` —
+     * e.g. USDT, native coin, or a plain ERC-20), so the gate can refuse to advertise a
+     * standard `exact` rail for it. Never derived from the symbol (USDC's domain name is
+     * "USD Coin", not "USDC"; EURC's is "EURC"). Called once at exact-rail resolution
+     * (cached by the gate). RPC-read; may throw on a transient read (the gate surfaces a
+     * clear config error). The first of two optional server methods for the `exact` rail.
+     */
+    exactDomain?(asset: string): Promise<{
+        name: string;
+        version: string;
+    } | null>;
+    /**
+     * OPTIONAL (EVM-only today) — verify a standard x402 `exact` (EIP-3009) payment
+     * locally, then SELF-SETTLE it by broadcasting `transferWithAuthorization` from the
+     * merchant's own `relayer` wallet (the merchant pays gas to receive; the signature
+     * binds `to`, so no redirect risk). RETURNS a `VerifyResult`:
+     *   - `{ ok:false, error }` for a CLIENT-fixable fault (bad signature, expired,
+     *     wrong recipient/amount, used nonce, simulation revert) → gate replies 402;
+     *   - `{ ok:true, receipt }` once the settle tx is mined.
+     * THROWS {@link SettlementError} when a VALID + simulated payment fails to BROADCAST
+     * (relayer out of gas / RPC down) → gate replies 5xx (the payer's authorization is
+     * still good and its nonce unused). Re-derives every checked field from the trusted
+     * `accept`, never the client echo.
+     */
+    settleExactSelf?(input: {
+        relayer: WalletHandle;
+        payload: ExactPaymentPayload;
+        accept: X402ExactAcceptEntry;
+    }): Promise<VerifyResult>;
 }
 interface ResolveOptions {
     /** The developer-supplied `chain` selector. */
@@ -4107,6 +4234,14 @@ interface DiscoveredResource {
     /** The payment options the index advertises (best-effort, cross-scheme). */
     rails: DiscoveredRail[];
 }
+/** Where a listing stands after a register attempt — a branchable lifecycle
+ *  state so an agent doesn't have to re-derive each index's behaviour:
+ *  - `'live'`           — findable now (search it immediately).
+ *  - `'pending-review'` — accepted, but the index reviews/propagates before it's
+ *                         publicly findable; allow a short delay before `discover()`.
+ *  - `'not-listable'`   — it didn't list (a failure, or this index structurally
+ *                         can't list a PipRail resource). See `detail` + `note`. */
+type ListingVisibility = 'live' | 'pending-review' | 'not-listable';
 /** The result of trying to list a resource on one open index. */
 interface RegisterOutcome {
     source: DiscoverySource;
@@ -4117,6 +4252,14 @@ interface RegisterOutcome {
     detail?: string;
     /** A link to the listing, when the index returns one. */
     listingUrl?: string;
+    /** The lifecycle state of this listing — `'live'`, `'pending-review'`, or
+     *  `'not-listable'`. Projected from {@link DIRECTORY_INFO}; branch on this
+     *  instead of guessing how soon `discover()` will find the resource. */
+    visibility?: ListingVisibility;
+    /** A one-line, agent-readable caveat for this source (from {@link DIRECTORY_INFO})
+     *  — e.g. "402 Index reviews before publishing" or "discover() doesn't read
+     *  x402scan, so a live listing there won't appear in discover() results". */
+    note?: string;
 }
 interface SearchOpenIndexesOptions {
     /** Free-text query (filtered client-side against name/description/resource). */
@@ -4148,6 +4291,48 @@ interface RegisterInput {
      */
     attribution?: boolean;
 }
+/**
+ * Static, agent-readable lifecycle facts about one open index — the SINGLE source
+ * of truth that {@link RegisterOutcome.visibility}/`note` are projected from, and
+ * that an agent can also query directly (via {@link getDirectoryInfo}) to reason
+ * about an index BEFORE calling. Best-effort: an index can change its behaviour,
+ * so treat the timing as guidance, not an SLA.
+ */
+interface DirectoryInfo {
+    source: DiscoverySource;
+    /** How a new listing is gated: a synchronous URL probe (`402index`, `x402scan`),
+     *  or coupled to a facilitator settling a payment (`bazaar`). */
+    review: 'probe-sync' | 'settle-coupled';
+    /** Auth needed to WRITE a listing. */
+    auth: 'none' | 'siwx' | 'facilitator-only';
+    /** Chains (CAIP-2) this index will list. `null` = any chain the resource advertises. */
+    chains: readonly string[] | null;
+    /** Visibility a SUCCESSFUL listing reaches here (the steady state a non-failed
+     *  outcome maps to). */
+    onSuccess: ListingVisibility;
+    /** Whether THIS SDK's {@link PipRailClient.discover} reads this index. It reads
+     *  `bazaar` + `402index`; it does NOT read `x402scan` — so a live x402scan listing
+     *  won't appear in `discover()` results. Don't read that absence as failure. */
+    readByDiscover: boolean;
+    /** One-line caveat: why a register might fail, or what to expect afterwards. */
+    caveat: string;
+}
+/**
+ * The open directories' lifecycle, as one queryable map. An agent can branch on
+ * this without embedding directory knowledge: `DIRECTORY_INFO[source].readByDiscover`,
+ * `.chains`, `.onSuccess`, etc. {@link PipRailClient.register} projects the relevant
+ * entry onto every {@link RegisterOutcome} (`visibility` + `note`).
+ */
+declare const DIRECTORY_INFO: Readonly<Record<DiscoverySource, DirectoryInfo>>;
+/** Lifecycle facts for one open index (auth, chains, how soon a listing is
+ *  findable, whether `discover()` reads it). See {@link DIRECTORY_INFO}. The param
+ *  is the closed {@link DiscoverySource} union (TS callers are safe); a string
+ *  outside it returns `undefined` at runtime. */
+declare function getDirectoryInfo(source: DiscoverySource): DirectoryInfo;
+/** Project the static {@link DIRECTORY_INFO} lifecycle facts onto a register
+ *  outcome, so an agent gets `visibility` + `note` in the result it already holds —
+ *  no second lookup. A failed outcome is always `'not-listable'`. Idempotent. */
+declare function decorateOutcome(o: RegisterOutcome): RegisterOutcome;
 /** Normalize an index's network field to CAIP-2 when we recognise the slug;
  *  pass a value that's already CAIP-2 (`namespace:reference`) through unchanged.
  *  An unknown slug returns unchanged (no `:`), which the client treats as
@@ -4161,8 +4346,11 @@ declare function normalizeNetwork(network: string): string;
 declare function searchOpenIndexes(opts?: SearchOpenIndexesOptions): Promise<DiscoveredResource[]>;
 /**
  * Register a resource on **402 Index** — the primary, friction-free path: a
- * single POST, no auth, no signature, no payment. Searchable within seconds.
- * Returns a structured outcome; never throws for an HTTP/transport problem.
+ * single POST, no auth, no signature, no payment. A self-registered listing is
+ * **pending review** (not searchable until approved — verify your domain on
+ * 402index.io for instant approval). Returns a structured outcome; never throws
+ * for an HTTP/transport problem. NOTE: the outcome is BARE — `visibility`/`note`
+ * are added by {@link PipRailClient.register} (or call {@link decorateOutcome}).
  */
 declare function register402Index(input: RegisterInput): Promise<RegisterOutcome>;
 /**
@@ -4170,7 +4358,9 @@ declare function register402Index(input: RegisterInput): Promise<RegisterOutcome
  * EIP-4361 challenge with the merchant's own key, resend with the
  * `SIGN-IN-WITH-X` header. Facilitator-free, but **Base/Solana-only** and EVM
  * signing today. EXPERIMENTAL — the open SIWX handshake is a moving convention;
- * validate against x402scan before relying on it. Never throws.
+ * validate against x402scan before relying on it. Never throws. NOTE: returns a
+ * BARE outcome — `visibility`/`note` are added by {@link PipRailClient.register}
+ * (or call {@link decorateOutcome}).
  */
 declare function registerX402Scan(input: {
     url: string;
@@ -4623,19 +4813,40 @@ declare class PipRailClient {
      *
      * Nothing PipRail-hosted: these are third-party open directories. Never throws
      * for a read problem — an index that's down or changed simply contributes
-     * nothing. Honest caveat: index results are cross-scheme (mostly the
-     * mainstream `exact` scheme); `fetch()` pays only `onchain-proof` rails
-     * directly (pay `exact` resources with the experimental `drivers/evm/exact.ts`).
+     * nothing. Honest caveats (see {@link DIRECTORY_INFO}):
+     * - Reads **`bazaar` + `402index`** only — **NOT `x402scan`** (its reads are paid). A
+     *   resource you registered on x402scan is live there but will NOT appear here; don't
+     *   read that absence as failure. (Passing `sources:['x402scan']` explicitly yields `[]`.)
+     * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
+     *   before publishing, so retry with a brief backoff if a fresh listing is missing.
+     * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
+     *   only `onchain-proof` rails directly (pay `exact` resources with the experimental
+     *   `drivers/evm/exact.ts`).
      */
     discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
     /**
      * List a resource you run on the OPEN x402 registries, so agents can find it.
-     * Default target is **402 Index** — one POST, no auth, no signature, no payment
-     * (searchable within seconds). Add `'x402scan'` to also register via SIWX (one
-     * wallet signature; EVM + a Base/Solana rail). Returns one {@link RegisterOutcome}
-     * per target — a target the chain can't satisfy comes back `{ ok:false, detail }`,
-     * never a throw. An explicit, developer-invoked action; it moves no funds, and
-     * nothing is PipRail-hosted — you're listing on third-party open directories.
+     * Default target is **402 Index** — one POST, no auth, no signature, no payment.
+     * Add `'x402scan'` to also register via SIWX (one wallet signature; EVM + a
+     * Base/Solana rail). Returns one {@link RegisterOutcome} per target — a target the
+     * chain can't satisfy comes back `{ ok:false, detail }`, never a throw. An explicit,
+     * developer-invoked action; it moves no funds, and nothing is PipRail-hosted —
+     * you're listing on third-party open directories.
+     *
+     * **Listing is asynchronous — each outcome carries a `visibility` + `note` so an
+     * agent knows when/where the resource is findable (don't assume `ok:true` means
+     * "searchable now"):**
+     * - **402 Index** → `visibility:'pending-review'`. It probes your URL on submit, then lists it
+     *   PENDING REVIEW — not searchable until approved (verify your domain on 402index.io for instant
+     *   approval), so `discover()` returns nothing for a fresh listing until then. Retry later.
+     * - **x402scan** → `visibility:'live'`, but **`discover()` does NOT read x402scan** — the
+     *   listing is real on x402scan.com yet won't show up in `discover()`. Base/Solana only;
+     *   needs a resolvable input schema (`/openapi.json` or the `extensions.bazaar` block).
+     * - **Bazaar** → `visibility:'not-listable'` for PipRail (it lists only what its facilitator
+     *   settles; PipRail uses none). You can still READ Bazaar via {@link discover} to find others.
+     *
+     * The per-source facts live in {@link DIRECTORY_INFO} (importable) if you'd rather branch
+     * on them before calling.
      */
     register(url: string, opts?: RegisterOptions): Promise<RegisterOutcome[]>;
     /**
@@ -4660,7 +4871,10 @@ declare class PipRailClient {
      * `quote()` (read-only) and `fetch()` (which then authorises + pays).
      */
     private resolveChallenge;
-    /** The candidate accepts this client could pay: our scheme, on the bound network. */
+    /** The candidate accepts this client could pay: our scheme, on the bound network.
+     *  A dual-advertised challenge may also carry standard `exact` rails — the PipRail
+     *  client ignores those (it pays the backendless `onchain-proof` rail); the type
+     *  predicate narrows the `X402AnyAccept` union to the rails we settle. */
     private gatherCandidates;
     /** Build the full {@link PaymentPlan} from an already-parsed challenge + bound
      *  net/wallet. Shared by `planPayment` (read-only) and `fetch`'s autoRoute. */
@@ -4768,7 +4982,8 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
  * consumed by every emitter below.
  */
 interface PaymentRail {
-    scheme: 'onchain-proof';
+    /** `onchain-proof` (PipRail's default) or the standard `exact` rail (dual-advertise). */
+    scheme: 'onchain-proof' | 'exact';
     network: Caip2;
     asset: AssetId;
     payTo: AddressId;
@@ -4931,6 +5146,30 @@ interface AcceptOption {
     /** RPC override for this chain (defaults to the top-level `rpcUrl`). */
     rpcUrl?: string;
 }
+/**
+ * Opt into ALSO advertising a standard x402 `exact` rail (EIP-3009) beside the
+ * default `onchain-proof` rail, so ANY standard x402 client can pay this gate
+ * (dual-advertise). EVM + EIP-3009 tokens only (USDC, EURC — NOT USDT, NOT native).
+ * Omitting `exact` leaves the gate byte-identical to today (onchain-proof only).
+ *
+ * Two settlement modes, both backendless (PipRail hosts nothing):
+ *  - `settle: 'self'`  — your own `relayer` key broadcasts `transferWithAuthorization`.
+ *     You pay gas to RECEIVE (the inverse of onchain-proof, where the payer pays gas)
+ *     and must keep the relayer funded. The signature binds `to`, so there's no
+ *     redirect risk. This is the on-brand default for the rail.
+ *  - `settle: { facilitator }` — delegate verify+settle to a third-party x402
+ *     facilitator YOU choose (Coinbase CDP, x402.org, …). No relayer key needed; the
+ *     facilitator pays gas. Also the only path onto Coinbase's Bazaar directory.
+ */
+interface ExactRailOption {
+    settle: 'self' | {
+        facilitator: string;
+        authHeaders?: () => Promise<Record<string, string>>;
+    };
+    /** Required for `settle: 'self'` — the gas-paying relayer wallet: EVM `{ privateKey }`
+     *  or a bring-your-own `{ walletClient }`. (Distinct from `payTo`, the receive address.) */
+    relayer?: unknown;
+}
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
@@ -4979,6 +5218,12 @@ interface RequirePaymentOptions {
     markUsed?: (ref: string) => void | Promise<void>;
     /** Fired when a payment verifies successfully. */
     onPaid?: (receipt: X402Receipt) => void;
+    /**
+     * ALSO advertise a standard x402 `exact` rail (EIP-3009) so any standard x402
+     * client can pay this gate — opt-in, EVM/EIP-3009 only. See {@link ExactRailOption}.
+     * Omit to keep the gate exactly as today (`onchain-proof` only).
+     */
+    exact?: ExactRailOption;
 }
 type VerifyPaymentResult = {
     kind: 'paid';
@@ -4990,12 +5235,21 @@ type VerifyPaymentResult = {
     requiredHeader: string;
     statusCode: 402;
 } | {
+    /**
+     * A submitted proof was rejected. Conformant: this carries a FRESH
+     * re-`challenge` (full v2 PaymentRequired with `accepts[]` + the reason in
+     * `error` + the machine code in `extensions.piprail`) so a standard x402
+     * client can immediately retry. Adapters emit `challenge` + the
+     * `PAYMENT-REQUIRED` header — NOT the legacy {@link toInvalidBody}.
+     */
     kind: 'invalid';
     error: string;
     detail: string;
+    challenge: X402Challenge;
+    requiredHeader: string;
     statusCode: 402;
 };
-/** The canonical x402 v2 JSON body for a rejected proof (a 402 'invalid'). */
+/** A minimal 402 'invalid' JSON body. @deprecated — see {@link toInvalidBody}. */
 interface X402InvalidBody {
     x402Version: 2;
     status: 'invalid';
@@ -5003,9 +5257,14 @@ interface X402InvalidBody {
     detail: string;
 }
 /**
- * Build the canonical 402 'invalid' body. Use this in EVERY framework adapter
- * (Express, Hono, Fastify, Workers, …) so a rejected proof returns the IDENTICAL
- * envelope everywhere — `verify()` produces the reason, this shapes the body.
+ * @deprecated LEGACY minimal rejection body. The gate now returns a fully
+ * **conformant** rejection: `gate.verify()`'s `kind:'invalid'` result carries a full
+ * v2 PaymentRequired re-`challenge` (with `accepts[]` so a standard x402 client can
+ * retry, the reason in `error`, and the machine code in `extensions.piprail`). The
+ * built-in `requirePayment` adapter emits `result.challenge` + the `PAYMENT-REQUIRED`
+ * header. PREFER that. This helper (a bare `{ status:'invalid', error, detail }` with
+ * NO `accepts[]`) remains only for back-compat with hand-rolled adapters; a standard
+ * client that receives it can't retry. Migrate to `result.challenge`.
  */
 declare function toInvalidBody(result: {
     error: string;
@@ -5058,6 +5317,68 @@ type ExpressLikeMiddleware = (req: ExpressLikeRequest, res: ExpressLikeResponse,
  */
 declare function requirePayment(options: RequirePaymentOptions): ExpressLikeMiddleware;
 
+/**
+ * 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
+ * nothing — this is two HTTP POSTs to the merchant's configured facilitator URL.
+ *
+ * PROTOCOL LAYER — pure `fetch`, ZERO chain libraries (STANDARDS §1). The other
+ * settlement mode (self-settle with the merchant's own relayer key) lives in the
+ * EVM driver; this one is chain-agnostic because the facilitator does the chain work.
+ *
+ * The wire contract (x402 v2, verified against coinbase/x402 core):
+ *   POST {url}/verify   body { x402Version, paymentPayload, paymentRequirements } → { isValid, invalidReason?, payer? }
+ *   POST {url}/settle   SAME body                                                → { success, transaction, network, payer?, errorReason? }
+ * Both protocol outcomes are HTTP 200 (the boolean flips); a non-200 is a
+ * transport/auth failure. There is no registration and no idempotency key — so a
+ * SELF-settling merchant must guard replay itself (the gate's used-proof set does).
+ */
+
+/** Standard x402 `exact` PaymentRequirements, built from the gate's TRUSTED rail. */
+interface FacilitatorPaymentRequirements {
+    scheme: 'exact';
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: {
+        name: string;
+        version: string;
+    };
+}
+/** 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). */
+    url: string;
+    /** Optional async auth-header provider (e.g. CDP JWT). Omit for the free, no-auth facilitators. */
+    authHeaders?: () => Promise<Record<string, string>>;
+}
+interface SettleViaFacilitatorInput extends FacilitatorConfig {
+    x402Version: number;
+    /** The decoded PaymentPayload the client sent — forwarded verbatim. */
+    paymentPayload: Record<string, unknown>;
+    /** PaymentRequirements built from the gate's trusted rail (never the client echo). */
+    paymentRequirements: FacilitatorPaymentRequirements;
+    /** The receipt's network (CAIP-2) + asset/amount/payTo, for building the X402Receipt on success. */
+    receipt: {
+        network: Caip2;
+        asset: AssetId;
+        payTo: AddressId;
+        amount: string;
+    };
+    /** authorization.from, for the receipt's `payer`. */
+    payerHint?: string;
+}
+/**
+ * Verify-then-settle a standard `exact` payment through a third-party facilitator.
+ * Returns a {@link VerifyResult}: `{ ok:false, error }` for a client-fixable
+ * facilitator rejection (verify isValid:false, or settle success:false) → 402;
+ * `{ ok:true, receipt }` on a settled payment. THROWS {@link SettlementError} on a
+ * transport/auth failure (non-200) — the gate replies 5xx, never a misleading 402.
+ */
+declare function settleViaFacilitator(input: SettleViaFacilitatorInput): Promise<VerifyResult>;
+
 /**
  * The driver registry — the ONLY place the families meet. Routing decides a
  * family from the `chain` value (synchronously), then asks that family's
@@ -5202,6 +5523,22 @@ declare class PaymentDeclinedError extends PipRailError {
 declare class ConfirmationTimeoutError extends PipRailError {
     readonly code = "CONFIRMATION_TIMEOUT";
 }
+/**
+ * A standard `exact` payment was VALID (signature recovered, params checked,
+ * simulation passed) but SETTLEMENT failed for a SERVER-side reason — the
+ * merchant's own relayer couldn't broadcast `transferWithAuthorization` (out of
+ * gas, RPC down, dropped tx), or a Mode-B facilitator returned a transport/auth
+ * error. This is NOT the payer's fault: their signed EIP-3009 authorization is
+ * still valid and its nonce UNUSED, so it can be re-presented once the merchant
+ * fixes their relayer/facilitator. The gate THROWS this (it's an operational
+ * problem to fix, not a proof to reject), so a framework adapter returns 5xx —
+ * never a 402, which would wrongly tell the payer to re-pay. `.cause` carries the
+ * raw chain/HTTP error. (Server-side; the `onchain-proof` rail can't raise it —
+ * there the payer broadcasts, so there's nothing for the merchant to settle.)
+ */
+declare class SettlementError extends PipRailError {
+    readonly code = "SETTLEMENT_FAILED";
+}
 /** Server returned 402 but the PAYMENT-REQUIRED envelope was missing or malformed. */
 declare class InvalidEnvelopeError extends PipRailError {
     readonly code = "INVALID_ENVELOPE";
@@ -5256,28 +5593,29 @@ declare class UnsupportedNetworkError extends PipRailError {
 }
 
 /**
- * ── EVM SECTION: x402 `exact` scheme (interop building block) ──────────────
+ * ── EVM SECTION: x402 `exact` scheme (EIP-3009) — BUYER + SELLER ───────────
  *
- * EXPERIMENTAL / ADVANCED. PipRail's own gates use the `onchain-proof` scheme
- * (client pays first, proves with a tx ref, server verifies locally — no
- * facilitator). This module is the opposite end: the building blocks to PAY a
- * server that speaks the mainstream x402 `exact` scheme (Coinbase-style), where
- * the client signs an EIP-3009 `transferWithAuthorization` and a third-party
- * facilitator broadcasts it. It lets a PipRail agent buy from `exact` servers
- * too — making PipRail a *universal* x402 client — while our servers stay
- * backendless.
+ * PipRail's own gates default to the `onchain-proof` scheme (client pays first,
+ * proves with a tx ref, server verifies locally). This module is the standard
+ * x402 `exact` interop, in BOTH directions, EVM + EIP-3009 only, on the existing
+ * `viem` peer (no new dep):
  *
- * What's here is the deterministic, unit-testable core: parse an `exact`
- * requirement, build + EIP-712-sign the authorization, and encode the
- * `X-PAYMENT` header. It is intentionally NOT wired into `PipRailClient.fetch`'s
- * default flow: `exact` is a cross-vendor wire protocol whose live acceptance
- * can only be confirmed against a real facilitator, and bolting a second
- * payment protocol into the core would cut against PipRail's keep-it-simple
- * design. Use these helpers to hand-roll an `exact` payment, and validate
- * against your target facilitator before production. See
- * `.claude/plans/agent-readiness/04-universal-exact.md`.
+ *   • BUYER side (client) — parse an `exact` requirement, build + EIP-712-sign the
+ *     EIP-3009 authorization, encode the `X-PAYMENT` header. Deterministic,
+ *     unit-testable; NOT wired into `PipRailClient.fetch`'s default (see
+ *     `.claude/plans/agent-readiness/04-universal-exact.md`).
  *
- * EVM + EIP-3009 only (USDC and kin). Uses the existing `viem` peer — no new dep.
+ *   • SELLER side (gate) — {@link readExactDomain} (read the token's true EIP-712
+ *     domain so the gate can advertise + verify it) and {@link verifyAndSettleExactEvm}
+ *     (verify an inbound EIP-3009 authorization locally, then SELF-SETTLE it by
+ *     broadcasting `transferWithAuthorization` from the merchant's own relayer key —
+ *     no third-party facilitator). This is what lets a PipRail gate get PAID by ANY
+ *     standard x402 client. See `.claude/plans/compliance/`.
+ *
+ * Self-settle uses `transferWithAuthorization` (NOT `receiveWithAuthorization`,
+ * which requires `msg.sender == payTo` and so can't be broadcast by a separate
+ * relayer key). The signature binds `to`=payTo, so a front-runner can only push
+ * the same funds to the same payTo and waste their own gas — no redirect risk.
  */
 
 /** x402 network slug → EVM chain id, for the chains PipRail ships with EIP-3009
@@ -5362,13 +5700,134 @@ declare function buildExactAuthorization(params: BuildExactParams): Promise<{
     authorization: ExactAuthorization;
     signature: Hex;
 }>;
-/** Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value. */
+/**
+ * Encode an x402 `exact` PaymentPayload into an `X-PAYMENT` header value — the
+ * **v1 flat shape** (`{ x402Version, scheme, network, payload }`). This is a
+ * client-side UTILITY (PipRail's own client pays only `onchain-proof`, never this);
+ * the v1 flat shape is what Coinbase's original reference emits and is still accepted
+ * by every x402 gate + facilitator, so `x402Version` defaults to `1` to stay
+ * INTERNALLY CONSISTENT with that shape (emitting `2` here would mislabel a v1 body —
+ * a proper v2 `exact` payload is the nested `accepted`-envelope shape instead). See
+ * the version-posture note in `x402.ts`.
+ */
 declare function encodeXPaymentHeader(input: {
     network: string;
     authorization: ExactAuthorization;
     signature: Hex;
-    /** x402 envelope version (Coinbase's reference uses 1). */
+    /** x402 envelope version. Defaults to `1` — consistent with this flat shape. */
     x402Version?: number;
 }): string;
+/**
+ * The minimal EIP-3009 ABI the seller needs: both `transferWithAuthorization`
+ * overloads (the 65-byte `(v,r,s)` form and the `(bytes signature)` ERC-1271 form),
+ * the `authorizationState` replay check, and `name()`/`version()` for the EIP-712
+ * domain. Mirrors Circle's deployed FiatToken.
+ */
+declare const eip3009Abi: readonly [{
+    readonly type: "function";
+    readonly name: "transferWithAuthorization";
+    readonly stateMutability: "nonpayable";
+    readonly outputs: readonly [];
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "v";
+        readonly type: "uint8";
+    }, {
+        readonly name: "r";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "s";
+        readonly type: "bytes32";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "transferWithAuthorization";
+    readonly stateMutability: "nonpayable";
+    readonly outputs: readonly [];
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "signature";
+        readonly type: "bytes";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "authorizationState";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "authorizer";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "name";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "version";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}];
+/**
+ * Read an EIP-3009 token's true EIP-712 domain `{ name, version }` from the
+ * contract — what a payer must sign over. Returns `null` if the asset is NOT an
+ * EIP-3009 token (no `authorizationState`/`version` — e.g. USDT, native coin, a
+ * plain ERC-20), so the gate refuses to advertise a standard `exact` rail for it.
+ *
+ * The name is NEVER assumed from the symbol: canonical USDC's domain name is
+ * "USD Coin" (not "USDC"), EURC's is "EURC". `eip712Domain()` (EIP-5267) reverts
+ * on these proxies, so we read `name()`+`version()` and probe `authorizationState`
+ * to confirm EIP-3009 support.
+ */
+declare function readExactDomain(publicClient: PublicClient, asset: string): Promise<{
+    name: string;
+    version: string;
+} | null>;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, 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, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody };