@haven_ai/sdk 0.1.2 → 0.1.4

package/dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var async_hooks = require('async_hooks');
 var schemes = require('x402/schemes');
 var accounts = require('viem/accounts');
 var ethers = require('ethers');
@@ -8,6 +9,102 @@ var crypto = require('crypto');
 // src/client.ts
 
 // src/types.ts
+var AgentPaymentPhase = {
+  /** The agent must sign and submit the prepared payment before Haven can relay it. */
+  AgentSignatureRequired: "agent_signature_required",
+  /** Haven has received the signed payment and the agent should poll for confirmation. */
+  PaymentSubmitted: "payment_submitted",
+  /** The direct payment is confirmed; the agent does not need to do more for this payment id. */
+  PaymentConfirmed: "payment_confirmed",
+  /** The payment needs wallet owner approval in Haven before it can continue. */
+  UserApprovalRequired: "user_approval_required",
+  /** The wallet owner approved the request and still needs to complete the funding payment. */
+  UserExecutionRequired: "user_execution_required",
+  /** The funding payment was proposed and is waiting for the remaining account approvals. */
+  WaitingForAdditionalApprovals: "waiting_for_additional_approvals",
+  /** The Haven funding leg was sent; the agent can continue the merchant/protocol leg. */
+  FundingSent: "funding_sent",
+  /** The wallet owner rejected the request; the agent should stop and tell the user. */
+  Rejected: "rejected",
+  /** The payment or approval request expired before completion. */
+  Expired: "expired",
+  /** Haven could not complete the payment; the agent should stop and surface the failure. */
+  Failed: "failed"
+};
+var AgentPaymentNextAction = {
+  /** Sign with the delegate key and submit the payment to Haven. */
+  SignAndSubmitPayment: "sign_and_submit_payment",
+  /** Poll getPaymentStatus later using this payment id. */
+  CheckStatusLater: "check_status_later",
+  /** No further agent action is required for this payment id. */
+  None: "none",
+  /** Wait for the wallet owner to approve or reject the request in Haven. */
+  WaitForUserApproval: "wait_for_user_approval",
+  /** Wait for the wallet owner to finish sending the approved funding payment. */
+  WaitForUserToCompletePayment: "wait_for_user_to_complete_payment",
+  /** Resume this payment id and retry the original x402 request with the merchant payment header. */
+  RetryOriginalX402Request: "retry_original_x402_request",
+  /** Stop retrying this payment and tell the user what happened. */
+  StopAndTellUser: "stop_and_tell_user",
+  /** Ask again only if the user still wants the payment after expiry. */
+  RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it"
+};
+var AgentPaymentRail = {
+  /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
+  Direct: "direct",
+  /** x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg. */
+  X402: "x402",
+  /** Machine Payment Protocol flow. */
+  Mpp: "mpp"
+};
+var AGENT_PAYMENT_PHASE_VALUES = Object.values(AgentPaymentPhase);
+var AGENT_PAYMENT_NEXT_ACTION_VALUES = Object.values(AgentPaymentNextAction);
+var AGENT_PAYMENT_RAIL_VALUES = Object.values(AgentPaymentRail);
+var AgentPaymentPhaseDescriptions = {
+  [AgentPaymentPhase.AgentSignatureRequired]: "The agent must sign and submit the prepared payment before Haven can relay it.",
+  [AgentPaymentPhase.PaymentSubmitted]: "Haven has received the signed payment and the agent should poll for confirmation.",
+  [AgentPaymentPhase.PaymentConfirmed]: "The direct payment is confirmed; the agent does not need to do more for this payment id.",
+  [AgentPaymentPhase.UserApprovalRequired]: "The payment needs wallet owner approval in Haven before it can continue.",
+  [AgentPaymentPhase.UserExecutionRequired]: "The wallet owner approved the request and still needs to complete the funding payment.",
+  [AgentPaymentPhase.WaitingForAdditionalApprovals]: "The funding payment was proposed and is waiting for the remaining account approvals.",
+  [AgentPaymentPhase.FundingSent]: "The Haven funding leg was sent; the agent can continue the merchant/protocol leg.",
+  [AgentPaymentPhase.Rejected]: "The wallet owner rejected the request; the agent should stop and tell the user.",
+  [AgentPaymentPhase.Expired]: "The payment or approval request expired before completion.",
+  [AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure."
+};
+var AgentPaymentNextActionDescriptions = {
+  [AgentPaymentNextAction.SignAndSubmitPayment]: "Sign with the delegate key and submit the payment to Haven.",
+  [AgentPaymentNextAction.CheckStatusLater]: "Poll getPaymentStatus later using this payment id.",
+  [AgentPaymentNextAction.None]: "No further agent action is required for this payment id.",
+  [AgentPaymentNextAction.WaitForUserApproval]: "Wait for the wallet owner to approve or reject the request in Haven.",
+  [AgentPaymentNextAction.WaitForUserToCompletePayment]: "Wait for the wallet owner to finish sending the approved funding payment.",
+  [AgentPaymentNextAction.RetryOriginalX402Request]: "Resume this payment id and retry the original x402 request with the merchant payment header.",
+  [AgentPaymentNextAction.StopAndTellUser]: "Stop retrying this payment and tell the user what happened.",
+  [AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry."
+};
+var AgentPaymentRailDescriptions = {
+  [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
+  [AgentPaymentRail.X402]: "x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg.",
+  [AgentPaymentRail.Mpp]: "Machine Payment Protocol flow."
+};
+var AgentPaymentPhaseSchema = {
+  type: "string",
+  enum: AGENT_PAYMENT_PHASE_VALUES,
+  description: "Stable Haven agent payment state phase.",
+  "x-enumDescriptions": AgentPaymentPhaseDescriptions
+};
+var AgentPaymentNextActionSchema = {
+  type: "string",
+  enum: AGENT_PAYMENT_NEXT_ACTION_VALUES,
+  description: "Stable next action an agent should take for a Haven payment state.",
+  "x-enumDescriptions": AgentPaymentNextActionDescriptions
+};
+var AgentPaymentRailSchema = {
+  type: "string",
+  enum: AGENT_PAYMENT_RAIL_VALUES,
+  description: "Stable rail identifier for Haven agent payment states.",
+  "x-enumDescriptions": AgentPaymentRailDescriptions
+};
 var HavenError = class extends Error {
   constructor(message, code, statusCode, paymentId) {
     super(message);
@@ -35,6 +132,7 @@ var HavenPaymentStateError = class extends HavenApiError {
     this.name = "HavenPaymentStateError";
   }
   state;
+  resumeState;
   get status() {
     return this.state.status;
   }
@@ -162,6 +260,10 @@ var BASE_TOKENS = {
   "0x0000000000000000000000000000000000000000": { symbol: "ETH", decimals: 18 },
   "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": { symbol: "USDC", decimals: 6 }
 };
+var ALL_TOKENS = {
+  ...GNOSIS_TOKENS,
+  ...BASE_TOKENS
+};
 var NETWORK_TOKENS = {
   "eip155:100": GNOSIS_TOKENS,
   "eip155:8453": BASE_TOKENS,
@@ -273,6 +375,13 @@ function encodePaymentProof(receipt) {
   };
   return btoa(JSON.stringify(payload));
 }
+function resolveTokenFromAddress(address, network) {
+  const lower = address.toLowerCase();
+  if (network && network in NETWORK_TOKENS) {
+    return NETWORK_TOKENS[network][lower] ?? null;
+  }
+  return ALL_TOKENS[lower] ?? null;
+}
 function decodeBase64Json2(value, label) {
   try {
     return JSON.parse(atob(value));
@@ -358,6 +467,9 @@ 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) : "";
+}
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
 var DEFAULT_POLLING_INTERVAL = 3e3;
@@ -379,30 +491,33 @@ function chainIdFromNetwork(network) {
   const chainId = Number(network.slice("eip155:".length));
   return Number.isFinite(chainId) ? chainId : void 0;
 }
+function chainIdOrNull(network) {
+  return chainIdFromNetwork(network) ?? null;
+}
 function phaseForStatus(status) {
-  if (status === "pending_signature") return "agent_signature_required";
-  if (status === "submitted") return "payment_submitted";
-  if (status === "confirmed") return "payment_confirmed";
-  if (status === "pending" || status === "pending_approval") return "user_approval_required";
-  if (status === "approved") return "user_execution_required";
-  if (status === "proposed") return "waiting_for_additional_approvals";
-  if (status === "executed") return "funding_sent";
-  if (status === "rejected") return "rejected";
-  if (status === "expired") return "expired";
-  if (status === "failed") return "failed";
+  if (status === "pending_signature") return AgentPaymentPhase.AgentSignatureRequired;
+  if (status === "submitted") return AgentPaymentPhase.PaymentSubmitted;
+  if (status === "confirmed") return AgentPaymentPhase.PaymentConfirmed;
+  if (status === "pending" || status === "pending_approval") return AgentPaymentPhase.UserApprovalRequired;
+  if (status === "approved") return AgentPaymentPhase.UserExecutionRequired;
+  if (status === "proposed") return AgentPaymentPhase.WaitingForAdditionalApprovals;
+  if (status === "executed") return AgentPaymentPhase.FundingSent;
+  if (status === "rejected") return AgentPaymentPhase.Rejected;
+  if (status === "expired") return AgentPaymentPhase.Expired;
+  if (status === "failed") return AgentPaymentPhase.Failed;
   return null;
 }
 function nextActionForStatus(status) {
-  if (status === "pending_signature") return "sign_and_submit_payment";
-  if (status === "submitted") return "check_status_later";
-  if (status === "confirmed") return "none";
-  if (status === "pending" || status === "pending_approval") return "wait_for_user_approval";
-  if (status === "approved") return "wait_for_user_to_complete_payment";
-  if (status === "proposed") return "wait_for_user_approval";
-  if (status === "executed") return "retry_original_x402_request";
-  if (status === "rejected") return "stop_and_tell_user";
-  if (status === "expired") return "request_again_if_user_still_wants_it";
-  if (status === "failed") return "stop_and_tell_user";
+  if (status === "pending_signature") return AgentPaymentNextAction.SignAndSubmitPayment;
+  if (status === "submitted") return AgentPaymentNextAction.CheckStatusLater;
+  if (status === "confirmed") return AgentPaymentNextAction.None;
+  if (status === "pending" || status === "pending_approval") return AgentPaymentNextAction.WaitForUserApproval;
+  if (status === "approved") return AgentPaymentNextAction.WaitForUserToCompletePayment;
+  if (status === "proposed") return AgentPaymentNextAction.WaitForUserApproval;
+  if (status === "executed") return AgentPaymentNextAction.RetryOriginalX402Request;
+  if (status === "rejected") return AgentPaymentNextAction.StopAndTellUser;
+  if (status === "expired") return AgentPaymentNextAction.RequestAgainIfUserStillWantsIt;
+  if (status === "failed") return AgentPaymentNextAction.StopAndTellUser;
   return null;
 }
 function messageForState(label, status, paymentId, nextAction) {
@@ -420,6 +535,31 @@ function messageForState(label, status, paymentId, nextAction) {
   }
   return `${label} is ${status}; next_action=${nextAction} (payment_id: ${paymentId}).`;
 }
+function sameAddress(a, b) {
+  return Boolean(a && b && a.toLowerCase() === b.toLowerCase());
+}
+function isMppRail(rail) {
+  return rail === "mpp" || Boolean(rail?.startsWith("mpp_"));
+}
+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 };
+}
 var HavenClient = class {
   apiKey;
   delegateKey;
@@ -431,6 +571,19 @@ var HavenClient = class {
   inFlightX402 = /* @__PURE__ */ new Map();
   x402ReceiptCache = /* @__PURE__ */ new Map();
   inFlightMachinePayments = /* @__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.
+   */
+  defaultHeaders;
+  /**
+   * 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.
+   */
+  requestContext = new async_hooks.AsyncLocalStorage();
   /** Delegate address derived from the private key (if provided) */
   delegateAddress;
   constructor(config) {
@@ -441,10 +594,29 @@ var HavenClient = class {
     this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
     this.confirmationTimeout = config.confirmationTimeout ?? DEFAULT_CONFIRMATION_TIMEOUT;
     this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
+    this.defaultHeaders = { ...config.defaultHeaders ?? {} };
     if (this.delegateKey) {
       this.delegateAddress = addressFromKey(this.delegateKey);
     }
   }
+  /**
+   * Run `fn` with extra Haven-API headers scoped to the async work it
+   * performs. Used by the MCP server to tag every Haven API request that
+   * a single tool dispatch makes with `X-Haven-MCP-Tool: <name>` so the
+   * backend can write an audit-log row attributing the call.
+   *
+   * The headers are held in an `AsyncLocalStorage` so overlapping
+   * dispatches do not leak headers into each other's requests. The store
+   * inherits across `await` boundaries, so any Haven API call made while
+   * `fn` is awaiting will pick up the right headers.
+   *
+   * Has no effect on outbound merchant requests (x402 / MPP) — those
+   * never go through the internal `request<T>` path that reads the
+   * context.
+   */
+  withRequestContext(headers, fn) {
+    return this.requestContext.run({ headers: { ...headers } }, fn);
+  }
   // ── High-Level API ───────────────────────────────────────────────
   /**
    * Send a payment in one call.
@@ -539,6 +711,66 @@ var HavenClient = class {
     const raw = await this.get(`/machine-payments/${paymentId}/status`);
     return this.mapPaymentStatusResult(raw);
   }
+  /**
+   * Get the agent identity tied to this API key.
+   */
+  async getAgent() {
+    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
+    };
+  }
+  /**
+   * 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
+        }
+      }))
+    };
+  }
+  /**
+   * 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));
+  }
+  /**
+   * Rehydrate the x402/MPP resume-state bundle for a payment id.
+   *
+   * The server returns stored protocol context only. The client still signs the
+   * merchant proof locally when resumeX402Payment() or resumeMppPayment() runs.
+   */
+  async getResumeState(paymentId) {
+    return this.get(`/payments/${paymentId}/resume_state`);
+  }
   /**
    * Poll until a payment reaches a terminal status (confirmed, failed, expired).
    */
@@ -563,7 +795,7 @@ var HavenClient = class {
    *
    * Requires `delegateKey` to be set in the client config.
    */
-  async authorizeX402(paymentRequired) {
+  async authorizeX402(paymentRequired, options = {}) {
     if (!this.delegateKey) {
       throw new HavenSigningError(
         "delegateKey is required for x402 payments. Pass it in the HavenClient config."
@@ -579,7 +811,7 @@ var HavenClient = class {
         400
       );
     }
-    const idempotencyKey = buildX402IdempotencyKey(paymentRequired, option);
+    const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
     const cached = this.x402ReceiptCache.get(idempotencyKey);
     if (cached && cached.expiresAt > Date.now()) return cached.receipt;
     const inFlight = this.inFlightX402.get(idempotencyKey);
@@ -588,10 +820,62 @@ var HavenClient = class {
     this.inFlightX402.set(idempotencyKey, promise);
     try {
       return await promise;
+    } catch (err) {
+      this.attachResumeState(err, {
+        rail: "x402",
+        paymentRequired,
+        accepted: option,
+        idempotencyKey
+      });
+      throw err;
     } finally {
       this.inFlightX402.delete(idempotencyKey);
     }
   }
+  /**
+   * Probe a paid endpoint and return its x402 quote without creating a Haven
+   * 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 globalThis.fetch(url, initialInit);
+    if (response.status !== 402) {
+      throw new HavenApiError(
+        `Expected an x402 quote response with HTTP 402, got HTTP ${response.status}.`,
+        response.status || 400
+      );
+    }
+    if (response.headers.get("MACHINE-PAYMENT-CHALLENGE")) {
+      throw new HavenApiError("quoteX402 only supports standard x402 Payment Required responses.", 400);
+    }
+    const paymentRequired = await parsePaymentRequiredResponse(response);
+    return this.buildX402Quote(paymentRequired, request, options.idempotencyKey);
+  }
+  /**
+   * 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 paymentHeader = await this.createStandardX402Header(paymentRequired, option);
     const raw = await this.post("/x402", {
@@ -605,21 +889,13 @@ var HavenClient = class {
       idempotencyKey
     });
     if (raw.success && raw.tx_hash) {
-      const receipt2 = {
-        success: true,
-        paymentId: raw.payment_id,
-        txHash: raw.tx_hash,
-        token: raw.token ?? "",
-        amount: raw.amount ?? "",
-        to: raw.to ?? "",
-        resourceUrl: paymentRequired.resource.url,
-        explorerUrl: raw.explorer_url ?? (raw.tx_hash ? buildExplorerUrl(raw.chain_id, raw.tx_hash) : ""),
-        accepted: option,
-        paymentHeader,
-        merchantTo: raw.merchant_to ?? option.payTo,
-        payer: raw.payer ?? raw.safe_address,
-        chainId: raw.chain_id ?? chainIdFromNetwork(option.network)
-      };
+      const receipt2 = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw);
+      this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
+      return receipt2;
+    }
+    const state = this.paymentStateFromRaw("x402 payment", raw);
+    if (state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request) {
+      const receipt2 = this.mapX402ReceiptFromStatus(paymentRequired, option, paymentHeader, state);
       this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
       return receipt2;
     }
@@ -635,24 +911,61 @@ var HavenClient = class {
     if (execResult.status !== "confirmed") {
       this.throwPaymentStateError("x402 payment", execResult);
     }
-    const receipt = {
-      success: true,
-      paymentId: raw.payment_id,
-      txHash: execResult.tx_hash ?? "",
-      token: execResult.token ?? raw.token ?? "",
-      amount: execResult.amount ?? raw.amount ?? "",
-      to: execResult.to ?? raw.to ?? "",
-      resourceUrl: paymentRequired.resource.url,
-      explorerUrl: execResult.explorer_url ?? (execResult.tx_hash ? buildExplorerUrl(execResult.chain_id, execResult.tx_hash) : ""),
-      accepted: option,
-      paymentHeader,
-      merchantTo: option.payTo,
-      payer: raw.payer ?? raw.safe_address ?? raw.sign_data?.components.safe,
-      chainId: execResult.chain_id ?? raw.chain_id ?? chainIdFromNetwork(option.network)
-    };
+    const receipt = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult);
     this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
     return receipt;
   }
+  async resumeAuthorizedX402(input) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "delegateKey is required for x402 payments. Pass it in the HavenClient config."
+      );
+    }
+    if (!this.delegateAddress) {
+      throw new HavenSigningError("delegateAddress could not be derived from delegateKey.");
+    }
+    const option = selectStandardPaymentOption(input.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 idempotencyKey = input.idempotencyKey ?? buildX402IdempotencyKey(input.paymentRequired, option);
+    const cached = this.x402ReceiptCache.get(idempotencyKey);
+    if (cached && cached.expiresAt > Date.now()) return cached.receipt;
+    const status = await this.getPaymentStatus(input.paymentId);
+    this.assertCanResumeX402(status, input.paymentRequired, option);
+    const paymentHeader = await this.createStandardX402Header(input.paymentRequired, option);
+    const receipt = this.mapX402ReceiptFromStatus(input.paymentRequired, option, paymentHeader, status);
+    this.cacheX402Receipt(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()
+    );
+    let paymentRequired = input.paymentRequired;
+    const url = input.url ?? input.request?.url;
+    if (!paymentRequired) {
+      if (!url) {
+        throw new HavenApiError("x402 resume requires the original URL or a captured request snapshot.", 400);
+      }
+      const response = await globalThis.fetch(url, initialInit);
+      if (response.status !== 402) {
+        throw new HavenApiError("Expected the original x402 request to return HTTP 402 before resuming.", 400);
+      }
+      paymentRequired = await parsePaymentRequiredResponse(response);
+    }
+    const receipt = await this.resumeAuthorizedX402({
+      paymentId: input.paymentId,
+      paymentRequired,
+      idempotencyKey: input.idempotencyKey
+    });
+    return this.retryX402Request(url ?? paymentRequired.resource.url, initialInit, paymentRequired, receipt);
+  }
   /**
    * Fetch wrapper that automatically handles HTTP 402 responses.
    *
@@ -666,7 +979,7 @@ var HavenClient = class {
    *
    * Requires `delegateKey` to be set in the client config.
    */
-  async fetch(url, init) {
+  async fetch(url, init, options = {}) {
     const initialInit = this.withX402Wallet(init, this.x402PayerAddress());
     const response = await globalThis.fetch(url, initialInit);
     if (response.status !== 402) return response;
@@ -687,7 +1000,70 @@ var HavenClient = class {
       }
       return this.fetchWithMachinePayment(url, initialInit, challenge);
     }
-    const receipt = await this.authorizeX402(paymentRequired);
+    const request = this.snapshotX402Request(url, initialInit);
+    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;
+    }
+    return this.retryX402Request(url, initialInit, paymentRequired, receipt);
+  }
+  /**
+   * Probe a paid MPP endpoint or inspect an existing challenge without creating
+   * a Haven payment or approval request.
+   */
+  async quoteMpp(challengeOrUrl, init, options = {}) {
+    if (typeof challengeOrUrl !== "string") {
+      const request2 = this.snapshotX402Request(challengeOrUrl.resource, init);
+      return this.buildMppQuote(challengeOrUrl, request2, options.idempotencyKey);
+    }
+    const request = this.snapshotX402Request(challengeOrUrl, init);
+    const response = await globalThis.fetch(challengeOrUrl, init);
+    if (response.status !== 402) {
+      throw new HavenApiError(
+        `Expected an MPP quote response with HTTP 402, got HTTP ${response.status}.`,
+        response.status || 400
+      );
+    }
+    const challenge = await parseMachinePaymentChallengeResponse(response);
+    return this.buildMppQuote(challenge, request, options.idempotencyKey);
+  }
+  /**
+   * Pay a previously inspected MPP quote and retry the exact captured request.
+   */
+  async payMppChallenge(quote, options = {}) {
+    const idempotencyKey = options.idempotencyKey ?? quote.idempotencyKey;
+    try {
+      const receipt = await this.authorizeMachinePayment(quote.challenge, { idempotencyKey });
+      return this.retryMppRequest(
+        quote.request.url,
+        this.requestInitFromSnapshot(quote.request),
+        quote.challenge,
+        receipt
+      );
+    } catch (err) {
+      this.attachResumeState(err, {
+        rail: "mpp",
+        challenge: quote.challenge,
+        idempotencyKey,
+        request: quote.request
+      });
+      throw err;
+    }
+  }
+  async retryX402Request(url, initialInit, paymentRequired, receipt) {
     if (!receipt.accepted) {
       throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
     }
@@ -725,6 +1101,14 @@ var HavenClient = class {
         }
       );
     }
+    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",
@@ -740,7 +1124,7 @@ var HavenClient = class {
     });
     return retryResponse;
   }
-  async authorizeMachinePayment(challenge) {
+  async authorizeMachinePayment(challenge, options = {}) {
     if (!this.delegateKey) {
       throw new HavenSigningError(
         "delegateKey is required for machine payments. Pass it in the HavenClient config."
@@ -749,13 +1133,20 @@ var HavenClient = class {
     if (challenge.rail !== "mpp_demo") {
       throw new HavenApiError(`Unsupported machine payment rail: ${challenge.rail}`, 400);
     }
-    const idempotencyKey = buildMachinePaymentIdempotencyKey(challenge);
+    const idempotencyKey = options.idempotencyKey ?? buildMachinePaymentIdempotencyKey(challenge);
     const inFlight = this.inFlightMachinePayments.get(idempotencyKey);
     if (inFlight) return inFlight;
     const promise = this.authorizeMppDemoPayment(challenge, idempotencyKey);
     this.inFlightMachinePayments.set(idempotencyKey, promise);
     try {
       return await promise;
+    } catch (err) {
+      this.attachResumeState(err, {
+        rail: "mpp",
+        challenge,
+        idempotencyKey
+      });
+      throw err;
     } finally {
       this.inFlightMachinePayments.delete(idempotencyKey);
     }
@@ -782,8 +1173,56 @@ var HavenClient = class {
     }
     return this.mapMachinePaymentReceipt(challenge, raw, execResult.tx_hash, execResult);
   }
+  async resumeAuthorizedMpp(input) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "delegateKey is required for machine payments. Pass it in the HavenClient config."
+      );
+    }
+    const status = await this.getPaymentStatus(input.paymentId);
+    this.assertCanResumeMpp(status, input.challenge);
+    return this.mapMachinePaymentReceiptFromStatus(input.challenge, status);
+  }
+  async resumeMppPayment(input) {
+    const inputInit = "init" in input ? input.init : void 0;
+    const initialInit = inputInit ?? (input.request ? this.requestInitFromSnapshot(input.request) : void 0);
+    let challenge = input.challenge;
+    const url = input.url ?? input.request?.url;
+    if (!challenge) {
+      if (!url) {
+        throw new HavenApiError("MPP resume requires the original URL or a captured request snapshot.", 400);
+      }
+      const response = await globalThis.fetch(url, initialInit);
+      if (response.status !== 402) {
+        throw new HavenApiError("Expected the original MPP request to return HTTP 402 before resuming.", 400);
+      }
+      challenge = await parseMachinePaymentChallengeResponse(response);
+    }
+    const receipt = await this.resumeAuthorizedMpp({
+      paymentId: input.paymentId,
+      challenge,
+      idempotencyKey: input.idempotencyKey
+    });
+    return this.retryMppRequest(url ?? challenge.resource, initialInit, challenge, receipt);
+  }
   async fetchWithMachinePayment(url, initialInit, challenge) {
-    const receipt = await this.authorizeMachinePayment(challenge);
+    const request = this.snapshotX402Request(url, initialInit);
+    const idempotencyKey = buildMachinePaymentIdempotencyKey(challenge);
+    let receipt;
+    try {
+      receipt = await this.authorizeMachinePayment(challenge, { idempotencyKey });
+    } catch (err) {
+      this.attachResumeState(err, {
+        rail: "mpp",
+        challenge,
+        idempotencyKey,
+        request
+      });
+      throw err;
+    }
+    return this.retryMppRequest(url, initialInit, challenge, receipt);
+  }
+  async retryMppRequest(url, initialInit, challenge, receipt) {
     const retryHeaders = new Headers(initialInit?.headers);
     retryHeaders.set("MACHINE-PAYMENT-PROOF", receipt.proofHeader);
     const retryResponse = await globalThis.fetch(url, {
@@ -827,6 +1266,212 @@ var HavenClient = class {
     });
     return retryResponse;
   }
+  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 && !sameAddress(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(option.amount));
+    if (approvedAmount && approvedAmount !== requestedAmount) {
+      throw new HavenApiError(
+        "x402 resume request does not match the approved amount.",
+        409,
+        { status, selectedPayment: option },
+        status.paymentId
+      );
+    }
+  }
+  assertCanResumeMpp(status, challenge) {
+    if (!isMppRail(status.rail)) {
+      throw new HavenPaymentStateError(
+        `Payment ${status.paymentId} is ${status.rail}, not MPP.`,
+        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(
+        `MPP payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    if (status.resourceUrl && status.resourceUrl !== challenge.resource) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved resource URL.",
+        409,
+        { status, challenge },
+        status.paymentId
+      );
+    }
+    if (status.merchantAddress && !sameAddress(status.merchantAddress, challenge.recipient)) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved merchant.",
+        409,
+        { status, challenge },
+        status.paymentId
+      );
+    }
+    if (status.chainId && status.chainId !== challenge.network.chainId) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved network.",
+        409,
+        { status, challenge },
+        status.paymentId
+      );
+    }
+    if (status.token && status.token !== challenge.asset.symbol) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved token.",
+        409,
+        { status, challenge },
+        status.paymentId
+      );
+    }
+    const approvedAmount = status.amount ? normalizeDecimal(status.amount) : "";
+    const requestedAmount = normalizeDecimal(challenge.amount.display);
+    if (approvedAmount && approvedAmount !== requestedAmount) {
+      throw new HavenApiError(
+        "MPP resume request does not match the approved amount.",
+        409,
+        { status, challenge },
+        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(option.amount);
+    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(option.amount),
+      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: input.accepted.amount,
+        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.");
@@ -872,6 +1517,33 @@ var HavenClient = class {
       proofHeader: encodeMachinePaymentProof(receiptWithoutHeader)
     };
   }
+  mapMachinePaymentReceiptFromStatus(challenge, status) {
+    if (!status.txHash) {
+      throw new HavenApiError(
+        `MPP payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    const receiptWithoutHeader = {
+      success: true,
+      rail: challenge.rail,
+      paymentId: status.paymentId,
+      challengeId: challenge.challengeId,
+      txHash: status.txHash,
+      token: status.token || challenge.asset.symbol,
+      amount: status.amount || challenge.amount.display,
+      to: status.merchantAddress ?? challenge.recipient,
+      resourceUrl: status.resourceUrl ?? challenge.resource,
+      explorerUrl: explorerUrlOrEmpty(status.chainId || challenge.network.chainId, status.txHash),
+      chainId: status.chainId || challenge.network.chainId
+    };
+    return {
+      ...receiptWithoutHeader,
+      proofHeader: encodeMachinePaymentProof(receiptWithoutHeader)
+    };
+  }
   async recordMerchantRetryRejected(input) {
     try {
       await this.post("/machine-payments/reconciliation-events", {
@@ -955,16 +1627,64 @@ var HavenClient = class {
       amount,
       token,
       resourceUrl: raw.resource_url ?? null,
-      merchantAddress: raw.merchant_to ?? null,
+      merchantAddress: raw.merchant_address ?? raw.merchant_to ?? null,
       txHash: raw.tx_hash ?? null,
       expiresAt: raw.expires_at ?? "",
       chainId: raw.chain_id ?? 0,
-      message
+      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);
@@ -976,6 +1696,134 @@ var HavenClient = class {
       headers
     };
   }
+  buildX402Quote(paymentRequired, request, idempotencyKey) {
+    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,
+      resourceUrl: paymentRequired.resource.url,
+      description: paymentRequired.resource.description ?? option.description ?? null,
+      mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
+      amountAtomic: option.amount,
+      amount: decimalFromUsdcAtomic(option.amount),
+      token: token?.symbol ?? "USDC",
+      asset: option.asset,
+      network: option.network,
+      chainId: chainIdOrNull(option.network),
+      merchantAddress: option.payTo,
+      maxTimeoutSeconds: option.maxTimeoutSeconds
+    };
+  }
+  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: input.accepted.amount,
+      amount: decimalFromUsdcAtomic(input.accepted.amount),
+      token: token?.symbol ?? "USDC",
+      asset: input.accepted.asset,
+      network: input.accepted.network,
+      chainId: chainIdOrNull(input.accepted.network),
+      merchantAddress: input.accepted.payTo
+    };
+  }
+  buildMppQuote(challenge, request, idempotencyKey) {
+    return {
+      rail: "mpp",
+      paymentRail: challenge.rail,
+      idempotencyKey: idempotencyKey ?? buildMachinePaymentIdempotencyKey(challenge),
+      challenge,
+      request,
+      resourceUrl: challenge.resource,
+      description: challenge.description ?? null,
+      amountAtomic: challenge.amount.atomic,
+      amount: challenge.amount.display,
+      token: challenge.asset.symbol,
+      asset: challenge.asset.address,
+      network: challenge.network.name,
+      chainId: challenge.network.chainId,
+      merchantAddress: challenge.recipient,
+      expiresAt: challenge.expiresAt
+    };
+  }
+  buildMppResumeState(input) {
+    const quote = this.buildMppQuote(
+      input.challenge,
+      input.request ?? this.snapshotX402Request(input.challenge.resource),
+      input.idempotencyKey
+    );
+    return {
+      rail: "mpp",
+      paymentRail: quote.paymentRail,
+      paymentId: input.paymentId,
+      idempotencyKey: quote.idempotencyKey,
+      challenge: input.challenge,
+      url: input.request?.url ?? input.challenge.resource,
+      request: input.request,
+      resourceUrl: quote.resourceUrl,
+      description: quote.description,
+      amountAtomic: quote.amountAtomic,
+      amount: quote.amount,
+      token: quote.token,
+      asset: quote.asset,
+      network: quote.network,
+      chainId: quote.chainId,
+      merchantAddress: quote.merchantAddress,
+      expiresAt: quote.expiresAt
+    };
+  }
+  attachResumeState(err, input) {
+    if (input.rail === "x402") {
+      this.attachX402ResumeState(
+        err,
+        input.paymentRequired,
+        input.accepted,
+        input.idempotencyKey,
+        input.request
+      );
+      return;
+    }
+    this.attachMppResumeState(err, input.challenge, 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
+    });
+  }
+  attachMppResumeState(err, challenge, idempotencyKey, request) {
+    if (!(err instanceof HavenPaymentStateError)) return;
+    if (!isMppRail(err.state.rail)) return;
+    err.resumeState = this.buildMppResumeState({
+      paymentId: err.state.paymentId,
+      challenge,
+      idempotencyKey,
+      request
+    });
+  }
   // ── Tool Execution (for agent frameworks) ────────────────────────
   /**
    * Execute a tool call by name and input.
@@ -1010,44 +1858,34 @@ var HavenClient = class {
       }
     }
     if (toolName === "authorize_x402_payment") {
-      const { url, payTo, amount, asset, network, description } = input;
+      const { url, payTo, amount, asset, network, description, idempotencyKey } = input;
       try {
-        const receipt = await this.authorizeX402({
-          x402Version: 2,
-          resource: { url, description },
-          accepts: [
-            {
-              scheme: "exact",
-              network,
-              amount,
-              asset,
-              payTo,
-              maxTimeoutSeconds: 30
-            }
-          ]
+        const receipt = await this.authorizeX402(
+          this.toolX402PaymentRequired({ url, payTo, amount, asset, network, description }),
+          { idempotencyKey }
+        );
+        return this.x402ToolReceipt(receipt);
+      } catch (err) {
+        return this.toolError(err);
+      }
+    }
+    if (toolName === "resume_x402_payment") {
+      const { payment_id, url, payTo, amount, asset, network, description, idempotencyKey } = input;
+      try {
+        const receipt = await this.resumeAuthorizedX402({
+          paymentId: payment_id,
+          paymentRequired: this.toolX402PaymentRequired({ url, payTo, amount, asset, network, description }),
+          idempotencyKey
         });
-        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
-        };
+        return this.x402ToolReceipt(receipt);
       } catch (err) {
         return this.toolError(err);
       }
     }
     if (toolName === "authorize_machine_payment") {
-      const { challenge } = input;
+      const { challenge, idempotencyKey } = input;
       try {
-        const receipt = await this.authorizeMachinePayment(challenge);
+        const receipt = await this.authorizeMachinePayment(challenge, { idempotencyKey });
         return {
           success: true,
           payment_id: receipt.paymentId,
@@ -1082,6 +1920,13 @@ var HavenClient = class {
         amount: result.amount,
         resource_url: result.resourceUrl,
         merchant_address: result.merchantAddress,
+        amount_atomic: result.amountAtomic,
+        asset: result.asset,
+        network: result.network,
+        description: result.description,
+        idempotency_key: result.idempotencyKey,
+        x402: result.x402,
+        mpp: result.mpp,
         expires_at: result.expiresAt,
         chain_id: result.chainId,
         message: result.message
@@ -1089,6 +1934,41 @@ 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 {
@@ -1104,6 +1984,31 @@ var HavenClient = class {
         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,
@@ -1135,11 +2040,14 @@ var HavenClient = class {
     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}`
+          "Authorization": `Bearer ${this.apiKey}`,
+          ...this.defaultHeaders,
+          ...contextHeaders
         },
         body: body ? JSON.stringify(body) : void 0,
         signal: controller.signal
@@ -1196,7 +2104,50 @@ var HavenClient = class {
       txHash: raw.tx_hash,
       expiresAt: raw.expires_at,
       chainId: raw.chain_id,
-      message: raw.message
+      message: raw.message,
+      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) {
+    return {
+      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
     };
   }
 };
@@ -1297,10 +2248,52 @@ var authorizeX402Schema = {
     description: {
       type: "string",
       description: "Description of the resource being paid for"
+    },
+    idempotencyKey: {
+      type: "string",
+      description: "Stable caller-supplied key for this user intent. Reuse it when resuming after user approval."
     }
   },
   required: ["url", "payTo", "amount", "asset", "network"]
 };
+var resumeX402Schema = {
+  type: "object",
+  properties: {
+    payment_id: {
+      type: "string",
+      description: "The payment or approval request ID returned by authorize_x402_payment."
+    },
+    url: {
+      type: "string",
+      description: "The original URL that returned HTTP 402."
+    },
+    payTo: {
+      type: "string",
+      description: "Payment recipient address from the original 402 response."
+    },
+    amount: {
+      type: "string",
+      description: "Payment amount in atomic units from the original 402 response."
+    },
+    asset: {
+      type: "string",
+      description: "Token contract address from the original 402 response."
+    },
+    network: {
+      type: "string",
+      description: "CAIP-2 chain ID or x402 network from the original 402 response."
+    },
+    description: {
+      type: "string",
+      description: "Description of the resource being paid for."
+    },
+    idempotencyKey: {
+      type: "string",
+      description: "Stable caller-supplied key used for the original authorization."
+    }
+  },
+  required: ["payment_id", "url", "payTo", "amount", "asset", "network"]
+};
 var authorizeMachinePaymentSchema = {
   type: "object",
   properties: {
@@ -1313,7 +2306,8 @@ var authorizeMachinePaymentSchema = {
 };
 var MAKE_PAYMENT_DESCRIPTION = "Request and sign a payment from the user-controlled Safe within approved on-chain limits. Haven authenticates the agent, validates the signed intent, and relays the Safe AllowanceModule transaction; it does not hold keys or control funds. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
 var GET_STATUS_DESCRIPTION = "Check the status of a previously initiated payment. Accepts payment intent IDs and approval request IDs. Returns the current status, phase, next_action, transaction hash if available, and payment details.";
-var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns x402 payment requirements, use this tool to sign with the agent-owned delegate key and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, call get_payment_status later, and retry the original x402 request only when next_action is retry_original_x402_request. Do not rewrite the SDK or loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request.";
+var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns x402 payment requirements, use this tool to sign with the agent-owned delegate key and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, preserve the original merchant/MCP session and x402 details, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not start a new merchant session or loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request when doing a manual HTTP retry.";
+var RESUME_X402_DESCRIPTION = "Resume an x402 payment after the user approved it in Haven. Use this only after get_payment_status returns next_action=retry_original_x402_request. It checks the approved payment, validates the original x402 details, and returns a merchant X-PAYMENT header without creating a new approval request or merchant session.";
 var AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION = "Authorize a Haven machine-payment challenge, currently for the internal MPP demo rail. The agent signs the payment, Haven relays it within the on-chain allowance, and the tool returns a proof header for the retry request.";
 function claudeTools() {
   return [
@@ -1332,6 +2326,11 @@ function claudeTools() {
       description: AUTHORIZE_X402_DESCRIPTION,
       input_schema: authorizeX402Schema
     },
+    {
+      name: "resume_x402_payment",
+      description: RESUME_X402_DESCRIPTION,
+      input_schema: resumeX402Schema
+    },
     {
       name: "authorize_machine_payment",
       description: AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION,
@@ -1365,6 +2364,14 @@ function openaiTools() {
         parameters: authorizeX402Schema
       }
     },
+    {
+      type: "function",
+      function: {
+        name: "resume_x402_payment",
+        description: RESUME_X402_DESCRIPTION,
+        parameters: resumeX402Schema
+      }
+    },
     {
       type: "function",
       function: {
@@ -1382,6 +2389,18 @@ var havenTools = {
   openai: openaiTools
 };
 
+exports.AGENT_PAYMENT_NEXT_ACTION_VALUES = AGENT_PAYMENT_NEXT_ACTION_VALUES;
+exports.AGENT_PAYMENT_PHASE_VALUES = AGENT_PAYMENT_PHASE_VALUES;
+exports.AGENT_PAYMENT_RAIL_VALUES = AGENT_PAYMENT_RAIL_VALUES;
+exports.AgentPaymentNextAction = AgentPaymentNextAction;
+exports.AgentPaymentNextActionDescriptions = AgentPaymentNextActionDescriptions;
+exports.AgentPaymentNextActionSchema = AgentPaymentNextActionSchema;
+exports.AgentPaymentPhase = AgentPaymentPhase;
+exports.AgentPaymentPhaseDescriptions = AgentPaymentPhaseDescriptions;
+exports.AgentPaymentPhaseSchema = AgentPaymentPhaseSchema;
+exports.AgentPaymentRail = AgentPaymentRail;
+exports.AgentPaymentRailDescriptions = AgentPaymentRailDescriptions;
+exports.AgentPaymentRailSchema = AgentPaymentRailSchema;
 exports.HavenApiError = HavenApiError;
 exports.HavenClient = HavenClient;
 exports.HavenError = HavenError;