@haven_ai/sdk 0.1.27-alpha.0 → 0.1.28-alpha.0

package/dist/index.js

@@ -1,9 +1,9 @@
-import { AsyncLocalStorage } from 'async_hooks';
-import { exact } from 'x402/schemes';
 import { recoverTypedDataAddress, hashTypedData } from 'viem';
-import { privateKeyToAccount } from 'viem/accounts';
 import { ethers } from 'ethers';
 import { createHash } from 'crypto';
+import { AsyncLocalStorage } from 'async_hooks';
+import { exact } from 'x402/schemes';
+import { privateKeyToAccount } from 'viem/accounts';
 
 // src/client.ts
 
@@ -392,24 +392,6 @@ function verifySignature(hash, signature, expectedAddress) {
     return false;
   }
 }
-var RECEIPT_VERSION = "haven-receipt-1";
-function defaultRecover(hash, signature) {
-  return ethers.recoverAddress(hash, signature);
-}
-function verifyPaymentReceipt(receipt, recover = defaultRecover) {
-  const { delegate, signHash: signHash2, signature } = receipt.authorization;
-  if (!signature) return { verified: false, reason: "missing_signature" };
-  let recovered;
-  try {
-    recovered = recover(signHash2, signature);
-  } catch {
-    return { verified: false, reason: "bad_signature" };
-  }
-  if (recovered.toLowerCase() !== delegate.toLowerCase()) {
-    return { verified: false, reason: "signer_mismatch", recoveredSigner: recovered };
-  }
-  return { verified: true, recoveredSigner: recovered };
-}
 
 // src/base64.ts
 function normalizeBase64(value) {
@@ -956,61 +938,173 @@ function stableStringify2(value) {
   const object = value;
   return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify2(object[key])}`).join(",")}}`;
 }
-function createJsonRpcProvider(url) {
-  return new ethers.JsonRpcProvider(url);
-}
-function createWallet(privateKey, provider) {
-  return new ethers.Wallet(privateKey, provider);
-}
-function createErc20Contract(address, abi, runner) {
-  return new ethers.Contract(address, abi, runner);
-}
-
-// src/client.ts
 var DEFAULT_BASE_URL = "http://localhost:3001";
-var CHAIN_EXPLORER_TX = {
-  100: "https://gnosisscan.io/tx",
-  8453: "https://basescan.org/tx"
-};
-var CHAIN_USDC = {
-  8453: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-  84532: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+var DEFAULT_REQUEST_TIMEOUT = 3e4;
+var HavenApiTransport = class {
+  apiKey;
+  baseUrl;
+  requestTimeout;
+  defaultHeaders;
+  requestContext = new AsyncLocalStorage();
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
+    this.defaultHeaders = { ...config.defaultHeaders ?? {} };
+  }
+  /** Run `fn` with extra headers scoped to its asynchronous Haven API work. */
+  withRequestContext(headers, fn) {
+    return this.requestContext.run({ headers: { ...headers } }, fn);
+  }
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async get(path) {
+    return this.request("GET", path);
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.requestTimeout);
+    try {
+      const contextHeaders = this.requestContext.getStore()?.headers ?? {};
+      const res = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`,
+          ...this.defaultHeaders,
+          ...contextHeaders
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        const record = data;
+        const errorText = typeof record.error === "string" ? record.error : void 0;
+        const rawDetails = record.details ?? record.detail;
+        const detailsText = typeof rawDetails === "string" ? rawDetails : rawDetails != null ? JSON.stringify(rawDetails) : void 0;
+        const message = errorText && detailsText ? `${errorText}: ${detailsText}` : errorText ?? detailsText ?? "API request failed";
+        throw new HavenApiError(message, res.status, data);
+      }
+      return data;
+    } catch (err) {
+      if (err instanceof HavenApiError) throw err;
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new HavenApiError(`Request to ${path} timed out`, 408);
+      }
+      throw new HavenApiError(
+        `Request to ${path} failed: ${err instanceof Error ? err.message : String(err)}`,
+        0
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
 };
-function buildExplorerUrl(chainId, txHash) {
-  const base = CHAIN_EXPLORER_TX[chainId ?? 8453] ?? CHAIN_EXPLORER_TX[8453];
-  return `${base}/${txHash}`;
-}
-function explorerUrlOrEmpty(chainId, txHash) {
-  return txHash ? buildExplorerUrl(chainId, txHash) : "";
+
+// src/payment-mappers.ts
+function mapPaymentResult(raw, buildExplorerUrl2) {
+  return {
+    paymentId: raw.payment_id,
+    status: raw.status,
+    token: raw.token,
+    amount: raw.amount,
+    to: raw.to,
+    txHash: raw.tx_hash,
+    errorMessage: raw.error_message,
+    explorerUrl: raw.explorer_url ?? (raw.tx_hash ? buildExplorerUrl2(raw.chain_id, raw.tx_hash) : null),
+    fee: raw.fee ? {
+      amount: raw.fee.amount,
+      token: raw.fee.token,
+      basisPoints: raw.fee.basis_points,
+      applied: raw.fee.applied
+    } : null,
+    createdAt: raw.created_at,
+    signedAt: raw.signed_at,
+    submittedAt: raw.submitted_at,
+    confirmedAt: raw.confirmed_at,
+    expiresAt: raw.expires_at
+  };
 }
-var DEFAULT_REQUEST_TIMEOUT = 3e4;
-var DEFAULT_MERCHANT_TIMEOUT = 3e5;
-var NOTIFY_TIMEOUT = 1e4;
-var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
-var DEFAULT_POLLING_INTERVAL = 3e3;
-function formatAtomicAmount(atomic, decimals) {
-  if (atomic < 0n) return "0.0";
-  const s = atomic.toString().padStart(decimals + 1, "0");
-  const intPart = s.slice(0, s.length - decimals) || "0";
-  const fracPart = s.slice(s.length - decimals).replace(/0+$/, "") || "0";
-  return `${intPart}.${fracPart}`;
+function mapPaymentStatusResult(raw) {
+  return {
+    paymentId: raw.payment_id,
+    kind: raw.kind,
+    rail: raw.rail,
+    status: raw.status,
+    phase: raw.phase,
+    nextAction: raw.next_action,
+    amount: raw.amount,
+    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,
+    message: raw.message,
+    fee: raw.fee ? {
+      amount: raw.fee.amount,
+      token: raw.fee.token,
+      basisPoints: raw.fee.basis_points,
+      applied: raw.fee.applied
+    } : null,
+    amountAtomic: raw.amount_atomic ?? raw.x402?.amount_atomic ?? null,
+    asset: raw.asset ?? raw.x402?.asset ?? null,
+    network: raw.network ?? raw.x402?.network ?? null,
+    description: raw.description ?? raw.x402?.description ?? null,
+    idempotencyKey: raw.idempotency_key ?? raw.x402?.idempotency_key ?? null,
+    x402: raw.x402 ? {
+      amountAtomic: raw.x402.amount_atomic ?? raw.amount_atomic ?? null,
+      asset: raw.x402.asset ?? raw.asset ?? null,
+      network: raw.x402.network ?? raw.network ?? null,
+      resourceUrl: raw.x402.resource_url ?? raw.resource_url,
+      merchantAddress: raw.x402.merchant_address ?? raw.merchant_address,
+      description: raw.x402.description ?? raw.description ?? null,
+      idempotencyKey: raw.x402.idempotency_key ?? raw.idempotency_key ?? null
+    } : void 0
+  };
 }
-function safeBigInt(value) {
-  try {
-    return BigInt(value);
-  } catch {
-    return 0n;
+function mapPaymentReceipt(raw) {
+  const receipt = {
+    id: raw.id,
+    paymentId: raw.payment_id,
+    rail: raw.rail,
+    proofStatus: raw.proof_status,
+    txHash: raw.tx_hash,
+    chainId: raw.chain_id,
+    resourceUrl: raw.resource_url,
+    merchantAddress: raw.merchant_address,
+    payerAddress: raw.payer_address,
+    settlementAddress: raw.settlement_address,
+    tokenSymbol: raw.token_symbol,
+    tokenAddress: raw.token_address,
+    amountRaw: raw.amount_raw,
+    amount: raw.amount_human,
+    challengeId: raw.challenge_id,
+    idempotencyKey: raw.idempotency_key,
+    challengePayload: raw.challenge_payload,
+    selectedPayment: raw.selected_payment,
+    paymentProofHeaderName: raw.payment_proof_header_name,
+    protocolReceiptHeaderName: raw.protocol_receipt_header_name,
+    protocolReceiptPayload: raw.protocol_receipt_payload,
+    merchantStatus: raw.merchant_status,
+    confirmedAt: raw.confirmed_at,
+    createdAt: raw.created_at,
+    updatedAt: raw.updated_at
+  };
+  if ("payment_intent_id" in raw) {
+    receipt.paymentIntentId = raw.payment_intent_id ?? null;
   }
+  if ("approval_request_id" in raw) {
+    receipt.approvalRequestId = raw.approval_request_id ?? null;
+  }
+  return receipt;
 }
-function deriveReadiness(status, allowances) {
-  if (status !== "active") return "revoked";
-  const hasSpendable = allowances.some((a) => safeBigInt(a.remainingAtomic) > 0n);
-  return hasSpendable ? "ready" : "needs_approval";
-}
-var MCP_PROTOCOL_VERSION = "2025-06-18";
-var MCP_ACCEPT = "application/json, text/event-stream";
-var MCP_CLIENT_INFO = { name: "haven-sdk", version: "1" };
-var MERCHANT_BODY_SNIPPET_LIMIT = 1e3;
+
+// src/payment-state.ts
 var PAYMENT_STATE_STATUS_CODES = {
   pending: 202,
   pending_approval: 202,
@@ -1023,15 +1117,8 @@ var PAYMENT_STATE_STATUS_CODES = {
   failed: 502,
   rejected: 409
 };
-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;
-}
-function chainIdOrNull(network) {
-  return chainIdFromNetwork(network) ?? null;
+function paymentStateStatusCode(status, fallback = 502) {
+  return PAYMENT_STATE_STATUS_CODES[status] ?? fallback;
 }
 function phaseForStatus(status) {
   if (status === "pending_signature") return AgentPaymentPhase.AgentSignatureRequired;
@@ -1074,69 +1161,1484 @@ function messageForState(label, status, paymentId, nextAction) {
   }
   return `${label} is ${status}; next_action=${nextAction} (payment_id: ${paymentId}).`;
 }
-function sameAddress3(a, b) {
-  return Boolean(a && b && a.toLowerCase() === b.toLowerCase());
-}
-function decimalFromUsdcAtomic(value) {
-  const amount = BigInt(value);
-  const whole = amount / 1000000n;
-  const fraction = (amount % 1000000n).toString().padStart(6, "0").replace(/0+$/, "");
-  return fraction ? `${whole}.${fraction}` : whole.toString();
-}
-function normalizeDecimal(value) {
-  if (!value.includes(".")) return value.replace(/^0+(?=\d)/, "") || "0";
-  const [whole, fraction = ""] = value.split(".");
-  const normalizedWhole = whole.replace(/^0+(?=\d)/, "") || "0";
-  const normalizedFraction = fraction.replace(/0+$/, "");
-  return normalizedFraction ? `${normalizedWhole}.${normalizedFraction}` : normalizedWhole;
-}
-function parseMerchantSettlement(header) {
-  if (!header) return {};
-  const parsed = parseProtocolReceiptHeader(header);
-  const tx = typeof parsed?.transaction === "string" ? parsed.transaction : typeof parsed?.txHash === "string" ? parsed.txHash : typeof parsed?.tx_hash === "string" ? parsed.tx_hash : null;
-  return { settlementTxHash: tx };
+function paymentStateFromRaw(label, raw) {
+  if (!raw.payment_id || !raw.status) return null;
+  const phase = raw.phase ?? phaseForStatus(raw.status);
+  const nextAction = raw.next_action ?? nextActionForStatus(raw.status);
+  if (!phase || !nextAction) return null;
+  const amount = raw.amount ?? raw.requested ?? "";
+  const token = raw.token ?? "";
+  const message = raw.message ?? raw.error ?? messageForState(label, raw.status, raw.payment_id, nextAction);
+  return {
+    paymentId: raw.payment_id,
+    kind: raw.kind === "payment_intent" ? "payment_intent" : "approval_request",
+    rail: raw.rail ?? "direct",
+    status: raw.status === "pending" ? "pending_approval" : raw.status,
+    phase,
+    nextAction,
+    amount,
+    token,
+    resourceUrl: raw.resource_url ?? null,
+    merchantAddress: raw.merchant_address ?? raw.merchant_to ?? null,
+    txHash: raw.tx_hash ?? null,
+    expiresAt: raw.expires_at ?? "",
+    chainId: raw.chain_id ?? 0,
+    message,
+    amountAtomic: raw.amount_atomic ?? raw.x402?.amount_atomic ?? raw.mpp?.amount_atomic ?? null,
+    asset: raw.asset ?? raw.x402?.asset ?? raw.mpp?.asset ?? null,
+    network: raw.network ?? raw.x402?.network ?? raw.mpp?.network ?? null,
+    description: raw.description ?? raw.x402?.description ?? raw.mpp?.description ?? null,
+    idempotencyKey: raw.idempotency_key ?? raw.x402?.idempotency_key ?? raw.mpp?.idempotency_key ?? null,
+    x402: raw.x402 ? {
+      amountAtomic: raw.x402.amount_atomic ?? raw.amount_atomic ?? null,
+      asset: raw.x402.asset ?? raw.asset ?? null,
+      network: raw.x402.network ?? raw.network ?? null,
+      resourceUrl: raw.x402.resource_url ?? raw.resource_url ?? null,
+      merchantAddress: raw.x402.merchant_address ?? raw.merchant_address ?? raw.merchant_to ?? null,
+      description: raw.x402.description ?? raw.description ?? null,
+      idempotencyKey: raw.x402.idempotency_key ?? raw.idempotency_key ?? null
+    } : void 0,
+    mpp: raw.mpp ? {
+      amountAtomic: raw.mpp.amount_atomic ?? raw.amount_atomic ?? null,
+      asset: raw.mpp.asset ?? raw.asset ?? null,
+      network: raw.mpp.network ?? raw.network ?? null,
+      resourceUrl: raw.mpp.resource_url ?? raw.resource_url ?? null,
+      merchantAddress: raw.mpp.merchant_address ?? raw.merchant_address ?? raw.merchant_to ?? null,
+      description: raw.mpp.description ?? raw.description ?? null,
+      idempotencyKey: raw.mpp.idempotency_key ?? raw.idempotency_key ?? null,
+      challengeId: raw.mpp.challenge_id ?? raw.challenge_id ?? null
+    } : void 0
+  };
 }
-function isMcpUrl(url) {
-  try {
-    return new URL(url).pathname.replace(/\/+$/, "").endsWith("/mcp");
-  } catch {
-    return /\/mcp(?:[/?#]|$)/.test(url);
+function throwPaymentStateError(label, raw) {
+  const statusCode = paymentStateStatusCode(raw.status);
+  const state = paymentStateFromRaw(label, raw);
+  if (state) {
+    throw new HavenPaymentStateError(state.message, statusCode, state, raw);
   }
-}
-async function responseHasBazaarExtension(response) {
-  try {
-    const body = await response.clone().json();
-    return body?.extensions?.bazaar != null;
-  } catch {
-    return false;
+  if (raw.status === "pending_approval") {
+    throw new HavenApiError(
+      `${label} exceeds the on-chain allowance and was queued for owner approval (payment_id: ${raw.payment_id}).`,
+      statusCode,
+      raw
+    );
+  }
+  if (raw.status === "expired") {
+    throw new HavenApiError(
+      `${label} expired before it could be completed (payment_id: ${raw.payment_id}).`,
+      statusCode,
+      raw
+    );
   }
+  const paymentId = raw.payment_id ? ` (payment_id: ${raw.payment_id})` : "";
+  const message = raw.error ?? `${label} ${raw.status}${paymentId}`;
+  throw new HavenApiError(message, statusCode, raw);
 }
-function parseSseJsonRpcMessages(text) {
-  const messages = [];
-  let dataLines = [];
-  const flush = () => {
-    if (dataLines.length === 0) return;
+
+// src/mcp-merchant-transport.ts
+var DEFAULT_MERCHANT_TIMEOUT = 3e5;
+var MCP_NOTIFICATION_TIMEOUT = 1e4;
+var MCP_PROTOCOL_VERSION = "2025-06-18";
+var MCP_ACCEPT = "application/json, text/event-stream";
+var MCP_CLIENT_INFO = { name: "haven-sdk", version: "1" };
+var McpMerchantTransport = class {
+  merchantTimeout;
+  fetchImpl;
+  requestId = 0;
+  constructor(options = {}) {
+    this.merchantTimeout = options.merchantTimeout ?? DEFAULT_MERCHANT_TIMEOUT;
+    this.fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  }
+  /** Fetch a merchant with a settlement-sized timeout and caller cancellation. */
+  async fetch(url, init = {}, timeoutMs = this.merchantTimeout) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
     try {
-      messages.push(JSON.parse(dataLines.join("\n")));
+      return await this.fetchImpl(url, { ...init, signal });
+    } catch (err) {
+      if (timeoutSignal.aborted) {
+        throw new MerchantTimeoutError(`Merchant request timed out after ${timeoutMs}ms: ${url}`);
+      }
+      throw err;
+    }
+  }
+  /**
+   * Establish an MCP Streamable-HTTP session. Any handshake failure degrades
+   * to `undefined`, allowing the caller to fall back to plain x402.
+   */
+  async initialize(url, init, wallet) {
+    try {
+      const headers = new Headers(init?.headers);
+      headers.set("Content-Type", "application/json");
+      headers.set("Accept", MCP_ACCEPT);
+      if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
+      const response = await this.fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: ++this.requestId,
+          method: "initialize",
+          params: {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: MCP_CLIENT_INFO
+          }
+        })
+      });
+      if (!response.ok) return void 0;
+      const sessionId = response.headers.get("mcp-session-id");
+      if (!sessionId) return void 0;
+      const message = await this.readMessage(response);
+      if (message && "error" in message) return void 0;
+      await this.notifyInitialized(url, init, sessionId, wallet);
+      return sessionId;
     } catch {
+      return void 0;
     }
-    dataLines = [];
-  };
-  for (const line of text.split(/\r?\n/)) {
-    if (line === "") {
-      flush();
-      continue;
+  }
+  /** Add the MCP session and response-content negotiation headers. */
+  withSessionHeaders(init, sessionId) {
+    const headers = new Headers(init?.headers);
+    headers.set("mcp-session-id", sessionId);
+    headers.set("Accept", MCP_ACCEPT);
+    return { ...init, headers };
+  }
+  /** Read one JSON-RPC message from a JSON or SSE response without consuming it. */
+  async readMessage(response) {
+    let text;
+    try {
+      text = await response.clone().text();
+    } catch {
+      return void 0;
     }
-    if (line.startsWith("data:")) {
-      dataLines.push(line.slice(5).replace(/^ /, ""));
+    if ((response.headers.get("content-type") ?? "").includes("text/event-stream")) {
+      return selectJsonRpcResult(parseSseJsonRpcMessages(text));
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      return void 0;
     }
   }
-  flush();
-  return messages;
-}
-function selectJsonRpcResult(messages) {
-  return messages.find((m) => "result" in m || "error" in m) ?? messages[messages.length - 1];
-}
+  /**
+   * Collapse an MCP SSE response to the JSON-RPC result. Non-SSE and
+   * unparseable responses pass through with their original body untouched.
+   */
+  async surfaceResult(response) {
+    if (!(response.headers.get("content-type") ?? "").includes("text/event-stream")) {
+      return response;
+    }
+    let text;
+    try {
+      text = await response.clone().text();
+    } catch {
+      return response;
+    }
+    const message = selectJsonRpcResult(parseSseJsonRpcMessages(text));
+    if (!message) return response;
+    const body = "result" in message ? message.result : message;
+    const headers = new Headers(response.headers);
+    headers.set("content-type", "application/json");
+    headers.delete("content-length");
+    headers.delete("mcp-session-id");
+    return new Response(JSON.stringify(body), {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+  }
+  /** Detect MCP transport from the URL or Coinbase Bazaar extension. */
+  async detect(url, paymentRequired, response) {
+    if (isMcpUrl(url)) return { handshakeRequired: true, source: "path" };
+    if (paymentRequired.extensions?.bazaar != null) {
+      return { handshakeRequired: true, source: "bazaar" };
+    }
+    if (await responseHasBazaarExtension(response)) {
+      return { handshakeRequired: true, source: "bazaar" };
+    }
+    return void 0;
+  }
+  /** Identify the conventional Streamable-HTTP MCP path without probing it. */
+  isMcpUrl(url) {
+    return isMcpUrl(url);
+  }
+  /** Detect Bazaar metadata without consuming the merchant response. */
+  hasBazaarExtension(response) {
+    return responseHasBazaarExtension(response);
+  }
+  /** Deliver an already-signed x402 header without changing the caller body. */
+  async deliverPayment(url, init, paymentHeader) {
+    const headers = new Headers(init?.headers);
+    headers.set("X-PAYMENT", paymentHeader);
+    return this.fetch(url, { ...init, headers });
+  }
+  async notifyInitialized(url, init, sessionId, wallet) {
+    try {
+      const headers = new Headers(init?.headers);
+      headers.set("Content-Type", "application/json");
+      headers.set("Accept", MCP_ACCEPT);
+      headers.set("mcp-session-id", sessionId);
+      if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
+      await this.fetch(
+        url,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })
+        },
+        MCP_NOTIFICATION_TIMEOUT
+      );
+    } catch {
+    }
+  }
+};
+async function captureMerchantResponse(response) {
+  const merchant_body = await response.text().catch(() => "");
+  return {
+    merchant_status: response.status,
+    merchant_status_text: response.statusText,
+    merchant_headers: Object.fromEntries(response.headers.entries()),
+    merchant_body
+  };
+}
+function isMcpUrl(url) {
+  try {
+    return new URL(url).pathname.replace(/\/+$/, "").endsWith("/mcp");
+  } catch {
+    return /\/mcp(?:[/?#]|$)/.test(url);
+  }
+}
+async function responseHasBazaarExtension(response) {
+  try {
+    const body = await response.clone().json();
+    return body?.extensions?.bazaar != null;
+  } catch {
+    return false;
+  }
+}
+function parseSseJsonRpcMessages(text) {
+  const messages = [];
+  let dataLines = [];
+  const flush = () => {
+    if (dataLines.length === 0) return;
+    try {
+      messages.push(JSON.parse(dataLines.join("\n")));
+    } catch {
+    }
+    dataLines = [];
+  };
+  for (const line of text.split(/\r?\n/)) {
+    if (line === "") {
+      flush();
+      continue;
+    }
+    if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+  }
+  flush();
+  return messages;
+}
+function selectJsonRpcResult(messages) {
+  return messages.find((message) => "result" in message || "error" in message) ?? messages.at(-1);
+}
+var RECEIPT_VERSION = "haven-receipt-1";
+function defaultRecover(hash, signature) {
+  return ethers.recoverAddress(hash, signature);
+}
+function verifyPaymentReceipt(receipt, recover = defaultRecover) {
+  const { delegate, signHash: signHash2, signature } = receipt.authorization;
+  if (!signature) return { verified: false, reason: "missing_signature" };
+  let recovered;
+  try {
+    recovered = recover(signHash2, signature);
+  } catch {
+    return { verified: false, reason: "bad_signature" };
+  }
+  if (recovered.toLowerCase() !== delegate.toLowerCase()) {
+    return { verified: false, reason: "signer_mismatch", recoveredSigner: recovered };
+  }
+  return { verified: true, recoveredSigner: recovered };
+}
+
+// src/account-reads.ts
+function safeBigInt(value) {
+  try {
+    return BigInt(value);
+  } catch {
+    return 0n;
+  }
+}
+function formatAtomicAmount(atomic, decimals) {
+  if (atomic < 0n) return "0.0";
+  const value = atomic.toString().padStart(decimals + 1, "0");
+  const whole = value.slice(0, value.length - decimals) || "0";
+  const fraction = value.slice(value.length - decimals).replace(/0+$/, "") || "0";
+  return `${whole}.${fraction}`;
+}
+function deriveReadiness(status, allowances) {
+  if (status !== "active") return "revoked";
+  return allowances.some((allowance) => safeBigInt(allowance.remainingAtomic) > 0n) ? "ready" : "needs_approval";
+}
+var AccountReads = class {
+  transport;
+  getPaymentStatus;
+  agentInFlight = null;
+  constructor(options) {
+    this.transport = options.transport;
+    this.getPaymentStatus = options.getPaymentStatus;
+  }
+  async getAgent() {
+    if (this.agentInFlight) return this.agentInFlight;
+    const request = this.fetchAgent();
+    this.agentInFlight = request;
+    request.finally(() => {
+      this.agentInFlight = null;
+    }).catch(() => {
+    });
+    return request;
+  }
+  async getAgentSummary() {
+    const [agent, allowanceSummary] = await Promise.all([this.getAgent(), this.getAllowances()]);
+    const allowances = allowanceSummary.allowances.map((allowance) => {
+      const token = resolveTokenFromAddress(allowance.tokenAddress);
+      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(allowance.onchain.remaining), token.decimals)} ${allowance.tokenSymbol}` : `${allowance.onchain.remaining} ${allowance.tokenSymbol} (atomic; unknown decimals)`;
+      return {
+        tokenSymbol: allowance.tokenSymbol,
+        remainingAtomic: allowance.onchain.remaining,
+        remainingDisplay,
+        configuredAmount: allowance.configuredAmount,
+        resetPeriodMin: allowance.resetPeriodMin,
+        isResetPending: allowance.onchain.isResetPending
+      };
+    });
+    const readiness = deriveReadiness(agent.status, allowances);
+    return { ...agent, readiness, spend_authority_readiness: readiness, allowances };
+  }
+  async getAllowances() {
+    const raw = await this.transport.get("/machine-payments/allowances");
+    return {
+      agentId: raw.agent_id,
+      safeAddress: raw.safe_address,
+      delegateAddress: raw.delegate_address,
+      chainId: raw.chain_id,
+      allowances: raw.allowances.map((allowance) => ({
+        id: allowance.id,
+        tokenAddress: allowance.token_address,
+        tokenSymbol: allowance.token_symbol,
+        configuredAmount: allowance.configured_amount,
+        resetPeriodMin: allowance.reset_period_min,
+        onchain: {
+          amount: allowance.onchain.amount,
+          spent: allowance.onchain.spent,
+          remaining: allowance.onchain.remaining,
+          effectiveSpent: allowance.onchain.effective_spent,
+          resetTimeMin: allowance.onchain.reset_time_min,
+          lastResetMin: allowance.onchain.last_reset_min,
+          nonce: allowance.onchain.nonce,
+          isResetPending: allowance.onchain.is_reset_pending,
+          remainingIsFromChain: allowance.onchain.remaining_is_from_chain
+        }
+      }))
+    };
+  }
+  async getPostPurchaseAllowanceSummary(paymentId) {
+    const unavailable = (detail, payment2 = null) => ({
+      payment: payment2,
+      allowance: null,
+      warnings: [{
+        code: AgentPaymentWarningCode.AllowanceCheckUnavailable,
+        message: `Could not read the post-purchase allowance/budget for payment ${paymentId} (${detail}). The payment itself succeeded \u2014 the on-chain policy remains the actual spend gate; this only affects the remaining-budget figure reported here.`
+      }]
+    });
+    const [statusResult, agentResult, allowanceResult] = await Promise.allSettled([
+      this.getPaymentStatus(paymentId),
+      this.getAgent(),
+      this.getAllowances()
+    ]);
+    if (statusResult.status === "rejected") {
+      return unavailable(statusResult.reason instanceof Error ? statusResult.reason.message : String(statusResult.reason));
+    }
+    const payment = statusResult.value;
+    if (agentResult.status === "rejected") {
+      return unavailable(agentResult.reason instanceof Error ? agentResult.reason.message : String(agentResult.reason), payment);
+    }
+    if (allowanceResult.status === "rejected") {
+      return unavailable(allowanceResult.reason instanceof Error ? allowanceResult.reason.message : String(allowanceResult.reason), payment);
+    }
+    try {
+      const tokenAddress = payment.asset ?? payment.x402?.asset ?? null;
+      if (!tokenAddress) return unavailable("the settled payment does not carry a resolvable token address", payment);
+      const match = allowanceResult.value.allowances.find(
+        (allowance) => allowance.tokenAddress.toLowerCase() === tokenAddress.toLowerCase()
+      );
+      if (!match) return unavailable("no allowance/budget row matches the settled token", payment);
+      const token = resolveTokenFromAddress(match.tokenAddress);
+      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(match.onchain.remaining), token.decimals)} ${match.tokenSymbol}` : void 0;
+      const rail = agentResult.value.executionRail;
+      return {
+        payment,
+        allowance: {
+          rail,
+          remaining_atomic: match.onchain.remaining,
+          ...remainingDisplay ? { remaining_display: remainingDisplay } : {},
+          token_symbol: match.tokenSymbol,
+          token_address: match.tokenAddress,
+          reset_period: match.resetPeriodMin,
+          source: rail === "delegation" ? "active_delegations" : "allowance_module"
+        },
+        warnings: []
+      };
+    } catch (error) {
+      return unavailable(error instanceof Error ? error.message : String(error));
+    }
+  }
+  async listReceipts(options = {}) {
+    const query = options.limit ? `?limit=${encodeURIComponent(String(options.limit))}` : "";
+    const raw = await this.transport.get(`/machine-payments/receipts${query}`);
+    return raw.receipts.map(mapPaymentReceipt);
+  }
+  async getReceipt(paymentId) {
+    const { receipt } = await this.transport.get(`/payments/${paymentId}/receipt`);
+    return { receipt, verification: verifyPaymentReceipt(receipt) };
+  }
+  async fetchAgent() {
+    const raw = await this.transport.get("/machine-payments/agent");
+    return {
+      id: raw.id,
+      name: raw.name,
+      status: raw.status,
+      safeAddress: raw.safe_address,
+      delegateAddress: raw.delegate_address,
+      chainId: raw.chain_id,
+      executionRail: raw.execution_rail === "delegation" ? "delegation" : "legacy"
+    };
+  }
+};
+function createJsonRpcProvider(url) {
+  return new ethers.JsonRpcProvider(url);
+}
+function createWallet(privateKey, provider) {
+  return new ethers.Wallet(privateKey, provider);
+}
+function createErc20Contract(address, abi, runner) {
+  return new ethers.Contract(address, abi, runner);
+}
+
+// src/delegate-sweep.ts
+var DelegateSweepApi = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async sweepDelegate() {
+    if (!this.options.delegateKey) throw new HavenSigningError("delegateKey is required for sweepDelegate.");
+    const agent = await this.options.getAgent();
+    if (!agent.delegateAddress) throw new HavenApiError("Agent has no delegate address.", 422);
+    const rpcUrl = this.options.chainRpcs[agent.chainId];
+    if (!rpcUrl) throw new HavenApiError(`chainRpcs[${agent.chainId}] must be configured to sweep the delegate wallet.`, 422);
+    const provider = createJsonRpcProvider(rpcUrl);
+    const wallet = createWallet(this.options.delegateKey, provider);
+    const transfers = [];
+    if (isSweepableChain(agent.chainId)) {
+      const contract = createErc20Contract(sweepUsdcAddress(agent.chainId), ["function balanceOf(address) view returns (uint256)", "function transfer(address to, uint256 amount) returns (bool)"], wallet);
+      const balance2 = await contract.balanceOf(agent.delegateAddress);
+      if (balance2 > 0n) {
+        const tx = await contract.transfer(agent.safeAddress, balance2);
+        const receipt = await tx.wait(1);
+        const txHash = receipt?.hash ?? tx.hash;
+        transfers.push({ asset: "USDC", amount: format(balance2, 6), amountAtomic: balance2.toString(), txHash, explorerUrl: this.options.buildExplorerUrl(agent.chainId, txHash) });
+      }
+    }
+    const balance = await provider.getBalance(agent.delegateAddress);
+    if (balance > 0n) {
+      const fee = await provider.getFeeData();
+      const send = balance - (fee.maxFeePerGas ?? fee.gasPrice ?? 1000000n) * 21000n * 2n;
+      if (send > 0n) {
+        const tx = await wallet.sendTransaction({ to: agent.safeAddress, value: send });
+        const receipt = await tx.wait(1);
+        const txHash = receipt?.hash ?? tx.hash;
+        transfers.push({ asset: "ETH", amount: format(send, 18), amountAtomic: send.toString(), txHash, explorerUrl: this.options.buildExplorerUrl(agent.chainId, txHash) });
+      }
+    }
+    return { fromAddress: agent.delegateAddress, toAddress: agent.safeAddress, chainId: agent.chainId, transfers };
+  }
+  prepareSweep() {
+    return this.options.transport.post("/machine-payments/sweep/prepare", {});
+  }
+  submitSweep(authorization, signature) {
+    return this.options.transport.post("/machine-payments/sweep/submit", { authorization, signature });
+  }
+};
+function format(value, decimals) {
+  const raw = value.toString().padStart(decimals + 1, "0");
+  return `${raw.slice(0, -decimals) || "0"}.${raw.slice(-decimals).replace(/0+$/, "") || "0"}`;
+}
+
+// src/x402-protocol.ts
+var CHAIN_EXPLORER_TX = {
+  100: "https://gnosisscan.io/tx",
+  8453: "https://basescan.org/tx"
+};
+function buildExplorerUrl(chainId, txHash) {
+  const base = CHAIN_EXPLORER_TX[chainId ?? 8453] ?? CHAIN_EXPLORER_TX[8453];
+  return `${base}/${txHash}`;
+}
+function explorerUrlOrEmpty(chainId, txHash) {
+  return txHash ? buildExplorerUrl(chainId, txHash) : "";
+}
+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;
+}
+function chainIdOrNull(network) {
+  return chainIdFromNetwork(network) ?? null;
+}
+function sameAddress3(a, b) {
+  return Boolean(a && b && a.toLowerCase() === b.toLowerCase());
+}
+function decimalFromUsdcAtomic(value) {
+  const amount = BigInt(value);
+  const whole = amount / 1000000n;
+  const fraction = (amount % 1000000n).toString().padStart(6, "0").replace(/0+$/, "");
+  return fraction ? `${whole}.${fraction}` : whole.toString();
+}
+function normalizeDecimal(value) {
+  if (!value.includes(".")) return value.replace(/^0+(?=\d)/, "") || "0";
+  const [whole, fraction = ""] = value.split(".");
+  const normalizedWhole = whole.replace(/^0+(?=\d)/, "") || "0";
+  const normalizedFraction = fraction.replace(/0+$/, "");
+  return normalizedFraction ? `${normalizedWhole}.${normalizedFraction}` : normalizedWhole;
+}
+function x402PayerAddress(delegateAddress, x402Wallet) {
+  return delegateAddress ?? x402Wallet;
+}
+function withX402Wallet(init, wallet) {
+  if (!wallet) return init;
+  const headers = new Headers(init?.headers);
+  if (!headers.has("x402-wallet")) {
+    headers.set("x402-wallet", wallet);
+  }
+  return {
+    ...init,
+    headers
+  };
+}
+function snapshotRequestBody(body) {
+  if (body == null) return void 0;
+  if (typeof body === "string") return body;
+  if (body instanceof URLSearchParams) return body.toString();
+  throw new HavenApiError(
+    "Quote helpers can only capture resumable request bodies that are strings or URLSearchParams. For streams, blobs, or binary bodies, preserve the original request yourself and call the matching resume method with fresh init.",
+    400
+  );
+}
+function snapshotX402Request(url, init) {
+  return {
+    url,
+    method: init?.method ?? "GET",
+    headers: Array.from(new Headers(init?.headers).entries()),
+    body: snapshotRequestBody(init?.body)
+  };
+}
+function requestInitFromSnapshot(request) {
+  return {
+    method: request.method,
+    headers: request.headers,
+    body: request.body
+  };
+}
+function buildX402Quote(paymentRequired, request, idempotencyKey, mcpTransport) {
+  const option = selectStandardPaymentOption(paymentRequired.accepts);
+  if (!option) {
+    throw new HavenApiError(
+      "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
+      400
+    );
+  }
+  const token = resolveTokenFromAddress(option.asset, option.network);
+  return {
+    rail: "x402",
+    idempotencyKey: idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option),
+    paymentRequired,
+    accepted: option,
+    request,
+    ...mcpTransport ? { mcpTransport } : {},
+    resourceUrl: paymentRequired.resource.url,
+    description: paymentRequired.resource.description ?? option.description ?? null,
+    mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
+    amountAtomic: x402AuthorizationAmount(option),
+    amount: decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
+    token: token?.symbol ?? "USDC",
+    // #1351: null when the asset is unrecognised on this network — the
+    // `token` fallback above is a LABEL, not evidence of 6 decimals, and a
+    // human-denominated cap must fail closed rather than convert against a
+    // guess. Same resolution as `token`, so the two never disagree.
+    decimals: token?.decimals ?? null,
+    asset: option.asset,
+    network: option.network,
+    chainId: chainIdOrNull(option.network),
+    merchantAddress: option.payTo,
+    maxTimeoutSeconds: option.maxTimeoutSeconds
+  };
+}
+function buildX402Receipt(input) {
+  const fundingExplorerUrl = input.explorerUrl || explorerUrlOrEmpty(input.chainId, input.txHash);
+  return {
+    success: true,
+    paymentId: input.paymentId,
+    txHash: input.txHash,
+    token: input.token,
+    amount: input.amount,
+    to: input.to,
+    resourceUrl: input.resourceUrl,
+    explorerUrl: input.explorerUrl,
+    accepted: input.accepted,
+    paymentHeader: input.paymentHeader,
+    merchantTo: input.merchantTo ?? input.accepted.payTo,
+    payer: input.payer,
+    chainId: input.chainId,
+    haven: {
+      paymentId: input.paymentId,
+      fundingTxHash: input.txHash,
+      fundingExplorerUrl
+    },
+    merchant: {
+      payTo: input.merchantTo ?? input.accepted.payTo
+    },
+    x402: {
+      amount: x402AuthorizationAmount(input.accepted),
+      token: input.token,
+      network: input.accepted.network,
+      asset: input.accepted.asset,
+      resource: input.accepted.resource ?? input.resourceUrl
+    }
+  };
+}
+function buildX402ResumeState(input) {
+  const token = resolveTokenFromAddress(input.accepted.asset, input.accepted.network);
+  return {
+    rail: "x402",
+    paymentId: input.paymentId,
+    idempotencyKey: input.idempotencyKey,
+    paymentRequired: input.paymentRequired,
+    accepted: input.accepted,
+    url: input.request?.url ?? input.paymentRequired.resource.url,
+    request: input.request,
+    resourceUrl: input.paymentRequired.resource.url,
+    description: input.paymentRequired.resource.description ?? input.accepted.description ?? null,
+    amountAtomic: x402AuthorizationAmount(input.accepted),
+    amount: decimalFromUsdcAtomic(x402AuthorizationAmount(input.accepted)),
+    token: token?.symbol ?? "USDC",
+    asset: input.accepted.asset,
+    network: input.accepted.network,
+    chainId: chainIdOrNull(input.accepted.network),
+    merchantAddress: input.accepted.payTo
+  };
+}
+function attachX402ResumeState(err, paymentRequired, accepted, idempotencyKey, request) {
+  if (!(err instanceof HavenPaymentStateError)) return;
+  if (err.state.rail !== "x402") return;
+  err.resumeState = buildX402ResumeState({
+    paymentId: err.state.paymentId,
+    paymentRequired,
+    accepted,
+    idempotencyKey,
+    request
+  });
+}
+function attachResumeState(err, input) {
+  attachX402ResumeState(
+    err,
+    input.paymentRequired,
+    input.accepted,
+    input.idempotencyKey,
+    input.request
+  );
+}
+function assertCanResumeX402(status, paymentRequired, option) {
+  if (status.rail !== "x402") {
+    throw new HavenPaymentStateError(
+      `Payment ${status.paymentId} is ${status.rail}, not x402.`,
+      409,
+      status
+    );
+  }
+  if (status.nextAction !== AgentPaymentNextAction.RetryOriginalX402Request) {
+    throw new HavenPaymentStateError(status.message, paymentStateStatusCode(status.status, 409), status);
+  }
+  if (!status.txHash) {
+    throw new HavenApiError(
+      `x402 payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
+      502,
+      status,
+      status.paymentId
+    );
+  }
+  if (status.resourceUrl && status.resourceUrl !== paymentRequired.resource.url) {
+    throw new HavenApiError(
+      "x402 resume request does not match the approved resource URL.",
+      409,
+      { status, paymentRequired },
+      status.paymentId
+    );
+  }
+  if (status.merchantAddress && !sameAddress3(status.merchantAddress, option.payTo)) {
+    throw new HavenApiError(
+      "x402 resume request does not match the approved merchant.",
+      409,
+      { status, selectedPayment: option },
+      status.paymentId
+    );
+  }
+  const optionChainId = chainIdFromNetwork(option.network);
+  if (status.chainId && optionChainId && status.chainId !== optionChainId) {
+    throw new HavenApiError(
+      "x402 resume request does not match the approved network.",
+      409,
+      { status, selectedPayment: option },
+      status.paymentId
+    );
+  }
+  if (status.token && status.token !== "USDC") {
+    throw new HavenApiError(
+      "x402 resume request does not match the approved token.",
+      409,
+      { status, selectedPayment: option },
+      status.paymentId
+    );
+  }
+  const approvedAmount = status.amount ? normalizeDecimal(status.amount) : "";
+  const requestedAmount = normalizeDecimal(decimalFromUsdcAtomic(x402AuthorizationAmount(option)));
+  if (approvedAmount && approvedAmount !== requestedAmount) {
+    throw new HavenApiError(
+      "x402 resume request does not match the approved amount.",
+      409,
+      { status, selectedPayment: option },
+      status.paymentId
+    );
+  }
+}
+var X402FundingLeg = class {
+  delegateKey;
+  delegateAddress;
+  x402Wallet;
+  chainRpcs;
+  post;
+  signForData;
+  assertSignableAuthorizationState;
+  /**
+   * Receipts keyed by idempotency key, held only as long as the underlying
+   * EIP-3009 authorization is valid. The cache belongs to this module rather
+   * than to the facade because its expiry is read out of the authorization
+   * header itself — a 3009 artifact.
+   */
+  receiptCache = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.delegateKey = options.delegateKey;
+    this.delegateAddress = options.delegateAddress;
+    this.x402Wallet = options.x402Wallet;
+    this.chainRpcs = options.chainRpcs;
+    this.post = options.post;
+    this.signForData = options.signForData;
+    this.assertSignableAuthorizationState = options.assertSignableAuthorizationState;
+  }
+  // ── Receipt cache ────────────────────────────────────────────────
+  /** A still-valid cached receipt for this key, or undefined. */
+  cachedReceipt(idempotencyKey) {
+    const cached = this.receiptCache.get(idempotencyKey);
+    if (cached && cached.expiresAt > Date.now()) return cached.receipt;
+    return void 0;
+  }
+  cacheReceipt(idempotencyKey, paymentHeader, receipt) {
+    const expiresAt = getPaymentHeaderValidBefore(paymentHeader);
+    if (expiresAt > Date.now()) {
+      this.receiptCache.set(idempotencyKey, { expiresAt, receipt });
+    }
+  }
+  // ── Authorization ────────────────────────────────────────────────
+  async authorize(paymentRequired, option, idempotencyKey) {
+    const raw = await this.post("/x402", {
+      url: paymentRequired.resource.url,
+      payTo: this.delegateAddress,
+      merchantPayTo: option.payTo,
+      amount: x402AuthorizationAmount(option),
+      asset: option.asset,
+      network: option.network,
+      description: paymentRequired.resource.description,
+      idempotencyKey,
+      // #1360: same explicit funding-leg declaration as createX402Intent —
+      // this local-key path derives payTo from the key (never stale), but the
+      // declaration keeps both writers of the 3009 shape loud-by-default.
+      settlementScheme: "eip3009"
+    });
+    const state = paymentStateFromRaw("x402 payment", raw);
+    const executedReplay = raw.success && raw.tx_hash ? "idempotency-collision" : state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request ? "approval-resume" : null;
+    if (executedReplay) {
+      const canFund = await this.delegateCanFund(
+        raw.chain_id ?? state?.chainId ?? chainIdFromNetwork(option.network),
+        option.asset,
+        x402AuthorizationAmount(option)
+      );
+      const refuse = executedReplay === "idempotency-collision" ? canFund !== true : canFund === false;
+      if (refuse) {
+        const settledReceipt = state && executedReplay === "approval-resume" ? this.receiptFromStatus(paymentRequired, option, void 0, state) : this.receiptFromAuthorization(paymentRequired, option, void 0, raw);
+        throw new X402AlreadySettledError(
+          canFund === false ? "This x402 payment already settled \u2014 the delegate no longer holds the funds to authorize it again. To buy the same item a second time, pass a distinct `idempotencyKey`; the synthesised key intentionally collapses repeat calls for the same product within a 5-minute window so a retried request cannot pay twice." : "This x402 payment already settled, and whether the delegate can still fund a new authorization could not be verified (no `chainRpcs` entry for this chain). Refusing rather than issue an authorization that may be unfundable. To buy the same item a second time, pass a distinct `idempotencyKey`; to finish an interrupted payment, resume it by `paymentId`.",
+          settledReceipt,
+          canFund === false ? "settled" : "unverifiable"
+        );
+      }
+    }
+    const paymentHeader = await this.createPaymentHeader(paymentRequired, option);
+    if (raw.success && raw.tx_hash) {
+      const receipt2 = this.receiptFromAuthorization(paymentRequired, option, paymentHeader, raw);
+      this.cacheReceipt(idempotencyKey, paymentHeader, receipt2);
+      return receipt2;
+    }
+    if (state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request) {
+      const receipt2 = this.receiptFromStatus(paymentRequired, option, paymentHeader, state);
+      this.cacheReceipt(idempotencyKey, paymentHeader, receipt2);
+      return receipt2;
+    }
+    this.assertSignableAuthorizationState("x402 payment", raw);
+    if (!raw.sign_data?.hash) {
+      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
+    }
+    const sig = await this.signForData(raw.sign_data);
+    const execResult = await this.post(
+      `/payments/${raw.payment_id}/sign`,
+      { signature: sig }
+    );
+    if (execResult.status !== "confirmed") {
+      throwPaymentStateError("x402 payment", execResult);
+    }
+    await this.waitForFundingTx(
+      execResult.tx_hash,
+      execResult.chain_id ?? chainIdFromNetwork(option.network)
+    );
+    const receipt = this.receiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult);
+    this.cacheReceipt(idempotencyKey, paymentHeader, receipt);
+    return receipt;
+  }
+  // ── Header minting ───────────────────────────────────────────────
+  async createPaymentHeader(paymentRequired, option) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError("delegateKey is required to sign x402 payment headers.");
+    }
+    const account = privateKeyToAccount(this.delegateKey);
+    const requirements = toStandardPaymentRequirements(paymentRequired, option);
+    const header = await exact.evm.createPaymentHeader(
+      account,
+      paymentRequired.x402Version,
+      requirements
+    );
+    if (paymentRequired.x402Version < 2) return header;
+    const payment = decodeBase64Json(header);
+    return encodeBase64Json({
+      x402Version: paymentRequired.x402Version,
+      accepted: option,
+      payload: payment.payload
+    });
+  }
+  // ── Receipt mapping ──────────────────────────────────────────────
+  receiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult) {
+    const txHash = execResult?.tx_hash ?? raw.tx_hash ?? "";
+    const chainId = execResult?.chain_id ?? raw.chain_id ?? chainIdFromNetwork(option.network);
+    const token = execResult?.token ?? raw.token ?? "USDC";
+    const amount = execResult?.amount ?? raw.amount ?? decimalFromUsdcAtomic(x402AuthorizationAmount(option));
+    const to = execResult?.to ?? raw.to ?? this.delegateAddress ?? "";
+    const explorerUrl = execResult?.explorer_url ?? raw.explorer_url ?? explorerUrlOrEmpty(chainId, txHash);
+    const merchantTo = execResult?.merchant_to ?? raw.merchant_to ?? option.payTo;
+    const payer = raw.payer ?? raw.safe_address ?? raw.sign_data?.components.safe;
+    return buildX402Receipt({
+      paymentId: raw.payment_id,
+      txHash,
+      token,
+      amount,
+      to,
+      resourceUrl: paymentRequired.resource.url,
+      explorerUrl,
+      accepted: option,
+      paymentHeader,
+      merchantTo,
+      payer,
+      chainId
+    });
+  }
+  receiptFromStatus(paymentRequired, option, paymentHeader, status) {
+    if (!status.txHash) {
+      throw new HavenApiError(
+        `x402 payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    return buildX402Receipt({
+      paymentId: status.paymentId,
+      txHash: status.txHash,
+      token: status.token || "USDC",
+      amount: status.amount || decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
+      to: this.delegateAddress ?? "",
+      resourceUrl: paymentRequired.resource.url,
+      explorerUrl: explorerUrlOrEmpty(status.chainId, status.txHash),
+      accepted: option,
+      paymentHeader,
+      merchantTo: status.merchantAddress ?? option.payTo,
+      payer: this.x402Wallet,
+      chainId: status.chainId || chainIdFromNetwork(option.network)
+    });
+  }
+  // ── On-chain reads ───────────────────────────────────────────────
+  /**
+   * Wait for a funding tx to be mined with ≥1 confirmation before the
+   * merchant retry, eliminating the race where the merchant's
+   * `balanceOf(delegate)` runs before the funding block propagates.
+   *
+   * Skipped when `chainRpcs` does not include the chain; in that case Haven's
+   * backend has already confirmed on-chain submission and callers accept the
+   * small propagation window as a trade-off for not configuring an RPC URL.
+   */
+  async waitForFundingTx(txHash, chainId, timeoutMs = 3e4) {
+    if (!txHash || !chainId) return;
+    const rpcUrl = this.chainRpcs[chainId];
+    if (!rpcUrl) return;
+    const provider = createJsonRpcProvider(rpcUrl);
+    const onChainReceipt = await provider.waitForTransaction(txHash, 1, timeoutMs);
+    if (!onChainReceipt || onChainReceipt.status !== 1) {
+      throw new HavenApiError(
+        "Funding tx did not confirm on-chain within the timeout window.",
+        500,
+        { txHash, chainId }
+      );
+    }
+  }
+  /**
+   * Can the delegate EOA still fund an authorization for `amountAtomic`?
+   *
+   * #1521: the only question that separates a legitimate resume (funding
+   * confirmed, merchant never paid — the delegate still holds the money) from
+   * a replayed settled payment (funding confirmed, merchant paid, delegate
+   * spent). The intent's own `status: 'confirmed'` is identical in both.
+   *
+   * The balance is asked of the CHAIN rather than of Haven's bookkeeping on
+   * purpose: the merchant-settlement evidence record is written by this SDK
+   * *after* the merchant call, so a client that dies between the two leaves
+   * the backend believing the merchant was never paid — the exact case the
+   * discriminator has to get right. The chain cannot be behind in that way.
+   *
+   * Returns `null` — never a guess — when `chainRpcs` has no entry for the
+   * chain or the read fails. Callers must treat that as "unverifiable", not
+   * as "funded".
+   */
+  async delegateCanFund(chainId, tokenAddress, amountAtomic, timeoutMs = 1e4) {
+    if (!chainId || !this.delegateAddress) return null;
+    const rpcUrl = this.chainRpcs[chainId];
+    if (!rpcUrl) return null;
+    try {
+      const provider = createJsonRpcProvider(rpcUrl);
+      const token = createErc20Contract(
+        tokenAddress,
+        ["function balanceOf(address) view returns (uint256)"],
+        provider
+      );
+      const balance = await Promise.race([
+        token.balanceOf(this.delegateAddress),
+        new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs).unref?.())
+      ]);
+      if (balance === null) return null;
+      return balance >= BigInt(amountAtomic);
+    } catch {
+      return null;
+    }
+  }
+};
+function getPaymentHeaderValidBefore(paymentHeader) {
+  try {
+    const payment = decodeBase64Json(
+      paymentHeader
+    );
+    const payload = payment.payload;
+    const validBeforeSeconds = Number(payload.authorization?.validBefore);
+    if (Number.isFinite(validBeforeSeconds)) return validBeforeSeconds * 1e3;
+  } catch {
+  }
+  return 0;
+}
+
+// src/x402-erc7710.ts
+var X402Erc7710 = class {
+  delegateKey;
+  post;
+  signForData;
+  getAgent;
+  constructor(options) {
+    this.delegateKey = options.delegateKey;
+    this.post = options.post;
+    this.signForData = options.signForData;
+    this.getAgent = options.getAgent;
+  }
+  /**
+   * 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 settle(paymentRequired, options = {}) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "delegateKey is required for x402 payments. Pass it in the HavenClient config."
+      );
+    }
+    const prepared = await this.prepare(paymentRequired, options);
+    const signature = await this.signForData(prepared.signData);
+    const paymentHeader = await this.submit(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 prepare(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 } : {},
+      // #1307/#1547: persisted so the settle leg can rehydrate the merchant
+      // call by payment_id on this scheme too, not only on the 3009 bridge.
+      ...options.mcpCallContext ? { mcpCallContext: options.mcpCallContext } : {}
+    });
+    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 submit(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;
+  }
+};
+
+// src/tool-adapter.ts
+function toolX402PaymentRequired(input) {
+  return {
+    x402Version: 2,
+    resource: { url: input.url, description: input.description },
+    accepts: [
+      {
+        scheme: "exact",
+        network: input.network,
+        amount: input.amount,
+        asset: input.asset,
+        payTo: input.payTo,
+        maxTimeoutSeconds: 30
+      }
+    ]
+  };
+}
+function x402ToolReceipt(receipt) {
+  return {
+    success: true,
+    payment_id: receipt.paymentId,
+    tx_hash: receipt.txHash,
+    token: receipt.token,
+    amount: receipt.amount,
+    to: receipt.to,
+    resource_url: receipt.resourceUrl,
+    explorer_url: receipt.explorerUrl,
+    payment_header: receipt.paymentHeader,
+    merchant_to: receipt.merchantTo,
+    payer: receipt.payer,
+    chain_id: receipt.chainId,
+    haven: receipt.haven,
+    merchant: receipt.merchant,
+    x402: receipt.x402
+  };
+}
+function toolError(err) {
+  if (err instanceof HavenPaymentStateError) {
+    return {
+      success: false,
+      payment_id: err.state.paymentId,
+      kind: err.state.kind,
+      rail: err.state.rail,
+      status: err.state.status,
+      phase: err.state.phase,
+      next_action: err.state.nextAction,
+      tx_hash: err.state.txHash,
+      token: err.state.token,
+      amount: err.state.amount,
+      resource_url: err.state.resourceUrl,
+      merchant_address: err.state.merchantAddress,
+      amount_atomic: err.state.amountAtomic,
+      asset: err.state.asset,
+      network: err.state.network,
+      description: err.state.description,
+      idempotency_key: err.state.idempotencyKey,
+      x402: err.state.x402 ? {
+        amount_atomic: err.state.x402.amountAtomic,
+        asset: err.state.x402.asset,
+        network: err.state.x402.network,
+        resource_url: err.state.x402.resourceUrl,
+        merchant_address: err.state.x402.merchantAddress,
+        description: err.state.x402.description,
+        idempotency_key: err.state.x402.idempotencyKey
+      } : void 0,
+      mpp: err.state.mpp ? {
+        amount_atomic: err.state.mpp.amountAtomic,
+        asset: err.state.mpp.asset,
+        network: err.state.mpp.network,
+        resource_url: err.state.mpp.resourceUrl,
+        merchant_address: err.state.mpp.merchantAddress,
+        description: err.state.mpp.description,
+        idempotency_key: err.state.mpp.idempotencyKey,
+        challenge_id: err.state.mpp.challengeId
+      } : void 0,
+      resume_state: err.resumeState,
+      expires_at: err.state.expiresAt,
+      chain_id: err.state.chainId,
+      message: err.state.message,
+      error: err.message
+    };
+  }
+  if (err instanceof HavenApiError) {
+    return {
+      success: false,
+      status_code: err.statusCode,
+      error: err.message,
+      body: err.body
+    };
+  }
+  return {
+    success: false,
+    error: err instanceof Error ? err.message : String(err)
+  };
+}
+
+// src/merchant-completion.ts
+var MERCHANT_BODY_SNIPPET_LIMIT = 1e3;
+var MerchantCompletion = class {
+  post;
+  merchantTransport;
+  getPaymentStatus;
+  getAgent;
+  delegateAddress;
+  x402Wallet;
+  constructor(options) {
+    this.post = options.post;
+    this.merchantTransport = options.merchantTransport;
+    this.getPaymentStatus = options.getPaymentStatus;
+    this.getAgent = options.getAgent;
+    this.delegateAddress = options.delegateAddress;
+    this.x402Wallet = options.x402Wallet;
+  }
+  async retryRequest(url, initialInit, paymentRequired, receipt) {
+    if (!receipt.accepted) {
+      throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
+    }
+    if (!receipt.paymentHeader) {
+      throw new HavenApiError("No x402 payment header was returned for payment retry", 500);
+    }
+    const retryResponse = await this.merchantTransport.deliverPayment(
+      url,
+      initialInit,
+      receipt.paymentHeader
+    );
+    if (!retryResponse.ok) {
+      const merchant = await captureMerchantResponse(retryResponse);
+      await this.recordRetryRejected({
+        rail: "x402",
+        paymentId: receipt.paymentId,
+        txHash: receipt.txHash,
+        resourceUrl: receipt.resourceUrl,
+        merchant,
+        details: {
+          merchant_to: receipt.merchantTo,
+          delegate_to: receipt.to
+        }
+      });
+      throw new HavenApiError(
+        "x402 retry failed after Haven funded the delegate wallet; reconciliation may be required.",
+        merchant.merchant_status,
+        {
+          marker: "x402_retry_rejected_after_funding",
+          payment_id: receipt.paymentId,
+          tx_hash: receipt.txHash,
+          resource_url: receipt.resourceUrl,
+          merchant_to: receipt.merchantTo,
+          delegate_to: receipt.to,
+          ...merchant
+        }
+      );
+    }
+    const merchantSettlement = parseMerchantSettlement(retryResponse.headers.get("PAYMENT-RESPONSE"));
+    if (receipt.merchant && merchantSettlement.settlementTxHash) {
+      receipt.merchant.settlementTxHash = merchantSettlement.settlementTxHash;
+      receipt.merchant.settlementExplorerUrl = buildExplorerUrl(
+        receipt.chainId,
+        merchantSettlement.settlementTxHash
+      );
+    }
+    await this.reportEvidence({
+      paymentId: receipt.paymentId,
+      rail: "x402",
+      txHash: receipt.txHash,
+      resourceUrl: receipt.resourceUrl,
+      merchantStatus: retryResponse.status,
+      challengePayload: paymentRequired,
+      selectedPayment: receipt.accepted,
+      paymentProofHeaderName: "X-PAYMENT",
+      paymentProofHeader: receipt.paymentHeader,
+      protocolReceiptHeaderName: "PAYMENT-RESPONSE",
+      protocolReceiptHeader: retryResponse.headers.get("PAYMENT-RESPONSE") ?? void 0
+    });
+    await this.reportMerchantReceipt(receipt.paymentId, retryResponse);
+    return retryResponse;
+  }
+  /**
+   * #956: capture the merchant's OWN receipt when the paid response carries
+   * one, and report it to Haven so the reporting feed can attach it next to
+   * the Haven-generated payment evidence (#498). Two supported signals on the
+   * paid response:
+   *
+   *   x-receipt-json: base64-encoded JSON receipt document (inline)
+   *   x-receipt-url:  https URL to the receipt document (reference)
+   *
+   * Strictly best-effort: absence is the normal case, and no failure here may
+   * ever affect the completed payment — the response is already paid for.
+   */
+  async reportMerchantReceipt(paymentId, response) {
+    try {
+      const inlineB64 = response.headers.get("x-receipt-json");
+      const url = response.headers.get("x-receipt-url");
+      if (!inlineB64 && !url) return;
+      let body = null;
+      if (inlineB64) {
+        if (inlineB64.length > Math.ceil(64 * 1024 * 4 / 3)) return;
+        const decoded = JSON.parse(Buffer.from(inlineB64, "base64").toString("utf8"));
+        if (decoded && typeof decoded === "object") body = { json: decoded };
+      } else if (url && url.startsWith("https://") && url.length <= 2048) {
+        body = { url };
+      }
+      if (!body) return;
+      await this.post(`/machine-payments/${paymentId}/merchant-receipt`, body);
+    } catch {
+    }
+  }
+  async resolveCompletionContext(input) {
+    const status = await this.getPaymentStatus(input.paymentId);
+    if (status.rail !== "x402") {
+      throw new HavenPaymentStateError(
+        `Payment ${status.paymentId} is ${status.rail}, not x402.`,
+        409,
+        status
+      );
+    }
+    const readyForMerchantCompletion = input.noFundingLeg ? status.kind === "payment_intent" && status.status === "submitted" : status.nextAction === AgentPaymentNextAction.RetryOriginalX402Request || status.kind === "payment_intent" && status.status === "confirmed" && status.phase === AgentPaymentPhase.PaymentConfirmed && status.nextAction === AgentPaymentNextAction.None;
+    if (!readyForMerchantCompletion) {
+      throw new HavenPaymentStateError(status.message, paymentStateStatusCode(status.status, 409), status);
+    }
+    if (!input.noFundingLeg && !status.txHash) {
+      throw new HavenApiError(
+        `x402 payment ${status.paymentId} is ready for merchant completion but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    const approvedResourceUrl = status.resourceUrl ?? status.x402?.resourceUrl ?? null;
+    if (approvedResourceUrl && approvedResourceUrl !== input.url) {
+      throw new HavenApiError(
+        "x402 merchant completion does not match the approved resource URL.",
+        409,
+        { status, url: input.url },
+        status.paymentId
+      );
+    }
+    return {
+      paymentId: status.paymentId,
+      txHash: status.txHash,
+      resourceUrl: approvedResourceUrl ?? input.url,
+      merchantAddress: status.merchantAddress ?? status.x402?.merchantAddress ?? null
+    };
+  }
+  async resolveWalletForMerchantCall() {
+    const localWallet = x402PayerAddress(this.delegateAddress, this.x402Wallet);
+    if (localWallet) return localWallet;
+    try {
+      const agent = await this.getAgent();
+      return agent.delegateAddress ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  // #1328: authorizeMachinePayment / authorizeMppDemoPayment / resumeAuthorizedMpp
+  // / resumeMppPayment / fetchWithMachinePayment / retryMppRequest (the
+  // MACHINE-PAYMENT-CHALLENGE / mpp_demo client surface) are retired — the
+  // backend's POST /machine-payments/authorize refuses unconditionally now,
+  // and MACHINE-PAYMENT-CHALLENGE was never produced by any other Haven
+  // surface. Use the x402 flow (authorizeX402 / fetch / quoteX402 / payX402Quote)
+  // for agent-to-merchant payments.
+  async recordRetryRejected(input) {
+    try {
+      await this.post("/machine-payments/reconciliation-events", {
+        paymentId: input.paymentId,
+        rail: input.rail,
+        eventType: "merchant_retry_rejected_after_payment",
+        txHash: input.txHash,
+        reason: `Merchant returned HTTP ${input.merchant.merchant_status} after Haven payment confirmation`,
+        details: {
+          resource_url: input.resourceUrl,
+          retry_status: input.merchant.merchant_status,
+          retry_body: input.merchant.merchant_body.slice(0, MERCHANT_BODY_SNIPPET_LIMIT) || null,
+          ...input.details
+        }
+      });
+    } catch {
+    }
+  }
+  async reportEvidence(input) {
+    try {
+      await this.post("/machine-payments/evidence", {
+        paymentId: input.paymentId,
+        rail: input.rail,
+        txHash: input.txHash,
+        resourceUrl: input.resourceUrl,
+        merchantStatus: input.merchantStatus,
+        challengePayload: input.challengePayload,
+        selectedPayment: input.selectedPayment,
+        paymentProofHeaderName: input.paymentProofHeaderName,
+        paymentProofHeader: input.paymentProofHeader,
+        protocolReceiptHeaderName: input.protocolReceiptHeaderName,
+        protocolReceiptHeader: input.protocolReceiptHeader,
+        protocolReceiptPayload: input.protocolReceiptHeader ? parseProtocolReceiptHeader(input.protocolReceiptHeader) : void 0
+      });
+    } catch {
+    }
+  }
+};
+function parseMerchantSettlement(header) {
+  if (!header) return {};
+  const parsed = parseProtocolReceiptHeader(header);
+  const tx = typeof parsed?.transaction === "string" ? parsed.transaction : typeof parsed?.txHash === "string" ? parsed.txHash : typeof parsed?.tx_hash === "string" ? parsed.tx_hash : null;
+  return { settlementTxHash: tx };
+}
+function parseProtocolReceiptHeader(value) {
+  try {
+    return decodeBase64Json(value);
+  } catch {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return void 0;
+    }
+  }
+}
+
+// src/client.ts
+var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
+var DEFAULT_POLLING_INTERVAL = 3e3;
 function x402TypedDataDigest(typedData) {
   if (!typedData || typeof typedData !== "object") return void 0;
   try {
@@ -1167,48 +2669,78 @@ function mapCatalogEntry(entry) {
   };
 }
 var HavenClient = class {
-  apiKey;
   delegateKey;
-  baseUrl;
+  havenApi;
+  accountReads;
+  delegateSweep;
   x402Wallet;
-  requestTimeout;
-  merchantTimeout;
+  merchantTransport;
   confirmationTimeout;
   pollingInterval;
   chainRpcs;
   inFlightX402 = /* @__PURE__ */ new Map();
-  x402ReceiptCache = /* @__PURE__ */ new Map();
   /**
-   * Setup-time headers configured via `HavenClientConfig.defaultHeaders`.
-   * Read-only after construction — use `withRequestContext` for per-call
-   * scoping so concurrent requests don't race on shared mutable state.
+   * The EIP-3009 funding-leg lifecycle (#1618). The facade holds a reference
+   * and delegates; it does not reimplement any of it.
    */
-  defaultHeaders;
+  fundingLeg;
   /**
-   * Async-local store for per-request context (currently: extra headers).
-   * Each `withRequestContext` invocation produces an isolated store, so
-   * overlapping async work — like two MCP tool dispatches in flight at
-   * the same time — see their own headers without stepping on each other.
+   * The erc7710 direct-settlement lifecycle (#1619). Separate from the funding
+   * leg on purpose: this scheme has no funding leg to share.
    */
-  requestContext = new AsyncLocalStorage();
-  /** Monotonic JSON-RPC id source for the MCP `initialize` handshake. */
-  mcpRequestId = 0;
+  erc7710;
+  /**
+   * Merchant delivery and the evidence trail behind it (#1620). Scheme-neutral
+   * on purpose — both settlement schemes finish through the same door.
+   */
+  merchantCompletion;
   /** Delegate address derived from the private key (if provided) */
   delegateAddress;
   constructor(config) {
-    this.apiKey = config.apiKey;
     this.delegateKey = config.delegateKey;
-    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.havenApi = new HavenApiTransport(config);
+    this.accountReads = new AccountReads({
+      transport: this.havenApi,
+      getPaymentStatus: (paymentId) => this.getPaymentStatus(paymentId)
+    });
+    this.delegateSweep = new DelegateSweepApi({
+      transport: this.havenApi,
+      delegateKey: config.delegateKey,
+      chainRpcs: config.chainRpcs ?? {},
+      getAgent: () => this.getAgent(),
+      buildExplorerUrl: (chainId, hash) => buildExplorerUrl(chainId, hash)
+    });
     this.x402Wallet = config.x402Wallet;
-    this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
-    this.merchantTimeout = config.merchantTimeout ?? DEFAULT_MERCHANT_TIMEOUT;
+    this.merchantTransport = new McpMerchantTransport({ merchantTimeout: config.merchantTimeout });
     this.confirmationTimeout = config.confirmationTimeout ?? DEFAULT_CONFIRMATION_TIMEOUT;
     this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
     this.chainRpcs = config.chainRpcs ?? {};
-    this.defaultHeaders = { ...config.defaultHeaders ?? {} };
     if (this.delegateKey) {
       this.delegateAddress = addressFromKey(this.delegateKey);
     }
+    this.fundingLeg = new X402FundingLeg({
+      delegateKey: this.delegateKey,
+      delegateAddress: this.delegateAddress,
+      x402Wallet: this.x402Wallet,
+      chainRpcs: this.chainRpcs,
+      post: (path, body) => this.post(path, body),
+      signForData: (signData) => this.signForData(signData),
+      assertSignableAuthorizationState: (label, raw) => this.throwIfNonSignableAuthorizationState(label, raw)
+    });
+    this.merchantCompletion = new MerchantCompletion({
+      post: (path, body) => this.post(path, body),
+      merchantTransport: this.merchantTransport,
+      getPaymentStatus: (paymentId) => this.getPaymentStatus(paymentId),
+      getAgent: () => this.getAgent(),
+      delegateAddress: this.delegateAddress,
+      x402Wallet: this.x402Wallet
+    });
+    this.erc7710 = new X402Erc7710({
+      delegateKey: this.delegateKey,
+      post: (path, body) => this.post(path, body),
+      signForData: (signData) => this.signForData(signData),
+      getAgent: () => this.getAgent()
+    });
   }
   /**
    * Run `fn` with extra Haven-API headers scoped to the async work it
@@ -1226,7 +2758,7 @@ var HavenClient = class {
    * context.
    */
   withRequestContext(headers, fn) {
-    return this.requestContext.run({ headers: { ...headers } }, fn);
+    return this.havenApi.withRequestContext(headers, fn);
   }
   // ── High-Level API ───────────────────────────────────────────────
   /**
@@ -1262,7 +2794,7 @@ var HavenClient = class {
       ...request.idempotencyKey ? { idempotency_key: request.idempotencyKey } : {}
     });
     if (raw.status === "pending_approval") {
-      this.throwPaymentStateError("Payment", raw);
+      throwPaymentStateError("Payment", raw);
     }
     return {
       paymentId: raw.payment_id,
@@ -1325,7 +2857,7 @@ var HavenClient = class {
       ...new TextEncoder().encode(JSON.stringify(paymentRequired)).length <= 65536 ? { paymentRequired } : {}
     });
     if (raw.status !== "pending_signature") {
-      this.throwPaymentStateError("x402 payment", raw);
+      throwPaymentStateError("x402 payment", raw);
     }
     if (!raw.sign_data?.hash) {
       throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
@@ -1446,7 +2978,7 @@ var HavenClient = class {
    */
   async getPayment(paymentId) {
     const raw = await this.get(`/payments/${paymentId}`);
-    return this.mapPaymentResult(raw);
+    return mapPaymentResult(raw, buildExplorerUrl);
   }
   /**
    * Get agent-actionable status for a payment intent or approval request.
@@ -1456,137 +2988,35 @@ var HavenClient = class {
    */
   async getPaymentStatus(paymentId) {
     const raw = await this.get(`/machine-payments/${paymentId}/status`);
-    return this.mapPaymentStatusResult(raw);
+    return mapPaymentStatusResult(raw);
   }
   /**
    * Get the agent identity tied to this API key.
    */
   async getAgent() {
-    if (this.agentInFlight) return this.agentInFlight;
-    const request = this.fetchAgent();
-    this.agentInFlight = request;
-    request.finally(() => {
-      this.agentInFlight = null;
-    }).catch(() => {
-    });
-    return request;
-  }
-  agentInFlight = null;
-  async fetchAgent() {
-    const raw = await this.get("/machine-payments/agent");
-    return {
-      id: raw.id,
-      name: raw.name,
-      status: raw.status,
-      safeAddress: raw.safe_address,
-      delegateAddress: raw.delegate_address,
-      chainId: raw.chain_id,
-      // Defensive normalization, not trust: the backend contract is exactly
-      // 'legacy' | 'delegation' (#1306), but an older/mismatched backend
-      // during a rollout window should degrade to the wider legacy bucket
-      // rather than propagate an unrecognized string.
-      executionRail: raw.execution_rail === "delegation" ? "delegation" : "legacy"
-    };
-  }
-  /**
-   * One-shot "am I ready?" bootstrap: identity + live spend authority + a
-   * readiness signal, in a single call. Folds {@link getAgent} and
-   * {@link getAllowances} together and derives a {@link HavenAgentReadiness}
-   * so an agent can answer "who am I and can I pay right now" at session start
-   * without two round trips and manual assembly.
-   */
-  async getAgentSummary() {
-    const [agent, allowanceSummary] = await Promise.all([
-      this.getAgent(),
-      this.getAllowances()
-    ]);
-    const allowances = allowanceSummary.allowances.map((a) => {
-      const token = resolveTokenFromAddress(a.tokenAddress);
-      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(a.onchain.remaining), token.decimals)} ${a.tokenSymbol}` : `${a.onchain.remaining} ${a.tokenSymbol} (atomic; unknown decimals)`;
-      return {
-        tokenSymbol: a.tokenSymbol,
-        remainingAtomic: a.onchain.remaining,
-        remainingDisplay,
-        configuredAmount: a.configuredAmount,
-        resetPeriodMin: a.resetPeriodMin,
-        isResetPending: a.onchain.isResetPending
-      };
-    });
-    const readiness = deriveReadiness(agent.status, allowances);
-    return { ...agent, readiness, spend_authority_readiness: readiness, allowances };
+    return this.accountReads.getAgent();
   }
   /**
-   * Sweep stranded USDC and ETH from the delegate EOA back to the originating Safe.
-   *
-   * The delegate key held by this client signs and submits the transfer transactions
-   * directly — Haven's backend never handles the key or constructs signed txs
-   * (CASP/MiCA Red Line #2). Funds always go to the Safe linked to this agent.
-   *
-   * Requires `chainRpcs` to be set for the agent's chain in `HavenClientConfig`.
-   */
-  async sweepDelegate() {
-    if (!this.delegateKey) {
-      throw new HavenSigningError("delegateKey is required for sweepDelegate.");
-    }
-    const agent = await this.getAgent();
-    const { safeAddress, delegateAddress, chainId } = agent;
-    if (!delegateAddress) {
-      throw new HavenApiError("Agent has no delegate address.", 422);
-    }
-    const rpcUrl = this.chainRpcs[chainId];
-    if (!rpcUrl) {
-      throw new HavenApiError(
-        `chainRpcs[${chainId}] must be configured to sweep the delegate wallet.`,
-        422
-      );
-    }
-    const provider = createJsonRpcProvider(rpcUrl);
-    const wallet = createWallet(this.delegateKey, provider);
-    const ERC20_TRANSFER_ABI = ["function balanceOf(address) view returns (uint256)", "function transfer(address to, uint256 amount) returns (bool)"];
-    const transfers = [];
-    const usdcAddress = CHAIN_USDC[chainId];
-    if (usdcAddress) {
-      const usdcContract = createErc20Contract(usdcAddress, ERC20_TRANSFER_ABI, wallet);
-      const usdcBalance = await usdcContract.balanceOf(delegateAddress);
-      if (usdcBalance > 0n) {
-        const tx = await usdcContract.transfer(safeAddress, usdcBalance);
-        const receipt = await tx.wait(1);
-        const txHash = receipt?.hash ?? tx.hash;
-        transfers.push({
-          asset: "USDC",
-          amount: formatAtomicAmount(usdcBalance, 6),
-          amountAtomic: usdcBalance.toString(),
-          txHash,
-          explorerUrl: buildExplorerUrl(chainId, txHash)
-        });
-      }
-    }
-    const ethBalance = await provider.getBalance(delegateAddress);
-    if (ethBalance > 0n) {
-      const fee = await provider.getFeeData();
-      const effectiveGasPrice = fee.maxFeePerGas ?? fee.gasPrice ?? 1000000n;
-      const gasLimit = 21000n;
-      const gasCost = effectiveGasPrice * gasLimit * 2n;
-      const ethToSend = ethBalance > gasCost ? ethBalance - gasCost : 0n;
-      if (ethToSend > 0n) {
-        const tx = await wallet.sendTransaction({ to: safeAddress, value: ethToSend });
-        const receipt = await tx.wait(1);
-        const txHash = receipt?.hash ?? tx.hash;
-        transfers.push({
-          asset: "ETH",
-          amount: formatAtomicAmount(ethToSend, 18),
-          amountAtomic: ethToSend.toString(),
-          txHash,
-          explorerUrl: buildExplorerUrl(chainId, txHash)
-        });
-      }
-    }
-    return {
-      fromAddress: delegateAddress,
-      toAddress: safeAddress,
-      chainId,
-      transfers
-    };
+   * One-shot "am I ready?" bootstrap: identity + live spend authority + a
+   * readiness signal, in a single call. Folds {@link getAgent} and
+   * {@link getAllowances} together and derives a {@link HavenAgentReadiness}
+   * so an agent can answer "who am I and can I pay right now" at session start
+   * without two round trips and manual assembly.
+   */
+  async getAgentSummary() {
+    return this.accountReads.getAgentSummary();
+  }
+  /**
+   * Sweep stranded USDC and ETH from the delegate EOA back to the originating Safe.
+   *
+   * The delegate key held by this client signs and submits the transfer transactions
+   * directly — Haven's backend never handles the key or constructs signed txs
+   * (CASP/MiCA Red Line #2). Funds always go to the Safe linked to this agent.
+   *
+   * Requires `chainRpcs` to be set for the agent's chain in `HavenClientConfig`.
+   */
+  async sweepDelegate() {
+    return this.delegateSweep.sweepDelegate();
   }
   /**
    * Hosted (keyless) split-signer sweep — step 1 of 2.
@@ -1597,7 +3027,7 @@ var HavenClient = class {
    * edge signer's `haven_sign_sweep_delegate`. No key is required on this client.
    */
   async prepareSweep() {
-    return this.post("/machine-payments/sweep/prepare", {});
+    return this.delegateSweep.prepareSweep();
   }
   /**
    * Hosted (keyless) split-signer sweep — step 2 of 2.
@@ -1607,40 +3037,13 @@ var HavenClient = class {
    * the key.
    */
   async submitSweep(authorization, signature) {
-    return this.post("/machine-payments/sweep/submit", {
-      authorization,
-      signature
-    });
+    return this.delegateSweep.submitSweep(authorization, signature);
   }
   /**
    * Get configured and on-chain allowances for the authenticated agent.
    */
   async getAllowances() {
-    const raw = await this.get("/machine-payments/allowances");
-    return {
-      agentId: raw.agent_id,
-      safeAddress: raw.safe_address,
-      delegateAddress: raw.delegate_address,
-      chainId: raw.chain_id,
-      allowances: raw.allowances.map((allowance) => ({
-        id: allowance.id,
-        tokenAddress: allowance.token_address,
-        tokenSymbol: allowance.token_symbol,
-        configuredAmount: allowance.configured_amount,
-        resetPeriodMin: allowance.reset_period_min,
-        onchain: {
-          amount: allowance.onchain.amount,
-          spent: allowance.onchain.spent,
-          remaining: allowance.onchain.remaining,
-          effectiveSpent: allowance.onchain.effective_spent,
-          resetTimeMin: allowance.onchain.reset_time_min,
-          lastResetMin: allowance.onchain.last_reset_min,
-          nonce: allowance.onchain.nonce,
-          isResetPending: allowance.onchain.is_reset_pending,
-          remainingIsFromChain: allowance.onchain.remaining_is_from_chain
-        }
-      }))
-    };
+    return this.accountReads.getAllowances();
   }
   /**
    * Post-purchase allowance/budget summary for a settled payment (#1310).
@@ -1671,62 +3074,7 @@ var HavenClient = class {
    * phrase it as guaranteed-fresh.
    */
   async getPostPurchaseAllowanceSummary(paymentId) {
-    const unavailable = (detail) => ({
-      payment: null,
-      allowance: null,
-      warnings: [
-        {
-          code: AgentPaymentWarningCode.AllowanceCheckUnavailable,
-          message: `Could not read the post-purchase allowance/budget for payment ${paymentId} (${detail}). The payment itself succeeded \u2014 the on-chain policy remains the actual spend gate; this only affects the remaining-budget figure reported here.`
-        }
-      ]
-    });
-    const [statusResult, agentResult, allowanceResult] = await Promise.allSettled([
-      this.getPaymentStatus(paymentId),
-      this.getAgent(),
-      this.getAllowances()
-    ]);
-    if (statusResult.status === "rejected") {
-      return unavailable(statusResult.reason instanceof Error ? statusResult.reason.message : String(statusResult.reason));
-    }
-    const status = statusResult.value;
-    if (agentResult.status === "rejected") {
-      return { ...unavailable(agentResult.reason instanceof Error ? agentResult.reason.message : String(agentResult.reason)), payment: status };
-    }
-    if (allowanceResult.status === "rejected") {
-      return { ...unavailable(allowanceResult.reason instanceof Error ? allowanceResult.reason.message : String(allowanceResult.reason)), payment: status };
-    }
-    try {
-      const tokenAddress = status.asset ?? status.x402?.asset ?? null;
-      if (!tokenAddress) {
-        return { ...unavailable("the settled payment does not carry a resolvable token address"), payment: status };
-      }
-      const rail = agentResult.value.executionRail;
-      const source = rail === "delegation" ? "active_delegations" : "allowance_module";
-      const match = allowanceResult.value.allowances.find(
-        (a) => a.tokenAddress.toLowerCase() === tokenAddress.toLowerCase()
-      );
-      if (!match) {
-        return { ...unavailable("no allowance/budget row matches the settled token"), payment: status };
-      }
-      const token = resolveTokenFromAddress(match.tokenAddress);
-      const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(match.onchain.remaining), token.decimals)} ${match.tokenSymbol}` : void 0;
-      return {
-        payment: status,
-        allowance: {
-          rail,
-          remaining_atomic: match.onchain.remaining,
-          ...remainingDisplay ? { remaining_display: remainingDisplay } : {},
-          token_symbol: match.tokenSymbol,
-          token_address: match.tokenAddress,
-          reset_period: match.resetPeriodMin,
-          source
-        },
-        warnings: []
-      };
-    } catch (err) {
-      return unavailable(err instanceof Error ? err.message : String(err));
-    }
+    return this.accountReads.getPostPurchaseAllowanceSummary(paymentId);
   }
   /**
    * `haven_get_payment_status` convenience: fetch status and, for a
@@ -1783,9 +3131,7 @@ var HavenClient = class {
    * List recent machine-payment receipts/evidence for bookkeeping.
    */
   async listReceipts(options = {}) {
-    const query = options.limit ? `?limit=${encodeURIComponent(String(options.limit))}` : "";
-    const raw = await this.get(`/machine-payments/receipts${query}`);
-    return raw.receipts.map((receipt) => this.mapPaymentReceipt(receipt));
+    return this.accountReads.listReceipts(options);
   }
   /**
    * Fetch the verifiable receipt bundle for a settled payment and verify it
@@ -1794,10 +3140,7 @@ var HavenClient = class {
    * authorisation, so the result is trustworthy even if the backend lied.
    */
   async getReceipt(paymentId) {
-    const { receipt } = await this.get(
-      `/payments/${paymentId}/receipt`
-    );
-    return { receipt, verification: verifyPaymentReceipt(receipt) };
+    return this.accountReads.getReceipt(paymentId);
   }
   /**
    * Rehydrate the x402 resume-state bundle for a payment id (#1328: the MPP
@@ -1850,17 +3193,16 @@ var HavenClient = class {
       );
     }
     const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
-    const cached = this.x402ReceiptCache.get(idempotencyKey);
-    if (cached && cached.expiresAt > Date.now()) return cached.receipt;
+    const cached = this.fundingLeg.cachedReceipt(idempotencyKey);
+    if (cached) return cached;
     const inFlight = this.inFlightX402.get(idempotencyKey);
     if (inFlight) return inFlight;
-    const promise = this.authorizeStandardX402(paymentRequired, option, idempotencyKey);
+    const promise = this.fundingLeg.authorize(paymentRequired, option, idempotencyKey);
     this.inFlightX402.set(idempotencyKey, promise);
     try {
       return await promise;
     } catch (err) {
-      this.attachResumeState(err, {
-        rail: "x402",
+      attachResumeState(err, {
         paymentRequired,
         accepted: option,
         idempotencyKey
@@ -1875,9 +3217,9 @@ var HavenClient = class {
    * payment or approval request.
    */
   async quoteX402(url, init, options = {}) {
-    const initialInit = this.withX402Wallet(init, this.x402PayerAddress());
-    const request = this.snapshotX402Request(url, initialInit);
-    const response = await this.merchantFetch(url, initialInit);
+    const initialInit = withX402Wallet(init, x402PayerAddress(this.delegateAddress, this.x402Wallet));
+    const request = snapshotX402Request(url, initialInit);
+    const response = await this.merchantTransport.fetch(url, initialInit);
     if (response.status !== 402) {
       throw new X402UnexpectedStatusError(
         `Expected an x402 quote response with HTTP 402, got HTTP ${response.status}.`,
@@ -1888,8 +3230,8 @@ var HavenClient = class {
       throw new HavenApiError("quoteX402 only supports standard x402 Payment Required responses.", 400);
     }
     const paymentRequired = await parsePaymentRequiredResponse(response);
-    const mcpTransport = await this.detectX402McpTransport(url, paymentRequired, response);
-    return this.buildX402Quote(paymentRequired, request, options.idempotencyKey, mcpTransport);
+    const mcpTransport = await this.merchantTransport.detect(url, paymentRequired, response);
+    return buildX402Quote(paymentRequired, request, options.idempotencyKey, mcpTransport);
   }
   /**
    * Probe an MCP tool for its x402 quote without creating a payment.
@@ -1902,8 +3244,8 @@ var HavenClient = class {
    * callers that need a plain x402 endpoint must use {@link quoteX402}.
    */
   async quoteMcpX402(url, init, options = {}) {
-    const wallet = await this.resolveX402WalletForMerchantCall();
-    const sessionId = await this.mcpInitialize(url, init, wallet);
+    const wallet = await this.merchantCompletion.resolveWalletForMerchantCall();
+    const sessionId = await this.merchantTransport.initialize(url, init, wallet);
     if (!sessionId) {
       throw new HavenApiError(
         "The merchant did not establish an MCP session before the x402 quote. No payment was created.",
@@ -1911,238 +3253,71 @@ var HavenClient = class {
         { mcpSessionNotEstablished: true }
       );
     }
-    let requestInit = this.withX402Wallet(init, wallet);
-    requestInit = this.withMcpHeaders(requestInit, sessionId);
+    let requestInit = withX402Wallet(init, wallet);
+    requestInit = this.merchantTransport.withSessionHeaders(requestInit, sessionId);
     const quote = await this.quoteX402(url, requestInit, options);
     return {
       ...quote,
       mcpTransport: quote.mcpTransport ?? { handshakeRequired: true, source: "path" }
     };
   }
-  /**
-   * Pay a previously inspected x402 quote and retry the exact captured request.
-   */
-  async payX402Quote(quote, options = {}) {
-    const idempotencyKey = options.idempotencyKey ?? quote.idempotencyKey;
-    try {
-      const receipt = await this.authorizeX402(quote.paymentRequired, { idempotencyKey });
-      return this.retryX402Request(
-        quote.request.url,
-        this.requestInitFromSnapshot(quote.request),
-        quote.paymentRequired,
-        receipt
-      );
-    } catch (err) {
-      this.attachResumeState(err, {
-        rail: "x402",
-        paymentRequired: quote.paymentRequired,
-        accepted: quote.accepted,
-        idempotencyKey,
-        request: quote.request
-      });
-      throw err;
-    }
-  }
-  async authorizeStandardX402(paymentRequired, option, idempotencyKey) {
-    const raw = await this.post("/x402", {
-      url: paymentRequired.resource.url,
-      payTo: this.delegateAddress,
-      merchantPayTo: option.payTo,
-      amount: x402AuthorizationAmount(option),
-      asset: option.asset,
-      network: option.network,
-      description: paymentRequired.resource.description,
-      idempotencyKey,
-      // #1360: same explicit funding-leg declaration as createX402Intent —
-      // this local-key path derives payTo from the key (never stale), but the
-      // declaration keeps both writers of the 3009 shape loud-by-default.
-      settlementScheme: "eip3009"
-    });
-    const state = this.paymentStateFromRaw("x402 payment", raw);
-    const executedReplay = raw.success && raw.tx_hash ? "idempotency-collision" : state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request ? "approval-resume" : null;
-    if (executedReplay) {
-      const canFund = await this.delegateCanFund(
-        raw.chain_id ?? state?.chainId ?? chainIdFromNetwork(option.network),
-        option.asset,
-        x402AuthorizationAmount(option)
-      );
-      const refuse = executedReplay === "idempotency-collision" ? canFund !== true : canFund === false;
-      if (refuse) {
-        const settledReceipt = state && executedReplay === "approval-resume" ? this.mapX402ReceiptFromStatus(paymentRequired, option, void 0, state) : this.mapX402ReceiptFromAuthorization(paymentRequired, option, void 0, raw);
-        throw new X402AlreadySettledError(
-          canFund === false ? "This x402 payment already settled \u2014 the delegate no longer holds the funds to authorize it again. To buy the same item a second time, pass a distinct `idempotencyKey`; the synthesised key intentionally collapses repeat calls for the same product within a 5-minute window so a retried request cannot pay twice." : "This x402 payment already settled, and whether the delegate can still fund a new authorization could not be verified (no `chainRpcs` entry for this chain). Refusing rather than issue an authorization that may be unfundable. To buy the same item a second time, pass a distinct `idempotencyKey`; to finish an interrupted payment, resume it by `paymentId`.",
-          settledReceipt,
-          canFund === false ? "settled" : "unverifiable"
-        );
-      }
-    }
-    const paymentHeader = await this.createStandardX402Header(paymentRequired, option);
-    if (raw.success && raw.tx_hash) {
-      const receipt2 = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw);
-      this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
-      return receipt2;
-    }
-    if (state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request) {
-      const receipt2 = this.mapX402ReceiptFromStatus(paymentRequired, option, paymentHeader, state);
-      this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
-      return receipt2;
-    }
-    this.throwIfNonSignableAuthorizationState("x402 payment", raw);
-    if (!raw.sign_data?.hash) {
-      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
-    }
-    const sig = await this.signForData(raw.sign_data);
-    const execResult = await this.post(
-      `/payments/${raw.payment_id}/sign`,
-      { signature: sig }
-    );
-    if (execResult.status !== "confirmed") {
-      this.throwPaymentStateError("x402 payment", execResult);
-    }
-    await this.waitForFundingTx(
-      execResult.tx_hash,
-      execResult.chain_id ?? chainIdFromNetwork(option.network)
-    );
-    const receipt = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult);
-    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 } : {},
-      // #1307/#1547: persisted so the settle leg can rehydrate the merchant
-      // call by payment_id on this scheme too, not only on the 3009 bridge.
-      ...options.mcpCallContext ? { mcpCallContext: options.mcpCallContext } : {}
-    });
-    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
+  /**
+   * Pay a previously inspected x402 quote and retry the exact captured request.
+   */
+  async payX402Quote(quote, options = {}) {
+    const idempotencyKey = options.idempotencyKey ?? quote.idempotencyKey;
+    try {
+      const receipt = await this.authorizeX402(quote.paymentRequired, { idempotencyKey });
+      return this.merchantCompletion.retryRequest(
+        quote.request.url,
+        requestInitFromSnapshot(quote.request),
+        quote.paymentRequired,
+        receipt
       );
+    } catch (err) {
+      attachResumeState(err, {
+        paymentRequired: quote.paymentRequired,
+        accepted: quote.accepted,
+        idempotencyKey,
+        request: quote.request
+      });
+      throw err;
     }
-    return {
-      paymentId: raw.payment_id,
-      signData,
-      settlement: {
-        paymentId: raw.payment_id,
-        merchantPayTo,
-        amountAtomic,
-        asset: option.asset,
-        network: option.network,
-        facilitatorAddresses: selection.facilitatorAddresses
-      }
-    };
+  }
+  /**
+   * Pay a merchant through **erc7710 direct settlement** (#1454, epic #1450).
+   *
+   * **Nothing has settled when this returns** — that is why it does not return
+   * an `X402Receipt`; the caller still has to retry the merchant with the
+   * header. **MCP callers must pass `options.resourceUrl`**, because an in-band
+   * MCP 402 challenge frequently carries no `resource` object at all.
+   *
+   * Both caveats, and why this scheme has no funding leg, are explained where
+   * the lifecycle lives: `x402-erc7710.ts` (#1619).
+   */
+  async settleX402Erc7710(paymentRequired, options = {}) {
+    return this.erc7710.settle(paymentRequired, options);
+  }
+  /**
+   * 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.
+   */
+  async prepareX402Erc7710(paymentRequired, options = {}) {
+    return this.erc7710.prepare(paymentRequired, options);
   }
   /**
    * 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.
+   * erc7710 payload. Whoever produced the signature (an in-process delegate
+   * key, or the local edge signer over the hosted boundary) is irrelevant.
    */
   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;
+    return this.erc7710.submit(paymentId, signature);
   }
   async resumeAuthorizedX402(input) {
     if (!this.delegateKey) {
@@ -2161,11 +3336,11 @@ var HavenClient = class {
       );
     }
     const idempotencyKey = input.idempotencyKey ?? buildX402IdempotencyKey(input.paymentRequired, option);
-    const cached = this.x402ReceiptCache.get(idempotencyKey);
-    if (cached && cached.expiresAt > Date.now()) return cached.receipt;
+    const cached = this.fundingLeg.cachedReceipt(idempotencyKey);
+    if (cached) return cached;
     const status = await this.getPaymentStatus(input.paymentId);
-    this.assertCanResumeX402(status, input.paymentRequired, option);
-    const canFund = await this.delegateCanFund(
+    assertCanResumeX402(status, input.paymentRequired, option);
+    const canFund = await this.fundingLeg.delegateCanFund(
       status.chainId ?? chainIdFromNetwork(option.network),
       option.asset,
       x402AuthorizationAmount(option)
@@ -2173,20 +3348,20 @@ var HavenClient = class {
     if (canFund === false) {
       throw new X402AlreadySettledError(
         `x402 payment ${status.paymentId} has already settled \u2014 the delegate no longer holds the funds to authorize it again, so there is nothing left to resume.`,
-        this.mapX402ReceiptFromStatus(input.paymentRequired, option, void 0, status),
+        this.fundingLeg.receiptFromStatus(input.paymentRequired, option, void 0, status),
         "settled"
       );
     }
-    const paymentHeader = await this.createStandardX402Header(input.paymentRequired, option);
-    const receipt = this.mapX402ReceiptFromStatus(input.paymentRequired, option, paymentHeader, status);
-    this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
+    const paymentHeader = await this.fundingLeg.createPaymentHeader(input.paymentRequired, option);
+    const receipt = this.fundingLeg.receiptFromStatus(input.paymentRequired, option, paymentHeader, status);
+    this.fundingLeg.cacheReceipt(idempotencyKey, paymentHeader, receipt);
     return receipt;
   }
   async resumeX402Payment(input) {
     const inputInit = "init" in input ? input.init : void 0;
-    const initialInit = this.withX402Wallet(
-      inputInit ?? (input.request ? this.requestInitFromSnapshot(input.request) : void 0),
-      this.x402PayerAddress()
+    const initialInit = withX402Wallet(
+      inputInit ?? (input.request ? requestInitFromSnapshot(input.request) : void 0),
+      x402PayerAddress(this.delegateAddress, this.x402Wallet)
     );
     let paymentRequired = input.paymentRequired;
     const url = input.url ?? input.request?.url;
@@ -2194,7 +3369,7 @@ var HavenClient = class {
       if (!url) {
         throw new HavenApiError("x402 resume requires the original URL or a captured request snapshot.", 400);
       }
-      const response = await this.merchantFetch(url, initialInit);
+      const response = await this.merchantTransport.fetch(url, initialInit);
       if (response.status !== 402) {
         throw new HavenApiError("Expected the original x402 request to return HTTP 402 before resuming.", 400);
       }
@@ -2205,7 +3380,7 @@ var HavenClient = class {
       paymentRequired,
       idempotencyKey: input.idempotencyKey
     });
-    return this.retryX402Request(url ?? paymentRequired.resource.url, initialInit, paymentRequired, receipt);
+    return this.merchantCompletion.retryRequest(url ?? paymentRequired.resource.url, initialInit, paymentRequired, receipt);
   }
   /**
    * Fetch wrapper that automatically handles HTTP 402 responses.
@@ -2219,268 +3394,57 @@ var HavenClient = class {
    * ```
    *
    * **MCP-over-x402 auto-handshake (issue #315):** when the endpoint is
-   * MCP-shaped — the URL path ends in `/mcp`, or the 402 body carries a
-   * Coinbase Bazaar `extensions.bazaar` block — the SDK runs the MCP
-   * `initialize` handshake, threads the resulting `mcp-session-id`,
-   * `Accept: application/json, text/event-stream`, and `x402-wallet` headers
-   * through every request, and collapses SSE responses to the JSON-RPC
-   * `result`. The caller just passes `(url, { body })` and never sees the
-   * protocol plumbing. A non-MCP server (handshake error / no session id)
-   * falls back to standard x402 behaviour.
-   *
-   * Requires `delegateKey` to be set in the client config.
-   */
-  async fetch(url, init, options = {}) {
-    let mcpSessionId;
-    if (isMcpUrl(url)) {
-      mcpSessionId = await this.mcpInitialize(url, init);
-    }
-    let requestInit = this.withX402Wallet(init, this.x402PayerAddress());
-    if (mcpSessionId) requestInit = this.withMcpHeaders(requestInit, mcpSessionId);
-    const response = await this.merchantFetch(url, requestInit);
-    if (response.status !== 402) {
-      return mcpSessionId ? this.surfaceMcpResult(response) : response;
-    }
-    let paymentRequired;
-    try {
-      paymentRequired = await parsePaymentRequiredResponse(response);
-    } catch {
-      return response;
-    }
-    if (!mcpSessionId && await responseHasBazaarExtension(response)) {
-      mcpSessionId = await this.mcpInitialize(url, init);
-      if (mcpSessionId) requestInit = this.withMcpHeaders(requestInit, mcpSessionId);
-    }
-    const request = this.snapshotX402Request(url, requestInit);
-    const option = selectStandardPaymentOption(paymentRequired.accepts);
-    const idempotencyKey = options.idempotencyKey ?? (option ? buildX402IdempotencyKey(paymentRequired, option) : void 0);
-    let receipt;
-    try {
-      receipt = await this.authorizeX402(paymentRequired, options);
-    } catch (err) {
-      if (option && idempotencyKey) {
-        this.attachResumeState(err, {
-          rail: "x402",
-          paymentRequired,
-          accepted: option,
-          idempotencyKey,
-          request
-        });
-      }
-      throw err;
-    }
-    const retryResponse = await this.retryX402Request(url, requestInit, paymentRequired, receipt);
-    return mcpSessionId ? this.surfaceMcpResult(retryResponse) : retryResponse;
-  }
-  // ── MCP-over-x402 transport helpers (issue #315) ─────────────────
-  /**
-   * Run the MCP `initialize` handshake against a Streamable-HTTP endpoint and
-   * return the `mcp-session-id` the server assigns.
-   *
-   * Returns `undefined` whenever the endpoint is not actually an MCP server —
-   * a transport/HTTP error, a missing session id, or a JSON-RPC error in the
-   * handshake response — so the caller can fall back to plain x402.
-   */
-  async mcpInitialize(url, init, wallet = this.x402PayerAddress()) {
-    try {
-      const headers = new Headers(init?.headers);
-      headers.set("Content-Type", "application/json");
-      headers.set("Accept", MCP_ACCEPT);
-      if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
-      const response = await this.merchantFetch(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          id: ++this.mcpRequestId,
-          method: "initialize",
-          params: {
-            protocolVersion: MCP_PROTOCOL_VERSION,
-            capabilities: {},
-            clientInfo: MCP_CLIENT_INFO
-          }
-        })
-      });
-      if (!response.ok) return void 0;
-      const sessionId = response.headers.get("mcp-session-id");
-      if (!sessionId) return void 0;
-      const message = await this.readMcpMessage(response);
-      if (message && "error" in message) return void 0;
-      await this.mcpNotifyInitialized(url, init, sessionId, wallet);
-      return sessionId;
-    } catch {
-      return void 0;
-    }
-  }
-  /**
-   * Send the MCP `notifications/initialized` notification that completes the
-   * lifecycle handshake. Best-effort: the session is already established, so a
-   * failed notification must not abort the payment.
-   */
-  async mcpNotifyInitialized(url, init, sessionId, wallet = this.x402PayerAddress()) {
-    try {
-      const headers = new Headers(init?.headers);
-      headers.set("Content-Type", "application/json");
-      headers.set("Accept", MCP_ACCEPT);
-      headers.set("mcp-session-id", sessionId);
-      if (wallet && !headers.has("x402-wallet")) headers.set("x402-wallet", wallet);
-      await this.merchantFetch(
-        url,
-        {
-          method: "POST",
-          headers,
-          body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })
-        },
-        NOTIFY_TIMEOUT
-      );
-    } catch {
-    }
-  }
-  /** Read a single JSON-RPC message from an MCP response (JSON or SSE body). */
-  async readMcpMessage(response) {
-    let text;
-    try {
-      text = await response.clone().text();
-    } catch {
-      return void 0;
-    }
-    if ((response.headers.get("content-type") ?? "").includes("text/event-stream")) {
-      return selectJsonRpcResult(parseSseJsonRpcMessages(text));
-    }
-    try {
-      return JSON.parse(text);
-    } catch {
-      return void 0;
-    }
-  }
-  /** Add the MCP transport headers (session id + SSE Accept) to a request. */
-  withMcpHeaders(init, sessionId) {
-    const headers = new Headers(init?.headers);
-    headers.set("mcp-session-id", sessionId);
-    headers.set("Accept", MCP_ACCEPT);
-    return { ...init, headers };
-  }
-  /**
-   * Collapse an MCP SSE response into a plain JSON response carrying the
-   * JSON-RPC `result`, so callers of `fetch()` never see raw SSE framing.
-   * Non-SSE responses pass through untouched.
-   */
-  async surfaceMcpResult(response) {
-    if (!(response.headers.get("content-type") ?? "").includes("text/event-stream")) {
-      return response;
-    }
-    let text;
-    try {
-      text = await response.clone().text();
-    } catch {
-      return response;
-    }
-    const message = selectJsonRpcResult(parseSseJsonRpcMessages(text));
-    if (!message) return response;
-    const body = "result" in message ? message.result : message;
-    const headers = new Headers(response.headers);
-    headers.set("content-type", "application/json");
-    headers.delete("content-length");
-    headers.delete("mcp-session-id");
-    return new Response(JSON.stringify(body), {
-      status: response.status,
-      statusText: response.statusText,
-      headers
-    });
-  }
-  async retryX402Request(url, initialInit, paymentRequired, receipt) {
-    if (!receipt.accepted) {
-      throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
-    }
-    if (!receipt.paymentHeader) {
-      throw new HavenApiError("No x402 payment header was returned for payment retry", 500);
-    }
-    const retryHeaders = new Headers(initialInit?.headers);
-    retryHeaders.set("X-PAYMENT", receipt.paymentHeader);
-    const retryResponse = await this.merchantFetch(url, {
-      ...initialInit,
-      headers: retryHeaders
-    });
-    if (!retryResponse.ok) {
-      const merchant = await captureMerchantResponse(retryResponse);
-      await this.recordMerchantRetryRejected({
-        rail: "x402",
-        paymentId: receipt.paymentId,
-        txHash: receipt.txHash,
-        resourceUrl: receipt.resourceUrl,
-        merchant,
-        details: {
-          merchant_to: receipt.merchantTo,
-          delegate_to: receipt.to
-        }
-      });
-      throw new HavenApiError(
-        "x402 retry failed after Haven funded the delegate wallet; reconciliation may be required.",
-        merchant.merchant_status,
-        {
-          marker: "x402_retry_rejected_after_funding",
-          payment_id: receipt.paymentId,
-          tx_hash: receipt.txHash,
-          resource_url: receipt.resourceUrl,
-          merchant_to: receipt.merchantTo,
-          delegate_to: receipt.to,
-          ...merchant
-        }
-      );
-    }
-    const merchantSettlement = parseMerchantSettlement(retryResponse.headers.get("PAYMENT-RESPONSE"));
-    if (receipt.merchant && merchantSettlement.settlementTxHash) {
-      receipt.merchant.settlementTxHash = merchantSettlement.settlementTxHash;
-      receipt.merchant.settlementExplorerUrl = buildExplorerUrl(
-        receipt.chainId,
-        merchantSettlement.settlementTxHash
-      );
-    }
-    await this.reportMachinePaymentEvidence({
-      paymentId: receipt.paymentId,
-      rail: "x402",
-      txHash: receipt.txHash,
-      resourceUrl: receipt.resourceUrl,
-      merchantStatus: retryResponse.status,
-      challengePayload: paymentRequired,
-      selectedPayment: receipt.accepted,
-      paymentProofHeaderName: "X-PAYMENT",
-      paymentProofHeader: receipt.paymentHeader,
-      protocolReceiptHeaderName: "PAYMENT-RESPONSE",
-      protocolReceiptHeader: retryResponse.headers.get("PAYMENT-RESPONSE") ?? void 0
-    });
-    await this.reportMerchantReceipt(receipt.paymentId, retryResponse);
-    return retryResponse;
-  }
-  /**
-   * #956: capture the merchant's OWN receipt when the paid response carries
-   * one, and report it to Haven so the reporting feed can attach it next to
-   * the Haven-generated payment evidence (#498). Two supported signals on the
-   * paid response:
-   *
-   *   x-receipt-json: base64-encoded JSON receipt document (inline)
-   *   x-receipt-url:  https URL to the receipt document (reference)
+   * MCP-shaped — the URL path ends in `/mcp`, or the 402 body carries a
+   * Coinbase Bazaar `extensions.bazaar` block — the SDK runs the MCP
+   * `initialize` handshake, threads the resulting `mcp-session-id`,
+   * `Accept: application/json, text/event-stream`, and `x402-wallet` headers
+   * through every request, and collapses SSE responses to the JSON-RPC
+   * `result`. The caller just passes `(url, { body })` and never sees the
+   * protocol plumbing. A non-MCP server (handshake error / no session id)
+   * falls back to standard x402 behaviour.
    *
-   * Strictly best-effort: absence is the normal case, and no failure here may
-   * ever affect the completed payment — the response is already paid for.
+   * Requires `delegateKey` to be set in the client config.
    */
-  async reportMerchantReceipt(paymentId, response) {
+  async fetch(url, init, options = {}) {
+    let mcpSessionId;
+    if (this.merchantTransport.isMcpUrl(url)) {
+      mcpSessionId = await this.merchantTransport.initialize(url, init);
+    }
+    let requestInit = withX402Wallet(init, x402PayerAddress(this.delegateAddress, this.x402Wallet));
+    if (mcpSessionId) requestInit = this.merchantTransport.withSessionHeaders(requestInit, mcpSessionId);
+    const response = await this.merchantTransport.fetch(url, requestInit);
+    if (response.status !== 402) {
+      return mcpSessionId ? this.merchantTransport.surfaceResult(response) : response;
+    }
+    let paymentRequired;
     try {
-      const inlineB64 = response.headers.get("x-receipt-json");
-      const url = response.headers.get("x-receipt-url");
-      if (!inlineB64 && !url) return;
-      let body = null;
-      if (inlineB64) {
-        if (inlineB64.length > Math.ceil(64 * 1024 * 4 / 3)) return;
-        const decoded = JSON.parse(Buffer.from(inlineB64, "base64").toString("utf8"));
-        if (decoded && typeof decoded === "object") body = { json: decoded };
-      } else if (url && url.startsWith("https://") && url.length <= 2048) {
-        body = { url };
-      }
-      if (!body) return;
-      await this.post(`/machine-payments/${paymentId}/merchant-receipt`, body);
+      paymentRequired = await parsePaymentRequiredResponse(response);
     } catch {
+      return response;
+    }
+    if (!mcpSessionId && await this.merchantTransport.hasBazaarExtension(response)) {
+      mcpSessionId = await this.merchantTransport.initialize(url, init);
+      if (mcpSessionId) requestInit = this.merchantTransport.withSessionHeaders(requestInit, mcpSessionId);
+    }
+    const request = snapshotX402Request(url, requestInit);
+    const option = selectStandardPaymentOption(paymentRequired.accepts);
+    const idempotencyKey = options.idempotencyKey ?? (option ? buildX402IdempotencyKey(paymentRequired, option) : void 0);
+    let receipt;
+    try {
+      receipt = await this.authorizeX402(paymentRequired, options);
+    } catch (err) {
+      if (option && idempotencyKey) {
+        attachResumeState(err, {
+          paymentRequired,
+          accepted: option,
+          idempotencyKey,
+          request
+        });
+      }
+      throw err;
     }
+    const retryResponse = await this.merchantCompletion.retryRequest(url, requestInit, paymentRequired, receipt);
+    return mcpSessionId ? this.merchantTransport.surfaceResult(retryResponse) : retryResponse;
   }
   /**
    * Deliver an already-signed x402 payment header to the merchant and return
@@ -2505,7 +3469,7 @@ var HavenClient = class {
    * and before delivering the X-PAYMENT header, so the merchant's
    * balanceOf(delegate) / transferWithAuthorization verification sees the funded
    * balance — otherwise it rejects with "Payment verification failed". The
-   * SDK's local path already does this (see authorizeStandardX402); the hosted
+   * SDK's local path already does this (see `X402FundingLeg.authorize`); the hosted
    * split flow regressed when the 5→3 collapse removed the incidental
    * inter-call latency that used to mask it.
    *
@@ -2522,28 +3486,25 @@ var HavenClient = class {
    */
   async ensureFundingConfirmed(paymentId, fundingTxHash) {
     const status = await this.getPaymentStatus(paymentId);
-    await this.waitForFundingTx(fundingTxHash ?? status.txHash ?? void 0, status.chainId);
+    await this.fundingLeg.waitForFundingTx(fundingTxHash ?? status.txHash ?? void 0, status.chainId);
   }
   async completeX402MerchantCall(input) {
-    const evidenceContext = await this.resolveX402MerchantCompletionContext({
+    const evidenceContext = await this.merchantCompletion.resolveCompletionContext({
       paymentId: input.paymentId,
       url: input.url,
       noFundingLeg: input.noFundingLeg === true
     });
     const fundingTxHash = evidenceContext.txHash;
-    const shouldHandshakeMcp = isMcpUrl(input.url) || input.mcpTransport?.handshakeRequired === true;
-    const x402Wallet = shouldHandshakeMcp ? await this.resolveX402WalletForMerchantCall() : this.x402PayerAddress();
+    const shouldHandshakeMcp = this.merchantTransport.isMcpUrl(input.url) || input.mcpTransport?.handshakeRequired === true;
+    const x402Wallet = shouldHandshakeMcp ? await this.merchantCompletion.resolveWalletForMerchantCall() : x402PayerAddress(this.delegateAddress, this.x402Wallet);
     let mcpSessionId;
     if (shouldHandshakeMcp) {
-      mcpSessionId = await this.mcpInitialize(input.url, input.init, x402Wallet);
+      mcpSessionId = await this.merchantTransport.initialize(input.url, input.init, x402Wallet);
     }
-    let requestInit = this.withX402Wallet(input.init, x402Wallet) ?? {};
-    if (mcpSessionId) requestInit = this.withMcpHeaders(requestInit, mcpSessionId);
-    const headers = new Headers(requestInit.headers);
-    headers.set("X-PAYMENT", input.paymentHeader);
-    requestInit = { ...requestInit, headers };
-    const response = await this.merchantFetch(input.url, requestInit);
-    const surfaced = mcpSessionId ? await this.surfaceMcpResult(response) : response;
+    let requestInit = withX402Wallet(input.init, x402Wallet) ?? {};
+    if (mcpSessionId) requestInit = this.merchantTransport.withSessionHeaders(requestInit, mcpSessionId);
+    const response = await this.merchantTransport.deliverPayment(input.url, requestInit, input.paymentHeader);
+    const surfaced = mcpSessionId ? await this.merchantTransport.surfaceResult(response) : response;
     const protocolReceiptHeader = surfaced.headers.get("PAYMENT-RESPONSE") ?? void 0;
     const settlement = parseMerchantSettlement(protocolReceiptHeader ?? null);
     const text = await surfaced.text();
@@ -2555,7 +3516,7 @@ var HavenClient = class {
     }
     if (!surfaced.ok) {
       if (!input.noFundingLeg && fundingTxHash) {
-        await this.recordMerchantRetryRejected({
+        await this.merchantCompletion.recordRetryRejected({
           rail: "x402",
           paymentId: evidenceContext.paymentId,
           txHash: fundingTxHash,
@@ -2573,7 +3534,7 @@ var HavenClient = class {
       }
     } else {
       if (!input.noFundingLeg && fundingTxHash) {
-        await this.reportMachinePaymentEvidence({
+        await this.merchantCompletion.reportEvidence({
           paymentId: evidenceContext.paymentId,
           rail: "x402",
           txHash: fundingTxHash,
@@ -2585,7 +3546,7 @@ var HavenClient = class {
           protocolReceiptHeader
         });
       }
-      await this.reportMerchantReceipt(evidenceContext.paymentId, surfaced);
+      await this.merchantCompletion.reportMerchantReceipt(evidenceContext.paymentId, surfaced);
     }
     return {
       status: surfaced.status,
@@ -2615,271 +3576,11 @@ var HavenClient = class {
       arguments: raw.arguments ?? {},
       ...raw.mcp_transport ? {
         mcpTransport: {
-          handshakeRequired: raw.mcp_transport.handshake_required,
-          source: raw.mcp_transport.source
-        }
-      } : {}
-    };
-  }
-  async resolveX402MerchantCompletionContext(input) {
-    const status = await this.getPaymentStatus(input.paymentId);
-    if (status.rail !== "x402") {
-      throw new HavenPaymentStateError(
-        `Payment ${status.paymentId} is ${status.rail}, not x402.`,
-        409,
-        status
-      );
-    }
-    const readyForMerchantCompletion = input.noFundingLeg ? status.kind === "payment_intent" && status.status === "submitted" : status.nextAction === AgentPaymentNextAction.RetryOriginalX402Request || status.kind === "payment_intent" && status.status === "confirmed" && status.phase === AgentPaymentPhase.PaymentConfirmed && status.nextAction === AgentPaymentNextAction.None;
-    if (!readyForMerchantCompletion) {
-      throw new HavenPaymentStateError(status.message, PAYMENT_STATE_STATUS_CODES[status.status] ?? 409, status);
-    }
-    if (!input.noFundingLeg && !status.txHash) {
-      throw new HavenApiError(
-        `x402 payment ${status.paymentId} is ready for merchant completion but has no Haven transaction hash.`,
-        502,
-        status,
-        status.paymentId
-      );
-    }
-    const approvedResourceUrl = status.resourceUrl ?? status.x402?.resourceUrl ?? null;
-    if (approvedResourceUrl && approvedResourceUrl !== input.url) {
-      throw new HavenApiError(
-        "x402 merchant completion does not match the approved resource URL.",
-        409,
-        { status, url: input.url },
-        status.paymentId
-      );
-    }
-    return {
-      paymentId: status.paymentId,
-      txHash: status.txHash,
-      resourceUrl: approvedResourceUrl ?? input.url,
-      merchantAddress: status.merchantAddress ?? status.x402?.merchantAddress ?? null
-    };
-  }
-  async resolveX402WalletForMerchantCall() {
-    const localWallet = this.x402PayerAddress();
-    if (localWallet) return localWallet;
-    try {
-      const agent = await this.getAgent();
-      return agent.delegateAddress ?? void 0;
-    } catch {
-      return void 0;
-    }
-  }
-  // #1328: authorizeMachinePayment / authorizeMppDemoPayment / resumeAuthorizedMpp
-  // / resumeMppPayment / fetchWithMachinePayment / retryMppRequest (the
-  // MACHINE-PAYMENT-CHALLENGE / mpp_demo client surface) are retired — the
-  // backend's POST /machine-payments/authorize refuses unconditionally now,
-  // and MACHINE-PAYMENT-CHALLENGE was never produced by any other Haven
-  // surface. Use the x402 flow (authorizeX402 / fetch / quoteX402 / payX402Quote)
-  // for agent-to-merchant payments.
-  assertCanResumeX402(status, paymentRequired, option) {
-    if (status.rail !== "x402") {
-      throw new HavenPaymentStateError(
-        `Payment ${status.paymentId} is ${status.rail}, not x402.`,
-        409,
-        status
-      );
-    }
-    if (status.nextAction !== AgentPaymentNextAction.RetryOriginalX402Request) {
-      throw new HavenPaymentStateError(status.message, PAYMENT_STATE_STATUS_CODES[status.status] ?? 409, status);
-    }
-    if (!status.txHash) {
-      throw new HavenApiError(
-        `x402 payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
-        502,
-        status,
-        status.paymentId
-      );
-    }
-    if (status.resourceUrl && status.resourceUrl !== paymentRequired.resource.url) {
-      throw new HavenApiError(
-        "x402 resume request does not match the approved resource URL.",
-        409,
-        { status, paymentRequired },
-        status.paymentId
-      );
-    }
-    if (status.merchantAddress && !sameAddress3(status.merchantAddress, option.payTo)) {
-      throw new HavenApiError(
-        "x402 resume request does not match the approved merchant.",
-        409,
-        { status, selectedPayment: option },
-        status.paymentId
-      );
-    }
-    const optionChainId = chainIdFromNetwork(option.network);
-    if (status.chainId && optionChainId && status.chainId !== optionChainId) {
-      throw new HavenApiError(
-        "x402 resume request does not match the approved network.",
-        409,
-        { status, selectedPayment: option },
-        status.paymentId
-      );
-    }
-    if (status.token && status.token !== "USDC") {
-      throw new HavenApiError(
-        "x402 resume request does not match the approved token.",
-        409,
-        { status, selectedPayment: option },
-        status.paymentId
-      );
-    }
-    const approvedAmount = status.amount ? normalizeDecimal(status.amount) : "";
-    const requestedAmount = normalizeDecimal(decimalFromUsdcAtomic(x402AuthorizationAmount(option)));
-    if (approvedAmount && approvedAmount !== requestedAmount) {
-      throw new HavenApiError(
-        "x402 resume request does not match the approved amount.",
-        409,
-        { status, selectedPayment: option },
-        status.paymentId
-      );
-    }
-  }
-  mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult) {
-    const txHash = execResult?.tx_hash ?? raw.tx_hash ?? "";
-    const chainId = execResult?.chain_id ?? raw.chain_id ?? chainIdFromNetwork(option.network);
-    const token = execResult?.token ?? raw.token ?? "USDC";
-    const amount = execResult?.amount ?? raw.amount ?? decimalFromUsdcAtomic(x402AuthorizationAmount(option));
-    const to = execResult?.to ?? raw.to ?? this.delegateAddress ?? "";
-    const explorerUrl = execResult?.explorer_url ?? raw.explorer_url ?? explorerUrlOrEmpty(chainId, txHash);
-    const merchantTo = execResult?.merchant_to ?? raw.merchant_to ?? option.payTo;
-    const payer = raw.payer ?? raw.safe_address ?? raw.sign_data?.components.safe;
-    return this.buildX402Receipt({
-      paymentId: raw.payment_id,
-      txHash,
-      token,
-      amount,
-      to,
-      resourceUrl: paymentRequired.resource.url,
-      explorerUrl,
-      accepted: option,
-      paymentHeader,
-      merchantTo,
-      payer,
-      chainId
-    });
-  }
-  mapX402ReceiptFromStatus(paymentRequired, option, paymentHeader, status) {
-    if (!status.txHash) {
-      throw new HavenApiError(
-        `x402 payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
-        502,
-        status,
-        status.paymentId
-      );
-    }
-    return this.buildX402Receipt({
-      paymentId: status.paymentId,
-      txHash: status.txHash,
-      token: status.token || "USDC",
-      amount: status.amount || decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
-      to: this.delegateAddress ?? "",
-      resourceUrl: paymentRequired.resource.url,
-      explorerUrl: explorerUrlOrEmpty(status.chainId, status.txHash),
-      accepted: option,
-      paymentHeader,
-      merchantTo: status.merchantAddress ?? option.payTo,
-      payer: this.x402Wallet,
-      chainId: status.chainId || chainIdFromNetwork(option.network)
-    });
-  }
-  buildX402Receipt(input) {
-    const fundingExplorerUrl = input.explorerUrl || explorerUrlOrEmpty(input.chainId, input.txHash);
-    return {
-      success: true,
-      paymentId: input.paymentId,
-      txHash: input.txHash,
-      token: input.token,
-      amount: input.amount,
-      to: input.to,
-      resourceUrl: input.resourceUrl,
-      explorerUrl: input.explorerUrl,
-      accepted: input.accepted,
-      paymentHeader: input.paymentHeader,
-      merchantTo: input.merchantTo ?? input.accepted.payTo,
-      payer: input.payer,
-      chainId: input.chainId,
-      haven: {
-        paymentId: input.paymentId,
-        fundingTxHash: input.txHash,
-        fundingExplorerUrl
-      },
-      merchant: {
-        payTo: input.merchantTo ?? input.accepted.payTo
-      },
-      x402: {
-        amount: x402AuthorizationAmount(input.accepted),
-        token: input.token,
-        network: input.accepted.network,
-        asset: input.accepted.asset,
-        resource: input.accepted.resource ?? input.resourceUrl
-      }
-    };
-  }
-  async createStandardX402Header(paymentRequired, option) {
-    if (!this.delegateKey) {
-      throw new HavenSigningError("delegateKey is required to sign x402 payment headers.");
-    }
-    const account = privateKeyToAccount(this.delegateKey);
-    const requirements = toStandardPaymentRequirements(paymentRequired, option);
-    const header = await exact.evm.createPaymentHeader(
-      account,
-      paymentRequired.x402Version,
-      requirements
-    );
-    if (paymentRequired.x402Version < 2) return header;
-    const payment = decodeBase64Json(header);
-    return encodeBase64Json({
-      x402Version: paymentRequired.x402Version,
-      accepted: option,
-      payload: payment.payload
-    });
-  }
-  cacheX402Receipt(idempotencyKey, paymentHeader, receipt) {
-    const expiresAt = getPaymentHeaderValidBefore(paymentHeader);
-    if (expiresAt > Date.now()) {
-      this.x402ReceiptCache.set(idempotencyKey, { expiresAt, receipt });
-    }
-  }
-  async recordMerchantRetryRejected(input) {
-    try {
-      await this.post("/machine-payments/reconciliation-events", {
-        paymentId: input.paymentId,
-        rail: input.rail,
-        eventType: "merchant_retry_rejected_after_payment",
-        txHash: input.txHash,
-        reason: `Merchant returned HTTP ${input.merchant.merchant_status} after Haven payment confirmation`,
-        details: {
-          resource_url: input.resourceUrl,
-          retry_status: input.merchant.merchant_status,
-          retry_body: input.merchant.merchant_body.slice(0, MERCHANT_BODY_SNIPPET_LIMIT) || null,
-          ...input.details
-        }
-      });
-    } catch {
-    }
-  }
-  async reportMachinePaymentEvidence(input) {
-    try {
-      await this.post("/machine-payments/evidence", {
-        paymentId: input.paymentId,
-        rail: input.rail,
-        txHash: input.txHash,
-        resourceUrl: input.resourceUrl,
-        merchantStatus: input.merchantStatus,
-        challengePayload: input.challengePayload,
-        selectedPayment: input.selectedPayment,
-        paymentProofHeaderName: input.paymentProofHeaderName,
-        paymentProofHeader: input.paymentProofHeader,
-        protocolReceiptHeaderName: input.protocolReceiptHeaderName,
-        protocolReceiptHeader: input.protocolReceiptHeader,
-        protocolReceiptPayload: input.protocolReceiptHeader ? parseProtocolReceiptHeader(input.protocolReceiptHeader) : void 0
-      });
-    } catch {
-    }
+          handshakeRequired: raw.mcp_transport.handshake_required,
+          source: raw.mcp_transport.source
+        }
+      } : {}
+    };
   }
   /**
    * Wait for a funding tx to be mined with ≥1 confirmation before the
@@ -2890,264 +3591,9 @@ var HavenClient = class {
    * backend has already confirmed on-chain submission and callers accept the
    * small propagation window as a trade-off for not configuring an RPC URL.
    */
-  async waitForFundingTx(txHash, chainId, timeoutMs = 3e4) {
-    if (!txHash || !chainId) return;
-    const rpcUrl = this.chainRpcs[chainId];
-    if (!rpcUrl) return;
-    const provider = createJsonRpcProvider(rpcUrl);
-    const onChainReceipt = await provider.waitForTransaction(txHash, 1, timeoutMs);
-    if (!onChainReceipt || onChainReceipt.status !== 1) {
-      throw new HavenApiError(
-        "Funding tx did not confirm on-chain within the timeout window.",
-        500,
-        { txHash, chainId }
-      );
-    }
-  }
-  /**
-   * Can the delegate EOA still fund an authorization for `amountAtomic`?
-   *
-   * #1521: the only question that separates a legitimate resume (funding
-   * confirmed, merchant never paid — the delegate still holds the money) from
-   * a replayed settled payment (funding confirmed, merchant paid, delegate
-   * spent). The intent's own `status: 'confirmed'` is identical in both.
-   *
-   * The balance is asked of the CHAIN rather than of Haven's bookkeeping on
-   * purpose: the merchant-settlement evidence record is written by this SDK
-   * *after* the merchant call, so a client that dies between the two leaves
-   * the backend believing the merchant was never paid — the exact case the
-   * discriminator has to get right. The chain cannot be behind in that way.
-   *
-   * Returns `null` — never a guess — when `chainRpcs` has no entry for the
-   * chain or the read fails. Callers must treat that as "unverifiable", not
-   * as "funded".
-   */
-  async delegateCanFund(chainId, tokenAddress, amountAtomic, timeoutMs = 1e4) {
-    if (!chainId || !this.delegateAddress) return null;
-    const rpcUrl = this.chainRpcs[chainId];
-    if (!rpcUrl) return null;
-    try {
-      const provider = createJsonRpcProvider(rpcUrl);
-      const token = createErc20Contract(
-        tokenAddress,
-        ["function balanceOf(address) view returns (uint256)"],
-        provider
-      );
-      const balance = await Promise.race([
-        token.balanceOf(this.delegateAddress),
-        new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs).unref?.())
-      ]);
-      if (balance === null) return null;
-      return balance >= BigInt(amountAtomic);
-    } catch {
-      return null;
-    }
-  }
   throwIfNonSignableAuthorizationState(label, raw) {
     if (raw.status === "pending_signature") return;
-    this.throwPaymentStateError(label, raw);
-  }
-  throwPaymentStateError(label, raw) {
-    const statusCode = PAYMENT_STATE_STATUS_CODES[raw.status] ?? 502;
-    const state = this.paymentStateFromRaw(label, raw);
-    if (state) {
-      throw new HavenPaymentStateError(state.message, statusCode, state, raw);
-    }
-    if (raw.status === "pending_approval") {
-      throw new HavenApiError(
-        `${label} exceeds the on-chain allowance and was queued for owner approval (payment_id: ${raw.payment_id}).`,
-        statusCode,
-        raw
-      );
-    }
-    if (raw.status === "expired") {
-      throw new HavenApiError(
-        `${label} expired before it could be completed (payment_id: ${raw.payment_id}).`,
-        statusCode,
-        raw
-      );
-    }
-    const paymentId = raw.payment_id ? ` (payment_id: ${raw.payment_id})` : "";
-    const message = raw.error ?? `${label} ${raw.status}${paymentId}`;
-    throw new HavenApiError(message, statusCode, raw);
-  }
-  paymentStateFromRaw(label, raw) {
-    if (!raw.payment_id || !raw.status) return null;
-    const phase = raw.phase ?? phaseForStatus(raw.status);
-    const nextAction = raw.next_action ?? nextActionForStatus(raw.status);
-    if (!phase || !nextAction) return null;
-    const amount = raw.amount ?? raw.requested ?? "";
-    const token = raw.token ?? "";
-    const message = raw.message ?? raw.error ?? messageForState(label, raw.status, raw.payment_id, nextAction);
-    return {
-      paymentId: raw.payment_id,
-      kind: raw.kind === "payment_intent" ? "payment_intent" : "approval_request",
-      rail: raw.rail ?? "direct",
-      status: raw.status === "pending" ? "pending_approval" : raw.status,
-      phase,
-      nextAction,
-      amount,
-      token,
-      resourceUrl: raw.resource_url ?? null,
-      merchantAddress: raw.merchant_address ?? raw.merchant_to ?? null,
-      txHash: raw.tx_hash ?? null,
-      expiresAt: raw.expires_at ?? "",
-      chainId: raw.chain_id ?? 0,
-      message,
-      amountAtomic: raw.amount_atomic ?? raw.x402?.amount_atomic ?? raw.mpp?.amount_atomic ?? null,
-      asset: raw.asset ?? raw.x402?.asset ?? raw.mpp?.asset ?? null,
-      network: raw.network ?? raw.x402?.network ?? raw.mpp?.network ?? null,
-      description: raw.description ?? raw.x402?.description ?? raw.mpp?.description ?? null,
-      idempotencyKey: raw.idempotency_key ?? raw.x402?.idempotency_key ?? raw.mpp?.idempotency_key ?? null,
-      x402: raw.x402 ? {
-        amountAtomic: raw.x402.amount_atomic ?? raw.amount_atomic ?? null,
-        asset: raw.x402.asset ?? raw.asset ?? null,
-        network: raw.x402.network ?? raw.network ?? null,
-        resourceUrl: raw.x402.resource_url ?? raw.resource_url ?? null,
-        merchantAddress: raw.x402.merchant_address ?? raw.merchant_address ?? raw.merchant_to ?? null,
-        description: raw.x402.description ?? raw.description ?? null,
-        idempotencyKey: raw.x402.idempotency_key ?? raw.idempotency_key ?? null
-      } : void 0,
-      mpp: raw.mpp ? {
-        amountAtomic: raw.mpp.amount_atomic ?? raw.amount_atomic ?? null,
-        asset: raw.mpp.asset ?? raw.asset ?? null,
-        network: raw.mpp.network ?? raw.network ?? null,
-        resourceUrl: raw.mpp.resource_url ?? raw.resource_url ?? null,
-        merchantAddress: raw.mpp.merchant_address ?? raw.merchant_address ?? raw.merchant_to ?? null,
-        description: raw.mpp.description ?? raw.description ?? null,
-        idempotencyKey: raw.mpp.idempotency_key ?? raw.idempotency_key ?? null,
-        challengeId: raw.mpp.challenge_id ?? raw.challenge_id ?? null
-      } : void 0
-    };
-  }
-  x402PayerAddress() {
-    return this.delegateAddress ?? this.x402Wallet;
-  }
-  snapshotX402Request(url, init) {
-    return {
-      url,
-      method: init?.method ?? "GET",
-      headers: Array.from(new Headers(init?.headers).entries()),
-      body: this.snapshotRequestBody(init?.body)
-    };
-  }
-  snapshotRequestBody(body) {
-    if (body == null) return void 0;
-    if (typeof body === "string") return body;
-    if (body instanceof URLSearchParams) return body.toString();
-    throw new HavenApiError(
-      "Quote helpers can only capture resumable request bodies that are strings or URLSearchParams. For streams, blobs, or binary bodies, preserve the original request yourself and call the matching resume method with fresh init.",
-      400
-    );
-  }
-  requestInitFromSnapshot(request) {
-    return {
-      method: request.method,
-      headers: request.headers,
-      body: request.body
-    };
-  }
-  withX402Wallet(init, wallet = this.x402PayerAddress()) {
-    if (!wallet) return init;
-    const headers = new Headers(init?.headers);
-    if (!headers.has("x402-wallet")) {
-      headers.set("x402-wallet", wallet);
-    }
-    return {
-      ...init,
-      headers
-    };
-  }
-  buildX402Quote(paymentRequired, request, idempotencyKey, mcpTransport) {
-    const option = selectStandardPaymentOption(paymentRequired.accepts);
-    if (!option) {
-      throw new HavenApiError(
-        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
-        400
-      );
-    }
-    const token = resolveTokenFromAddress(option.asset, option.network);
-    return {
-      rail: "x402",
-      idempotencyKey: idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option),
-      paymentRequired,
-      accepted: option,
-      request,
-      ...mcpTransport ? { mcpTransport } : {},
-      resourceUrl: paymentRequired.resource.url,
-      description: paymentRequired.resource.description ?? option.description ?? null,
-      mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
-      amountAtomic: x402AuthorizationAmount(option),
-      amount: decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
-      token: token?.symbol ?? "USDC",
-      // #1351: null when the asset is unrecognised on this network — the
-      // `token` fallback above is a LABEL, not evidence of 6 decimals, and a
-      // human-denominated cap must fail closed rather than convert against a
-      // guess. Same resolution as `token`, so the two never disagree.
-      decimals: token?.decimals ?? null,
-      asset: option.asset,
-      network: option.network,
-      chainId: chainIdOrNull(option.network),
-      merchantAddress: option.payTo,
-      maxTimeoutSeconds: option.maxTimeoutSeconds
-    };
-  }
-  async detectX402McpTransport(url, paymentRequired, response) {
-    if (isMcpUrl(url)) {
-      return { handshakeRequired: true, source: "path" };
-    }
-    if (paymentRequired.extensions?.bazaar != null) {
-      return { handshakeRequired: true, source: "bazaar" };
-    }
-    if (await responseHasBazaarExtension(response)) {
-      return { handshakeRequired: true, source: "bazaar" };
-    }
-    return void 0;
-  }
-  buildX402ResumeState(input) {
-    const token = resolveTokenFromAddress(input.accepted.asset, input.accepted.network);
-    return {
-      rail: "x402",
-      paymentId: input.paymentId,
-      idempotencyKey: input.idempotencyKey,
-      paymentRequired: input.paymentRequired,
-      accepted: input.accepted,
-      url: input.request?.url ?? input.paymentRequired.resource.url,
-      request: input.request,
-      resourceUrl: input.paymentRequired.resource.url,
-      description: input.paymentRequired.resource.description ?? input.accepted.description ?? null,
-      amountAtomic: x402AuthorizationAmount(input.accepted),
-      amount: decimalFromUsdcAtomic(x402AuthorizationAmount(input.accepted)),
-      token: token?.symbol ?? "USDC",
-      asset: input.accepted.asset,
-      network: input.accepted.network,
-      chainId: chainIdOrNull(input.accepted.network),
-      merchantAddress: input.accepted.payTo
-    };
-  }
-  // #1328: attachResumeState's 'mpp' branch (buildMppQuote / buildMppResumeState
-  // / attachMppResumeState) is retired along with the rest of the MPP-demo
-  // client surface — every remaining caller passes rail: 'x402' only, so this
-  // is now a direct alias for attachX402ResumeState rather than a dispatcher.
-  attachResumeState(err, input) {
-    this.attachX402ResumeState(
-      err,
-      input.paymentRequired,
-      input.accepted,
-      input.idempotencyKey,
-      input.request
-    );
-  }
-  attachX402ResumeState(err, paymentRequired, accepted, idempotencyKey, request) {
-    if (!(err instanceof HavenPaymentStateError)) return;
-    if (err.state.rail !== "x402") return;
-    err.resumeState = this.buildX402ResumeState({
-      paymentId: err.state.paymentId,
-      paymentRequired,
-      accepted,
-      idempotencyKey,
-      request
-    });
+    throwPaymentStateError(label, raw);
   }
   // ── Tool Execution (for agent frameworks) ────────────────────────
   /**
@@ -3179,19 +3625,19 @@ var HavenClient = class {
           error: result.errorMessage
         };
       } catch (err) {
-        return this.toolError(err);
+        return toolError(err);
       }
     }
     if (toolName === "authorize_x402_payment") {
       const { url, payTo, amount, asset, network, description, idempotencyKey } = input;
       try {
         const receipt = await this.authorizeX402(
-          this.toolX402PaymentRequired({ url, payTo, amount, asset, network, description }),
+          toolX402PaymentRequired({ url, payTo, amount, asset, network, description }),
           { idempotencyKey }
         );
-        return this.x402ToolReceipt(receipt);
+        return x402ToolReceipt(receipt);
       } catch (err) {
-        return this.toolError(err);
+        return toolError(err);
       }
     }
     if (toolName === "resume_x402_payment") {
@@ -3199,12 +3645,12 @@ var HavenClient = class {
       try {
         const receipt = await this.resumeAuthorizedX402({
           paymentId: payment_id,
-          paymentRequired: this.toolX402PaymentRequired({ url, payTo, amount, asset, network, description }),
+          paymentRequired: toolX402PaymentRequired({ url, payTo, amount, asset, network, description }),
           idempotencyKey
         });
-        return this.x402ToolReceipt(receipt);
+        return x402ToolReceipt(receipt);
       } catch (err) {
-        return this.toolError(err);
+        return toolError(err);
       }
     }
     if (toolName === "get_payment_status") {
@@ -3239,302 +3685,17 @@ var HavenClient = class {
     }
     throw new Error(`Unknown tool: ${toolName}`);
   }
-  toolX402PaymentRequired(input) {
-    return {
-      x402Version: 2,
-      resource: { url: input.url, description: input.description },
-      accepts: [
-        {
-          scheme: "exact",
-          network: input.network,
-          amount: input.amount,
-          asset: input.asset,
-          payTo: input.payTo,
-          maxTimeoutSeconds: 30
-        }
-      ]
-    };
-  }
-  x402ToolReceipt(receipt) {
-    return {
-      success: true,
-      payment_id: receipt.paymentId,
-      tx_hash: receipt.txHash,
-      token: receipt.token,
-      amount: receipt.amount,
-      to: receipt.to,
-      resource_url: receipt.resourceUrl,
-      explorer_url: receipt.explorerUrl,
-      payment_header: receipt.paymentHeader,
-      merchant_to: receipt.merchantTo,
-      payer: receipt.payer,
-      chain_id: receipt.chainId,
-      haven: receipt.haven,
-      merchant: receipt.merchant,
-      x402: receipt.x402
-    };
-  }
-  toolError(err) {
-    if (err instanceof HavenPaymentStateError) {
-      return {
-        success: false,
-        payment_id: err.state.paymentId,
-        kind: err.state.kind,
-        rail: err.state.rail,
-        status: err.state.status,
-        phase: err.state.phase,
-        next_action: err.state.nextAction,
-        tx_hash: err.state.txHash,
-        token: err.state.token,
-        amount: err.state.amount,
-        resource_url: err.state.resourceUrl,
-        merchant_address: err.state.merchantAddress,
-        amount_atomic: err.state.amountAtomic,
-        asset: err.state.asset,
-        network: err.state.network,
-        description: err.state.description,
-        idempotency_key: err.state.idempotencyKey,
-        x402: err.state.x402 ? {
-          amount_atomic: err.state.x402.amountAtomic,
-          asset: err.state.x402.asset,
-          network: err.state.x402.network,
-          resource_url: err.state.x402.resourceUrl,
-          merchant_address: err.state.x402.merchantAddress,
-          description: err.state.x402.description,
-          idempotency_key: err.state.x402.idempotencyKey
-        } : void 0,
-        mpp: err.state.mpp ? {
-          amount_atomic: err.state.mpp.amountAtomic,
-          asset: err.state.mpp.asset,
-          network: err.state.mpp.network,
-          resource_url: err.state.mpp.resourceUrl,
-          merchant_address: err.state.mpp.merchantAddress,
-          description: err.state.mpp.description,
-          idempotency_key: err.state.mpp.idempotencyKey,
-          challenge_id: err.state.mpp.challengeId
-        } : void 0,
-        resume_state: err.resumeState,
-        expires_at: err.state.expiresAt,
-        chain_id: err.state.chainId,
-        message: err.state.message,
-        error: err.message
-      };
-    }
-    if (err instanceof HavenApiError) {
-      return {
-        success: false,
-        status_code: err.statusCode,
-        error: err.message,
-        body: err.body
-      };
-    }
-    return {
-      success: false,
-      error: err instanceof Error ? err.message : String(err)
-    };
-  }
   // ── HTTP Helpers ─────────────────────────────────────────────────
   async post(path, body) {
-    return this.request("POST", path, body);
+    return this.havenApi.post(path, body);
   }
   async get(path) {
-    return this.request("GET", path);
-  }
-  /**
-   * #1300: every MERCHANT-facing fetch goes through here. Haven API calls
-   * have always been bounded (request() below); the merchant probes/retries
-   * called globalThis.fetch bare, so a slow-loris merchant could hold a tool
-   * call open forever. A caller-supplied signal still applies (combined via
-   * AbortSignal.any); a timeout abort surfaces as a clear HavenApiError 504
-   * naming the URL rather than a bare AbortError.
-   */
-  async merchantFetch(url, init = {}, timeoutMs = this.merchantTimeout) {
-    const timeoutSignal = AbortSignal.timeout(timeoutMs);
-    const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
-    try {
-      return await globalThis.fetch(url, { ...init, signal });
-    } catch (err) {
-      if (timeoutSignal.aborted) {
-        throw new MerchantTimeoutError(`Merchant request timed out after ${timeoutMs}ms: ${url}`);
-      }
-      throw err;
-    }
-  }
-  async request(method, path, body) {
-    const url = `${this.baseUrl}${path}`;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), this.requestTimeout);
-    try {
-      const contextHeaders = this.requestContext.getStore()?.headers ?? {};
-      const res = await fetch(url, {
-        method,
-        headers: {
-          "Content-Type": "application/json",
-          "Authorization": `Bearer ${this.apiKey}`,
-          ...this.defaultHeaders,
-          ...contextHeaders
-        },
-        body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      const data = await res.json();
-      if (!res.ok) {
-        const record = data;
-        const errorText = typeof record.error === "string" ? record.error : void 0;
-        const rawDetails = record.details ?? record.detail;
-        const detailsText = typeof rawDetails === "string" ? rawDetails : rawDetails != null ? JSON.stringify(rawDetails) : void 0;
-        const message = errorText && detailsText ? `${errorText}: ${detailsText}` : errorText ?? detailsText ?? `API request failed`;
-        throw new HavenApiError(message, res.status, data);
-      }
-      return data;
-    } catch (err) {
-      if (err instanceof HavenApiError) throw err;
-      if (err instanceof Error && err.name === "AbortError") {
-        throw new HavenApiError(`Request to ${path} timed out`, 408);
-      }
-      throw new HavenApiError(
-        `Request to ${path} failed: ${err instanceof Error ? err.message : String(err)}`,
-        0
-      );
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-  // ── Mapping Helpers ──────────────────────────────────────────────
-  mapPaymentResult(raw) {
-    return {
-      paymentId: raw.payment_id,
-      status: raw.status,
-      token: raw.token,
-      amount: raw.amount,
-      to: raw.to,
-      txHash: raw.tx_hash,
-      errorMessage: raw.error_message,
-      explorerUrl: raw.explorer_url ?? (raw.tx_hash ? buildExplorerUrl(raw.chain_id, raw.tx_hash) : null),
-      fee: raw.fee ? {
-        amount: raw.fee.amount,
-        token: raw.fee.token,
-        basisPoints: raw.fee.basis_points,
-        applied: raw.fee.applied
-      } : null,
-      createdAt: raw.created_at,
-      signedAt: raw.signed_at,
-      submittedAt: raw.submitted_at,
-      confirmedAt: raw.confirmed_at,
-      expiresAt: raw.expires_at
-    };
-  }
-  mapPaymentStatusResult(raw) {
-    return {
-      paymentId: raw.payment_id,
-      kind: raw.kind,
-      rail: raw.rail,
-      status: raw.status,
-      phase: raw.phase,
-      nextAction: raw.next_action,
-      amount: raw.amount,
-      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,
-      message: raw.message,
-      fee: raw.fee ? {
-        amount: raw.fee.amount,
-        token: raw.fee.token,
-        basisPoints: raw.fee.basis_points,
-        applied: raw.fee.applied
-      } : null,
-      amountAtomic: raw.amount_atomic ?? raw.x402?.amount_atomic ?? null,
-      asset: raw.asset ?? raw.x402?.asset ?? null,
-      network: raw.network ?? raw.x402?.network ?? null,
-      description: raw.description ?? raw.x402?.description ?? null,
-      idempotencyKey: raw.idempotency_key ?? raw.x402?.idempotency_key ?? null,
-      x402: raw.x402 ? {
-        amountAtomic: raw.x402.amount_atomic ?? raw.amount_atomic ?? null,
-        asset: raw.x402.asset ?? raw.asset ?? null,
-        network: raw.x402.network ?? raw.network ?? null,
-        resourceUrl: raw.x402.resource_url ?? raw.resource_url,
-        merchantAddress: raw.x402.merchant_address ?? raw.merchant_address,
-        description: raw.x402.description ?? raw.description ?? null,
-        idempotencyKey: raw.x402.idempotency_key ?? raw.idempotency_key ?? null
-      } : void 0
-    };
-  }
-  mapPaymentReceipt(raw) {
-    const receipt = {
-      id: raw.id,
-      paymentId: raw.payment_id,
-      rail: raw.rail,
-      proofStatus: raw.proof_status,
-      txHash: raw.tx_hash,
-      chainId: raw.chain_id,
-      resourceUrl: raw.resource_url,
-      merchantAddress: raw.merchant_address,
-      payerAddress: raw.payer_address,
-      settlementAddress: raw.settlement_address,
-      tokenSymbol: raw.token_symbol,
-      tokenAddress: raw.token_address,
-      amountRaw: raw.amount_raw,
-      amount: raw.amount_human,
-      challengeId: raw.challenge_id,
-      idempotencyKey: raw.idempotency_key,
-      challengePayload: raw.challenge_payload,
-      selectedPayment: raw.selected_payment,
-      paymentProofHeaderName: raw.payment_proof_header_name,
-      protocolReceiptHeaderName: raw.protocol_receipt_header_name,
-      protocolReceiptPayload: raw.protocol_receipt_payload,
-      merchantStatus: raw.merchant_status,
-      confirmedAt: raw.confirmed_at,
-      createdAt: raw.created_at,
-      updatedAt: raw.updated_at
-    };
-    if ("payment_intent_id" in raw) {
-      receipt.paymentIntentId = raw.payment_intent_id ?? null;
-    }
-    if ("approval_request_id" in raw) {
-      receipt.approvalRequestId = raw.approval_request_id ?? null;
-    }
-    return receipt;
+    return this.havenApi.get(path);
   }
 };
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function getPaymentHeaderValidBefore(paymentHeader) {
-  try {
-    const payment = decodeBase64Json(
-      paymentHeader
-    );
-    const payload = payment.payload;
-    const validBeforeSeconds = Number(payload.authorization?.validBefore);
-    if (Number.isFinite(validBeforeSeconds)) return validBeforeSeconds * 1e3;
-  } catch {
-  }
-  return 0;
-}
-function parseProtocolReceiptHeader(value) {
-  try {
-    return decodeBase64Json(value);
-  } catch {
-    try {
-      return JSON.parse(value);
-    } catch {
-      return void 0;
-    }
-  }
-}
-async function captureMerchantResponse(response) {
-  const merchant_body = await response.text().catch(() => "");
-  return {
-    merchant_status: response.status,
-    merchant_status_text: response.statusText,
-    merchant_headers: Object.fromEntries(response.headers.entries()),
-    merchant_body
-  };
-}
 
 // src/tool-descriptions.ts
 function composeDescription(d) {