@haven_ai/sdk 0.1.2 → 0.1.3

package/README.md

@@ -97,8 +97,13 @@ Production merchant acceptance, facilitator, settlement, fiat, or acquiring func
 Haven natively supports the [x402](https://x402.org) payment protocol. When an API returns HTTP 402, the SDK evaluates the challenge against the agent's approved limits, uses the configured delegate key for the required signature, and retries automatically:
 
 ```typescript
-// Automatic — fetch() intercepts 402, pays, and retries
-const response = await haven.fetch('https://paid-api.example.com/data')
+// Automatic — fetch() intercepts 402, pays, and retries.
+// Use a stable idempotencyKey when one user intent may need manual approval.
+const response = await haven.fetch(
+  'https://paid-api.example.com/data',
+  undefined,
+  { idempotencyKey: 'paid-api-data-2026-05-22' },
+)
 const data = await response.json()
 
 // Manual — parse and authorize the 402 yourself
@@ -107,7 +112,9 @@ import { parsePaymentRequiredResponse } from '@haven_ai/sdk'
 const apiResponse = await fetch('https://paid-api.example.com/data')
 if (apiResponse.status === 402) {
   const paymentRequired = await parsePaymentRequiredResponse(apiResponse)
-  const receipt = await haven.authorizeX402(paymentRequired)
+  const receipt = await haven.authorizeX402(paymentRequired, {
+    idempotencyKey: 'paid-api-data-2026-05-22',
+  })
   // Retry with { 'X-PAYMENT': receipt.paymentHeader }
   console.log(receipt.explorerUrl)
 }
@@ -152,6 +159,7 @@ for (const block of response.content) {
 | `make_payment` | Request and sign a payment from the user-controlled Safe within approved limits |
 | `get_payment_status` | Check the status of a payment intent or approval request |
 | `authorize_x402_payment` | Authorize a policy-limited x402 payment and return a payment header for an HTTP 402 resource |
+| `resume_x402_payment` | Resume an approved x402 payment and return a merchant payment header without creating a duplicate approval |
 
 ## Configuration
 
@@ -179,11 +187,12 @@ Surface that to the user: the payment isn't dead, it's waiting for a human to
 sign off. Check `getPaymentStatus(payment_id)` or the `get_payment_status`
 tool later instead of retrying in a tight loop.
 
-For x402, the manual approval path has two steps. First, the user approves the
-funding movement from the Haven wallet to the agent's delegate wallet. Once
-Haven reports `next_action: 'retry_original_x402_request'`, retry the original
-paid API request so the SDK can attach the merchant x402 payment header. Do not
-rewrite the SDK while waiting for approval.
+For x402, approval resume is explicit. If `authorizeX402()` or `haven.fetch()`
+throws `HavenPaymentStateError` with `nextAction: 'wait_for_user_approval'`,
+stop and tell the user the request is waiting in Haven. Do not loop. After the
+user approves, call `getPaymentStatus(payment_id)`. When Haven reports
+`nextAction: 'retry_original_x402_request'`, call `resumeX402Payment()` with the
+same user-intent idempotency key and the original x402 details.
 
 ```typescript
 try {
@@ -197,10 +206,38 @@ try {
 
 const status = await haven.getPaymentStatus('approval-or-payment-id')
 if (status.nextAction === 'retry_original_x402_request') {
-  // Retry the original paid API request.
+  const response = await haven.resumeX402Payment({
+    paymentId: status.paymentId,
+    url: 'https://paid-api.example.com/data',
+    paymentRequired,
+    idempotencyKey: 'paid-api-data-2026-05-22',
+  })
+  const data = await response.json()
 }
 ```
 
+For manual HTTP stacks, use `resumeAuthorizedX402()` to get the merchant header
+without retrying the request for you:
+
+```typescript
+const receipt = await haven.resumeAuthorizedX402({
+  paymentId: status.paymentId,
+  paymentRequired,
+  idempotencyKey: 'paid-api-data-2026-05-22',
+})
+
+await fetch('https://paid-api.example.com/data', {
+  headers: { 'X-PAYMENT': receipt.paymentHeader! },
+})
+```
+
+For MCP/SSE x402 tools, keep the same MCP session and JSON-RPC payload where the
+merchant requires it: initialize, retain `mcp-session-id`, send the original
+`tools/call`, parse the 402 challenge, wait for approval if needed, then resume
+with the same `payment_id` and retry the original `tools/call` with
+`X-PAYMENT`. Use a stable `idempotencyKey` for the user intent so fresh merchant
+quotes or sessions do not become duplicate Haven approval requests.
+
 ## Error Handling
 
 ```typescript

package/dist/index.cjs

@@ -358,6 +358,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;
@@ -420,6 +423,28 @@ 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 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;
@@ -563,7 +588,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 +604,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);
@@ -605,21 +630,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 === "retry_original_x402_request") {
+      const receipt2 = this.mapX402ReceiptFromStatus(paymentRequired, option, paymentHeader, state);
       this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
       return receipt2;
     }
@@ -635,24 +652,53 @@ 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 initialInit = this.withX402Wallet(input.init, this.x402PayerAddress());
+    let paymentRequired = input.paymentRequired;
+    if (!paymentRequired) {
+      const response = await globalThis.fetch(input.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(input.url, initialInit, paymentRequired, receipt);
+  }
   /**
    * Fetch wrapper that automatically handles HTTP 402 responses.
    *
@@ -666,7 +712,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 +733,10 @@ var HavenClient = class {
       }
       return this.fetchWithMachinePayment(url, initialInit, challenge);
     }
-    const receipt = await this.authorizeX402(paymentRequired);
+    const receipt = await this.authorizeX402(paymentRequired, options);
+    return this.retryX402Request(url, initialInit, paymentRequired, receipt);
+  }
+  async retryX402Request(url, initialInit, paymentRequired, receipt) {
     if (!receipt.accepted) {
       throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
     }
@@ -725,6 +774,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",
@@ -827,6 +884,150 @@ 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 !== "retry_original_x402_request") {
+      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
+      );
+    }
+  }
+  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.");
@@ -1010,36 +1211,26 @@ 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);
       }
@@ -1089,6 +1280,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 {
@@ -1297,10 +1523,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 +1581,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, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not 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.";
 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 +1601,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 +1639,14 @@ function openaiTools() {
         parameters: authorizeX402Schema
       }
     },
+    {
+      type: "function",
+      function: {
+        name: "resume_x402_payment",
+        description: RESUME_X402_DESCRIPTION,
+        parameters: resumeX402Schema
+      }
+    },
     {
       type: "function",
       function: {