uvd-x402-sdk 2.85.0 → 2.87.0

package/dist/index-BHfYxpzI.d.mts

@@ -0,0 +1,3865 @@
+import { S as SigningWalletAdapter } from './wallet-w7BnImDG.mjs';
+import { X as X402Version, i as X402Header, j as X402PayloadData } from './index-DOBhTF-j.mjs';
+
+/**
+ * uvd-x402-sdk - Signed lifecycle orders for `release` / `refundInEscrow`.
+ *
+ * Both actions move money that is ALREADY escrowed, so neither carries an
+ * ERC-3009 signature: there is no transfer left to authorize. That left the
+ * other half of the question open — who is entitled to ask for the move —
+ * and the de-facto answer was "whoever calls". On 2026-08-30 a third party
+ * probed exactly that: five calls with a fabricated `paymentInfo`, two of
+ * them mined, gas spent.
+ *
+ * This module is the client half of the answer: an EIP-712 order signed by
+ * the party the action belongs to, hung off `payload.lifecycleAuth`.
+ *
+ * >>> THE SIGNER IS INJECTED <<<
+ * The SDK never reaches for a key on its own. Any adapter that can sign
+ * typed data works — `EnvKeyAdapter` (server / CLI), `OWSWalletAdapter`, a
+ * wagmi/viem wallet client in the browser ({@link wagmiLifecycleSigner}), a
+ * KMS. In H2A/H2H the PAYER signs in their own browser with the same wallet
+ * they paid with, and the marketplace merely transports the block.
+ *
+ * >>> TWO SHAPES, ONE ORDER <<<
+ * `buildLifecycleAuth` does the whole ceremony in one call: it mints the
+ * nonce and the deadline, signs through the injected adapter, and returns the
+ * block. That is the server and the `wagmi` paths.
+ *
+ * A publisher's browser cannot use it. There the backend assembles the
+ * document — nonce and deadline included — the browser signs whatever it was
+ * handed, and gives back a signature and nothing else. That is
+ * {@link buildLifecycleTypedData} on one side and
+ * {@link lifecycleAuthFromSignature} on the other, and it produces the SAME
+ * bytes as the one-call path for the same nonce and deadline, pinned in
+ * `src/lifecycle-auth.test.ts`.
+ *
+ * Source of truth for the format is the facilitator, `x402-rs`
+ * `src/payment_operator/lifecycle_auth.rs` (PR #21). The Python twin is
+ * `uvd_x402_sdk.escrow_signing.build_lifecycle_auth` (0.78.0); the two must
+ * produce byte-identical signatures, pinned here by the shared vector in
+ * `src/lifecycle-auth.test.ts`.
+ *
+ * Facilitator rollout is by `ESCROW_LIFECYCLE_AUTH`: `off` (default, the
+ * order is not looked at), `log` (verify when present, log the verdict,
+ * never reject) and `enforce`. That is why `lifecycleSigner` is OPTIONAL
+ * everywhere: without one, the request goes out byte-for-byte as before.
+ *
+ * @example Server-side (EnvKeyAdapter)
+ * ```typescript
+ * import { buildLifecycleAuth, EnvKeyAdapter } from 'uvd-x402-sdk';
+ *
+ * const auth = await buildLifecycleAuth({
+ *   action: 'release',
+ *   paymentInfo: pi,          // the SAME camelCase object that is sent
+ *   payer: payerAddress,      // payload.payer — NOT inside paymentInfo
+ *   amount: '1000000',        // the SAME as payload.amount
+ *   chainId: 8453,
+ *   wallet: new EnvKeyAdapter(),
+ * });
+ * // -> payload.lifecycleAuth = auth
+ * ```
+ */
+/**
+ * EIP-712 domain. `chainId` is the payment network's; there is NO
+ * `verifyingContract` because `paymentInfo.operator` already rides inside the
+ * signed struct. Copied from `lifecycle_auth.rs:69-70` (DOMAIN_NAME /
+ * DOMAIN_VERSION).
+ */
+declare const LIFECYCLE_DOMAIN_NAME = "x402 escrow lifecycle";
+declare const LIFECYCLE_DOMAIN_VERSION = "1";
+/**
+ * The facilitator's `deadline` ceiling: 900 s (`lifecycle_auth.rs:64`,
+ * `DEFAULT_MAX_DEADLINE_SECS`). A leaked order is not a standing permission.
+ */
+declare const LIFECYCLE_MAX_DEADLINE_SECS = 900;
+/**
+ * What we sign by default, leaving 300 s of headroom under the ceiling.
+ * Signing the full 900 s is an order that a facilitator clock five seconds
+ * behind already reads as `deadline_too_far`: the margin is not cosmetic, it
+ * is what separates a valid order from a rejection the caller cannot explain.
+ */
+declare const LIFECYCLE_DEFAULT_DEADLINE_SECS = 600;
+/** The two wire values, which are also what enters the signature. */
+declare const LIFECYCLE_ACTIONS: readonly ["release", "refundInEscrow"];
+type LifecycleAction = (typeof LIFECYCLE_ACTIONS)[number];
+/**
+ * The EIP-712 types. `PaymentInfo` is the AuthCaptureEscrow type string
+ * VERBATIM — the same one this SDK already types for ERC-3009. The field
+ * ORDER is part of the type hash: reordering it invalidates every order ever
+ * issued. Exact mirror of `lifecycle_auth.rs:73-99`.
+ */
+declare const LIFECYCLE_ORDER_TYPES: Record<string, Array<{
+    name: string;
+    type: string;
+}>>;
+/** The wire `paymentInfo` of a lifecycle request (camelCase, `salt` in hex). */
+interface LifecyclePaymentInfo {
+    operator: string;
+    receiver: string;
+    token: string;
+    /** Atomic units (uint120 on-chain). */
+    maxAmount: string | number | bigint;
+    preApprovalExpiry: number | string;
+    authorizationExpiry: number | string;
+    refundExpiry: number | string;
+    minFeeBps: number | string;
+    maxFeeBps: number | string;
+    feeReceiver: string;
+    /** 32-byte hex on the wire; uint256 in the signature. */
+    salt: string | number | bigint;
+}
+/**
+ * Minimal signer for {@link buildLifecycleAuth}: an address plus EIP-712
+ * typed-data signing over the full typed-data JSON string. This is the same
+ * contract as `SigningWalletAdapter`, so `EnvKeyAdapter` and
+ * `OWSWalletAdapter` satisfy it structurally, and a browser wallet only has
+ * to wrap its own `signTypedData` in this shape — the key never leaves it.
+ */
+interface LifecycleSigner {
+    /** The EVM address that will be claimed as `lifecycleAuth.signer`. */
+    getAddress(): string;
+    /** Sign the full EIP-712 JSON (`domain`, `types`, `primaryType`, `message`). */
+    signTypedData(typedData: string): Promise<{
+        signature: string;
+    }>;
+}
+/** The block that goes in `payload.lifecycleAuth`. */
+interface LifecycleAuth {
+    /** Who claims to have signed. Checked against the recovered address. */
+    signer: string;
+    /** Unix seconds after which the order is dead. */
+    deadline: number;
+    /** 32-byte hex replay guard, consumed by the facilitator on success. */
+    nonce: string;
+    /** 65-byte EIP-712 signature over the `LifecycleOrder`. */
+    signature: string;
+}
+interface LifecycleTypedDataParams {
+    /** `'release'` or `'refundInEscrow'`. */
+    action: LifecycleAction;
+    /**
+     * The paymentInfo EXACTLY as it is serialized on the wire. This same object
+     * is signed, which is what keeps the two ends from drifting.
+     */
+    paymentInfo: LifecyclePaymentInfo;
+    /** The escrow's payer — travels as `payload.payer`, not inside paymentInfo. */
+    payer: string;
+    /** Atomic amount, the SAME one as `payload.amount`. */
+    amount: string | number | bigint;
+    /** EVM chain id of the payment network. */
+    chainId: number;
+    /**
+     * Unix seconds after which the order is dead. Default: `now + 600`, which
+     * leaves 300 s of headroom under the facilitator's 900 s ceiling.
+     */
+    deadline?: number;
+    /**
+     * 32 bytes, hex. Default: a fresh random one. Distinct PER ORDER — the
+     * facilitator consumes it on acceptance.
+     */
+    nonce?: string;
+    /** Unix seconds, for the `deadline` default and for tests. Default: the clock. */
+    now?: number;
+}
+/**
+ * The EIP-712 document itself: what {@link buildLifecycleTypedData} returns and
+ * what {@link lifecycleAuthFromSignature} reads back.
+ *
+ * Named because it is a WIRE type in the split flow: a backend builds it,
+ * ships it to a browser as JSON, and the browser hands it to `signTypedData`.
+ * `types` carries no `EIP712Domain` entry — ethers and viem both derive that
+ * one, and including it makes ethers throw `ambiguous primary types`.
+ */
+interface LifecycleTypedData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+    };
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    primaryType: 'LifecycleOrder';
+    message: Record<string, unknown>;
+}
+interface BuildLifecycleAuthParams extends LifecycleTypedDataParams {
+    /**
+     * The signer. Must be the payer, the receiver or the operator owner
+     * depending on the action — see the table in the module docblock.
+     */
+    wallet: LifecycleSigner;
+}
+/**
+ * The exact EIP-712 document a lifecycle order signs.
+ *
+ * Kept separate from {@link buildLifecycleAuth} because it is the useful
+ * seam: it is what the Python twin mirrors, what a test can poke field by
+ * field to confirm the signature stops verifying, and — the reason it is
+ * PUBLIC — what a backend hands to a browser that signs.
+ *
+ * {@link buildLifecycleAuth} cannot serve that browser: it takes an injected
+ * `WalletAdapter` and mints its own nonce and deadline, while a publisher
+ * signs a document the backend already assembled and hands back only a
+ * signature. Build it here, ship it, and reassemble the wire block with
+ * {@link lifecycleAuthFromSignature} — which reads `deadline` and `nonce`
+ * back out of this same document, so the two cannot disagree.
+ *
+ * @example The split flow, backend half
+ * ```typescript
+ * const typedData = buildLifecycleTypedData({
+ *   action: 'release',
+ *   paymentInfo: pi,   // the SAME object that will be sent
+ *   payer,             // payload.payer
+ *   amount,            // the SAME as payload.amount
+ *   chainId: 8453,
+ * });                  // deadline -> now + 600, nonce -> 32 fresh bytes
+ * // -> res.json({ typedData })  ... the browser signs it and posts back a signature
+ * const lifecycleAuth = lifecycleAuthFromSignature(typedData, signature, payer);
+ * ```
+ *
+ * @throws {X402Error} `INVALID_CONFIG` on an unknown action or a paymentInfo
+ *   missing a field; `INVALID_AMOUNT` on a negative amount. Nothing IN THE
+ *   SIGNED STRUCT is defaulted: an invented field is a signature over a
+ *   different struct than the one that is sent, i.e. a rejection the caller
+ *   cannot diagnose. `deadline` and `nonce` are the exception because they
+ *   exist nowhere else — they are born here and read back from the document.
+ */
+declare function buildLifecycleTypedData(params: LifecycleTypedDataParams): LifecycleTypedData;
+/**
+ * Sign the order and return the complete `payload.lifecycleAuth` block.
+ *
+ * This is the first link of enforce: the facilitator already verifies these
+ * orders in `log` mode and measured ZERO signatures across 17 days of traffic
+ * (2,953 release/refund, 22 payers, 9 networks) — the field did not exist and
+ * nobody sent it. Under `enforce` today, 100% would be rejected.
+ *
+ * The signer is INJECTED; the SDK does not read keys from the environment.
+ *
+ * @throws {X402Error} `INVALID_CONFIG` if the deadline has already passed or
+ *   sits past the facilitator's 900 s ceiling. It fails HERE and not there:
+ *   an out-of-window order is an `expired` / `deadline_too_far` that under
+ *   `enforce` is stuck money, and the caller has no log to see it in.
+ */
+declare function buildLifecycleAuth(params: BuildLifecycleAuthParams): Promise<LifecycleAuth>;
+/**
+ * Reassemble `payload.lifecycleAuth` from a document that was signed
+ * ELSEWHERE — the other half of the split flow.
+ *
+ * `buildLifecycleAuth` owns the whole ceremony: it mints the nonce and the
+ * deadline, signs, and returns the block. A publisher's browser owns none of
+ * that. It receives a document the backend already assembled and gives back
+ * one string. This is the seam where that string becomes a wire block.
+ *
+ * `deadline` and `nonce` are NOT parameters: they are read out of
+ * `typedData.message`, which is the document that was actually hashed. Taking
+ * them from the caller would let the block claim a nonce the signature never
+ * committed to — a `bad_signature` the caller cannot see, because both halves
+ * look right on their own.
+ *
+ * The signature is NOT recovered here. This SDK's payers include ERC-7702
+ * delegated accounts and contract wallets that validate through ERC-1271
+ * (`src/erc7702.ts:8`), whose signatures do not ecrecover to their address;
+ * `ethers.verifyTypedData` would reject the good ones. Recovery — and the
+ * role check that goes with it — is the facilitator's, against the chain.
+ *
+ * @param typedData - what {@link buildLifecycleTypedData} returned, unmodified.
+ * @param signature - the 0x-hex the wallet gave back (`signTypedData`).
+ * @param signer - the address that signed, claimed in the block and checked
+ *   against the recovered one by the facilitator.
+ *
+ * @throws {X402Error} `INVALID_CONFIG` if the document is not a
+ *   `LifecycleOrder` for this domain, if the signature is not hex, or if the
+ *   signer is not an address.
+ *
+ * @example The browser half
+ * ```typescript
+ * const signature = await walletClient.signTypedData({
+ *   domain: typedData.domain,
+ *   types: typedData.types,
+ *   primaryType: typedData.primaryType,
+ *   message: typedData.message,
+ * });
+ * const lifecycleAuth = lifecycleAuthFromSignature(typedData, signature, address);
+ * ```
+ */
+declare function lifecycleAuthFromSignature(typedData: LifecycleTypedData, signature: string, signer: string): LifecycleAuth;
+/**
+ * Minimal wagmi/viem wallet client: what {@link wagmiLifecycleSigner} needs.
+ *
+ * Deliberately narrower than this SDK's payment `WalletClient`: a lifecycle
+ * domain has NO `verifyingContract`, so a client typed to require one cannot
+ * sign these orders.
+ */
+interface WagmiLifecycleWalletClient {
+    account?: {
+        address: string;
+    } | null;
+    signTypedData(args: {
+        domain: Record<string, unknown>;
+        types: Record<string, Array<{
+            name: string;
+            type: string;
+        }>>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<string>;
+}
+/**
+ * Wrap a wagmi/viem wallet client as a {@link LifecycleSigner}, so the PAYER
+ * signs the order in their own browser with the same wallet they paid with,
+ * and the marketplace only transports the block.
+ *
+ * @param walletClient - from `useWalletClient()` (wagmi) or `createWalletClient` (viem).
+ * @param address - the signing account; defaults to `walletClient.account.address`.
+ *
+ * @example
+ * ```typescript
+ * const { data: walletClient } = useWalletClient();
+ * const auth = await buildLifecycleAuth({
+ *   action: 'release',
+ *   paymentInfo: pi,
+ *   payer: address,
+ *   amount: task.bountyAtomic,
+ *   chainId: 8453,
+ *   wallet: wagmiLifecycleSigner(walletClient!),
+ * });
+ * await fetch('/api/tasks/x/approve', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ lifecycleAuth: auth }),
+ * });
+ * ```
+ */
+declare function wagmiLifecycleSigner(walletClient: WagmiLifecycleWalletClient, address?: string): LifecycleSigner;
+
+/**
+ * Reading a facilitator refusal as DATA instead of prose.
+ *
+ * # Why this file exists
+ *
+ * `402` and `503` say opposite things and the SDK used to collapse both into
+ * `success: false` plus an English sentence.
+ *
+ * - **402** means the payment was REJECTED. The credential is spent; sign a new
+ *   authorization.
+ * - **503** means NO VERDICT WAS REACHED. Nothing was rejected and nothing was
+ *   executed; retry the SAME credential.
+ *
+ * Turning a 503 into a 402 makes the buyer sign and send a second payment for a
+ * money movement that was never refused — they pay twice. That is the most
+ * expensive mistake this SDK can make, so every facilitator edge now reports the
+ * status, the facilitator's own `reason`, and whether the request may be
+ * replayed.
+ *
+ * # The writer lease
+ *
+ * The facilitator serialises every EVM write through the one process that holds
+ * the EVM writer lease, because they all spend gas from the same EOA and the
+ * nonce for it is allocated in memory. A task that does not hold the lease
+ * forwards the request to the one that does; when it cannot, it answers
+ * `503` + `Retry-After: 5` + `{"error": "...", "reason": "<why>"}`.
+ *
+ * The five reasons do NOT share retry semantics, which is the whole point of
+ * surfacing them:
+ *
+ * | reason                     | did the write run? | replay? |
+ * |----------------------------|--------------------|---------|
+ * | `holder_unknown`           | no                 | yes     |
+ * | `forwarding_disabled`      | no                 | yes     |
+ * | `forwarded_but_not_writer` | no                 | yes     |
+ * | `body_unreadable`          | no                 | yes     |
+ * | `forward_failed`           | **maybe**          | **no**  |
+ *
+ * `forward_failed` is emitted after the forward was attempted: the holder may
+ * have executed the write and the response been lost on the way back. It is a
+ * timeout wearing a status code. Replaying a `/register` on it is exactly the
+ * sequence that once minted five duplicate agents — reconcile with
+ * `GET /identity/{network}/owner/{recipient}` or `getRegisterStatus` instead.
+ *
+ * # The two `502`s of `/settle`, which mean opposite things
+ *
+ * | body `error`               | `Retry-After` | did the money move? | retry?    |
+ * |----------------------------|---------------|---------------------|-----------|
+ * | `upstream_rpc_unavailable` | `30`          | no, never broadcast | **yes**   |
+ * | `settlement_unconfirmed`   | **absent**    | **maybe — mined?**  | **NEVER** |
+ *
+ * `settlement_unconfirmed` is answered after the transaction was broadcast and
+ * no receipt ever arrived, so it MAY be mined. Retrying re-signs a new
+ * authorization with a fresh nonce, which the chain accepts as a second,
+ * perfectly valid payment for the same purchase — the buyer pays twice, in
+ * exactly the case the facilitator emits it to prevent. The `transaction` hash
+ * and `paymentId` travel in the body so the caller can LOOK AT THE CHAIN; they
+ * are not an invitation to send it again.
+ *
+ * The status cannot tell the two apart, which is why this file used to get it
+ * wrong: every `502` was retryable, and until `settlement_unconfirmed` existed
+ * that was correct. **Branch on the body.**
+ *
+ * The general form of that rule — **a 5xx whose body carries a transaction hash
+ * was broadcast, whatever the error is called** — is adopted from the Python
+ * SDK, which has carried it as its anti-double-settle guard
+ * (`uvd_x402_sdk/client.py`, `_is_retryable_settle_error`) while this one had
+ * only the status to go on.
+ *
+ * Source of the shape: x402-rs `src/handlers.rs` `writer_lease_unavailable()`
+ * and `require_writer_lease()`; `SettlementUnconfirmedResponse` in
+ * `src/types.rs`, built in the `IntoResponse` of `FacilitatorLocalError`.
+ */
+/**
+ * A `reason` the facilitator attaches to a writer-lease 503.
+ *
+ * Typed as a union for discrimination but never used to VALIDATE: the fields
+ * that carry it are plain `string`, so a reason added on the server does not
+ * break compilation here.
+ */
+type WriterLeaseReason = 'holder_unknown' | 'forwarding_disabled' | 'forwarded_but_not_writer' | 'body_unreadable' | 'forward_failed';
+/** Every writer-lease reason the facilitator emits today. */
+declare const WRITER_LEASE_REASONS: readonly WriterLeaseReason[];
+/**
+ * The reasons returned BEFORE the write is handed to anyone.
+ *
+ * The facilitator refuses these in its router, so the request provably did not
+ * execute and re-sending the identical body is safe — including a mint.
+ */
+declare const REPLAYABLE_LEASE_REASONS: readonly WriterLeaseReason[];
+/**
+ * The reason that is ambiguous: the write may already have happened.
+ *
+ * Still `retryable` — the credential was not rejected — but never replayed
+ * automatically. Resolve it by reading state, not by re-POSTing.
+ */
+declare const AMBIGUOUS_LEASE_REASONS: readonly WriterLeaseReason[];
+/**
+ * The facilitator's `error` code for a settle it broadcast and could not confirm.
+ *
+ * The transaction may be mined. This is the one upstream failure that must
+ * never be retried; reconcile with `transaction` / `paymentId` instead.
+ */
+declare const SETTLEMENT_UNCONFIRMED = "settlement_unconfirmed";
+/**
+ * Ceiling, in seconds, on how long an automatic retry will wait.
+ *
+ * `Retry-After` is a hint from a server that may be misconfigured. Honouring a
+ * literal `Retry-After: 3600` would hang the caller's request for an hour
+ * inside a function documented as returning promptly, so the header is honoured
+ * only up to this bound.
+ */
+declare const MAX_RETRY_AFTER_SECONDS = 15;
+/** Wait used when a 503 carries no usable `Retry-After`. */
+declare const DEFAULT_RETRY_AFTER_SECONDS = 5;
+/** How many EXTRA attempts a retryable facilitator refusal gets by default. */
+declare const DEFAULT_FACILITATOR_RETRIES = 2;
+/**
+ * A non-2xx answer from the facilitator, kept structured.
+ *
+ * `error` is byte-identical to the string this SDK has always produced, so
+ * callers matching on it keep working; everything else is new and optional.
+ */
+interface FacilitatorErrorInfo {
+    /** Legacy flattened message: `Facilitator error: <status> - <body>`. */
+    error: string;
+    /** HTTP status the facilitator answered with. */
+    status: number;
+    /** The facilitator's own `reason`, when the body carried one. */
+    reason?: string;
+    /**
+     * The facilitator's machine-readable `error` code, verbatim.
+     *
+     * Some codes carry a `(ref: <uuid>)` suffix, so compare with care —
+     * {@link SETTLEMENT_UNCONFIRMED} is emitted bare. Branch on this rather than
+     * on the status: `/settle` has two `502`s that mean opposite things.
+     */
+    errorCode?: string;
+    /**
+     * The hash of a transaction that WAS broadcast, in that chain's own encoding.
+     *
+     * Present on {@link SETTLEMENT_UNCONFIRMED}. Not always `0x`-prefixed:
+     * Algorand prints base32 and Solana base58, and reformatting it makes it
+     * unpasteable in an explorer — which is the entire remedy on offer.
+     */
+    transaction?: string;
+    /** `keccak256(caip2 ‖ txHash)`, the same id a successful settle would print. */
+    paymentId?: string;
+    /**
+     * Seconds to wait before retrying, already clamped to
+     * {@link MAX_RETRY_AFTER_SECONDS}. Absent when the answer is not retryable.
+     */
+    retryAfterSeconds?: number;
+    /**
+     * The request reached no verdict; the credential is untouched and the SAME
+     * request may be sent again. Never surface this as a payment rejection.
+     */
+    retryable: boolean;
+    /**
+     * The facilitator NAMED a reason that proves it executed nothing, so an
+     * automatic replay cannot double-write.
+     *
+     * False for `forward_failed`, whose write may already have landed, and false
+     * for an unattributed 5xx from a proxy — "something in front answered" is not
+     * evidence that nothing ran.
+     */
+    safeToReplay: boolean;
+    /** Raw response body, for logs. */
+    body: string;
+}
+/** Fields every facilitator response type gained so a 503 stops looking terminal. */
+interface FacilitatorFailureFields {
+    /** HTTP status, when the failure was transport-level rather than a verdict. */
+    status?: number;
+    /** The facilitator's `reason` for the refusal (see {@link WriterLeaseReason}). */
+    reason?: string;
+    /** The facilitator's machine-readable `error` code (see {@link FacilitatorErrorInfo.errorCode}). */
+    errorCode?: string;
+    /**
+     * A transaction that WAS broadcast and could not be confirmed. Look it up on
+     * chain; do NOT send the payment again. See {@link SETTLEMENT_UNCONFIRMED}.
+     */
+    transaction?: string;
+    /** The payment id for that transaction, identical to the one a settle prints. */
+    paymentId?: string;
+    /** True when the same request may be sent again without re-signing anything. */
+    retryable?: boolean;
+    /** Seconds to wait before retrying, clamped to {@link MAX_RETRY_AFTER_SECONDS}. */
+    retryAfterSeconds?: number;
+    /** True when the facilitator provably executed nothing. */
+    safeToReplay?: boolean;
+}
+/** A 503/429 that carries a reason known to be pre-execution. */
+declare function isReplayableLeaseReason(reason?: string): boolean;
+/** A 503 whose write may already have run. Reconcile, do not re-POST. */
+declare function isAmbiguousLeaseReason(reason?: string): boolean;
+/**
+ * Read `Retry-After` and clamp it.
+ *
+ * Tolerates a `Response`-shaped object with no `headers` at all: test doubles
+ * and non-standard fetch polyfills routinely omit it, and throwing there would
+ * turn a readable refusal into an unreadable crash.
+ */
+declare function parseRetryAfterSeconds(response: {
+    headers?: {
+        get?: (name: string) => string | null;
+    };
+}): number | undefined;
+/** Everything this SDK reads out of a facilitator error body. */
+interface ParsedFacilitatorErrorBody {
+    /** The `error` code, verbatim. */
+    errorCode?: string;
+    /** The writer-lease `reason`. */
+    reason?: string;
+    /** A broadcast transaction hash, in its own chain's encoding. */
+    transaction?: string;
+    /** The payment id for that hash. */
+    paymentId?: string;
+    /**
+     * The facilitator's OWN retry verdict, when it stated one.
+     *
+     * `undefined` on every body that does not carry the field — which is most of
+     * them, so absence means "the facilitator did not say", never "no".
+     */
+    retryable?: boolean;
+}
+/**
+ * Read a JSON error body, tolerating anything that is not one.
+ *
+ * Exported so {@link FacilitatorErrorInfo} and `Erc8004LookupError` read the
+ * SAME fields the same way. Two subtly different parses of the same body is how
+ * one code path stops honouring a `retryable: false` the other one honours.
+ */
+declare function parseFacilitatorErrorBody(body: string): ParsedFacilitatorErrorBody;
+/**
+ * This refusal reports a transaction that may already be mined.
+ *
+ * The caller's move is to look up `transaction` / `paymentId` on chain. Sending
+ * the payment again is the double-charge.
+ */
+declare function isSettlementUnconfirmed(failure: {
+    errorCode?: string;
+}): boolean;
+/**
+ * Turn a non-2xx facilitator response into {@link FacilitatorErrorInfo}.
+ *
+ * Reads the body exactly once. The `error` string keeps the historical format
+ * verbatim; reformatting it would break callers that match on it.
+ */
+declare function readFacilitatorError(response: {
+    status: number;
+    text: () => Promise<string>;
+    headers?: {
+        get?: (name: string) => string | null;
+    };
+}): Promise<FacilitatorErrorInfo>;
+/**
+ * Copy the failure fields off one response onto another.
+ *
+ * Used where a wrapper returns its own shape: without this the wrapper flattens
+ * a `503` back into a bare failure and reintroduces, one level up, exactly the
+ * ambiguity the fields exist to remove.
+ */
+declare function carryFailureFields(source: FacilitatorFailureFields): FacilitatorFailureFields;
+/** Options for {@link facilitatorFetch}. */
+interface FacilitatorFetchOptions {
+    /** Abort the request after this many milliseconds. */
+    timeoutMs: number;
+    /** Extra attempts after the first. Default {@link DEFAULT_FACILITATOR_RETRIES}. */
+    retries?: number;
+    /**
+     * Whether this particular refusal may be replayed.
+     *
+     * Default: only when the facilitator proved it executed nothing
+     * (`info.safeToReplay`). Pass a stricter predicate on paths where even a
+     * proven-safe replay is unwanted.
+     */
+    canReplay?: (info: FacilitatorErrorInfo) => boolean;
+    /** Injected for tests. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests, so a retry does not really sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+/**
+ * POST/GET the facilitator, replaying a refusal that provably executed nothing.
+ *
+ * Returns the response plus, when it was not ok, the structured refusal — the
+ * body has already been consumed to build it, so callers must not read it
+ * again.
+ *
+ * Network errors and timeouts still THROW, exactly as before: callers already
+ * have `catch` blocks that turn them into `{ success: false }`, and an
+ * `AbortError` on the escrow paths triggers an on-chain reconciliation that
+ * must keep firing.
+ */
+declare function facilitatorFetch(url: string, init: RequestInit, options: FacilitatorFetchOptions): Promise<{
+    response: Response;
+    error?: FacilitatorErrorInfo;
+}>;
+
+/**
+ * Payment requirements sent to the facilitator
+ */
+interface PaymentRequirements {
+    /** Payment scheme */
+    scheme: 'exact' | 'escrow' | 'commerce';
+    /** Network name (v1) or CAIP-2 identifier (v2) */
+    network: string;
+    /** Maximum amount required in atomic units (e.g., "1000000" for 1 USDC) */
+    maxAmountRequired: string;
+    /** Resource URL being paid for */
+    resource: string;
+    /** Description of what's being paid for */
+    description: string;
+    /** MIME type of the resource */
+    mimeType: string;
+    /** Recipient address for payment */
+    payTo: string;
+    /** Maximum timeout in seconds */
+    maxTimeoutSeconds: number;
+    /** Token contract address */
+    asset: string;
+    /** Optional output schema for the resource */
+    outputSchema?: unknown;
+    /** Optional extra data */
+    extra?: unknown;
+}
+/**
+ * Verify request body for the facilitator /verify endpoint -- the **v1**
+ * envelope. {@link VerifyRequestV2} is the other one.
+ */
+interface VerifyRequest {
+    /**
+     * Always `1`: this marker names the ENVELOPE, and this envelope is v1.
+     *
+     * Narrowed from `X402Version` on 2026-09-04. A `VerifyRequest` carrying `2`
+     * was always an uninhabitable value -- a body declaring v2 while shaped as
+     * v1 -- and typing it as `1 | 2` is what let the payer's marker be copied in
+     * here. The payer's version lives in `paymentPayload.x402Version`, which is
+     * still the full union.
+     */
+    x402Version: 1;
+    paymentPayload: X402Header;
+    paymentRequirements: PaymentRequirements;
+}
+/**
+ * Settle request body for the facilitator /settle endpoint -- the **v1**
+ * envelope. {@link SettleRequestV2} is the other one.
+ */
+interface SettleRequest {
+    /** Always `1` -- see {@link VerifyRequest.x402Version}. */
+    x402Version: 1;
+    paymentPayload: X402Header;
+    paymentRequirements: PaymentRequirements;
+}
+/**
+ * Verify response from the facilitator
+ */
+interface VerifyResponse extends FacilitatorFailureFields {
+    isValid: boolean;
+    /**
+     * Why the payment is not valid.
+     *
+     * Read `retryable` before showing this to anyone. When `retryable` is true the
+     * facilitator reached NO VERDICT -- it did not reject the payment, so this
+     * string is a transport diagnosis, not a rejection, and re-signing on it makes
+     * the buyer pay twice.
+     */
+    invalidReason?: string;
+    payer?: string;
+    network?: string;
+}
+/**
+ * Settle response from the facilitator
+ */
+interface SettleResponse extends FacilitatorFailureFields {
+    success: boolean;
+    transactionHash?: string;
+    network?: string;
+    /**
+     * Transport-level failure (unreachable facilitator, non-2xx, timeout).
+     *
+     * `success: false` with `retryable: true` is NOT a rejected payment. The
+     * authorization is untouched and the same one must be resent; treating it as
+     * a refusal and asking for a new signature charges the buyer twice.
+     */
+    error?: string;
+    /**
+     * The facilitator's own reason when it settled nothing — e.g. a transfer that
+     * mined and reverted. Distinct from `error` above, which is this client
+     * failing to ask; this one is the facilitator answering "no".
+     */
+    errorReason?: string;
+    /** The address the facilitator confirmed as the payer. */
+    payer?: string;
+    /**
+     * Settlement proof, present when the ERC-8004 extension asked for it.
+     *
+     * Typed here rather than only on {@link SettleResponseWithProof} because
+     * `settle()` returns it whenever the facilitator sends it, and it is what
+     * DX402's `anchorEvidence` needs to reach `verified: true`.
+     */
+    proofOfPayment?: ProofOfPayment;
+}
+/**
+ * Options for building payment requirements
+ */
+interface PaymentRequirementsOptions {
+    /** Amount in human-readable format (e.g., "1.00") */
+    amount: string;
+    /** Recipient address */
+    recipient: string;
+    /** Resource URL being protected */
+    resource: string;
+    /** Chain name (e.g., "base") */
+    chainName?: string;
+    /** Description of the resource */
+    description?: string;
+    /** MIME type of the resource */
+    mimeType?: string;
+    /** Timeout in seconds (default: 300) */
+    timeoutSeconds?: number;
+    /** x402 version to use */
+    x402Version?: X402Version;
+}
+/**
+ * x402 payment option advertised in a 402 response.
+ *
+ * The SDK keeps the response shape richer than the minimal protocol fields so
+ * servers can preserve settlement-critical metadata such as payTo and extra.
+ */
+interface PaymentAcceptance {
+    network: string;
+    asset: string;
+    amount: string;
+    /**
+     * Payment scheme. REQUIRED by the facilitator's v2 `PaymentRequirementsV2`.
+     *
+     * Optional here only so existing callers keep compiling — when it is absent,
+     * `buildRequirementFromAcceptance` defaults it to `'exact'`. Do not treat its
+     * optionality as "the facilitator does not need it": an accepts[] entry that
+     * reaches a v2 client without a scheme is unpayable.
+     */
+    scheme?: string;
+    payTo?: string;
+    facilitator?: string;
+    resource?: string;
+    description?: string;
+    mimeType?: string;
+    maxTimeoutSeconds?: number;
+    outputSchema?: unknown;
+    extra?: unknown;
+}
+/**
+ * Verified payment context attached by server middleware.
+ */
+interface VerifiedPaymentState {
+    payment: X402Header;
+    requirements: PaymentRequirements;
+    verifyResult: VerifyResponse;
+    settle: () => Promise<SettleResponse>;
+}
+/**
+ * Shared server middleware options.
+ */
+interface PaymentMiddlewareOptions extends FacilitatorClientOptions {
+    /** Alias for baseUrl to keep middleware options ergonomic */
+    facilitatorUrl?: string;
+    /**
+     * Settlement behavior after verification.
+     * - manual: verify only; caller settles explicitly
+     * - before-handler: settle immediately before calling next()
+     */
+    settlementStrategy?: 'manual' | 'before-handler';
+}
+/**
+ * Custom resolver for selecting the correct payment requirement when multiple
+ * accepts are advertised.
+ */
+type PaymentRequirementResolver = (payment: X402Header, requirements: PaymentRequirements[]) => PaymentRequirements | null | Promise<PaymentRequirements | null>;
+/**
+ * Parse X-PAYMENT or PAYMENT-SIGNATURE header value
+ *
+ * @param headerValue - Base64-encoded header value (or undefined/null)
+ * @returns Parsed x402 header object, or null if invalid
+ *
+ * @example
+ * ```ts
+ * // Express.js
+ * const payment = parsePaymentHeader(req.headers['x-payment']);
+ * if (!payment) {
+ *   return res.status(400).json({ error: 'Invalid payment header' });
+ * }
+ * ```
+ */
+declare function parsePaymentHeader(headerValue: string | undefined | null): X402Header | null;
+/**
+ * Extract payment header from request headers object
+ *
+ * Checks both X-PAYMENT and PAYMENT-SIGNATURE headers.
+ *
+ * @param headers - Request headers object (case-insensitive)
+ * @returns Parsed x402 header object, or null if not found/invalid
+ *
+ * @example
+ * ```ts
+ * const payment = extractPaymentFromHeaders(req.headers);
+ * ```
+ */
+declare function extractPaymentFromHeaders(headers: Record<string, string | string[] | undefined>): X402Header | null;
+/**
+ * Build payment requirements for the facilitator
+ *
+ * @param options - Payment requirements options
+ * @returns PaymentRequirements object ready for verify/settle
+ *
+ * @example
+ * ```ts
+ * const requirements = buildPaymentRequirements({
+ *   amount: '1.00',
+ *   recipient: '0x1234...',
+ *   resource: 'https://api.example.com/premium-data',
+ *   chainName: 'base',
+ * });
+ * ```
+ */
+declare function buildPaymentRequirements(options: PaymentRequirementsOptions): PaymentRequirements;
+/**
+ * Build a verify request for the facilitator /verify endpoint
+ *
+ * @param paymentHeader - Parsed x402 payment header
+ * @param requirements - Payment requirements
+ * @returns VerifyRequest body ready for fetch/axios
+ *
+ * @example
+ * ```ts
+ * const payment = parsePaymentHeader(req.headers['x-payment']);
+ * const verifyBody = buildVerifyRequest(payment, requirements);
+ *
+ * const response = await fetch('https://facilitator.uvd.xyz/verify', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify(verifyBody),
+ * });
+ * ```
+ */
+declare function buildVerifyRequest(paymentHeader: X402Header, requirements: PaymentRequirements): VerifyRequest;
+/**
+ * Build a settle request for the facilitator /settle endpoint
+ *
+ * @param paymentHeader - Parsed x402 payment header
+ * @param requirements - Payment requirements
+ * @returns SettleRequest body ready for fetch/axios
+ */
+/**
+ * Describes the protected resource, as x402 v2 expects it.
+ *
+ * Note this is an OBJECT in v2. Sending a bare URL string here is the single
+ * most common v2 mistake and it fails as an unhelpful "no variant matched"
+ * deserialization error at the facilitator, naming no field.
+ */
+interface ResourceInfoV2 {
+    url: string;
+    description: string;
+    mimeType: string;
+}
+/**
+ * Payment requirements in x402 v2 form.
+ *
+ * Differences from v1 that actually bite:
+ * - `network` is CAIP-2 (`eip155:8453`), NOT a plain name (`base`). Mixing a v1
+ *   name into a v2 request fails deserialization, and vice versa.
+ * - `maxAmountRequired` is renamed to `amount`.
+ * - `resource` / `description` / `mimeType` moved out to {@link ResourceInfoV2}.
+ */
+interface PaymentRequirementsV2 {
+    scheme: string;
+    /** CAIP-2 chain id, e.g. `eip155:8453`. */
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: unknown;
+}
+/** The v2 payment payload — note it carries no top-level scheme/network. */
+interface PaymentPayloadV2 {
+    x402Version: 2;
+    resource: ResourceInfoV2;
+    accepted: PaymentRequirementsV2;
+    payload: X402PayloadData;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Verify request body in x402 v2 form.
+ *
+ * There is deliberately NO `paymentRequirements` key: that is the v1 envelope.
+ * v2 carries `resource` and `accepted` at the top level instead.
+ */
+interface VerifyRequestV2 {
+    x402Version: 2;
+    paymentPayload: PaymentPayloadV2;
+    resource: ResourceInfoV2;
+    accepted: PaymentRequirementsV2;
+}
+/** Settle request body in x402 v2 form. Same shape as {@link VerifyRequestV2}. */
+type SettleRequestV2 = VerifyRequestV2;
+/**
+ * Build a verify request for the facilitator `/verify` endpoint, in **v2** form.
+ *
+ * Use this whenever your 402 advertises CAIP-2 networks. {@link buildVerifyRequest}
+ * emits the v1 envelope `{x402Version, paymentPayload, paymentRequirements}` and
+ * cannot express v2 — putting a v2 payload inside it matches no variant at the
+ * facilitator and fails with an error that names no field.
+ *
+ * @example
+ * ```ts
+ * const body = buildVerifyRequestV2(
+ *   payment.payload,
+ *   { url: 'https://api.example.com/thing', description: 'Thing', mimeType: 'application/json' },
+ *   { scheme: 'exact', network: 'eip155:8453', asset: '0x8335...', amount: '100000',
+ *     payTo: '0xabc...', maxTimeoutSeconds: 300 }
+ * );
+ * ```
+ */
+declare function buildVerifyRequestV2(payload: X402PayloadData, resource: ResourceInfoV2, accepted: PaymentRequirementsV2): VerifyRequestV2;
+/**
+ * Build a settle request for the facilitator `/settle` endpoint, in **v2** form.
+ *
+ * See {@link buildVerifyRequestV2} — the envelope is identical.
+ */
+declare function buildSettleRequestV2(payload: X402PayloadData, resource: ResourceInfoV2, accepted: PaymentRequirementsV2): SettleRequestV2;
+declare function buildSettleRequest(paymentHeader: X402Header, requirements: PaymentRequirements): SettleRequest;
+/**
+ * Derive the v2 `resource` object from v1-shaped requirements.
+ *
+ * v2 moved `resource` / `description` / `mimeType` out of the requirements and
+ * into an object of their own, and the facilitator requires ALL THREE keys:
+ * measured 2026-09-03, a `resource` carrying only `url` is a 400.
+ *
+ * The `??` defaults are not decoration. `PaymentRequirements` types these as
+ * required, but a JavaScript caller can still hand over an object without them,
+ * and a missing key does not fail with "description is missing" -- it fails with
+ * `data did not match any variant of untagged enum VerifyRequestEnvelope`, which
+ * names no field. That error is what cost two teams a day.
+ */
+declare function toResourceInfoV2(requirements: PaymentRequirements): ResourceInfoV2;
+/**
+ * Derive v2 `accepted` requirements from v1-shaped requirements.
+ *
+ * Two renames do the damage, and neither is reported by name when it is wrong:
+ * - `maxAmountRequired` is spelled `amount` in v2.
+ * - `network` must be CAIP-2; a plain name inside a v2 body is a 400.
+ *
+ * `extra` is carried through when present -- it is where the EIP-712 domain
+ * `name`/`version` live for tokens the facilitator does not know by address, so
+ * dropping it breaks EURC and the bridged USDCs.
+ *
+ * @throws If `requirements.network` has NO CAIP-2 form. `chainToCAIP2` answers
+ * with the name unchanged when it does not know a chain, and XRPL maps to
+ * itself on purpose -- its v1 string IS its network id. Passing that through
+ * would put a plain name inside a v2 body, which is a measured 400 (the same
+ * `no variant matched` that names no field). Only reachable by PINNING version
+ * 2 on such a network; `auto` leaves them on v1, where they work. Failing here
+ * names the network and the fix, which a 400 from the facilitator does not.
+ */
+declare function toPaymentRequirementsV2(requirements: PaymentRequirements): PaymentRequirementsV2;
+/**
+ * Decide which envelope this (payment, requirements) pair has to travel in.
+ *
+ * `requested` wins when it names a version; `'auto'` (the default) reads the
+ * wire.
+ *
+ * **Auto keys off CAIP-2, NOT off `paymentHeader.x402Version`,** and that is a
+ * measured decision rather than a stylistic one. The facilitator's envelope enum
+ * is untagged: it matches on SHAPE and ignores the version marker.
+ *
+ * Re-measured against `https://facilitator.ultravioletadao.xyz/verify` on
+ * **2026-09-04** with a fabricated signature. The signature never verifies, so
+ * every row is an HTTP 400 and the STATUS discriminates nothing -- what does is
+ * the error code. `invalid_request_body` means the facilitator could not
+ * deserialize the body; `contract_call_failed` means it read the body, resolved
+ * the chain and got as far as the on-chain call, i.e. the envelope was fine.
+ *
+ * | payload network | requirements network | v1 envelope today |
+ * |-----------------|----------------------|-------------------|
+ * | `base`          | `base`               | understood        |
+ * | `base` (header says `x402Version: 2`) | `base` | understood |
+ * | `eip155:8453`   | `base`               | understood        |
+ * | `base`          | `eip155:8453`        | understood        |
+ * | `eip155:8453`   | `eip155:8453`        | understood        |
+ *
+ * **The last three rows used to be a hard 400** (`unknown variant
+ * \`eip155:8453\``) when this function was written on 2026-09-03. The
+ * facilitator has since taught the v1 envelope to read CAIP-2, so the original
+ * argument for this rule -- "every CAIP-2 combination is already a 400, so
+ * upgrading them cannot regress anyone" -- **is no longer true**. The rule is
+ * unchanged; three other reasons hold it up:
+ *
+ * 1. A CAIP-2 network on the wire means the 402 that produced it advertised v2.
+ *    Answering in v2 is speaking the protocol the seller announced.
+ * 2. v2-with-CAIP-2 is the only shape BOTH generations of the facilitator
+ *    accept. v1-with-CAIP-2 is a hard 400 on any build older than 2026-09-04,
+ *    so choosing v1 there is what breaks against a self-hosted or pinned one.
+ * 3. The Python SDK resolves the identical rule, so the same wire produces the
+ *    same body in both SDKs -- pinned by phase 6 of `npm run test:xlang`.
+ *
+ * And the marker still decides nothing: row 2 above is served correctly today,
+ * so upgrading on the strength of it would change a call that works.
+ *
+ * The negative half of that measurement, without which "understood" proves
+ * nothing -- the same run, bodies broken on purpose, all three
+ * `invalid_request_body`: a v2 body carrying a plain network name, one with
+ * `resource` as a bare string, and one with `accepted` removed. A well-formed
+ * v2 body with CAIP-2 reached `contract_call_failed` like the rows above.
+ */
+declare function resolveEnvelopeVersion(paymentHeader: X402Header | PaymentPayloadV2, requirements: PaymentRequirements, requested?: X402Version | 'auto'): X402Version;
+/**
+ * Build a `/verify` body in whichever envelope `version` names.
+ *
+ * The v1 return is byte-for-byte what {@link buildVerifyRequest} produces, so
+ * pinning `1` is exactly today's behaviour.
+ *
+ * @example
+ * ```ts
+ * const version = resolveEnvelopeVersion(payment, requirements);
+ * const body = buildVerifyRequestForVersion(payment, requirements, version);
+ * ```
+ */
+declare function buildVerifyRequestForVersion(paymentHeader: X402Header, requirements: PaymentRequirements, version: X402Version): VerifyRequest | VerifyRequestV2;
+/**
+ * Build a `/settle` body in whichever envelope `version` names.
+ *
+ * See {@link buildVerifyRequestForVersion} -- `/settle` takes the same body as
+ * `/verify` in both versions.
+ */
+declare function buildSettleRequestForVersion(paymentHeader: X402Header, requirements: PaymentRequirements, version: X402Version): SettleRequest | SettleRequestV2;
+/**
+ * Recommended CORS headers for x402 payment APIs
+ *
+ * These headers allow browsers to send payment headers in cross-origin requests.
+ */
+declare const X402_CORS_HEADERS: {
+    readonly 'Access-Control-Allow-Headers': "Content-Type, X-PAYMENT, PAYMENT-SIGNATURE, Authorization";
+    readonly 'Access-Control-Expose-Headers': "X-PAYMENT-RESPONSE, PAYMENT-RESPONSE, PAYMENT-REQUIRED";
+    readonly 'Access-Control-Allow-Methods': "GET, POST, OPTIONS";
+};
+/**
+ * All x402 custom header names that should be allowed in CORS
+ */
+declare const X402_HEADER_NAMES: readonly ["X-PAYMENT", "PAYMENT-SIGNATURE", "X-PAYMENT-RESPONSE", "PAYMENT-RESPONSE", "PAYMENT-REQUIRED"];
+/**
+ * Get CORS headers with custom origin
+ *
+ * @param origin - Allowed origin (use '*' for any, or specific domain)
+ * @returns Complete CORS headers object
+ *
+ * @example
+ * ```ts
+ * // Express.js middleware
+ * app.use((req, res, next) => {
+ *   const corsHeaders = getCorsHeaders('https://myapp.com');
+ *   Object.entries(corsHeaders).forEach(([key, value]) => {
+ *     res.setHeader(key, value);
+ *   });
+ *   if (req.method === 'OPTIONS') {
+ *     return res.status(204).end();
+ *   }
+ *   next();
+ * });
+ * ```
+ */
+declare function getCorsHeaders(origin?: string): Record<string, string>;
+/**
+ * Options for the FacilitatorClient
+ */
+interface FacilitatorClientOptions {
+    /** Base URL of the facilitator (default: https://facilitator.ultravioletadao.xyz) */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds (default: auto per network).
+     * When not set, the client uses per-network defaults from ESCROW_TIMEOUT_MS
+     * (960s for Ethereum L1, 90s for L2s, 30s for others).
+     * Set explicitly to override per-network auto-detection.
+     */
+    timeout?: number;
+    /**
+     * Extra attempts after the first when the facilitator answers a refusal it
+     * proved it did not execute (`safeToReplay`). Default 2; `0` disables.
+     *
+     * Only ever spent on `429` and on a `503` naming a pre-execution writer-lease
+     * reason. An ambiguous `forward_failed` -- whose write may already have landed
+     * -- is never replayed here, at any setting.
+     */
+    retries?: number;
+    /**
+     * Which envelope to send to `/verify` and `/settle`. Default `'auto'`.
+     *
+     * `'auto'` reads the wire: CAIP-2 networks get the v2 envelope, plain names
+     * get v1. See {@link resolveEnvelopeVersion} for the measurements behind that
+     * rule. Pin `1` or `2` to take the decision yourself -- a pin is honoured
+     * even when it contradicts the wire, because choosing the version is the
+     * point of the option.
+     */
+    x402Version?: X402Version | 'auto';
+}
+/**
+ * Client for interacting with the x402 facilitator API
+ *
+ * @example
+ * ```ts
+ * const client = new FacilitatorClient();
+ *
+ * // Verify a payment
+ * const verifyResult = await client.verify(paymentHeader, requirements);
+ * if (!verifyResult.isValid) {
+ *   return res.status(402).json({ error: verifyResult.invalidReason });
+ * }
+ *
+ * // Provide the service, then settle
+ * const settleResult = await client.settle(paymentHeader, requirements);
+ * if (!settleResult.success) {
+ *   // Handle settlement failure (maybe refund or retry)
+ * }
+ * ```
+ */
+declare class FacilitatorClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly explicitTimeout;
+    private readonly retries;
+    private readonly x402Version;
+    constructor(options?: FacilitatorClientOptions);
+    /**
+     * Get timeout for a specific network, using per-chain defaults when no explicit timeout was set.
+     */
+    private getTimeout;
+    /**
+     * Verify a payment with the facilitator
+     *
+     * Call this before providing the paid resource to validate the payment.
+     *
+     * @param paymentHeader - Parsed x402 payment header
+     * @param requirements - Payment requirements
+     * @returns Verification result
+     */
+    verify(paymentHeader: X402Header, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settle a payment with the facilitator
+     *
+     * Call this after providing the paid resource to execute the on-chain transfer.
+     *
+     * @param paymentHeader - Parsed x402 payment header
+     * @param requirements - Payment requirements
+     * @returns Settlement result with transaction hash
+     */
+    settle(paymentHeader: X402Header, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Verify and settle atomically
+     *
+     * Convenience method that verifies first, then settles if valid.
+     * Use this for simple payment flows where you don't need custom logic between verify and settle.
+     *
+     * @param paymentHeader - Parsed x402 payment header
+     * @param requirements - Payment requirements
+     * @returns Combined result with verify and settle status
+     */
+    verifyAndSettle(paymentHeader: X402Header, requirements: PaymentRequirements): Promise<{
+        verified: boolean;
+        settled: boolean;
+        transactionHash?: string;
+        error?: string;
+    } & FacilitatorFailureFields>;
+    /**
+     * Check if the facilitator is healthy
+     *
+     * @returns True if the facilitator is responding
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Get the facilitator version info
+     *
+     * @returns Version info (e.g., { version: "1.37.0" })
+     */
+    getVersion(): Promise<{
+        version: string;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Get the facilitator's supported networks and payment schemes
+     *
+     * @returns Supported networks/schemes with 'kinds' array
+     *
+     * @example
+     * ```ts
+     * const supported = await client.getSupported();
+     * for (const kind of supported.kinds) {
+     *   console.log(`${kind.network} - ${kind.scheme}`);
+     * }
+     * ```
+     */
+    getSupported(): Promise<{
+        kinds: Array<{
+            network: string;
+            scheme: string;
+            [key: string]: unknown;
+        }>;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Aggregated totals per network and asset (`GET /api/stats`).
+     *
+     * **An index, not a ledger.** Records are written best-effort AFTER
+     * settlement, so an outage loses rows while payments proceed — verify
+     * anything that matters against the transaction hash. Counting starts when
+     * the operator enabled the store, so earlier operations are UNKNOWN, not
+     * zero. And unless `X402_EVENTS_PUBLISH_FAILURES=true`, operations that ERROR
+     * are not recorded at all: a 100% success rate means "no failures were
+     * recorded".
+     *
+     * `volumeAtomic` is a STRING (u256-shaped; a JS number loses precision above
+     * 2^53) and each row carries its own `decimals`. **Use that, never a
+     * constant** — USDC is 6 decimals nearly everywhere and 18 on BSC, so scaling
+     * by 6 there overstates volume by 10^12. `decimals` is null when the asset is
+     * unrecognised; render the atomic value rather than guessing a scale.
+     */
+    getStats(): Promise<{
+        totals: {
+            settlesOk: number;
+            settlesFailed: number;
+            verifies: number;
+            networks: number;
+        };
+        byNetworkAndAsset: Array<{
+            network: string;
+            asset: string;
+            settlesOk: number;
+            settlesFailed: number;
+            verifies: number;
+            volumeAtomic: string;
+            decimals: number | null;
+            lastTs: number;
+        }>;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Recent recorded operations, newest first (`GET /transactions`).
+     *
+     * There is **no pagination and no cursor**: this returns the newest N,
+     * walking back at most 30 days. With 10,000 rows you get the newest 200, not
+     * page one of fifty. `limit` is clamped to 200 by the facilitator.
+     *
+     * `network` matches the canonical slug `/supported` uses, which is not always
+     * the alias you may send — `skale` is accepted inbound but records say
+     * `skale-base`.
+     */
+    getTransactions(options?: {
+        limit?: number;
+        network?: string;
+    }): Promise<{
+        transactions: Array<Record<string, unknown>>;
+        count: number;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Get the facilitator's blocked/sanctioned addresses
+     *
+     * @returns Blacklist info (totalBlocked, loadedAtStartup, addresses)
+     *
+     * @example
+     * ```ts
+     * const bl = await client.getBlacklist();
+     * console.log(`Blocked: ${bl.totalBlocked} addresses`);
+     * ```
+     */
+    getBlacklist(): Promise<{
+        totalBlocked: number;
+        loadedAtStartup: boolean;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Negotiate payment requirements with the facilitator via POST /accepts.
+     *
+     * Sends merchant payment requirements to the facilitator, which matches
+     * them against its supported capabilities and returns enriched requirements
+     * with facilitator data (feePayer, tokens, escrow configuration).
+     *
+     * This is used by Faremeter middleware and clients that need to discover
+     * what the facilitator can settle before constructing payment authorizations.
+     *
+     * @param paymentRequirements - List of payment requirement objects
+     * @param x402Version - x402 protocol version (default: 2)
+     * @returns List of enriched payment requirements with facilitator extras
+     *
+     * @example
+     * ```ts
+     * const enriched = await client.accepts([
+     *   {
+     *     scheme: 'exact',
+     *     network: 'base-mainnet',
+     *     maxAmountRequired: '1000000',
+     *     resource: 'https://api.example.com/data',
+     *     payTo: '0xMerchant...',
+     *   },
+     * ]);
+     * // enriched[0].extra.feePayer is now set
+     * ```
+     */
+    accepts(paymentRequirements: PaymentRequirements[], x402Version?: number): Promise<PaymentRequirements[]>;
+}
+/**
+ * Create a 402 Payment Required response
+ *
+ * @param requirements - Payment requirements
+ * @param options - Additional response options
+ * @returns Object with status code, headers, and body for the 402 response
+ *
+ * @example
+ * ```ts
+ * // Express.js
+ * app.get('/premium-data', (req, res) => {
+ *   const payment = extractPaymentFromHeaders(req.headers);
+ *
+ *   if (!payment) {
+ *     const { status, headers, body } = create402Response({
+ *       amount: '1.00',
+ *       recipient: '0x...',
+ *       resource: 'https://api.example.com/premium-data',
+ *     });
+ *     return res.status(status).set(headers).json(body);
+ *   }
+ *
+ *   // Verify and serve...
+ * });
+ * ```
+ */
+declare function create402Response(requirements: PaymentRequirementsOptions, options?: {
+    accepts?: PaymentAcceptance[];
+}): {
+    status: 402;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+};
+/** The body of a no-verdict refusal. See {@link buildUnavailableResponse}. */
+interface UnavailableBody {
+    /** Human-readable summary. Never says the payment was rejected. */
+    error: string;
+    /** The facilitator's own reason, under whichever field it populated. */
+    reason?: string;
+    /** Always `true` — this response exists to say "no verdict", not "refused". */
+    retryable: true;
+    /** Whole seconds to wait, mirroring the `Retry-After` header. */
+    retryAfterSeconds: number;
+    /**
+     * `false` for `forward_failed` and for a bare timeout: the write may already
+     * have landed, so the caller must reconcile before resending.
+     */
+    safeToReplay: boolean;
+}
+/** A framework-agnostic HTTP response. See {@link buildUnavailableResponse}. */
+interface UnavailableResponse {
+    /** Always 503. */
+    status: 503;
+    /** `Retry-After`, ready to spread onto any framework's header setter. */
+    headers: Record<string, string>;
+    body: UnavailableBody;
+    /** Same value as the header, already clamped to a whole second >= 1. */
+    retryAfterSeconds: number;
+}
+/**
+ * Build the answer to a facilitator refusal that reached NO VERDICT.
+ *
+ * `verify` returns invalid for two different things: a payment that was
+ * REJECTED, and a facilitator that never reached a verdict (`retryable`).
+ * Answering `402` in the second case tells the buyer to sign a NEW
+ * authorization while the first one is still live and still spendable by the
+ * facilitator — so the buyer pays twice. The correct answer is `503` plus
+ * `Retry-After`, which asks for the SAME credential again.
+ *
+ * This returns plain data — status, headers, body — so a handler written
+ * without Express (Lambda, Hono, a Next route, Fastify, a bare `Response`) can
+ * answer correctly without re-deriving the rule. The Express and Hono
+ * middlewares in this SDK both build their reply from it.
+ *
+ * @param message - Summary for the `error` field, e.g. `'Payment verification unavailable'`
+ * @param failure - The facilitator result. Only its failure fields are read.
+ *
+ * @example Lambda / any framework
+ * ```ts
+ * const verifyResult = await client.verify(payment, requirements);
+ * if (!verifyResult.isValid && verifyResult.retryable) {
+ *   const r = buildUnavailableResponse('Payment verification unavailable', verifyResult);
+ *   return { statusCode: r.status, headers: r.headers, body: JSON.stringify(r.body) };
+ * }
+ * ```
+ *
+ * @example Web `Response`
+ * ```ts
+ * const r = buildUnavailableResponse('Payment settlement unavailable', settleResult);
+ * return Response.json(r.body, { status: r.status, headers: r.headers });
+ * ```
+ */
+declare function buildUnavailableResponse(message: string, failure: FacilitatorFailureFields & {
+    error?: string;
+    invalidReason?: string;
+}): UnavailableResponse;
+/**
+ * Create an Express-compatible middleware for x402 payments
+ *
+ * @param getRequirements - Function to get payment requirements for a request
+ * @param options - Middleware options
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * const paymentMiddleware = createPaymentMiddleware(
+ *   (req) => ({
+ *     amount: '1.00',
+ *     recipient: process.env.PAYMENT_RECIPIENT,
+ *     resource: `${req.protocol}://${req.get('host')}${req.originalUrl}`,
+ *   }),
+ *   { facilitatorUrl: 'https://facilitator.uvd.xyz' }
+ * );
+ *
+ * app.get('/premium/*', paymentMiddleware, async (req, res) => {
+ *   const settleResult = await req.x402?.settle();
+ *   if (!settleResult?.success) {
+ *     return res.status(500).json({ error: settleResult?.error });
+ *   }
+ *
+ *   res.json({ premium: 'data' });
+ * });
+ * ```
+ */
+declare function createPaymentMiddleware(getRequirements: (req: {
+    headers: Record<string, string | string[] | undefined>;
+}) => PaymentRequirementsOptions, options?: PaymentMiddlewareOptions): (req: {
+    headers: Record<string, string | string[] | undefined>;
+    x402?: VerifiedPaymentState;
+}, res: {
+    status: (code: number) => {
+        json: (body: unknown) => void;
+        set: (headers: Record<string, string>) => {
+            json: (body: unknown) => void;
+        };
+    };
+}, next: () => void) => Promise<void>;
+/**
+ * Options for creating a Hono x402 payment middleware
+ */
+interface HonoMiddlewareOptions extends PaymentMiddlewareOptions {
+    /** Payment requirements to advertise */
+    accepts: PaymentAcceptance[];
+    /** Response version to advertise (defaults to auto) */
+    x402Version?: X402Version | 'auto';
+    /** Custom requirement resolver for ambiguous multi-accept flows */
+    resolveRequirement?: PaymentRequirementResolver;
+}
+declare function createHonoMiddleware(options: HonoMiddlewareOptions): (c: {
+    req: {
+        header: (name: string) => string | undefined;
+        url: string;
+    };
+    json: (body: unknown, status?: number) => unknown;
+    set?: (key: string, value: unknown) => void;
+    /** Hono's response-header setter. Optional so older context doubles still fit. */
+    header?: (name: string, value: string) => void;
+}, next: () => Promise<void>) => Promise<unknown>;
+/**
+ * Maximum length of the free-text `q` filter.
+ *
+ * Mirrors the facilitator's `MAX_SEARCH_LEN`; a longer needle is rejected
+ * server-side with a 400.
+ */
+declare const MAX_SEARCH_LEN = 128;
+/**
+ * Liveness of a registered resource, as measured by the facilitator's prober.
+ *
+ * Resources that stop answering are quarantined rather than deleted, so filter
+ * on this before paying anyone.
+ */
+type DiscoveryHealthStatus = 'alive' | 'degraded' | 'auth_gated' | 'quarantined' | 'unknown' | 'unprobeable';
+/** Values accepted by the `health` filter, including the `any` escape hatch. */
+declare const HEALTH_FILTERS: readonly ["alive", "degraded", "auth_gated", "quarantined", "unknown", "unprobeable", "any"];
+/** Curated tier, in descending order of trust. */
+type DiscoveryTier = 'first_party' | 'vip' | 'verified' | 'listed';
+/** Values accepted by the `tier` filter. */
+declare const TIER_FILTERS: readonly ["first_party", "vip", "verified", "listed"];
+/** How a resource got into the registry. */
+type DiscoverySource = 'self_registered' | 'settlement' | 'crawled' | 'aggregated';
+/** Health of a single resource, as reported by the registry's prober. */
+interface DiscoveryHealth {
+    /** Last observed liveness */
+    status?: DiscoveryHealthStatus;
+    /** Unix epoch seconds of the last probe */
+    lastChecked?: number;
+    /** HTTP status the probe got back (402 is the healthy answer for x402) */
+    httpStatus?: number;
+    /** Round-trip time of the last probe, in milliseconds */
+    latencyMs?: number;
+}
+/** Curation metadata attached to a resource. */
+interface DiscoveryCuration {
+    /** Curated tier */
+    tier?: DiscoveryTier;
+    /** Human-readable name of the curated set */
+    label?: string;
+}
+/** One payment method a resource declares. */
+interface DiscoveryAccepts {
+    /** Payment scheme ("exact", "escrow", "commerce") */
+    scheme: string;
+    /** CAIP-2 network id, e.g. "eip155:8453" */
+    network: string;
+    /** Token contract address */
+    asset?: string;
+    /** Price in atomic units of `asset` */
+    amount?: string;
+    /** Recipient address */
+    payTo?: string;
+    /** Settlement deadline in seconds */
+    maxTimeoutSeconds?: number;
+    /** Scheme-specific extras (EIP-712 domain, etc.) */
+    extra?: Record<string, unknown>;
+    /** Anything the registry adds later */
+    [key: string]: unknown;
+}
+/**
+ * A discoverable paid resource, exactly as `GET /discovery/resources` serves it.
+ *
+ * Timestamps are Unix epoch **seconds**, not ISO strings and not milliseconds.
+ */
+interface DiscoveryResource {
+    /** Resource URL. This is the registry's primary key -- there is no `id` */
+    url: string;
+    /** Resource type ("http", "mcp", "a2a") */
+    type: string;
+    /** x402 protocol version the resource speaks */
+    x402Version: number;
+    /** Human-readable description */
+    description?: string;
+    /** Payment methods the resource accepts */
+    accepts: DiscoveryAccepts[];
+    /** Free-form metadata (category, provider, tags) */
+    metadata?: Record<string, unknown>;
+    /** How this resource entered the registry */
+    source?: DiscoverySource;
+    /** Facilitator this resource was aggregated from */
+    sourceFacilitator?: string;
+    /** Unix epoch seconds when the registry first saw this resource */
+    firstSeen?: number;
+    /** Unix epoch seconds when the registry last saw this resource */
+    lastSeen?: number;
+    /** Unix epoch seconds of the last change to this record */
+    lastUpdated?: number;
+    /** Liveness, when the resource has been probed */
+    health?: DiscoveryHealth;
+    /** Curation tier, when the resource has been curated */
+    curation?: DiscoveryCuration;
+    /** Anything the registry adds later */
+    [key: string]: unknown;
+}
+/** Pagination envelope of `GET /discovery/resources`. */
+interface DiscoveryPagination {
+    /** Page size that was applied */
+    limit: number;
+    /** Offset that was applied */
+    offset: number;
+    /** Total number of resources matching the filters, across all pages */
+    total: number;
+}
+/** Paginated response from `GET /discovery/resources`. */
+interface DiscoveryResponse {
+    /** x402 protocol version of the response envelope */
+    x402Version: number;
+    /** Resources on this page */
+    items: DiscoveryResource[];
+    /** Pagination state */
+    pagination: DiscoveryPagination;
+}
+/**
+ * Filters for `listResources()`.
+ *
+ * Every one of these is applied server-side over the whole catalog, so
+ * `pagination.total` reflects the filtered set. Filtering a page after the
+ * fact is not the same thing and will under-report.
+ */
+interface DiscoveryListOptions {
+    /** Page size (default: 10, max: 100) */
+    limit?: number;
+    /** Number of resources to skip */
+    offset?: number;
+    /** Filter by category */
+    category?: string;
+    /** Filter by network, CAIP-2 or v1 name */
+    network?: string;
+    /** Filter by provider name */
+    provider?: string;
+    /** Filter by tag */
+    tag?: string;
+    /** Filter by how the resource was discovered */
+    source?: DiscoverySource;
+    /** Filter by originating facilitator */
+    sourceFacilitator?: string;
+    /** Filter by liveness, or 'any' to opt out of the default visibility rules */
+    health?: DiscoveryHealthStatus | 'any';
+    /** Filter by curated tier */
+    tier?: DiscoveryTier;
+    /** Free-text search over url / description / provider / category / tags */
+    q?: string;
+}
+/** Options for `registerResource()`. */
+interface DiscoveryRegisterOptions {
+    /** URL of the paid resource. Doubles as its identity in the registry */
+    url: string;
+    /** Resource type (default: "http") */
+    type?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Payment methods the resource accepts */
+    accepts?: DiscoveryAccepts[];
+    /** Free-form metadata (category, provider, tags) */
+    metadata?: Record<string, unknown>;
+}
+/** Aggregate catalog metrics from `GET /discovery/stats`. */
+interface DiscoveryStats {
+    /** Every record the registry holds, including quarantined ones */
+    total: number;
+    /** Records served by default listings */
+    visible: number;
+    /** Counts by discovery source */
+    bySource: Record<string, number>;
+    /** Counts by originating facilitator */
+    bySourceFacilitator: Record<string, number>;
+    /** Counts by CAIP-2 network */
+    byNetwork: Record<string, number>;
+    /** Counts by curated tier */
+    byTier: Record<string, number>;
+    /** Counts by liveness */
+    byHealth: Record<string, number>;
+    /** Unix epoch seconds this snapshot was computed (60s cache) */
+    generatedAt?: number;
+}
+/** Options for the {@link BazaarClient}. */
+interface BazaarClientOptions {
+    /** Facilitator base URL (default: https://facilitator.ultravioletadao.xyz) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/** Render an epoch-seconds field as a `Date`. */
+declare function epochToDate(seconds?: number): Date | undefined;
+/** True when the last probe reached this resource. */
+declare function isAlive(resource: DiscoveryResource): boolean;
+/**
+ * Client for the x402 Bazaar Discovery API.
+ *
+ * The Bazaar is the facilitator's own registry of x402-enabled resources.
+ * Providers register their endpoints and consumers discover them, with a
+ * liveness probe and a curation tier attached to every record.
+ *
+ * @example
+ * ```ts
+ * const bazaar = new BazaarClient();
+ *
+ * // Only endpoints a probe actually reached, best-curated first
+ * const page = await bazaar.listResources({ limit: 20, health: 'alive', tier: 'vip' });
+ * for (const r of page.items) {
+ *   console.log(r.url, r.health?.status, r.health?.latencyMs, r.curation?.label);
+ * }
+ *
+ * // Free-text search runs server-side over the whole catalog
+ * const hits = await bazaar.listResources({ q: 'logs' });
+ * console.log(hits.pagination.total);
+ *
+ * // Register your own
+ * await bazaar.registerResource({
+ *   url: 'https://api.example.com/v1/generate',
+ *   description: 'Generate images with AI',
+ *   accepts: [{
+ *     scheme: 'exact',
+ *     network: 'eip155:8453',
+ *     asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ *     amount: '10000',
+ *     payTo: '0xYourWallet...',
+ *     maxTimeoutSeconds: 60,
+ *   }],
+ *   metadata: { category: 'ai', tags: ['image'] },
+ * });
+ * ```
+ */
+declare class BazaarClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options?: BazaarClientOptions);
+    /**
+     * Issue a request against the facilitator with the configured timeout.
+     */
+    private request;
+    /**
+     * List resources from the discovery registry.
+     *
+     * @param options - Server-side filters and pagination
+     * @returns One page of resources plus the total across all pages
+     *
+     * @example
+     * ```ts
+     * const page = await bazaar.listResources({ network: 'eip155:8453', health: 'alive' });
+     * ```
+     */
+    listResources(options?: DiscoveryListOptions): Promise<DiscoveryResponse>;
+    /**
+     * Walk the whole filtered catalog, one page at a time.
+     *
+     * Pages are fetched in sequence rather than in parallel: the read routes are
+     * rate limited, and a burst of parallel pages is how a legitimate catalog
+     * walk turns into a wall of 429s.
+     *
+     * @param options - Same filters as {@link listResources}; `limit` is the page size
+     *
+     * @example
+     * ```ts
+     * for await (const r of bazaar.iterateResources({ health: 'alive' })) {
+     *   console.log(r.url);
+     * }
+     * ```
+     */
+    iterateResources(options?: DiscoveryListOptions): AsyncGenerator<DiscoveryResource, void, undefined>;
+    /**
+     * Look up a single resource by its URL.
+     *
+     * The registry keys on URL and has no by-id lookup, so this searches and
+     * then matches exactly.
+     *
+     * @param resourceUrl - Exact URL of the resource
+     * @returns The resource, or null when it is not registered
+     */
+    getResourceByUrl(resourceUrl: string): Promise<DiscoveryResource | null>;
+    /**
+     * Register a paid resource in the discovery registry.
+     *
+     * Registration is open and rate limited; re-registering a known URL updates
+     * the existing record rather than creating a duplicate.
+     *
+     * @param options - Resource details
+     * @returns The registry's acknowledgement
+     */
+    registerResource(options: DiscoveryRegisterOptions): Promise<Record<string, unknown>>;
+    /**
+     * Aggregate catalog metrics (60s cached server-side).
+     *
+     * @returns Counts by source, facilitator, network, tier and liveness
+     */
+    getStats(): Promise<DiscoveryStats>;
+    /**
+     * Check that the facilitator serving the registry is up.
+     *
+     * @returns True when the facilitator answers its health check
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * @deprecated Renamed to {@link listResources}, which returns the registry's
+     * real `{ items, pagination }` envelope. The old `discover()` returned a
+     * `{ resources, page, totalPages }` shape that no endpoint ever served.
+     */
+    discover(options?: DiscoveryListOptions): Promise<DiscoveryResponse>;
+}
+/**
+ * @deprecated Use {@link DiscoveryResource}. The old shape (`id`, `name`,
+ * `pricePerRequest`, `isActive`, ISO `createdAt`) described an API that was
+ * never deployed.
+ */
+type BazaarResource = DiscoveryResource;
+/** @deprecated Use {@link DiscoveryResponse}. */
+type BazaarDiscoverResponse = DiscoveryResponse;
+/** @deprecated Use {@link DiscoveryListOptions}. */
+type BazaarDiscoverOptions = DiscoveryListOptions;
+/** @deprecated Use {@link DiscoveryRegisterOptions}. */
+type BazaarRegisterOptions = DiscoveryRegisterOptions;
+/**
+ * Escrow payment status
+ */
+type EscrowStatus = 'pending' | 'held' | 'released' | 'refunded' | 'disputed' | 'expired';
+/**
+ * Refund request status
+ */
+type RefundStatus = 'pending' | 'approved' | 'rejected' | 'processed' | 'disputed';
+/**
+ * Dispute resolution outcome
+ */
+type DisputeOutcome = 'pending' | 'payer_wins' | 'recipient_wins' | 'split';
+/**
+ * Escrow payment record
+ */
+interface EscrowPayment {
+    /** Unique escrow ID */
+    id: string;
+    /** Original payment header (base64 encoded) */
+    paymentHeader: string;
+    /** Current status */
+    status: EscrowStatus;
+    /** Network where payment was made */
+    network: string;
+    /** Payer address */
+    payer: string;
+    /** Recipient address */
+    recipient: string;
+    /** Amount in atomic units */
+    amount: string;
+    /** Token/asset contract */
+    asset: string;
+    /** Resource URL being paid for */
+    resource: string;
+    /** Escrow expiration timestamp (ISO) */
+    expiresAt: string;
+    /** Release conditions (optional) */
+    releaseConditions?: {
+        /** Minimum time before release (seconds) */
+        minHoldTime?: number;
+        /** Required confirmations */
+        confirmations?: number;
+        /** Custom condition metadata */
+        custom?: unknown;
+    };
+    /** Transaction hash if released/refunded */
+    transactionHash?: string;
+    /** Creation timestamp (ISO) */
+    createdAt: string;
+    /** Last update timestamp (ISO) */
+    updatedAt: string;
+}
+/**
+ * Refund request record
+ */
+interface RefundRequest {
+    /** Unique refund request ID */
+    id: string;
+    /** Related escrow ID */
+    escrowId: string;
+    /** Current status */
+    status: RefundStatus;
+    /** Reason for refund request */
+    reason: string;
+    /** Additional evidence/details */
+    evidence?: string;
+    /** Amount requested (may be partial) */
+    amountRequested: string;
+    /** Amount approved (if any) */
+    amountApproved?: string;
+    /** Requester (payer) address */
+    requester: string;
+    /** Transaction hash if processed */
+    transactionHash?: string;
+    /** Response from recipient/facilitator */
+    response?: {
+        status: 'approved' | 'rejected';
+        reason?: string;
+        respondedAt: string;
+    };
+    /** Creation timestamp (ISO) */
+    createdAt: string;
+    /** Last update timestamp (ISO) */
+    updatedAt: string;
+}
+/**
+ * Dispute record
+ */
+interface Dispute {
+    /** Unique dispute ID */
+    id: string;
+    /** Related escrow ID */
+    escrowId: string;
+    /** Related refund request ID (if any) */
+    refundRequestId?: string;
+    /** Dispute outcome */
+    outcome: DisputeOutcome;
+    /** Initiator (payer or recipient) */
+    initiator: 'payer' | 'recipient';
+    /** Reason for dispute */
+    reason: string;
+    /** Evidence from payer */
+    payerEvidence?: string;
+    /** Evidence from recipient */
+    recipientEvidence?: string;
+    /** Arbitration notes */
+    arbitrationNotes?: string;
+    /** Amount resolved to payer */
+    payerAmount?: string;
+    /** Amount resolved to recipient */
+    recipientAmount?: string;
+    /** Transaction hash(es) for resolution */
+    transactionHashes?: string[];
+    /** Creation timestamp (ISO) */
+    createdAt: string;
+    /** Resolution timestamp (ISO) */
+    resolvedAt?: string;
+}
+/**
+ * Options for creating an escrow payment
+ */
+interface CreateEscrowOptions {
+    /** Payment header (from client SDK) */
+    paymentHeader: string;
+    /** Payment requirements */
+    requirements: PaymentRequirements;
+    /** Escrow duration in seconds (default: 86400 = 24h) */
+    escrowDuration?: number;
+    /** Release conditions */
+    releaseConditions?: {
+        minHoldTime?: number;
+        confirmations?: number;
+        custom?: unknown;
+    };
+}
+/**
+ * Options for requesting a refund
+ */
+interface RequestRefundOptions {
+    /** Escrow ID to refund */
+    escrowId: string;
+    /** Reason for refund */
+    reason: string;
+    /** Amount to refund (full amount if not specified) */
+    amount?: string;
+    /** Supporting evidence */
+    evidence?: string;
+}
+/**
+ * Options for the EscrowClient
+ */
+interface EscrowClientOptions {
+    /** Base URL of the Escrow API (default: https://escrow.ultravioletadao.xyz) */
+    baseUrl?: string;
+    /** API key for authenticated operations */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Client for x402 Escrow & Refund operations
+ *
+ * The Escrow system holds payments until service is verified,
+ * enabling refunds and dispute resolution.
+ *
+ * @example
+ * ```ts
+ * // Create escrow payment (backend)
+ * const escrow = new EscrowClient();
+ * const escrowPayment = await escrow.createEscrow({
+ *   paymentHeader: req.headers['x-payment'],
+ *   requirements: paymentRequirements,
+ *   escrowDuration: 86400, // 24 hours
+ * });
+ *
+ * // After service is provided, release the escrow
+ * await escrow.release(escrowPayment.id);
+ *
+ * // If service not provided, payer can request refund
+ * await escrow.requestRefund({
+ *   escrowId: escrowPayment.id,
+ *   reason: 'Service not delivered within expected timeframe',
+ * });
+ * ```
+ */
+declare class EscrowClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly timeout;
+    constructor(options?: EscrowClientOptions);
+    private getHeaders;
+    /**
+     * Create an escrow payment
+     *
+     * Holds the payment in escrow until released or refunded.
+     *
+     * @param options - Escrow creation options
+     * @returns Created escrow payment
+     */
+    createEscrow(options: CreateEscrowOptions): Promise<EscrowPayment>;
+    /**
+     * Get escrow payment by ID
+     *
+     * @param escrowId - Escrow payment ID
+     * @returns Escrow payment details
+     */
+    getEscrow(escrowId: string): Promise<EscrowPayment>;
+    /**
+     * Release escrow funds to recipient
+     *
+     * Call this after service has been successfully provided.
+     *
+     * @param escrowId - Escrow payment ID
+     * @returns Updated escrow payment with transaction hash
+     */
+    release(escrowId: string): Promise<EscrowPayment>;
+    /**
+     * Request a refund for an escrow payment
+     *
+     * Initiates a refund request that must be approved.
+     *
+     * @param options - Refund request options
+     * @returns Created refund request
+     */
+    requestRefund(options: RequestRefundOptions): Promise<RefundRequest>;
+    /**
+     * Approve a refund request (for recipients)
+     *
+     * @param refundId - Refund request ID
+     * @param amount - Amount to approve (may be less than requested)
+     * @returns Updated refund request
+     */
+    approveRefund(refundId: string, amount?: string): Promise<RefundRequest>;
+    /**
+     * Reject a refund request (for recipients)
+     *
+     * @param refundId - Refund request ID
+     * @param reason - Reason for rejection
+     * @returns Updated refund request
+     */
+    rejectRefund(refundId: string, reason: string): Promise<RefundRequest>;
+    /**
+     * Get refund request by ID
+     *
+     * @param refundId - Refund request ID
+     * @returns Refund request details
+     */
+    getRefund(refundId: string): Promise<RefundRequest>;
+    /**
+     * Open a dispute for an escrow payment
+     *
+     * Initiates arbitration when payer and recipient disagree.
+     *
+     * @param escrowId - Escrow payment ID
+     * @param reason - Reason for dispute
+     * @param evidence - Supporting evidence
+     * @returns Created dispute
+     */
+    openDispute(escrowId: string, reason: string, evidence?: string): Promise<Dispute>;
+    /**
+     * Submit evidence to a dispute
+     *
+     * @param disputeId - Dispute ID
+     * @param evidence - Evidence to submit
+     * @returns Updated dispute
+     */
+    submitEvidence(disputeId: string, evidence: string): Promise<Dispute>;
+    /**
+     * Get dispute by ID
+     *
+     * @param disputeId - Dispute ID
+     * @returns Dispute details
+     */
+    getDispute(disputeId: string): Promise<Dispute>;
+    /**
+     * List escrow payments (with filters)
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated list of escrow payments
+     */
+    listEscrows(options?: {
+        status?: EscrowStatus;
+        payer?: string;
+        recipient?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        escrows: EscrowPayment[];
+        total: number;
+        page: number;
+        limit: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * Query on-chain escrow state from the facilitator
+     *
+     * Calls POST /escrow/state to read current escrow state without settlement.
+     *
+     * @param options - Escrow state query parameters
+     * @returns On-chain escrow state (status, balance, timestamps)
+     *
+     * @example
+     * ```ts
+     * const state = await escrow.getEscrowState({
+     *   network: 'base-mainnet',
+     *   payer: '0xPayer...',
+     *   recipient: '0xRecipient...',
+     *   nonce: '0x1234...',
+     * });
+     * console.log(`Status: ${state.status}`);
+     * ```
+     */
+    getEscrowState(options: {
+        network: string;
+        payer: string;
+        recipient: string;
+        nonce: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Check Escrow API health
+     *
+     * @returns True if healthy
+     */
+    healthCheck(): Promise<boolean>;
+}
+/**
+ * Check if an escrow can be released
+ *
+ * @param escrow - Escrow payment to check
+ * @returns True if the escrow can be released
+ */
+declare function canReleaseEscrow(escrow: EscrowPayment): boolean;
+/**
+ * Check if an escrow can be refunded
+ *
+ * @param escrow - Escrow payment to check
+ * @returns True if the escrow can be refunded
+ */
+declare function canRefundEscrow(escrow: EscrowPayment): boolean;
+/**
+ * Check if an escrow is expired
+ *
+ * @param escrow - Escrow payment to check
+ * @returns True if the escrow is expired
+ */
+declare function isEscrowExpired(escrow: EscrowPayment): boolean;
+/**
+ * Calculate time remaining until escrow expires
+ *
+ * @param escrow - Escrow payment to check
+ * @returns Milliseconds until expiration (negative if expired)
+ */
+declare function escrowTimeRemaining(escrow: EscrowPayment): number;
+/**
+ * ERC-8004 extension identifier
+ */
+declare const ERC8004_EXTENSION_ID = "8004-reputation";
+/**
+ * Agent ID type: EVM uses sequential uint256 (number), Solana uses base58 pubkey (string)
+ */
+type AgentId = number | string;
+/**
+ * ERC-8004 contract addresses per network (21 networks: 19 EVM + 2 Solana)
+ */
+declare const ERC8004_CONTRACTS: Record<string, {
+    identityRegistry?: string;
+    reputationRegistry?: string;
+    validationRegistry?: string;
+    agentRegistryProgram?: string;
+    atomEngineProgram?: string;
+}>;
+/**
+ * Return the network name the facilitator actually accepts.
+ *
+ * `base-mainnet` reads like the canonical spelling and is not: the facilitator
+ * answers `400 {"error": "Invalid network: base-mainnet"}`. Every name is passed
+ * through here before it reaches a URL or a request body, so callers holding the
+ * old spelling keep working instead of being rejected at the edge.
+ */
+declare function wireNetwork(network: string): string;
+/**
+ * Network type for ERC-8004 operations (21 networks: 19 EVM + 2 Solana)
+ *
+ * These are the names the FACILITATOR accepts, verified against
+ * GET /feedback -> supportedNetworks. 'base-mainnet' is kept only as a
+ * deprecated alias: the facilitator rejects it outright (400 "Invalid network"),
+ * so anything passed through this module is normalised to 'base' before it
+ * reaches the wire. Use 'base'.
+ */
+type Erc8004Network = 'ethereum' | 'base' | 'polygon' | 'arbitrum' | 'optimism' | 'celo' | 'bsc' | 'monad' | 'avalanche' | 'scroll' | 'skale-base' | 'base-mainnet' | 'ethereum-sepolia' | 'base-sepolia' | 'polygon-amoy' | 'arbitrum-sepolia' | 'optimism-sepolia' | 'celo-sepolia' | 'avalanche-fuji' | 'skale-base-sepolia' | 'solana' | 'solana-devnet';
+/**
+ * Networks where the facilitator serves the RELAYED feedback rail, i.e. where
+ * Execution Market has deployed a `FeedbackDelegate` and the facilitator
+ * verified it on-chain (code present, and its `REPUTATION_REGISTRY()` reads
+ * back that network's registry).
+ *
+ * Anywhere else `POST /feedback/evm/prepare` answers 400 — and it should. An
+ * invented delegate address would send a type-4 transaction to an account with
+ * no code behind it, and in the EVM a `.call()` to an address with no code
+ * RETURNS SUCCESS. The failure would look exactly like a rating that rated
+ * nobody.
+ *
+ * `avalanche` is absent and is not waiting to join: the C-Chain rejects the
+ * transaction type itself (`-32000 transaction type not supported`), so there
+ * is nothing to deploy against. Anchor the rating on a chain that supports
+ * EIP-7702; the payment stays where it was made.
+ */
+declare const RELAYED_FEEDBACK_NETWORKS: readonly Erc8004Network[];
+/**
+ * Whether `network` serves the rater-authored feedback rail.
+ *
+ * Lets a caller route without paying a round trip for a 400. The facilitator
+ * re-checks the delegate on-chain on every request regardless — this list is a
+ * routing hint, never the authority.
+ */
+declare function supportsRelayedFeedback(network: string): boolean;
+/**
+ * An EIP-7702 authorization, as a wallet produces it.
+ *
+ * Needed only the first time a rater rates: it points their EOA at the
+ * `FeedbackDelegate`. Once delegated, `prepare` answers `delegated: true` and
+ * the submission carries no authorization at all.
+ */
+interface RelayAuthorizationParams {
+    /**
+     * Chain the authorization is for.
+     *
+     * `0` is EIP-7702's wildcard and is valid on EVERY chain — a far broader
+     * grant than pinning this one. Send the chain id `prepare` returned.
+     */
+    chainId: number;
+    /**
+     * The delegate the account is pointed at. Must be the address `prepare`
+     * offered; the facilitator refuses anything else before it pays for a
+     * transaction.
+     */
+    address: string;
+    /** The rater account's nonce at the moment the authorization executes */
+    nonce: number;
+    yParity: number;
+    r: string;
+    s: string;
+}
+/**
+ * Request body for `POST /feedback/evm/prepare`.
+ *
+ * `rater` is the address that will appear on-chain as the author, which is the
+ * whole point of this rail.
+ */
+interface PrepareRelayFeedbackRequest {
+    x402Version: 1 | 2;
+    network: Erc8004Network;
+    feedback: FeedbackParams & {
+        rater: string;
+    };
+}
+/**
+ * Response from `POST /feedback/evm/prepare`.
+ *
+ * Everything the rater has to sign so the CHAIN records them as the author
+ * while the facilitator pays the gas.
+ */
+interface PrepareRelayFeedbackResponse {
+    success: boolean;
+    /** The `FeedbackDelegate` the rater's EOA must be delegated to */
+    delegate?: string;
+    /** Registry calldata the rater is authorising, hex-encoded */
+    data?: string;
+    /**
+     * The value the rater's signature must recover against.
+     *
+     * **The EIP-191 envelope is already applied here.** A holder of a raw key
+     * signs this directly as a prehash (viem's `sign({ hash })`, ethers'
+     * `signingKey.sign`). A WALLET must not be handed this value: `personal_sign`
+     * applies the envelope itself, so it gets wrapped twice and recovers an
+     * address that is not the rater. Wallets sign {@link signingPayload}.
+     */
+    digest?: string;
+    /**
+     * The same hash with the envelope still OFF — what a wallet signs.
+     *
+     * `keccak256('\x19Ethereum Signed Message:\n32' || signingPayload)` is
+     * exactly {@link digest}, so a client can check the two against each other
+     * rather than rebuilding the preimage from `data`.
+     *
+     * Requires facilitator v1.95.0+. Older facilitators omit it; a client that
+     * needs it should fail loudly rather than fall back to signing `digest`
+     * through a wallet, which produces a well-formed signature that authorises
+     * nobody.
+     */
+    signingPayload?: string;
+    /**
+     * The full `eth_signTypedData_v4` payload. **v4 delegates only.**
+     *
+     * Present exactly when the delegate deployed on that chain is v4, which the
+     * facilitator reads from the chain per request rather than assuming from a
+     * release. **When it is present, sign IT** — the wallet renders the agent, the
+     * score, the tags and the deadline as named fields, so the rater sees what
+     * they authorise instead of a hex blob.
+     *
+     * v4 carries no {@link signingPayload} and needs none: `signTypedData` has no
+     * envelope to apply twice, which is the entire class of bug that kept the v3
+     * rail at zero signatures for days.
+     *
+     * Requires facilitator v1.96.0+.
+     */
+    typedData?: Record<string, unknown>;
+    /**
+     * Unix seconds after which the authorisation is void. Short on purpose:
+     * relaying is permissionless, so a signed authorisation is live in the wild
+     * until it expires.
+     */
+    deadline?: number;
+    /** Single-use value binding this authorisation. Echo it back on submit */
+    nonce?: string;
+    /**
+     * Whether the account is already delegated. When `false` the submission MUST
+     * carry an `authorization`.
+     */
+    delegated: boolean;
+    /** The account nonce to put in the EIP-7702 authorization, when needed */
+    accountNonce?: number;
+    chainId: number;
+    error?: string;
+    network: Erc8004Network;
+}
+/**
+ * Request body for `POST /feedback/evm/submit`.
+ *
+ * The feedback parameters are not redundant with `prepare`: the facilitator
+ * rebuilds the registry calldata from them and requires the rater's signature
+ * to cover exactly that. It does not relay calldata it was handed.
+ */
+interface SubmitRelayFeedbackRequest {
+    x402Version: 1 | 2;
+    network: Erc8004Network;
+    feedback: FeedbackParams & {
+        rater: string;
+    };
+    /** The deadline `prepare` returned */
+    deadline: number;
+    /** The single-use nonce `prepare` returned */
+    nonce: string;
+    /**
+     * The rater's signature. It must recover to `rater` over `digest` — so
+     * either a raw-key prehash signature over `digest`, or a wallet
+     * `personal_sign` over `signingPayload`. Not `personal_sign` over `digest`.
+     */
+    signature: string;
+    /** Required only when `prepare` answered `delegated: false` */
+    authorization?: RelayAuthorizationParams;
+}
+/**
+ * Request body for `POST /feedback/response/evm/prepare`.
+ *
+ * `responder` is the address the chain will record as the author.
+ */
+interface PrepareRelayResponseRequest {
+    x402Version: 1 | 2;
+    network: Erc8004Network;
+    responder: string;
+    agentId: number | string;
+    /** WHOSE feedback is being answered — inside the signed struct. */
+    clientAddress: string;
+    /** Which feedback (1-indexed) — also inside the struct. */
+    feedbackIndex: number;
+    responseUri: string;
+    responseHash?: string;
+}
+/** Request body for `POST /feedback/response/evm/submit`. */
+interface SubmitRelayResponseRequest {
+    x402Version: 1 | 2;
+    network: Erc8004Network;
+    responder: string;
+    agentId: number | string;
+    clientAddress: string;
+    feedbackIndex: number;
+    responseUri: string;
+    responseHash?: string;
+    deadline: number;
+    nonce: string;
+    /** The responder's signature over the typed data. */
+    signature: string;
+    authorization?: RelayAuthorizationParams;
+}
+/**
+ * Proof of payment returned when settling with ERC-8004 extension
+ */
+interface ProofOfPayment {
+    /** Transaction hash of the settled payment */
+    transactionHash: string;
+    /** Block number where the transaction was included */
+    blockNumber: number;
+    /** Network where the payment was settled */
+    network: string;
+    /** The payer (consumer/client) address */
+    payer: string;
+    /** The payee (agent/resource owner) address */
+    payee: string;
+    /** Amount paid in token base units */
+    amount: string;
+    /** Token contract address */
+    token: string;
+    /** Unix timestamp of the block */
+    timestamp: number;
+    /** Keccak256 hash of the payment data for verification */
+    paymentHash: string;
+}
+/**
+ * Extended settle response with ERC-8004 proof of payment
+ */
+interface SettleResponseWithProof extends SettleResponse {
+    /** Proof of payment for ERC-8004 reputation submission */
+    proofOfPayment?: ProofOfPayment;
+}
+/**
+ * Agent identity from the Identity Registry
+ */
+interface AgentIdentity {
+    /** The agent's ID (EVM: sequential uint256, Solana: base58 pubkey string) */
+    agentId: AgentId;
+    /** Owner address of the agent NFT */
+    owner: string;
+    /** URI pointing to agent registration file */
+    agentUri: string;
+    /** Payment wallet address (if set) */
+    agentWallet?: string;
+    /** Network where the agent is registered */
+    network: Erc8004Network;
+}
+/**
+ * Agent registration file structure (resolved from agentURI)
+ */
+interface AgentRegistrationFile {
+    /** Type identifier */
+    type: string;
+    /** Agent name */
+    name: string;
+    /** Agent description */
+    description: string;
+    /** Image URL */
+    image?: string;
+    /** List of services the agent provides */
+    services: AgentService[];
+    /** Whether x402 payments are supported */
+    x402Support: boolean;
+    /** Whether the agent is active */
+    active: boolean;
+    /** List of registrations across chains */
+    registrations: AgentRegistration[];
+    /** Supported trust models */
+    supportedTrust: string[];
+}
+/**
+ * Agent service entry
+ */
+interface AgentService {
+    name: string;
+    endpoint: string;
+    version?: string;
+}
+/**
+ * Agent registration reference
+ */
+interface AgentRegistration {
+    agentId: AgentId;
+    agentRegistry: string;
+}
+/**
+ * Reputation summary for an agent
+ */
+interface ReputationSummary {
+    /** Agent ID (EVM: number, Solana: string) */
+    agentId: AgentId;
+    /** Number of feedback entries */
+    count: number;
+    /** Aggregated value */
+    summaryValue: number;
+    /** Decimal places for summaryValue */
+    summaryValueDecimals: number;
+    /** Network */
+    network: Erc8004Network;
+}
+/**
+ * Individual feedback entry
+ */
+interface FeedbackEntry {
+    /** Client who submitted the feedback */
+    client: string;
+    /** Feedback index (1-indexed) */
+    feedbackIndex: number;
+    /** Feedback value */
+    value: number;
+    /** Value decimals */
+    valueDecimals: number;
+    /** Primary tag */
+    tag1: string;
+    /** Secondary tag */
+    tag2: string;
+    /** Whether this feedback was revoked */
+    isRevoked: boolean;
+}
+/**
+ * Parameters for submitting reputation feedback
+ */
+interface FeedbackParams {
+    /** The agent's ID (EVM: tokenId number, Solana: base58 pubkey string) */
+    agentId: AgentId;
+    /** Feedback value (e.g., 87 for 87/100) */
+    value: number;
+    /** Decimal places for value interpretation (0-18) */
+    valueDecimals?: number;
+    /** Primary categorization tag (e.g., "starred", "uptime") */
+    tag1?: string;
+    /** Secondary categorization tag */
+    tag2?: string;
+    /** Service endpoint that was used */
+    endpoint?: string;
+    /** URI to off-chain feedback file (IPFS, HTTPS) */
+    feedbackUri?: string;
+    /** Keccak256 hash of feedback content (for integrity) */
+    feedbackHash?: string;
+    /**
+     * Quality score 0-100.
+     *
+     * Solana only, and effectively required there: the ATOM Engine ignores an
+     * unscored feedback. It is written to the agent but contributes nothing to
+     * reputation, and the program reports `had_impact=false`. This is not
+     * retroactive — reputation stays at zero however much unscored feedback
+     * accumulates.
+     */
+    score?: number;
+    /** Proof of payment (required for authorized feedback) */
+    proof?: ProofOfPayment;
+}
+/**
+ * Feedback request body for POST /feedback
+ */
+interface FeedbackRequest {
+    /** x402 protocol version */
+    x402Version: 1 | 2;
+    /** Network where feedback will be submitted */
+    network: Erc8004Network;
+    /** Feedback parameters */
+    feedback: FeedbackParams;
+}
+/**
+ * Feedback response from POST /feedback
+ */
+interface FeedbackResponse extends FacilitatorFailureFields {
+    /** Whether the feedback was successfully submitted */
+    success: boolean;
+    /** Transaction hash of the feedback submission */
+    transaction?: string;
+    /** Feedback index assigned (1-indexed) */
+    feedbackIndex?: number;
+    /** Error message (if failed) */
+    error?: string;
+    /** Network where feedback was submitted */
+    network: Erc8004Network;
+}
+/**
+ * Reputation query response
+ */
+/**
+ * Error from an ERC-8004 lookup, carrying the HTTP status as a field.
+ *
+ * `notFound` and `retryable` are mutually exclusive and must stay that way in
+ * calling code: the facilitator answers 404 for "this address owns no agent"
+ * and 503 for "I could not find out", usually an RPC failure behind it.
+ * Treating a 503 as absence is how a transient failure becomes a permanent
+ * wrong answer — on a registration path it mints a second agent for an owner
+ * who already has one, burning gas and leaving an orphan.
+ */
+declare class Erc8004LookupError extends Error {
+    /** HTTP status returned by the facilitator */
+    readonly status: number;
+    /** Raw response body, for debugging */
+    readonly body: string;
+    /**
+     * `Retry-After`, already clamped, when the facilitator sent one.
+     *
+     * Optional so every existing three-argument construction keeps compiling; it
+     * falls back to the default wait rather than to zero, because a caller that
+     * retries instantly on a 503 is the load that caused it.
+     */
+    private readonly retryAfterHint;
+    constructor(message: string, status: number, body: string, retryAfterSeconds?: number);
+    /** The address genuinely owns no agent on this network. */
+    get notFound(): boolean;
+    /**
+     * The lookup reached no verdict. Retry; never read as "owns nothing".
+     *
+     * `502` and `504` join `503` and `429` here: a gateway that answered on the
+     * facilitator's behalf is exactly as silent about the agent's existence, and
+     * reading either as absence has the same consequence -- a duplicate mint.
+     *
+     * **Except when the body says otherwise.** `POST /register` goes through the
+     * same EVM `send_transaction_from` as a settle, so it can answer
+     * `settlement_unconfirmed`: the mint was broadcast and may be mined. That is
+     * a `502` where retrying is precisely the thing that mints the duplicate this
+     * class exists to prevent, so an explicit `retryable: false` wins over the
+     * status. See {@link SETTLEMENT_UNCONFIRMED}.
+     */
+    get retryable(): boolean;
+    /**
+     * The facilitator's own `reason`, when the body carried one.
+     *
+     * On a WRITE route this is the writer-lease reason and it decides whether the
+     * request may be re-sent; see {@link isReplayableLeaseReason}.
+     */
+    get reason(): string | undefined;
+    /** The facilitator's machine-readable `error` code, when the body carried one. */
+    get errorCode(): string | undefined;
+    /**
+     * A transaction that WAS broadcast and could not be confirmed.
+     *
+     * Present on `settlement_unconfirmed`. This is what to do INSTEAD of
+     * retrying: look it up on chain. An error that carries "do not retry" and no
+     * hash leaves the caller with nothing to act on.
+     */
+    get transaction(): string | undefined;
+    /** The payment id for {@link transaction}, identical to a successful settle's. */
+    get paymentId(): string | undefined;
+    /**
+     * The facilitator NAMED a reason proving it executed nothing.
+     *
+     * False for `forward_failed` and for every unattributed 5xx: "something
+     * answered" is not evidence that nothing ran. On `/register`, replaying when
+     * this is false is the sequence that minted five duplicate agents.
+     */
+    get safeToReplay(): boolean;
+    /** Seconds to wait before retrying, clamped. Absent when not retryable. */
+    get retryAfterSeconds(): number | undefined;
+}
+/**
+ * ATOM Engine reputation analytics (Solana only).
+ *
+ * Present only when the agent's `atom_stats` account has been initialized. The
+ * facilitator does that during `registerAgent`; agents registered elsewhere may
+ * never have it, in which case their feedback is never scored.
+ *
+ * The engine measures quality through EMA scores, so there are no
+ * positive/negative tallies.
+ */
+interface AtomStats {
+    /** Trust tier 0-4 */
+    trustTier: number;
+    /** Human-readable trust tier */
+    trustTierName: string;
+    /** Cached quality score */
+    qualityScore: number;
+    /** Cached loyalty score */
+    loyaltyScore: number;
+    /** Statistical confidence */
+    confidence: number;
+    /** Risk assessment (lower is better) */
+    riskScore: number;
+    /** Client diversity from HyperLogLog */
+    diversityRatio: number;
+    /** Lowest score ever recorded */
+    minScore: number;
+    /** Highest score ever recorded */
+    maxScore: number;
+    /** Most recent score recorded */
+    lastScore: number;
+    /** Total feedback counted by the engine */
+    feedbackCount: number;
+    /** Slot of the most recent feedback */
+    lastFeedbackSlot: number;
+}
+interface ReputationResponse {
+    agentId: AgentId;
+    summary: ReputationSummary;
+    feedback?: FeedbackEntry[];
+    /** ATOM Engine analytics; absent when the agent has no initialized stats */
+    atomStats?: AtomStats | null;
+    network: Erc8004Network;
+}
+/**
+ * Key-value metadata entry for agent registration
+ */
+interface MetadataEntryParam {
+    /** Metadata key */
+    key: string;
+    /** Metadata value (hex-encoded bytes or UTF-8 string) */
+    value: string;
+}
+/**
+ * Request body for POST /register
+ */
+interface RegisterAgentRequest {
+    /** x402 protocol version */
+    x402Version: 1 | 2;
+    /** Network where agent will be registered */
+    network: Erc8004Network;
+    /** URI pointing to agent registration file (IPFS, HTTPS) */
+    agentUri: string;
+    /** Optional metadata key-value pairs */
+    metadata?: MetadataEntryParam[];
+    /** Optional recipient address - NFT is transferred to this address after minting */
+    recipient?: string;
+}
+/**
+ * Response from POST /register
+ */
+interface RegisterAgentResponse extends FacilitatorFailureFields {
+    /** Whether registration succeeded */
+    success: boolean;
+    /** The newly assigned agent ID (EVM: tokenId number, Solana: base58 pubkey string) */
+    agentId?: AgentId;
+    /** Registration transaction hash */
+    transaction?: string;
+    /** Transfer transaction hash (if recipient was specified) */
+    transferTransaction?: string;
+    /** Owner address of the agent NFT */
+    owner?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Network where agent was registered */
+    network: string;
+}
+/**
+ * Response from GET /identity/{network}/owner/{address}
+ */
+interface IdentityByOwnerResponse {
+    /** First (lowest) token ID owned by this address */
+    agentId: AgentId;
+    /** The queried address (checksummed) */
+    owner: string;
+    /** Agent's registration URI (may be empty) */
+    agentUri: string;
+    /** Network name */
+    network: string;
+    /** Total number of agent NFTs owned (as string) */
+    balance: string;
+}
+/**
+ * Response from GET /identity/{network}/{agent_id}/metadata/{key}
+ */
+/**
+ * Lifecycle of an async registration. `mint_confirmed` and `done` carry an
+ * `agentId`; `failed` carries an `error`.
+ */
+type RegisterJobStatus = 'pending' | 'mint_confirmed' | 'done' | 'failed';
+/**
+ * Status of an asynchronous registration.
+ *
+ * Returned by `POST /register` with `Prefer: respond-async` (HTTP 202) and by
+ * `GET /register/status/{jobId}`.
+ *
+ * Terminal jobs are retained for one hour and then age out, after which the
+ * status endpoint 404s. Read the agent id before then, or it is only
+ * recoverable from the chain.
+ */
+interface RegisterJobResponse {
+    jobId: string;
+    status: RegisterJobStatus;
+    network?: string;
+    agentId?: AgentId;
+    transaction?: string;
+    transferTransaction?: string;
+    owner?: string;
+    error?: string;
+}
+/** Whether polling can stop: the job either finished or failed. */
+declare function isRegisterJobTerminal(job: RegisterJobResponse): boolean;
+/**
+ * Thrown when a registration is still running after the wait elapsed.
+ *
+ * This is emphatically **not** a failure. The mint may still land. `jobId` is a
+ * field rather than only part of the message, because the correct recovery is to
+ * keep polling `getRegisterStatus(jobId)` — and a caller who cannot reach the id
+ * without parsing a string will re-register instead, minting a duplicate agent.
+ * That is the exact sequence that once produced five duplicate mints.
+ *
+ * Never map this to "registration failed".
+ */
+declare class RegistrationPendingError extends Error {
+    readonly jobId: string;
+    readonly lastStatus: RegisterJobStatus;
+    readonly timeoutMs: number;
+    readonly retryable = true;
+    constructor(jobId: string, lastStatus: RegisterJobStatus, timeoutMs: number);
+}
+interface IdentityMetadataResponse {
+    /** Agent ID (EVM: number, Solana: string) */
+    agentId: AgentId;
+    /** Metadata key */
+    key: string;
+    /**
+     * Raw hex-encoded value. The facilitator sends this as `value`; this field
+     * used to be declared as `valueHex`, which no response ever carried, so it
+     * was always undefined at runtime.
+     */
+    value: string;
+    /** UTF-8 decoded value (if decodable) */
+    valueUtf8?: string;
+    /** Whether the entry can still be changed */
+    immutable?: boolean;
+    /** Network */
+    network: string;
+}
+/**
+ * Response from GET /identity/{network}/total-supply
+ *
+ * On Solana the counts come from the Metaplex Core collection, not the registry,
+ * which keeps no counter of its own.
+ */
+interface IdentityTotalSupplyResponse {
+    /** Registered agents, net of burns */
+    totalSupply: number;
+    /** All-time mint count (Solana) */
+    numMinted?: number;
+    /** Metaplex Core collection backing the count (Solana) */
+    collection?: string;
+    /** Network */
+    network: string;
+}
+/**
+ * Options for the ERC8004Client
+ */
+interface Erc8004ClientOptions {
+    /** Base URL of the facilitator (default: https://facilitator.ultravioletadao.xyz) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /**
+     * Extra attempts after the first, spent only on a refusal the facilitator
+     * proved it did not execute. Default 2; `0` disables. An ambiguous
+     * `forward_failed` is never replayed at any setting.
+     */
+    retries?: number;
+}
+/**
+ * Client for ERC-8004 Trustless Agents API
+ *
+ * Provides methods for:
+ * - Registering new agents (gasless, facilitator pays gas)
+ * - Registering agents on behalf of users (gasless delegation)
+ * - Querying agent identity, metadata, and total supply
+ * - Querying agent reputation
+ * - Submitting reputation feedback
+ * - Revoking feedback
+ *
+ * @example
+ * ```ts
+ * const client = new Erc8004Client();
+ *
+ * // Get agent identity
+ * const identity = await client.getIdentity('ethereum', 42);
+ * console.log(identity.agentUri);
+ *
+ * // Get agent reputation
+ * const reputation = await client.getReputation('ethereum', 42);
+ * console.log(`Score: ${reputation.summary.summaryValue}`);
+ *
+ * // Submit feedback after payment
+ * const result = await client.submitFeedback({
+ *   x402Version: 1,
+ *   network: 'ethereum',
+ *   feedback: {
+ *     agentId: 42,
+ *     value: 95,
+ *     valueDecimals: 0,
+ *     tag1: 'quality',
+ *     proof: settleResponse.proofOfPayment,
+ *   },
+ * });
+ * ```
+ */
+declare class Erc8004Client {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retries;
+    constructor(options?: Erc8004ClientOptions);
+    /**
+     * POST a write route, keeping a refusal readable.
+     *
+     * Every ERC-8004 write goes through the facilitator's EVM writer lease, so
+     * every one of them can answer `503` + `reason`. Flattened to a string, those
+     * are indistinguishable from "the registry rejected your feedback" — and on
+     * `/register` the wrong reading re-POSTs a mint that may already have landed,
+     * which is precisely how five duplicate agents were once created.
+     *
+     * A refusal the facilitator proved it did not execute is replayed
+     * automatically (`safeToReplay`); `forward_failed` never is.
+     */
+    private writeJson;
+    /**
+     * Get agent identity from the Identity Registry
+     *
+     * @param network - Network where agent is registered
+     * @param agentId - Agent's tokenId
+     * @returns Agent identity information
+     */
+    getIdentity(network: Erc8004Network, agentId: AgentId): Promise<AgentIdentity>;
+    /**
+     * Get agent identity by owner address
+     *
+     * Resolves the first ERC-8004 agent ID owned by a wallet address on a given network.
+     *
+     * @param network - Network to query
+     * @param address - Owner wallet address
+     * @returns Agent identity information including balance
+     *
+     * @example
+     * ```ts
+     * const identity = await client.getIdentityByOwner('base-mainnet', '0x52E0...');
+     * console.log(`Agent #${identity.agentId}, balance: ${identity.balance}`);
+     * ```
+     */
+    getIdentityByOwner(network: Erc8004Network, address: string): Promise<IdentityByOwnerResponse>;
+    /**
+     * Resolve agent registration file from agentURI
+     *
+     * @param agentUri - URI pointing to agent registration file
+     * @returns Resolved agent registration file
+     */
+    resolveAgentUri(agentUri: string): Promise<AgentRegistrationFile>;
+    /**
+     * Get agent reputation from the Reputation Registry
+     *
+     * @param network - Network where agent is registered
+     * @param agentId - Agent's tokenId
+     * @param options - Query options (tag filters, include individual feedback, client addresses)
+     * @param options.clientAddresses - Comma-separated client addresses to filter by.
+     *   If omitted, the facilitator auto-discovers all clients via getClients().
+     * @returns Reputation summary and optionally individual feedback entries
+     */
+    getReputation(network: Erc8004Network, agentId: AgentId, options?: {
+        tag1?: string;
+        tag2?: string;
+        includeFeedback?: boolean;
+        clientAddresses?: string;
+    }): Promise<ReputationResponse>;
+    /**
+     * Submit reputation feedback for an agent
+     *
+     * Requires proof of payment for authorized feedback submission.
+     *
+     * @deprecated On this route the facilitator is the AUTHOR: the registry
+     * records `msg.sender`, and that is the facilitator's wallet — which can also
+     * revoke what it wrote. On the networks in {@link RELAYED_FEEDBACK_NETWORKS}
+     * use {@link Erc8004Client.prepareRelayedFeedback} +
+     * {@link Erc8004Client.submitRelayedFeedback} instead, which record the RATER
+     * as author. This route still works and is not going away without notice: it
+     * is the only one available where no `FeedbackDelegate` is deployed.
+     *
+     * @param request - Feedback request with agent ID, value, and proof
+     * @returns Feedback response with transaction hash
+     *
+     * @example
+     * ```ts
+     * // After settling a payment with ERC-8004 extension
+     * const settleResult = await facilitator.settle(payment, {
+     *   ...requirements,
+     *   extra: { '8004-reputation': { includeProof: true } },
+     * });
+     *
+     * // Submit feedback with proof of payment
+     * const feedback = await erc8004.submitFeedback({
+     *   x402Version: 1,
+     *   network: 'ethereum',
+     *   feedback: {
+     *     agentId: 42,
+     *     value: 95,  // 95/100
+     *     valueDecimals: 0,
+     *     tag1: 'quality',
+     *     tag2: 'response-time',
+     *     proof: settleResult.proofOfPayment,
+     *   },
+     * });
+     * ```
+     */
+    submitFeedback(request: FeedbackRequest): Promise<FeedbackResponse>;
+    /**
+     * Ask the facilitator what the rater must sign to author a rating.
+     *
+     * Step 1 of the rater-authored rail. Writes nothing on-chain and costs
+     * nothing: it reads the delegate, the rater's delegation state and their
+     * account nonce, then hands back a digest, a deadline and a single-use nonce.
+     *
+     * Why this exists: the ERC-8004 Reputation Registry records `msg.sender` as
+     * the author, and the deployed implementation has no delegation path — no
+     * `giveFeedbackWithSignature`, no ERC-2771 forwarder. So a rating the
+     * facilitator relays the ordinary way is a rating attributed to the
+     * FACILITATOR. EIP-7702 fixes it without touching the registry: the rater
+     * delegates their own EOA to the `FeedbackDelegate` and the transaction is
+     * sent TO THE RATER'S ADDRESS, so the registry sees the rater while the
+     * facilitator pays.
+     *
+     * What to do with the answer:
+     * 1. Produce the rater's signature. **Which value you sign depends on how you
+     *    sign it**, and getting it wrong yields a well-formed signature that
+     *    authorises nobody:
+     *    - raw key: sign `digest` as a **prehash**. It already carries the
+     *      EIP-191 envelope.
+     *    - wallet: `personal_sign` over `signingPayload`. `personal_sign` adds the
+     *      envelope itself, so signing `digest` with it wraps the value TWICE and
+     *      recovers a stranger — the only symptom is `relay_bad_signature`.
+     *    - **unless `typedData` came back** — that chain runs a v4 delegate. Then
+     *      sign THAT with `eth_signTypedData_v4` and ignore the other two: it is
+     *      the only form the rater can read, and it has no envelope ambiguity.
+     * 2. If `delegated` is `false`, also produce an EIP-7702 authorization over
+     *    `(chainId, delegate, accountNonce)`.
+     * 3. Hand both to {@link submitRelayedFeedback} with the SAME feedback
+     *    parameters, `deadline` and `nonce`.
+     *
+     * @param request - Network, rater address and feedback parameters
+     * @returns Everything needed to sign, including whether an EIP-7702
+     * authorization is still required
+     *
+     * @example
+     * ```ts
+     * const prep = await erc8004.prepareRelayedFeedback({
+     *   x402Version: 1,
+     *   network: 'base',
+     *   feedback: { agentId: 18896, value: 95, tag1: 'quality', rater: raterAddress },
+     * });
+     * // prep.delegated === false -> an EIP-7702 authorization is required
+     * ```
+     */
+    prepareRelayedFeedback(request: PrepareRelayFeedbackRequest): Promise<PrepareRelayFeedbackResponse>;
+    /**
+     * Relay a rater-authored rating; the facilitator pays the gas.
+     *
+     * Step 2 of the rater-authored rail. The on-chain record that comes out of it
+     * has the RATER as `msg.sender`, so `getClients(agentId)` shows the rater
+     * rather than the facilitator.
+     *
+     * Pass back the same feedback parameters, `deadline` and `nonce` that
+     * {@link prepareRelayedFeedback} returned. They are not redundant: the
+     * facilitator rebuilds the registry calldata from them and requires the
+     * rater's signature to cover exactly that.
+     *
+     * `authorization` is required only when `prepare` answered
+     * `delegated: false`. One that names a different delegate than the one
+     * `prepare` offered is refused before any gas is spent.
+     *
+     * @param request - Feedback parameters plus the rater's signature
+     * @returns Feedback response with the transaction hash
+     */
+    submitRelayedFeedback(request: SubmitRelayFeedbackRequest): Promise<FeedbackResponse>;
+    /**
+     * Revoke previously submitted feedback
+     *
+     * Only the original submitter can revoke their feedback.
+     *
+     * @param network - Network where feedback was submitted
+     * @param agentId - Agent ID
+     * @param feedbackIndex - Index of feedback to revoke
+     * @returns Revocation result
+     */
+    revokeFeedback(network: Erc8004Network, agentId: AgentId, feedbackIndex: number, options?: {
+        sealHash?: string;
+        originalFeedback?: Omit<FeedbackParams, 'agentId' | 'proof'>;
+    }): Promise<FeedbackResponse>;
+    /**
+     * Get ERC-8004 contract addresses for a network
+     *
+     * @param network - Network to get contracts for
+     * @returns Contract addresses or undefined if not deployed
+     */
+    getContracts(network: Erc8004Network): typeof ERC8004_CONTRACTS[Erc8004Network] | undefined;
+    /**
+     * Check if ERC-8004 is available on a network
+     *
+     * @param network - Network to check
+     * @returns True if ERC-8004 contracts are deployed
+     */
+    isAvailable(network: string): network is Erc8004Network;
+    /**
+     * Get feedback endpoint metadata
+     *
+     * @returns Endpoint information for /feedback
+     */
+    getFeedbackMetadata(): Promise<{
+        endpoint: string;
+        supportedNetworks: Erc8004Network[];
+        version: string;
+    }>;
+    /**
+     * Ask what the RESPONDER must sign to author a response on-chain.
+     *
+     * The mirror of {@link prepareRelayedFeedback}, for the other write the
+     * registry accepts from anybody. `appendResponse` is not agent-only — the
+     * registry takes it from any address — so on the plain {@link appendResponse}
+     * route the `responder` recorded on-chain is the FACILITATOR. That does not
+     * destroy anyone's reputation the way a revoke would; it ties the
+     * facilitator's on-chain identity to a third party's content, which is its own
+     * kind of wrong.
+     *
+     * **v4 delegates only.** The v3 delegate accepts exactly two selectors and
+     * `appendResponse` is not one of them, so a v3 network answers 400
+     * `relay_response_needs_v4` rather than silently falling back to the route
+     * this replaces.
+     *
+     * `clientAddress` and `feedbackIndex` are inside the signed struct: without
+     * them one signature would answer any client's rating, or any rating at that
+     * index.
+     */
+    prepareRelayedResponse(request: PrepareRelayResponseRequest): Promise<PrepareRelayFeedbackResponse>;
+    /**
+     * Relay a responder-authored response; the facilitator pays the gas.
+     *
+     * Pass back the same parameters, `deadline` and `nonce` that
+     * {@link prepareRelayedResponse} returned: the facilitator rebuilds the struct
+     * from them and refuses to relay anything the signature does not cover.
+     */
+    submitRelayedResponse(request: SubmitRelayResponseRequest): Promise<FeedbackResponse>;
+    /** Shared POST for the relay routes: a refusal is data, never a throw. */
+    private postRelay;
+    /**
+     * Append a response to existing feedback
+     *
+     * @deprecated On this route the facilitator is the AUTHOR: the registry
+     * records `msg.sender` as the `responder`, and that is the facilitator's
+     * wallet. Where the delegate is **v4**, use {@link prepareRelayedResponse} +
+     * {@link submitRelayedResponse} instead. This route still works and is the
+     * only one available where the delegate is still v3.
+     *
+     * **This is NOT agent-only**, despite what this comment claimed until
+     * 2026-08-25. Verified on-chain on 2026-08-18: the registry accepts
+     * `appendResponse` from ANY address. There is no identity-owner check, here or
+     * in the contract.
+     *
+     * @param network - Network where feedback was submitted
+     * @param agentId - Agent ID
+     * @param feedbackIndex - Index of feedback to respond to
+     * @param response - Response content
+     * @param responseUri - Optional URI to off-chain response file
+     * @returns Response result
+     *
+     * @example
+     * ```ts
+     * // Agent responds to feedback
+     * const result = await erc8004.appendResponse(
+     *   'ethereum',
+     *   42,
+     *   1,
+     *   'Thank you for your feedback! We have addressed the issue.',
+     * );
+     * ```
+     */
+    appendResponse(network: Erc8004Network, agentId: AgentId, feedbackIndex: number, response: string, options?: {
+        responseUri?: string;
+        sealHash?: string;
+    }): Promise<FeedbackResponse>;
+    /**
+     * Register an agent on the Identity Registry (idempotent)
+     *
+     * If the recipient already owns an agent on the target network, returns the
+     * existing one instead of minting a duplicate. The facilitator pays gas fees.
+     * Optionally transfer the NFT to a recipient address (gasless delegation).
+     *
+     * @param request - Registration request
+     * @returns Registration response with agent ID and transaction hash
+     *
+     * @example
+     * ```ts
+     * // Register agent owned by facilitator
+     * const result = await client.registerAgent({
+     *   x402Version: 1,
+     *   network: 'ethereum',
+     *   agentUri: 'ipfs://QmYourAgentFile',
+     * });
+     * console.log(`Agent #${result.agentId} registered`);
+     *
+     * // Register agent and transfer to user
+     * const result = await client.registerAgent({
+     *   x402Version: 1,
+     *   network: 'ethereum',
+     *   agentUri: 'ipfs://QmYourAgentFile',
+     *   recipient: '0xUserAddress...',
+     * });
+     * console.log(`Agent #${result.agentId} transferred to user`);
+     * ```
+     */
+    registerAgent(request: RegisterAgentRequest, options?: {
+        asyncTransport?: boolean;
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<RegisterAgentResponse>;
+    /**
+     * Start a registration without waiting for the chain to confirm it.
+     *
+     * Registration waits on a mint receipt, which on a congested chain outlives
+     * client and proxy timeouts. A timed-out synchronous call is genuinely
+     * ambiguous — the mint may well have landed — and retrying it is how five
+     * duplicate agents once got minted. This returns immediately with a job id
+     * instead; poll {@link getRegisterStatus} or use {@link waitForRegistration}.
+     *
+     * On Solana, `recipient` is a base58 address: the facilitator mints,
+     * initializes the ATOM stats and transfers, paying every fee.
+     */
+    registerAgentAsync(request: RegisterAgentRequest): Promise<RegisterJobResponse>;
+    /**
+     * Read the current state of an asynchronous registration.
+     *
+     * Throws {@link Erc8004LookupError} with `notFound` when the job is unknown or
+     * has aged out — terminal jobs are kept for one hour.
+     */
+    getRegisterStatus(jobId: string): Promise<RegisterJobResponse>;
+    /**
+     * Poll an asynchronous registration until it finishes.
+     *
+     * Rejects on timeout rather than resolving with the last non-terminal status,
+     * so "still pending" is never mistaken for "did not happen": the mint may
+     * still land afterwards, and treating a timeout as failure is what leads to
+     * registering the same agent twice. Keep the job id and poll again rather
+     * than re-registering.
+     */
+    waitForRegistration(jobId: string, options?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<RegisterJobResponse>;
+    /**
+     * Get registration endpoint metadata
+     *
+     * @returns Endpoint information for POST /register
+     */
+    getRegisterInfo(): Promise<Record<string, unknown>>;
+    /**
+     * Get a specific metadata entry for an agent
+     *
+     * @param network - Network where agent is registered
+     * @param agentId - Agent's tokenId
+     * @param key - Metadata key to retrieve
+     * @returns Metadata value (hex-encoded and UTF-8 decoded if possible)
+     */
+    getIdentityMetadata(network: Erc8004Network, agentId: AgentId, key: string): Promise<IdentityMetadataResponse>;
+    /**
+     * Get total number of registered agents on a network
+     *
+     * @param network - Network to query
+     * @returns Total supply count
+     */
+    getIdentityTotalSupply(network: Erc8004Network): Promise<IdentityTotalSupplyResponse>;
+}
+/**
+ * Build payment requirements with ERC-8004 extension
+ *
+ * Adds the 8004-reputation extension to include proof of payment
+ * in settlement responses for reputation submission.
+ *
+ * @param options - Base payment requirements options
+ * @returns Payment requirements with ERC-8004 extension
+ *
+ * @example
+ * ```ts
+ * const requirements = buildErc8004PaymentRequirements({
+ *   amount: '1.00',
+ *   recipient: '0x...',
+ *   resource: 'https://api.example.com/service',
+ *   chainName: 'ethereum',
+ * });
+ *
+ * // Settlement will include proofOfPayment
+ * const result = await facilitator.settle(payment, requirements);
+ * console.log(result.proofOfPayment);
+ * ```
+ */
+declare function buildErc8004PaymentRequirements(options: PaymentRequirementsOptions): PaymentRequirements & {
+    extra: {
+        '8004-reputation': {
+            includeProof: boolean;
+        };
+    };
+};
+/**
+ * PAYMENT_INFO_TYPEHASH used for nonce computation.
+ * Must match the on-chain AuthCaptureEscrow contract.
+ */
+declare const PAYMENT_INFO_TYPEHASH = "0xae68ac7ce30c86ece8196b61a7c486d8f0061f575037fbd34e7fe4e2820c6591";
+declare const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/**
+ * Contract deposit limit (enforced by PaymentOperator condition).
+ * As of 2026-02-03, commerce-payments contracts enforce $100 max per deposit.
+ */
+declare const DEPOSIT_LIMIT_USDC = "100000000";
+/**
+ * Default facilitator request timeout per chain in milliseconds.
+ * Ethereum L1 (~12s blocks) needs much longer than L2s (~2s blocks).
+ * Timeout chain: Client > SDK > Facilitator. The facilitator uses 900s for Ethereum L1.
+ *
+ * These are correct, and they are also a PRODUCT constraint worth reading before
+ * you offer a network in a checkout: Ethereum L1 is 960s against 90s for every
+ * L2 here. A buyer waiting in a browser will not wait sixteen minutes, so a
+ * human-facing flow should offer the L2s and leave L1 to agent-to-agent or
+ * batch callers that can tolerate the wait. Do not shorten this to make a
+ * checkout feel faster — the value tracks L1 block time and the facilitator's
+ * own 900s TxWatcher, and cutting it just times out a payment that was going
+ * to land.
+ */
+declare const ESCROW_TIMEOUT_MS: Record<number, number>;
+/**
+ * USDC EIP-712 domain name per chain.
+ * Most chains use "USD Coin", but some (Celo, Monad, HyperEVM) use "USDC".
+ * This must match the on-chain token's name() for EIP-712 signing to work.
+ */
+declare const USDC_DOMAIN_NAME: Record<number, string>;
+/**
+ * Multi-chain escrow contract addresses for the Advanced Escrow system.
+ * Keyed by EVM chain ID. Source: x402r-sdk A1igator/multichain-config deployment.
+ */
+/**
+ * Per-chain escrow contract addresses.
+ *
+ * KNOWN GAP, measured 2026-09-05: the `operator` entries are
+ * PaymentOperatorFactory addresses, not deployed PaymentOperator instances.
+ * Verified on Base mainnet, Base Sepolia and Arbitrum — they answer
+ * `ESCROW()` and `operators(bytes32)` and revert on `FEE_CALCULATOR()`,
+ * `FEE_RECIPIENT()` and `release(...)` — and x402-rs
+ * `docs/X402R_MULTICHAIN_DEPLOYMENT.md` labels the same addresses
+ * "PaymentOperatorFactory". A factory has no `release`/`charge`, so the direct
+ * on-chain paths below cannot execute against these addresses as written;
+ * resolve the real operator from the marketplace's own escrow config
+ * ({@link EscrowNetworkConfig}) and pass it via `options.contracts`.
+ * See {@link OPERATOR_FEE_BPS} for the commands.
+ */
+declare const ESCROW_CONTRACTS: Record<number, AdvancedEscrowContracts>;
+/**
+ * Base Mainnet contract addresses for the Advanced Escrow system.
+ * @deprecated Use ESCROW_CONTRACTS[8453] or getEscrowContractsByChainId(8453) instead.
+ */
+declare const BASE_MAINNET_CONTRACTS: AdvancedEscrowContracts;
+/**
+ * Get escrow contract addresses for a given chain ID.
+ *
+ * @param chainId - EVM chain ID (e.g., 8453 for Base, 1 for Ethereum)
+ * @returns Contract addresses or undefined if chain is not supported
+ */
+declare function getEscrowContractsByChainId(chainId: number): AdvancedEscrowContracts | undefined;
+/**
+ * Get all chain IDs that have escrow contracts deployed.
+ *
+ * @returns Array of chain IDs with escrow support
+ */
+declare function getEscrowSupportedChainIds(): number[];
+/**
+ * Check if escrow contracts are deployed on a given chain.
+ *
+ * @param chainId - EVM chain ID
+ * @returns True if escrow is supported on this chain
+ */
+declare function isEscrowSupportedOnChain(chainId: number): boolean;
+/**
+ * Task tiers determine timing parameters for escrow operations.
+ */
+type AdvancedEscrowTaskTier = 'micro' | 'standard' | 'premium' | 'enterprise';
+/**
+ * Timing configuration per task tier (in seconds).
+ */
+declare const TIER_TIMINGS: Record<AdvancedEscrowTaskTier, {
+    pre: number;
+    auth: number;
+    refund: number;
+}>;
+/**
+ * PaymentInfo struct matching the on-chain PaymentOperator contract.
+ */
+interface AdvancedPaymentInfo {
+    operator: string;
+    receiver: string;
+    token: string;
+    maxAmount: string;
+    preApprovalExpiry: number;
+    authorizationExpiry: number;
+    refundExpiry: number;
+    minFeeBps: number;
+    maxFeeBps: number;
+    feeReceiver: string;
+    salt: string;
+}
+/**
+ * Optional signed lifecycle order for `releaseViaFacilitator` /
+ * `refundViaFacilitator`.
+ *
+ * Both actions move money that is ALREADY escrowed, so neither carries an
+ * ERC-3009 signature and the entitlement question — who may ask for the move —
+ * has no other answer. Supplying a `lifecycleSigner` answers it; omitting one
+ * leaves the request byte-for-byte as it was, which is why every field here is
+ * optional and the default is to send nothing.
+ *
+ * The accepted signers are the facilitator's, not this SDK's: `release` takes
+ * the payer or the operator owner (`FEE_RECIPIENT()`); `refundInEscrow` takes
+ * the receiver, the operator owner, or the payer once `authorizationExpiry`
+ * has passed. Anything else is logged as `unauthorized_role`.
+ */
+interface LifecycleAuthOptions {
+    /**
+     * Who signs the order. Any adapter with `getAddress()` + `signTypedData()`:
+     * `EnvKeyAdapter` server-side, `OWSWalletAdapter`, or
+     * `wagmiLifecycleSigner(walletClient)` when the PAYER signs in their own
+     * browser and this backend only transports the block.
+     */
+    lifecycleSigner?: LifecycleSigner;
+    /**
+     * Unix seconds. Default: `now + 600`, which leaves 300 s of headroom under
+     * the facilitator's 900 s ceiling. Only read alongside `lifecycleSigner` —
+     * a `lifecycleAuth` already carries the deadline it was signed with.
+     */
+    lifecycleDeadline?: number;
+    /**
+     * An order that was ALREADY SIGNED somewhere else — the publisher's browser
+     * — and that this backend only transports.
+     *
+     * The signing side builds the document with `buildLifecycleTypedData`, the
+     * browser signs it, and `lifecycleAuthFromSignature` turns the signature
+     * back into this block. Nothing is re-derived here: the `paymentInfo`, the
+     * `payer` and the `amount` this call sends must be the ones the order
+     * committed to, or the facilitator reads `bad_signature`.
+     *
+     * MUTUALLY EXCLUSIVE with `lifecycleSigner`. Passing both is not a
+     * preference to resolve — it means the caller believes two different orders
+     * are about to travel, and only one can. It throws.
+     */
+    lifecycleAuth?: LifecycleAuth;
+}
+/**
+ * Result of an AUTHORIZE operation.
+ */
+interface AdvancedAuthorizationResult {
+    success: boolean;
+    transactionHash?: string;
+    paymentInfo?: AdvancedPaymentInfo;
+    salt?: string;
+    error?: string;
+}
+/**
+ * Result of an on-chain transaction (release, refund, charge).
+ */
+interface AdvancedTransactionResult extends FacilitatorFailureFields {
+    success: boolean;
+    transactionHash?: string;
+    gasUsed?: number;
+    /**
+     * Why it failed.
+     *
+     * On the gasless (`*ViaFacilitator`) paths, check `retryable` first: a
+     * facilitator that could not hand the write to its lease holder rejected
+     * nothing on-chain, and the escrow is exactly as it was. Reporting that as a
+     * failed refund is how funds get written off while they are still sitting in
+     * escrow, recoverable.
+     */
+    error?: string;
+}
+/**
+ * Response from the facilitator's /escrow/state endpoint.
+ * Represents the on-chain state of an escrow for a given paymentInfo + payer.
+ */
+interface EscrowStateResponse {
+    /** Whether the payment has already been collected (released) */
+    hasCollectedPayment: boolean;
+    /** Amount that can still be captured/released (in atomic units) */
+    capturableAmount: string;
+    /** Amount that can still be refunded to the payer (in atomic units) */
+    refundableAmount: string;
+    /** Keccak256 hash of the paymentInfo struct */
+    paymentInfoHash: string;
+    /** Network in CAIP-2 format (e.g., "eip155:8453") */
+    network: string;
+}
+/**
+ * Contract addresses configuration for AdvancedEscrowClient.
+ *
+ * Maps to the on-chain x402r escrow contracts:
+ * - operator: PaymentOperatorFactory
+ * - escrow: AuthCaptureEscrow
+ * - tokenCollector: TokenCollector
+ * - protocolFeeConfig: ProtocolFeeConfig
+ * - refundRequest: RefundRequest
+ * - usdc: USDC token contract
+ */
+interface AdvancedEscrowContracts {
+    /** PaymentOperatorFactory contract address */
+    operator: string;
+    /** AuthCaptureEscrow contract address */
+    escrow: string;
+    /** TokenCollector contract address */
+    tokenCollector: string;
+    /** ProtocolFeeConfig contract address */
+    protocolFeeConfig: string;
+    /** RefundRequest contract address */
+    refundRequest: string;
+    /** USDC token contract address */
+    usdc: string;
+}
+/**
+ * Configuration options for AdvancedEscrowClient.
+ */
+interface AdvancedEscrowClientOptions {
+    /** Facilitator URL for AUTHORIZE operations */
+    facilitatorUrl?: string;
+    /** JSON-RPC URL for on-chain operations (required when using SigningWalletAdapter) */
+    rpcUrl?: string;
+    /**
+     * Chain ID (default: 8453 for Base Mainnet).
+     * Supported chains: 8453 (Base), 84532 (Base Sepolia), 1 (Ethereum),
+     * 11155111 (Ethereum Sepolia), 137 (Polygon), 42161 (Arbitrum),
+     * 10 (Optimism), 42220 (Celo), 143 (Monad), 43114 (Avalanche).
+     */
+    chainId?: number;
+    /** Contract addresses (auto-resolved from chainId if not provided) */
+    contracts?: AdvancedEscrowContracts;
+    /** Gas limit for transactions (default: 300000) */
+    gasLimit?: number;
+    /**
+     * Request timeout in milliseconds for facilitator HTTP calls (authorize, gasless release/refund).
+     * Default is per-network: 960s for Ethereum L1, 90s for L2s.
+     * Ethereum L1 confirmations can take several minutes under congestion.
+     */
+    timeout?: number;
+    /**
+     * SigningWalletAdapter for OWS wallet signing (v2.36.0+).
+     *
+     * When provided, the client uses the adapter for all signing operations
+     * instead of requiring a raw ethers.Signer. The first constructor argument
+     * is ignored when `wallet` is set.
+     *
+     * Requires `rpcUrl` to be set for on-chain transaction building.
+     *
+     * @example
+     * ```typescript
+     * import { OWSWalletAdapter, AdvancedEscrowClient } from 'uvd-x402-sdk/backend';
+     *
+     * const wallet = new OWSWalletAdapter(owsWallet);
+     * const client = new AdvancedEscrowClient(null, {
+     *   wallet,
+     *   rpcUrl: 'https://mainnet.base.org',
+     *   chainId: 8453,
+     * });
+     * ```
+     */
+    wallet?: SigningWalletAdapter;
+    /**
+     * Extra attempts on the gasless facilitator paths when the facilitator proved
+     * it executed nothing. Default 2; `0` disables.
+     */
+    retries?: number;
+}
+/**
+ * Minimal PaymentOperator ABI for the 4 on-chain functions.
+ * (AUTHORIZE goes through the facilitator, not directly on-chain)
+ */
+declare const OPERATOR_ABI: string[];
+/**
+ * CREATE3-deployed operators (SKALE, future chains) use updated ABI with extra `bytes data` param
+ * on release() and refundInEscrow(). Pass empty bytes (0x) for the data parameter.
+ */
+declare const OPERATOR_ABI_CREATE3: string[];
+/**
+ * AdvancedEscrowClient provides the 5 Advanced Escrow flows via the
+ * PaymentOperator contract on 9 supported EVM networks.
+ *
+ * Supported chains: Base (8453), Base Sepolia (84532), Ethereum (1),
+ * Ethereum Sepolia (11155111), Polygon (137), Arbitrum (42161),
+ * Optimism (10), Celo (42220), Monad (143), Avalanche (43114).
+ *
+ * Contract addresses are auto-resolved from the chain ID.
+ * Pass custom contracts to override.
+ *
+ * Two signer modes (v2.36.0+):
+ * - **Legacy**: Pass an ethers.Signer as the first argument.
+ * - **OWS Wallet**: Pass a SigningWalletAdapter via `options.wallet`.
+ *   The adapter signs transactions offline (no raw private key needed).
+ *   Requires `rpcUrl` for transaction building and broadcast.
+ *
+ * @example Legacy mode (ethers.Signer)
+ * ```typescript
+ * import { ethers } from 'ethers';
+ * import { AdvancedEscrowClient } from 'uvd-x402-sdk/backend';
+ *
+ * const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
+ * const signer = new ethers.Wallet(process.env.KEY!, provider);
+ * const client = new AdvancedEscrowClient(signer, { chainId: 8453 });
+ * ```
+ *
+ * @example OWS Wallet mode (SigningWalletAdapter)
+ * ```typescript
+ * import { OWSWalletAdapter } from 'uvd-x402-sdk';
+ * import { AdvancedEscrowClient } from 'uvd-x402-sdk/backend';
+ *
+ * const wallet = new OWSWalletAdapter(owsWallet);
+ * const client = new AdvancedEscrowClient(null, {
+ *   wallet,
+ *   rpcUrl: 'https://mainnet.base.org',
+ *   chainId: 8453,
+ * });
+ * await client.init();
+ *
+ * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+ * const auth = await client.authorize(pi);
+ * const release = await client.release(pi);
+ * ```
+ */
+declare class AdvancedEscrowClient {
+    private facilitatorUrl;
+    private chainId;
+    private gasLimit;
+    private readonly timeout;
+    private readonly retries;
+    private contracts;
+    private signer;
+    private walletAdapter;
+    private rpcUrl;
+    private payerAddress;
+    /**
+     * Create an AdvancedEscrowClient.
+     *
+     * Two modes of operation:
+     *
+     * 1. **Legacy (ethers.Signer)**: Pass an ethers Signer as the first argument.
+     *    ```ts
+     *    const client = new AdvancedEscrowClient(signer, { rpcUrl, chainId });
+     *    ```
+     *
+     * 2. **OWS Wallet (SigningWalletAdapter)**: Pass `wallet` in options. The
+     *    first argument is ignored (pass `null`). Requires `rpcUrl` for on-chain
+     *    transaction building and broadcast.
+     *    ```ts
+     *    const wallet = new OWSWalletAdapter(owsWallet);
+     *    const client = new AdvancedEscrowClient(null, { wallet, rpcUrl, chainId });
+     *    ```
+     *
+     * @param signer - ethers.Signer instance (ignored when options.wallet is set)
+     * @param options - Configuration options
+     */
+    constructor(signer: any, options?: AdvancedEscrowClientOptions);
+    /**
+     * Initialize the client (resolves payer address).
+     * Call this before using any methods.
+     */
+    init(): Promise<void>;
+    /**
+     * Build a PaymentInfo struct with appropriate timing for the task tier.
+     *
+     * @param receiver - Worker's wallet address
+     * @param amount - Amount in token atomic units (e.g., '5000000' for $5 USDC)
+     * @param tier - Task tier determines timing parameters
+     * @param salt - Random salt (auto-generated if not provided)
+     */
+    buildPaymentInfo(receiver: string, amount: string, tier?: AdvancedEscrowTaskTier, salt?: string, opts?: {
+        deadline?: number;
+        reviewWindowSec?: number;
+        /**
+         * Fee bounds to sign, in basis points. Default
+         * {@link DEFAULT_MIN_FEE_BPS} / {@link DEFAULT_MAX_FEE_BPS}. Override
+         * only against an operator whose fee you have actually read on-chain —
+         * `maxFeeBps` is a CEILING, so a value under the operator's own fee does
+         * not shave the fee, it reverts the deposit.
+         */
+        minFeeBps?: number;
+        maxFeeBps?: number;
+    }): AdvancedPaymentInfo;
+    /**
+     * Compute the correct nonce (with PAYMENT_INFO_TYPEHASH).
+     * Matches the on-chain AuthCaptureEscrow nonce derivation.
+     */
+    private computeNonce;
+    /**
+     * Sign ReceiveWithAuthorization for ERC-3009.
+     *
+     * Uses SigningWalletAdapter.signTypedData() when in OWS mode,
+     * or ethers Signer.signTypedData() in legacy mode.
+     */
+    private signErc3009;
+    /**
+     * Build the on-chain PaymentInfo tuple for contract calls.
+     */
+    private buildTuple;
+    /**
+     * AUTHORIZE: Lock funds in escrow via the facilitator.
+     *
+     * Sends an ERC-3009 ReceiveWithAuthorization to the facilitator,
+     * which calls PaymentOperator.authorize() on-chain.
+     */
+    authorize(paymentInfo: AdvancedPaymentInfo): Promise<AdvancedAuthorizationResult>;
+    /**
+     * RELEASE: Capture escrowed funds to receiver (worker gets paid).
+     *
+     * Calls PaymentOperator.release() -> escrow.capture()
+     *
+     * @param paymentInfo - PaymentInfo from the authorize step
+     * @param amount - Amount to release (defaults to maxAmount)
+     */
+    release(paymentInfo: AdvancedPaymentInfo, amount?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * REFUND IN ESCROW: Return escrowed funds to payer (cancel task).
+     *
+     * Calls PaymentOperator.refundInEscrow() -> escrow.partialVoid()
+     *
+     * @param paymentInfo - PaymentInfo from the authorize step
+     * @param amount - Amount to refund (defaults to maxAmount)
+     */
+    refundInEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * GASLESS RELEASE: Release escrowed funds via the facilitator.
+     *
+     * Instead of calling the PaymentOperator contract directly (which requires
+     * gas), this sends a release request to the facilitator, which submits
+     * the transaction on your behalf.
+     *
+     * @param paymentInfo - PaymentInfo from the authorize step
+     * @param amount - Amount to release in atomic units (defaults to maxAmount)
+     * @returns Transaction result from the facilitator
+     *
+     * @example
+     * ```typescript
+     * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+     * await client.authorize(pi);
+     * // Worker completes task...
+     * const result = await client.releaseViaFacilitator(pi);
+     * console.log(result.transactionHash);
+     * ```
+     *
+     * @example Signed release (the payer proves the release is theirs to ask for)
+     * ```typescript
+     * await client.releaseViaFacilitator(pi, undefined, {
+     *   lifecycleSigner: payerWallet,   // EnvKeyAdapter, OWS, wagmiLifecycleSigner(...)
+     * });
+     * ```
+     *
+     * @example Transporting an order the publisher signed in their browser
+     * ```typescript
+     * // The browser sent back a signature over a document THIS backend built.
+     * const lifecycleAuth = lifecycleAuthFromSignature(typedData, signature, payer);
+     * await client.releaseViaFacilitator(pi, amount, { lifecycleAuth });
+     * ```
+     */
+    releaseViaFacilitator(paymentInfo: AdvancedPaymentInfo, amount?: string, options?: LifecycleAuthOptions): Promise<AdvancedTransactionResult>;
+    /**
+     * GASLESS REFUND: return escrowed funds to the payer via the facilitator.
+     *
+     * Sends `action: "refundInEscrow"` to `POST /settle`; the facilitator's
+     * PaymentOperator calls `AuthCaptureEscrow.partialVoid`.
+     *
+     * # This is how an EXPIRED escrow is recovered
+     *
+     * A widely repeated claim — including in this SDK's own comments until now —
+     * says that once `authorizationExpiry` passes, only the payer's `reclaim()`
+     * can move the funds. **That is false, and believing it has left real money
+     * stranded.**
+     *
+     * Read the contract (`AuthCaptureEscrow.sol`):
+     *
+     * - `partialVoid` is `onlySender(paymentInfo.operator)` — the operator is the
+     *   FACILITATOR, not the payer — it sends the tokens **to the payer**, and it
+     *   **does not check `authorizationExpiry` at all**. It works before expiry
+     *   and after it, and the payer never has to appear.
+     * - `reclaim` is `onlySender(paymentInfo.payer)` and only after expiry. It is
+     *   a payer's self-service escape hatch, which is why this facilitator does
+     *   not expose it — **not** the only way out.
+     *
+     * So a release that reverted with `AfterAuthorizationExpiry` is recoverable
+     * from here, with no gas and no cooperation from the payer. Get the amount
+     * from {@link queryEscrowState}'s `capturableAmount`.
+     *
+     * # A refusal that is not a refusal
+     *
+     * Check `retryable` before writing an escrow off. A `503` means the
+     * facilitator never reached the chain — the escrow is untouched and the same
+     * request should be sent again.
+     *
+     * @param paymentInfo - PaymentInfo from the authorize step
+     * @param amount - Amount to refund in atomic units (defaults to maxAmount).
+     *   For a stuck escrow pass `capturableAmount` from {@link queryEscrowState}.
+     * @returns Transaction result from the facilitator
+     *
+     * @example Recovering an escrow whose release window already closed
+     * ```typescript
+     * const state = await client.queryEscrowState(pi);
+     * if (state.capturableAmount !== '0') {
+     *   // No payer needed, no gas, and expiry is irrelevant to partialVoid.
+     *   const result = await client.refundViaFacilitator(pi, state.capturableAmount);
+     *   if (!result.success && result.retryable) {
+     *     // No verdict was reached. The funds are still there; send it again.
+     *   }
+     * }
+     * ```
+     */
+    refundViaFacilitator(paymentInfo: AdvancedPaymentInfo, amount?: string, options?: LifecycleAuthOptions): Promise<AdvancedTransactionResult>;
+    /**
+     * QUERY ESCROW STATE: Read on-chain escrow state via the facilitator.
+     *
+     * This is a read-only operation that queries the facilitator for the
+     * current escrow state without requiring gas or a signer.
+     *
+     * @param paymentInfo - PaymentInfo to query state for
+     * @returns Escrow state including capturable/refundable amounts
+     *
+     * @example
+     * ```typescript
+     * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
+     * await client.authorize(pi);
+     *
+     * const state = await client.queryEscrowState(pi);
+     * console.log(`Capturable: ${state.capturableAmount}`);
+     * console.log(`Refundable: ${state.refundableAmount}`);
+     * console.log(`Already collected: ${state.hasCollectedPayment}`);
+     * ```
+     */
+    queryEscrowState(paymentInfo: AdvancedPaymentInfo): Promise<EscrowStateResponse>;
+    /**
+     * CHARGE: Direct instant payment (no escrow hold).
+     *
+     * Calls PaymentOperator.charge() -> escrow.charge()
+     * Funds go directly from payer to receiver.
+     *
+     * @param paymentInfo - PaymentInfo with receiver and amount
+     * @param amount - Amount to charge (defaults to maxAmount)
+     */
+    charge(paymentInfo: AdvancedPaymentInfo, amount?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * REFUND POST ESCROW: Dispute refund after funds were released.
+     *
+     * Calls PaymentOperator.refundPostEscrow() -> escrow.refund()
+     *
+     * WARNING: NOT FUNCTIONAL IN PRODUCTION (as of 2026-02-03).
+     * The protocol team has not implemented the required tokenCollector
+     * contract. This call will fail on-chain.
+     *
+     * For dispute resolution, use refundInEscrow() instead: keep funds
+     * in escrow and refund before releasing. This guarantees funds are
+     * available and under arbiter control.
+     *
+     * Kept for future use when tokenCollector is implemented.
+     *
+     * @param paymentInfo - PaymentInfo from the original authorization
+     * @param amount - Amount to refund (defaults to maxAmount)
+     * @param tokenCollector - Address of token collector for refund sourcing
+     * @param collectorData - Data for the token collector
+     */
+    refundPostEscrow(paymentInfo: AdvancedPaymentInfo, amount?: string, tokenCollector?: string, collectorData?: string): Promise<AdvancedTransactionResult>;
+    /**
+     * Build an unsigned transaction, sign via SigningWalletAdapter, and broadcast.
+     *
+     * Used by release(), refundInEscrow(), charge(), refundPostEscrow() when
+     * operating in OWS wallet adapter mode. The adapter signs the serialized
+     * transaction offline; the RPC provider broadcasts the signed raw TX.
+     *
+     * @param ethersModule - ethers namespace (from `const { ethers } = await import('ethers')`)
+     * @param abi - Contract ABI (OPERATOR_ABI or OPERATOR_ABI_CREATE3)
+     * @param encodeCalldata - Function that encodes the calldata using the interface
+     * @returns Transaction result
+     */
+    private sendViaAdapter;
+}
+
+export { getCorsHeaders as $, AMBIGUOUS_LEASE_REASONS as A, type BuildLifecycleAuthParams as B, buildLifecycleAuth as C, DEFAULT_FACILITATOR_RETRIES as D, buildLifecycleTypedData as E, FacilitatorClient as F, buildPaymentRequirements as G, type HonoMiddlewareOptions as H, buildSettleRequest as I, buildSettleRequestForVersion as J, buildSettleRequestV2 as K, LIFECYCLE_ACTIONS as L, MAX_RETRY_AFTER_SECONDS as M, buildVerifyRequest as N, buildVerifyRequestForVersion as O, type ParsedFacilitatorErrorBody as P, buildVerifyRequestV2 as Q, REPLAYABLE_LEASE_REASONS as R, SETTLEMENT_UNCONFIRMED as S, create402Response as T, createHonoMiddleware as U, type VerifiedPaymentState as V, WRITER_LEASE_REASONS as W, X402_CORS_HEADERS as X, createPaymentMiddleware as Y, extractPaymentFromHeaders as Z, facilitatorFetch as _, DEFAULT_RETRY_AFTER_SECONDS as a, type FeedbackResponse as a$, isAmbiguousLeaseReason as a0, isReplayableLeaseReason as a1, isSettlementUnconfirmed as a2, lifecycleAuthFromSignature as a3, parseFacilitatorErrorBody as a4, parseRetryAfterSeconds as a5, readFacilitatorError as a6, resolveEnvelopeVersion as a7, toPaymentRequirementsV2 as a8, toResourceInfoV2 as a9, type DiscoveryHealthStatus as aA, type DiscoveryListOptions as aB, type DiscoveryPagination as aC, type DiscoveryRegisterOptions as aD, type DiscoveryResource as aE, type DiscoveryResponse as aF, type DiscoverySource as aG, type DiscoveryStats as aH, type DiscoveryTier as aI, type Dispute as aJ, type DisputeOutcome as aK, ERC8004_CONTRACTS as aL, ERC8004_EXTENSION_ID as aM, ESCROW_CONTRACTS as aN, ESCROW_TIMEOUT_MS as aO, Erc8004Client as aP, type Erc8004ClientOptions as aQ, Erc8004LookupError as aR, type Erc8004Network as aS, EscrowClient as aT, type EscrowClientOptions as aU, type EscrowPayment as aV, type EscrowStateResponse as aW, type EscrowStatus as aX, type FeedbackEntry as aY, type FeedbackParams as aZ, type FeedbackRequest as a_, wagmiLifecycleSigner as aa, type AdvancedAuthorizationResult as ab, AdvancedEscrowClient as ac, type AdvancedEscrowClientOptions as ad, type AdvancedEscrowContracts as ae, type AdvancedEscrowTaskTier as af, type AdvancedPaymentInfo as ag, type AdvancedTransactionResult as ah, type AgentId as ai, type AgentIdentity as aj, type AgentRegistration as ak, type AgentRegistrationFile as al, type AgentService as am, type AtomStats as an, BASE_MAINNET_CONTRACTS as ao, BazaarClient as ap, type BazaarClientOptions as aq, type BazaarDiscoverOptions as ar, type BazaarDiscoverResponse as as, type BazaarRegisterOptions as at, type BazaarResource as au, type CreateEscrowOptions as av, DEPOSIT_LIMIT_USDC as aw, type DiscoveryAccepts as ax, type DiscoveryCuration as ay, type DiscoveryHealth as az, type FacilitatorClientOptions as b, HEALTH_FILTERS as b0, type IdentityByOwnerResponse as b1, type IdentityMetadataResponse as b2, type IdentityTotalSupplyResponse as b3, type LifecycleAuthOptions as b4, MAX_SEARCH_LEN as b5, type MetadataEntryParam as b6, OPERATOR_ABI as b7, OPERATOR_ABI_CREATE3 as b8, PAYMENT_INFO_TYPEHASH as b9, USDC_DOMAIN_NAME as bA, type UnavailableBody as bB, type UnavailableResponse as bC, type VerifyRequest as bD, type VerifyResponse as bE, ZERO_ADDRESS as bF, buildErc8004PaymentRequirements as bG, buildUnavailableResponse as bH, canRefundEscrow as bI, canReleaseEscrow as bJ, carryFailureFields as bK, epochToDate as bL, escrowTimeRemaining as bM, getEscrowContractsByChainId as bN, getEscrowSupportedChainIds as bO, isAlive as bP, isEscrowExpired as bQ, isEscrowSupportedOnChain as bR, isRegisterJobTerminal as bS, parsePaymentHeader as bT, supportsRelayedFeedback as bU, wireNetwork as bV, type PaymentRequirementResolver as ba, type PaymentRequirements as bb, type PaymentRequirementsOptions as bc, type PrepareRelayFeedbackRequest as bd, type PrepareRelayFeedbackResponse as be, type PrepareRelayResponseRequest as bf, type ProofOfPayment as bg, RELAYED_FEEDBACK_NETWORKS as bh, type RefundRequest as bi, type RefundStatus as bj, type RegisterAgentRequest as bk, type RegisterAgentResponse as bl, type RegisterJobResponse as bm, type RegisterJobStatus as bn, RegistrationPendingError as bo, type RelayAuthorizationParams as bp, type ReputationResponse as bq, type ReputationSummary as br, type RequestRefundOptions as bs, type SettleRequest as bt, type SettleResponse as bu, type SettleResponseWithProof as bv, type SubmitRelayFeedbackRequest as bw, type SubmitRelayResponseRequest as bx, TIER_FILTERS as by, TIER_TIMINGS as bz, type FacilitatorErrorInfo as c, type FacilitatorFailureFields as d, type FacilitatorFetchOptions as e, LIFECYCLE_DEFAULT_DEADLINE_SECS as f, LIFECYCLE_DOMAIN_NAME as g, LIFECYCLE_DOMAIN_VERSION as h, LIFECYCLE_MAX_DEADLINE_SECS as i, LIFECYCLE_ORDER_TYPES as j, type LifecycleAction as k, type LifecycleAuth as l, type LifecyclePaymentInfo as m, type LifecycleSigner as n, type LifecycleTypedData as o, type LifecycleTypedDataParams as p, type PaymentAcceptance as q, type PaymentMiddlewareOptions as r, type PaymentPayloadV2 as s, type PaymentRequirementsV2 as t, type ResourceInfoV2 as u, type SettleRequestV2 as v, type VerifyRequestV2 as w, type WagmiLifecycleWalletClient as x, type WriterLeaseReason as y, X402_HEADER_NAMES as z };