@haven_ai/sdk 0.1.23-alpha.2 → 0.1.24-alpha.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from 'async_hooks';
 import { exact } from 'x402/schemes';
-import { hashTypedData } from 'viem';
+import { recoverTypedDataAddress, hashTypedData } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { ethers } from 'ethers';
 import { createHash } from 'crypto';
@@ -342,7 +342,7 @@ function signHash(privateKey, hash) {
     );
   }
 }
-async function signUserOpTypedDataForDelegation(privateKey, typedData) {
+async function signTypedDataVerbatim(privateKey, typedData, label) {
   try {
     const wallet = new ethers.Wallet(privateKey);
     const types = { ...typedData.types };
@@ -354,10 +354,16 @@ async function signUserOpTypedDataForDelegation(privateKey, typedData) {
     );
   } catch (err) {
     throw new HavenSigningError(
-      `Failed to sign delegation UserOperation: ${err instanceof Error ? err.message : String(err)}`
+      `Failed to sign ${label}: ${err instanceof Error ? err.message : String(err)}`
     );
   }
 }
+async function signUserOpTypedDataForDelegation(privateKey, typedData) {
+  return signTypedDataVerbatim(privateKey, typedData, "delegation UserOperation");
+}
+async function signSettlementDelegationTypedData(privateKey, typedData) {
+  return signTypedDataVerbatim(privateKey, typedData, "x402 settlement delegation");
+}
 function addressFromKey(privateKey) {
   try {
     return new ethers.Wallet(privateKey).address;
@@ -435,12 +441,128 @@ function decodeBase64Json(value, label) {
   }
 }
 
+// src/sweep.ts
+var SWEEP_BASE_CHAIN_ID = 8453;
+var SWEEP_BASE_SEPOLIA_CHAIN_ID = 84532;
+var SWEEP_BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var SWEEP_BASE_SEPOLIA_USDC_ADDRESS = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+var USDC_EIP712_DOMAIN_BY_CHAIN = {
+  [SWEEP_BASE_CHAIN_ID]: {
+    name: "USD Coin",
+    version: "2",
+    chainId: SWEEP_BASE_CHAIN_ID,
+    verifyingContract: SWEEP_BASE_USDC_ADDRESS
+  },
+  [SWEEP_BASE_SEPOLIA_CHAIN_ID]: {
+    name: "USDC",
+    version: "2",
+    chainId: SWEEP_BASE_SEPOLIA_CHAIN_ID,
+    verifyingContract: SWEEP_BASE_SEPOLIA_USDC_ADDRESS
+  }
+};
+var USDC_ADDRESS_BY_CHAIN = {
+  [SWEEP_BASE_CHAIN_ID]: SWEEP_BASE_USDC_ADDRESS,
+  [SWEEP_BASE_SEPOLIA_CHAIN_ID]: SWEEP_BASE_SEPOLIA_USDC_ADDRESS
+};
+var SWEEPABLE_CHAIN_IDS = Object.keys(USDC_ADDRESS_BY_CHAIN).map(Number);
+function isSweepableChain(chainId) {
+  return chainId in USDC_ADDRESS_BY_CHAIN;
+}
+var TRANSFER_WITH_AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+function sweepUsdcAddress(chainId) {
+  const address = USDC_ADDRESS_BY_CHAIN[chainId];
+  if (!address) {
+    throw new HavenSigningError(
+      `Sweep is not supported on chain ${chainId}. Supported: ${SWEEPABLE_CHAIN_IDS.join(", ")}.`
+    );
+  }
+  return address;
+}
+function sweepUsdcDomain(chainId) {
+  const domain = USDC_EIP712_DOMAIN_BY_CHAIN[chainId];
+  if (!domain) {
+    throw new HavenSigningError(
+      `Sweep is not supported on chain ${chainId}. Supported: ${SWEEPABLE_CHAIN_IDS.join(", ")}.`
+    );
+  }
+  return domain;
+}
+function sameAddress(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+function buildSweepTypedData(auth) {
+  const domain = sweepUsdcDomain(auth.chainId);
+  const expectedToken = sweepUsdcAddress(auth.chainId);
+  if (!sameAddress(auth.token, expectedToken)) {
+    throw new HavenSigningError(
+      `Sweep token ${auth.token} is not the canonical USDC contract for chain ${auth.chainId}.`
+    );
+  }
+  if (!/^0x[0-9a-fA-F]{64}$/.test(auth.nonce)) {
+    throw new HavenSigningError("Sweep nonce must be a 0x-prefixed 32-byte hex string.");
+  }
+  return {
+    domain,
+    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: auth.from,
+      to: auth.to,
+      value: BigInt(auth.value),
+      validAfter: BigInt(auth.validAfter),
+      validBefore: BigInt(auth.validBefore),
+      nonce: auth.nonce
+    }
+  };
+}
+function buildSweepAuthorizationMessage(auth) {
+  return `Haven sweep authorization v1
+${stableStringify({
+    version: 1,
+    kind: "haven.sweep.authorization",
+    from: auth.from.toLowerCase(),
+    to: auth.to.toLowerCase(),
+    value: auth.value,
+    validAfter: auth.validAfter,
+    validBefore: auth.validBefore,
+    nonce: auth.nonce.toLowerCase(),
+    token: auth.token.toLowerCase(),
+    chainId: auth.chainId
+  })}`;
+}
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  const object = value;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
+}
+
 // src/x402.ts
 var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
 var BASE_SEPOLIA_USDC_ADDRESS = "0x036cbd53842c5426634e7929541ec2318f3dcf7e";
 var STANDARD_X402_USDC_ADDRESSES = /* @__PURE__ */ new Set([BASE_USDC_ADDRESS, BASE_SEPOLIA_USDC_ADDRESS]);
 var X402_IDEMPOTENCY_BUCKET_MS = 3e5;
 var DECIMAL_ATOMIC_AMOUNT_RE = /^[0-9]+$/;
+var X402_PAYMENT_HEADER_MAX_LENGTH = 65536;
+var BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var SIGNATURE_RE = /^0x[0-9a-fA-F]{130}$/;
+var NONCE_RE = /^0x[0-9a-fA-F]{64}$/;
+var X402PaymentHeaderValidationError = class extends Error {
+  constructor() {
+    super("Invalid X-PAYMENT header.");
+    this.name = "X402PaymentHeaderValidationError";
+  }
+};
 function isPositiveDecimalAtomicAmount(value) {
   return DECIMAL_ATOMIC_AMOUNT_RE.test(value) && BigInt(value) > 0n;
 }
@@ -483,7 +605,7 @@ function normalizePaymentRequired(value) {
   if (!candidate || typeof candidate !== "object" || typeof candidate.x402Version !== "number" || !Array.isArray(candidate.accepts)) {
     return null;
   }
-  const accepts = candidate.accepts.map((option) => normalizePaymentOption(option)).filter((option) => !!option);
+  const accepts = candidate.accepts.map((option) => normalizePaymentOption(option)).filter((option) => !!option && typeof option === "object");
   if (accepts.length === 0) return null;
   const first = accepts[0];
   const resourceUrl = candidate.resource?.url ?? first.resource;
@@ -588,13 +710,52 @@ function selectPaymentOption(accepts) {
   }
   return null;
 }
+var ERC7710_ASSET_TRANSFER_METHOD = "erc7710";
+function x402AssetTransferMethod(option) {
+  const raw = option.extra?.assetTransferMethod;
+  return typeof raw === "string" ? raw : null;
+}
+function isErc7710Option(option) {
+  return x402AssetTransferMethod(option) === ERC7710_ASSET_TRANSFER_METHOD;
+}
+function x402FacilitatorAddresses(option) {
+  const raw = option.extra?.facilitatorAddresses;
+  if (!Array.isArray(raw)) return null;
+  const addresses = raw.filter((a) => typeof a === "string" && ADDRESS_RE.test(a));
+  return addresses.length > 0 ? addresses : null;
+}
+function isPayableStandardOption(opt) {
+  return opt.scheme === "exact" && opt.network in STANDARD_X402_NETWORKS && STANDARD_X402_USDC_ADDRESSES.has(opt.asset.toLowerCase()) && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt));
+}
 function selectStandardPaymentOption(accepts) {
   if (!accepts || accepts.length === 0) return null;
   for (const opt of accepts) {
-    if (opt.scheme === "exact" && opt.network in STANDARD_X402_NETWORKS && STANDARD_X402_USDC_ADDRESSES.has(opt.asset.toLowerCase()) && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
-      return opt;
+    if (opt === null || typeof opt !== "object") continue;
+    if (!isErc7710Option(opt) && isPayableStandardOption(opt)) return opt;
+  }
+  return null;
+}
+function selectErc7710PaymentOption(accepts) {
+  if (!accepts || accepts.length === 0) return null;
+  for (const opt of accepts) {
+    if (opt === null || typeof opt !== "object") continue;
+    if (isErc7710Option(opt) && isPayableStandardOption(opt)) return opt;
+  }
+  return null;
+}
+function selectX402SettlementScheme(accepts, opts) {
+  if (opts.delegationRail) {
+    const preferred = selectErc7710PaymentOption(accepts);
+    if (preferred) {
+      return {
+        scheme: "erc7710",
+        option: preferred,
+        facilitatorAddresses: x402FacilitatorAddresses(preferred)
+      };
     }
   }
+  const fallback = selectStandardPaymentOption(accepts);
+  if (fallback) return { scheme: "eip3009", option: fallback, facilitatorAddresses: null };
   return null;
 }
 function x402AuthorizationAmount(option) {
@@ -624,7 +785,7 @@ function buildX402ExpectedMessage(context) {
     payload.typedDataHash = context.typedDataHash.toLowerCase();
   }
   return `Haven x402 expected context v${version}
-${stableStringify(payload)}`;
+${stableStringify2(payload)}`;
 }
 function toStandardPaymentRequirements(paymentRequired, option) {
   const network = STANDARD_X402_NETWORKS[option.network];
@@ -655,6 +816,89 @@ function toStandardPaymentRequirements(paymentRequired, option) {
     extra: option.extra
   };
 }
+async function validateStandardX402PaymentHeader(paymentHeader, context) {
+  try {
+    if (typeof paymentHeader !== "string" || paymentHeader.length === 0 || paymentHeader.length > X402_PAYMENT_HEADER_MAX_LENGTH || paymentHeader.length % 4 !== 0 || !BASE64_RE.test(paymentHeader)) {
+      throw new Error("wire");
+    }
+    const decoded = decodeBase64Json(paymentHeader);
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) throw new Error("shape");
+    const version = decoded.x402Version;
+    const payload = decoded.payload;
+    if (version !== 1 && version !== 2 || !payload || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error("shape");
+    }
+    if (version === 1) {
+      if (!hasOnlyKeys(decoded, ["x402Version", "scheme", "network", "payload"])) throw new Error("shape");
+      if (decoded.scheme !== "exact" || decoded.network !== standardX402WireNetwork(context.network)) {
+        throw new Error("context");
+      }
+    } else {
+      if (!hasOnlyKeys(decoded, ["x402Version", "accepted", "payload"])) throw new Error("shape");
+      const accepted = selectStandardPaymentOption([decoded.accepted]);
+      if (!accepted || !matchesHeaderContext(accepted, context)) throw new Error("context");
+    }
+    const record = payload;
+    if (!hasOnlyKeys(record, ["signature", "authorization"])) throw new Error("shape");
+    if (typeof record.signature !== "string" || !SIGNATURE_RE.test(record.signature)) throw new Error("shape");
+    const authorization = record.authorization;
+    if (!authorization || typeof authorization !== "object" || Array.isArray(authorization)) throw new Error("shape");
+    const auth = authorization;
+    if (!hasOnlyKeys(auth, ["from", "to", "value", "validAfter", "validBefore", "nonce"])) throw new Error("shape");
+    if (typeof auth.from !== "string" || !ADDRESS_RE.test(auth.from) || typeof auth.to !== "string" || !ADDRESS_RE.test(auth.to) || typeof auth.value !== "string" || !isPositiveDecimalAtomicAmount(auth.value) || typeof auth.validAfter !== "string" || !DECIMAL_ATOMIC_AMOUNT_RE.test(auth.validAfter) || typeof auth.validBefore !== "string" || !DECIMAL_ATOMIC_AMOUNT_RE.test(auth.validBefore) || typeof auth.nonce !== "string" || !NONCE_RE.test(auth.nonce)) {
+      throw new Error("shape");
+    }
+    if (!sameAddress2(auth.from, context.payer) || !sameAddress2(auth.to, context.merchantTo) || auth.value !== context.amountAtomic) {
+      throw new Error("context");
+    }
+    const validAfter = BigInt(auth.validAfter);
+    const validBefore = BigInt(auth.validBefore);
+    const now = BigInt(Math.floor(Date.now() / 1e3));
+    if (validBefore <= now || validAfter > validBefore) throw new Error("expired");
+    const typedData = buildSweepTypedData({
+      from: auth.from,
+      to: auth.to,
+      value: auth.value,
+      validAfter: auth.validAfter,
+      validBefore: auth.validBefore,
+      nonce: auth.nonce,
+      token: context.asset,
+      chainId: context.chainId
+    });
+    const recovered = await recoverTypedDataAddress({
+      ...typedData,
+      // `buildSweepTypedData` keeps the public domain framework-neutral;
+      // viem brands contract addresses at this crypto call boundary only.
+      domain: {
+        ...typedData.domain,
+        verifyingContract: typedData.domain.verifyingContract
+      },
+      message: {
+        ...typedData.message,
+        from: typedData.message.from,
+        to: typedData.message.to,
+        nonce: typedData.message.nonce
+      },
+      signature: record.signature
+    });
+    if (!sameAddress2(recovered, context.payer)) throw new Error("recovery");
+  } catch {
+    throw new X402PaymentHeaderValidationError();
+  }
+}
+function hasOnlyKeys(value, allowed) {
+  return Object.keys(value).every((key) => allowed.includes(key)) && allowed.every((key) => key in value);
+}
+function sameAddress2(left, right) {
+  return left.toLowerCase() === right.toLowerCase();
+}
+function standardX402WireNetwork(network) {
+  return STANDARD_X402_NETWORKS[network] ?? null;
+}
+function matchesHeaderContext(option, context) {
+  if (option.scheme !== "exact" || !sameAddress2(option.payTo, context.merchantTo) || !sameAddress2(option.asset, context.asset) || option.network !== context.network || x402AuthorizationAmount(option) !== context.amountAtomic) return false;
+  return option.resource === void 0 || option.resource === context.resourceUrl;
+}
 function buildX402IdempotencyKey(paymentRequired, option, now = Date.now()) {
   const bucket = Math.floor(now / X402_IDEMPOTENCY_BUCKET_MS);
   const material = [
@@ -691,15 +935,15 @@ function resolveTokenFromAddress(address, network) {
   }
   return ALL_TOKENS[lower] ?? null;
 }
-function stableStringify(value) {
+function stableStringify2(value) {
   if (value === null || typeof value !== "object") {
     const primitive = JSON.stringify(value);
     return primitive === void 0 ? "undefined" : primitive;
   }
   if (value instanceof Date) return JSON.stringify(value.toISOString());
-  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify2(item)).join(",")}]`;
   const object = value;
-  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify2(object[key])}`).join(",")}}`;
 }
 function createJsonRpcProvider(url) {
   return new ethers.JsonRpcProvider(url);
@@ -770,6 +1014,7 @@ var PAYMENT_STATE_STATUS_CODES = {
 };
 function chainIdFromNetwork(network) {
   if (network === "base") return 8453;
+  if (network === "base-sepolia") return 84532;
   if (!network?.startsWith("eip155:")) return void 0;
   const chainId = Number(network.slice("eip155:".length));
   return Number.isFinite(chainId) ? chainId : void 0;
@@ -818,7 +1063,7 @@ function messageForState(label, status, paymentId, nextAction) {
   }
   return `${label} is ${status}; next_action=${nextAction} (payment_id: ${paymentId}).`;
 }
-function sameAddress(a, b) {
+function sameAddress3(a, b) {
   return Boolean(a && b && a.toLowerCase() === b.toLowerCase());
 }
 function decimalFromUsdcAtomic(value) {
@@ -1155,6 +1400,14 @@ var HavenClient = class {
       }
       return signUserOpTypedDataForDelegation(this.delegateKey, signData.typed_data);
     }
+    if (scheme === "eip712_delegation") {
+      if (!signData.typed_data) {
+        throw new HavenSigningError(
+          "sign_data.signature_scheme is eip712_delegation but typed_data is missing \u2014 refusing to sign the bare hash (the settlement would be rejected on redemption)."
+        );
+      }
+      return signSettlementDelegationTypedData(this.delegateKey, signData.typed_data);
+    }
     if (scheme === void 0) {
       return signHash(this.delegateKey, signData.hash);
     }
@@ -1725,6 +1978,140 @@ var HavenClient = class {
     this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
     return receipt;
   }
+  /**
+   * Pay a merchant through **erc7710 direct settlement** (#1454, epic #1450).
+   *
+   * The whole point of this path is what it does NOT do. There is no funding
+   * leg: the merchant redeems a delegation chain and pulls from the treasury
+   * directly, so the delegate EOA never holds the money, no sweep can strand
+   * it, and the #713 reconciliation class does not apply. It is also why this
+   * method is SMALLER than the 3009 path — the backend assembles the merchant
+   * `X-PAYMENT` header in `assembleSettlementPayload`, so the SDK builds no
+   * header locally.
+   *
+   *     authorize (payTo = the MERCHANT) → sign the child → settle → header
+   *
+   * The caller then retries the merchant with that header. **Nothing has
+   * settled when this returns** — that is why it does not return an
+   * `X402Receipt`.
+   *
+   * Requires a delegation-rail account. The backend enforces that
+   * (`validateGenericSchemeRail`), and so does this method, before building a
+   * request the backend would only reject: an error a client can explain is
+   * worth more than a 400 it has to decode.
+   *
+   * **MCP callers must pass `options.resourceUrl`.** An in-band MCP 402
+   * challenge frequently carries no `resource` object at all, so
+   * `paymentRequired.resource?.url` is undefined and the backend answers
+   * "Valid url is required". The QA scenario this path was ported from falls
+   * back to the request URL for exactly that reason — the SDK cannot, because
+   * it never saw the request. Pass it.
+   */
+  async settleX402Erc7710(paymentRequired, options = {}) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "delegateKey is required for x402 payments. Pass it in the HavenClient config."
+      );
+    }
+    const prepared = await this.prepareX402Erc7710(paymentRequired, options);
+    const signature = await this.signForData(prepared.signData);
+    const paymentHeader = await this.submitX402Erc7710(prepared.paymentId, signature);
+    return { ...prepared.settlement, paymentHeader };
+  }
+  /**
+   * The AUTHORIZE half of erc7710 settlement (#1456): select the scheme, build
+   * the request, and return the child to be signed — without signing it.
+   *
+   * Split out because the hosted topology cannot use `settleX402Erc7710()`:
+   * that method signs in-process with `delegateKey`, and hosted Haven does not
+   * have one and must not. The hosted MCP server drives these two halves with
+   * the LOCAL signer in between, so the key stays where it belongs and the
+   * request shaping stays in one place rather than being reimplemented.
+   */
+  async prepareX402Erc7710(paymentRequired, options = {}) {
+    const delegationRail = options.delegationRail ?? (await this.getAgent()).executionRail === "delegation";
+    if (!delegationRail) {
+      throw new HavenApiError(
+        "erc7710 settlement requires a delegation-rail account; this one is not on it. Use authorizeX402() for the standard EIP-3009 path.",
+        400
+      );
+    }
+    const selection = selectX402SettlementScheme(paymentRequired.accepts, { delegationRail });
+    if (!selection || selection.scheme !== "erc7710") {
+      throw new HavenApiError(
+        "This merchant does not advertise an erc7710 settlement option (no accepts[] entry carries extra.assetTransferMethod: 'erc7710'). Use authorizeX402() for the standard EIP-3009 path.",
+        400
+      );
+    }
+    const option = selection.option;
+    const merchantPayTo = option.payTo;
+    const amountAtomic = x402AuthorizationAmount(option);
+    const raw = await this.post("/x402", {
+      url: options.resourceUrl ?? paymentRequired.resource?.url,
+      // payTo = the MERCHANT is what selects direct settlement server-side.
+      // The explicit settlementScheme must AGREE with that shape (#1360) —
+      // disagreement is a 400 by design, so that a stale delegate address
+      // becomes a loud mismatch instead of a silent reroute to the 3009 leg.
+      payTo: merchantPayTo,
+      settlementScheme: "erc7710",
+      amount: amountAtomic,
+      asset: option.asset,
+      network: option.network,
+      // The v2 header echoes the accepted entry field-for-field, so the quoted
+      // timeout must round-trip or the merchant rejects the echo (#1064).
+      maxTimeoutSeconds: option.maxTimeoutSeconds,
+      // #1058: forward the advertised facilitators verbatim — the child becomes
+      // redeemable ONLY by them. `null` here means the merchant advertised none
+      // (or an empty array, which the backend 400s on), so the field is OMITTED
+      // rather than sent empty. See x402FacilitatorAddresses.
+      ...selection.facilitatorAddresses ? { facilitatorAddresses: selection.facilitatorAddresses } : {}
+    });
+    if (!raw.payment_id) {
+      throw new HavenApiError("No payment_id returned from x402/authorize", 500, raw);
+    }
+    const signData = raw.sign_data;
+    if (signData?.signature_scheme !== "eip712_delegation" || !signData.typed_data) {
+      throw new HavenApiError(
+        `x402/authorize did not return an erc7710 settlement child (signature_scheme was ${JSON.stringify(signData?.signature_scheme)}). Refusing to sign a payload this path did not ask for.`,
+        500,
+        raw
+      );
+    }
+    return {
+      paymentId: raw.payment_id,
+      signData,
+      settlement: {
+        paymentId: raw.payment_id,
+        merchantPayTo,
+        amountAtomic,
+        asset: option.asset,
+        network: option.network,
+        facilitatorAddresses: selection.facilitatorAddresses
+      }
+    };
+  }
+  /**
+   * The SETTLE half (#1456): exchange the signed child for the merchant header.
+   *
+   * The SDK builds no header on this path — the backend assembles the MetaMask
+   * erc7710 payload in `assembleSettlementPayload`. Whoever produced the
+   * signature (an in-process delegate key, or the local edge signer over the
+   * hosted boundary) is irrelevant here.
+   */
+  async submitX402Erc7710(paymentId, signature) {
+    const settled = await this.post(
+      `/x402/${paymentId}/settle`,
+      { signature }
+    );
+    if (!settled.payment_header) {
+      throw new HavenApiError(
+        "x402 settle returned no payment_header \u2014 the merchant cannot be retried.",
+        500,
+        settled
+      );
+    }
+    return settled.payment_header;
+  }
   async resumeAuthorizedX402(input) {
     if (!this.delegateKey) {
       throw new HavenSigningError(
@@ -2255,7 +2642,7 @@ var HavenClient = class {
         status.paymentId
       );
     }
-    if (status.merchantAddress && !sameAddress(status.merchantAddress, option.payTo)) {
+    if (status.merchantAddress && !sameAddress3(status.merchantAddress, option.payTo)) {
       throw new HavenApiError(
         "x402 resume request does not match the approved merchant.",
         409,
@@ -2950,6 +3337,7 @@ var HavenClient = class {
       token: raw.token,
       resourceUrl: raw.resource_url,
       merchantAddress: raw.merchant_address,
+      payerAddress: raw.payer_address ?? null,
       txHash: raw.tx_hash,
       expiresAt: raw.expires_at,
       chainId: raw.chain_id,
@@ -3412,14 +3800,18 @@ normal, not an error.
 
 1. \`mcp__haven__haven_discover_tools\` to find a payable service and its
    \`catalog_id\`.
-2. \`mcp__haven__haven_prepare_catalog_purchase\` with \`catalog_id\` and a
+2. If the user needs the live price before authorizing a cap, call
+   \`mcp__haven__haven_quote_catalog_purchase\` with \`catalog_id\`. It is
+   read-only and informational only: it never reserves a price or creates a
+   payment. Tell the user its \`amount\` / \`amount_atomic\`, then choose a cap.
+3. \`mcp__haven__haven_prepare_catalog_purchase\` with \`catalog_id\` and a
    spending cap. A cap is REQUIRED on this tool and is best practice on every
    paid call below too \u2014 it caps what the LIVE merchant quote may charge,
    checked before any funding intent is created. Write it the way the user
    said it: \`max_amount_human\` is whole tokens, so "no more than 1 USDC" is
    \`max_amount_human: "1"\`. (\`max_amount\` is the atomic-unit form, where
    "1" means 0.000001 USDC \u2014 do not convert by hand, and never send both.)
-3. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: \`next_action\`, \`next_tool\`,
+4. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: \`next_action\`, \`next_tool\`,
    and \`next_arguments\` name the exact next call \u2014 act on those first; the
    prose in this section is fallback and debugging detail. If the catalog
    entry is missing or degraded, the response instead names
@@ -3447,7 +3839,12 @@ do not re-pay.
 
 Step-by-step alternative (also key-safe; for an older signer or backend, or
 when you already have a merchant URL and tool name instead of a
-\`catalog_id\`): \`mcp__haven__haven_pay_mcp_tool\` then
+\`catalog_id\`): if the user needs the live price before choosing a cap, first
+call \`mcp__haven__haven_quote_mcp_tool\` with that merchant URL, tool name,
+and arguments. It is informational only; then call
+\`mcp__haven__haven_pay_mcp_tool\` with the same inputs and the explicit cap.
+The paid call always obtains a fresh quote before it creates any intent. Then
+continue \`mcp__haven__haven_pay_mcp_tool\` \u2192
 \`mcp__haven-signer__haven_sign\` \u2192 \`mcp__haven__haven_submit\` \u2192
 \`mcp__haven-signer__haven_x402_sign_header\` \u2192
 \`mcp__haven__haven_complete_mcp_tool\`. Pass \`payment_required\`,
@@ -3469,11 +3866,13 @@ when the result says \`retry_original_x402_request\`.
 \`arguments\` field (for example
 \`tool_arguments: { "tier": "50gb" }\` -> \`arguments: { "tier": "50gb" }\`).
 
-**Prices:** show the user the live price from the pay-tool result, never a
-catalog price. \`haven_discover_tools\` prices are indicative
-(\`price_is_indicative\`) and can be stale. The pay-tool result's \`amount\` /
-\`amount_atomic\` is the amount Haven authorizes for the call \u2014 a ceiling the
-merchant settles at or below \u2014 so present it as the most the user will pay.
+**Prices:** show the user the live price from a read-only quote or the pay-tool
+result, never a catalog price. \`haven_discover_tools\` prices are indicative
+(\`price_is_indicative\`) and can be stale. A read-only quote is informational
+only and does not reserve a price; the later paid call re-quotes and enforces
+the cap. The pay-tool result's \`amount\` / \`amount_atomic\` is the amount
+Haven authorizes for that call \u2014 a ceiling the merchant settles at or below \u2014
+so present it as the most the user will pay.
 
 **Status:** \`mcp__haven__haven_get_payment_status\` with a \`payment_id\` to
 check on queued or in-flight payments. Do not poll in a tight loop.
@@ -3540,6 +3939,7 @@ the agent in the Haven dashboard under Agents. New requests stop immediately
 for that credential.
 `;
 var SKILL_FOLDER_NAME = "haven-pay";
+var HAVEN_SKILL_BODY_MD = HAVEN_SKILL_MD.replace(/^---\n[\s\S]*?\n---\n+/, "");
 
 // src/node-version.ts
 var HAVEN_MINIMUM_NODE_VERSION = "22.0.0";
@@ -3580,111 +3980,6 @@ function major(version) {
   return String(parseNodeVersion(version)[0]);
 }
 
-// src/sweep.ts
-var SWEEP_BASE_CHAIN_ID = 8453;
-var SWEEP_BASE_SEPOLIA_CHAIN_ID = 84532;
-var SWEEP_BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
-var SWEEP_BASE_SEPOLIA_USDC_ADDRESS = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
-var USDC_EIP712_DOMAIN_BY_CHAIN = {
-  [SWEEP_BASE_CHAIN_ID]: {
-    name: "USD Coin",
-    version: "2",
-    chainId: SWEEP_BASE_CHAIN_ID,
-    verifyingContract: SWEEP_BASE_USDC_ADDRESS
-  },
-  [SWEEP_BASE_SEPOLIA_CHAIN_ID]: {
-    name: "USDC",
-    version: "2",
-    chainId: SWEEP_BASE_SEPOLIA_CHAIN_ID,
-    verifyingContract: SWEEP_BASE_SEPOLIA_USDC_ADDRESS
-  }
-};
-var USDC_ADDRESS_BY_CHAIN = {
-  [SWEEP_BASE_CHAIN_ID]: SWEEP_BASE_USDC_ADDRESS,
-  [SWEEP_BASE_SEPOLIA_CHAIN_ID]: SWEEP_BASE_SEPOLIA_USDC_ADDRESS
-};
-var SWEEPABLE_CHAIN_IDS = Object.keys(USDC_ADDRESS_BY_CHAIN).map(Number);
-function isSweepableChain(chainId) {
-  return chainId in USDC_ADDRESS_BY_CHAIN;
-}
-var TRANSFER_WITH_AUTHORIZATION_TYPES = {
-  TransferWithAuthorization: [
-    { name: "from", type: "address" },
-    { name: "to", type: "address" },
-    { name: "value", type: "uint256" },
-    { name: "validAfter", type: "uint256" },
-    { name: "validBefore", type: "uint256" },
-    { name: "nonce", type: "bytes32" }
-  ]
-};
-function sweepUsdcAddress(chainId) {
-  const address = USDC_ADDRESS_BY_CHAIN[chainId];
-  if (!address) {
-    throw new HavenSigningError(
-      `Sweep is not supported on chain ${chainId}. Supported: ${SWEEPABLE_CHAIN_IDS.join(", ")}.`
-    );
-  }
-  return address;
-}
-function sweepUsdcDomain(chainId) {
-  const domain = USDC_EIP712_DOMAIN_BY_CHAIN[chainId];
-  if (!domain) {
-    throw new HavenSigningError(
-      `Sweep is not supported on chain ${chainId}. Supported: ${SWEEPABLE_CHAIN_IDS.join(", ")}.`
-    );
-  }
-  return domain;
-}
-function sameAddress2(a, b) {
-  return a.toLowerCase() === b.toLowerCase();
-}
-function buildSweepTypedData(auth) {
-  const domain = sweepUsdcDomain(auth.chainId);
-  const expectedToken = sweepUsdcAddress(auth.chainId);
-  if (!sameAddress2(auth.token, expectedToken)) {
-    throw new HavenSigningError(
-      `Sweep token ${auth.token} is not the canonical USDC contract for chain ${auth.chainId}.`
-    );
-  }
-  if (!/^0x[0-9a-fA-F]{64}$/.test(auth.nonce)) {
-    throw new HavenSigningError("Sweep nonce must be a 0x-prefixed 32-byte hex string.");
-  }
-  return {
-    domain,
-    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
-    primaryType: "TransferWithAuthorization",
-    message: {
-      from: auth.from,
-      to: auth.to,
-      value: BigInt(auth.value),
-      validAfter: BigInt(auth.validAfter),
-      validBefore: BigInt(auth.validBefore),
-      nonce: auth.nonce
-    }
-  };
-}
-function buildSweepAuthorizationMessage(auth) {
-  return `Haven sweep authorization v1
-${stableStringify2({
-    version: 1,
-    kind: "haven.sweep.authorization",
-    from: auth.from.toLowerCase(),
-    to: auth.to.toLowerCase(),
-    value: auth.value,
-    validAfter: auth.validAfter,
-    validBefore: auth.validBefore,
-    nonce: auth.nonce.toLowerCase(),
-    token: auth.token.toLowerCase(),
-    chainId: auth.chainId
-  })}`;
-}
-function stableStringify2(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map((item) => stableStringify2(item)).join(",")}]`;
-  const object = value;
-  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify2(object[key])}`).join(",")}}`;
-}
-
 // src/merchant-discovery.ts
 var MERCHANT_DISCOVERY_PATHS = ["/.well-known/haven-demo-merchant", "/"];
 var DISCOVERY_MAX_BYTES = 64 * 1024;
@@ -3729,6 +4024,6 @@ function sameUrl(a, b) {
   }
 }
 
-export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, AgentPaymentWarningCode, DISCOVERY_MAX_BYTES, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, MerchantTimeoutError, RECEIPT_VERSION, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, SignerRefusalCode, TRANSFER_WITH_AUTHORIZATION_TYPES, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parsePaymentRequired, parsePaymentRequiredResponse, resolveTokenFromAddress, sameUrl, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
+export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, AgentPaymentWarningCode, DISCOVERY_MAX_BYTES, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_BODY_MD, HAVEN_SKILL_MD, HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, MerchantTimeoutError, RECEIPT_VERSION, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, SignerRefusalCode, TRANSFER_WITH_AUTHORIZATION_TYPES, X402PaymentHeaderValidationError, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, havenTools, isErc7710Option, isSupportedNodeVersion, isSweepableChain, normalizePaymentRequired, parsePaymentRequired, parsePaymentRequiredResponse, resolveTokenFromAddress, sameUrl, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, verifyPaymentReceipt, verifySignature, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map