@piprail/sdk 2.13.0 → 2.14.0

package/dist/index.js

@@ -31,7 +31,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-SC2ZYDHD.js";
+} from "./chunk-PAMKCWVW.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -1780,6 +1780,37 @@ function buildReceiptExtension(bundle) {
   if (bundle.attestation) info.receipt = bundle.attestation;
   return { [EXT_OFFER_RECEIPT]: { info } };
 }
+var EXT_PAYMENT_IDENTIFIER = "payment-identifier";
+var PAYMENT_ID_MIN = 16;
+var PAYMENT_ID_MAX = 128;
+var PAYMENT_ID_RE = /^[A-Za-z0-9_-]+$/;
+function buildPaymentIdentifierAdvertisement() {
+  return {
+    [EXT_PAYMENT_IDENTIFIER]: {
+      info: { required: false },
+      schema: { properties: { id: { type: "string", minLength: PAYMENT_ID_MIN, maxLength: PAYMENT_ID_MAX } } }
+    }
+  };
+}
+function readPaymentIdentifier(payload) {
+  if (typeof payload !== "object" || payload === null) return null;
+  const ext = payload.extensions;
+  if (typeof ext !== "object" || ext === null) return null;
+  const block = ext[EXT_PAYMENT_IDENTIFIER];
+  if (typeof block !== "object" || block === null) return null;
+  const info = block.info;
+  if (typeof info !== "object" || info === null) return null;
+  const id = info.id;
+  if (id === void 0) return null;
+  if (typeof id !== "string") return { invalid: "payment-identifier id must be a string" };
+  if (id.length < PAYMENT_ID_MIN || id.length > PAYMENT_ID_MAX) {
+    return { invalid: `payment-identifier id must be ${PAYMENT_ID_MIN}\u2013${PAYMENT_ID_MAX} chars (got ${id.length})` };
+  }
+  if (!PAYMENT_ID_RE.test(id)) {
+    return { invalid: "payment-identifier id must match [A-Za-z0-9_-]" };
+  }
+  return id;
+}
 function buildSignatureHeader(signature) {
   return toBase64Json(signature);
 }
@@ -1806,7 +1837,10 @@ function parseReceipt(response) {
   const headerValue = response.headers.get(HEADER_RESPONSE) ?? response.headers.get(HEADER_RESPONSE_V1);
   if (!headerValue) return null;
   const parsed = fromBase64Json(headerValue);
-  return isValidReceipt(parsed) ? parsed : null;
+  if (!isValidReceipt(parsed)) return null;
+  const r = parsed;
+  if (typeof r.transaction !== "string" && typeof r.txHash === "string") r.transaction = r.txHash;
+  return r;
 }
 function parseReceiptExtension(response) {
   const headerValue = response.headers.get(HEADER_RESPONSE) ?? response.headers.get(HEADER_RESPONSE_V1);
@@ -1836,7 +1870,8 @@ function parseSettleResponse(response) {
   if (!parsed || typeof parsed !== "object" || typeof parsed.success !== "boolean") return null;
   return {
     success: parsed.success,
-    ...typeof parsed.transaction === "string" ? { transaction: parsed.transaction } : {},
+    // Tolerate the legacy v1 `txHash` alias for `transaction` (mirrors isValidReceipt/parseReceipt).
+    ...typeof parsed.transaction === "string" ? { transaction: parsed.transaction } : typeof parsed.txHash === "string" ? { transaction: parsed.txHash } : {},
     ...typeof parsed.network === "string" ? { network: parsed.network } : {},
     ...typeof parsed.payer === "string" ? { payer: parsed.payer } : {},
     ...typeof parsed.errorReason === "string" ? { errorReason: parsed.errorReason } : {},
@@ -1855,6 +1890,14 @@ function parseSignatureObject(parsed) {
   if (!payload || typeof payload.txHash !== "string" || typeof payload.nonce !== "string") {
     return null;
   }
+  if (!accepted) {
+    const synthesized = {
+      scheme: "onchain-proof",
+      ...typeof v.network === "string" ? { network: v.network } : {},
+      ...typeof v.asset === "string" ? { asset: v.asset } : {}
+    };
+    return { ...v, accepted: synthesized, payload };
+  }
   return parsed;
 }
 function parseSignatureHeader(value) {
@@ -1994,7 +2037,11 @@ var evmDriver = {
   resolve(opts) {
     if (typeof opts.chain === "string" && /^(solana|ton|stellar)/.test(opts.chain)) return null;
     if (typeof opts.chain === "string") {
-      return makeEvmNetwork(resolveChain(opts.chain, opts.rpcUrl));
+      try {
+        return makeEvmNetwork(resolveChain(opts.chain, opts.rpcUrl));
+      } catch (err) {
+        throw new UnsupportedNetworkError(err instanceof Error ? err.message : String(err), { cause: err });
+      }
     }
     let resolved;
     try {
@@ -2039,8 +2086,13 @@ function makeEvmNetwork(resolved) {
           `chain ${network} is EVM; a custom token must be { address, decimals }.`
         );
       }
+      if (!isAddress(token.address)) {
+        throw new WrongFamilyError(
+          `chain ${network} is EVM, but token address "${token.address}" is not a valid 0x address.`
+        );
+      }
       return {
-        asset: token.address,
+        asset: getAddress5(token.address),
         decimals: token.decimals,
         ...token.symbol ? { symbol: token.symbol } : {}
       };
@@ -2121,9 +2173,9 @@ function makeEvmNetwork(resolved) {
     },
     async estimateCost(accept) {
       const { decimals, symbol } = resolved.chain.nativeCurrency;
-      if (accept.scheme === "exact") {
-        const m = accept.extra.assetTransferMethod;
-        const permit2 = m === "permit2" || m === "permit2-exact";
+      if (accept.scheme === "exact" || accept.scheme === "upto") {
+        const m = accept.extra?.assetTransferMethod;
+        const permit2 = m === "permit2" || m === "permit2-exact" || m === "permit2-upto";
         return nativeCost({
           symbol,
           decimals,
@@ -2329,7 +2381,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-ELUWO6N5.js");
+      mod = await import("./solana-HITVI3HF.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -2341,7 +2393,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-7GKCTC5H.js");
+      mod = await import("./ton-5FWDQ4QR.js");
     } catch (cause) {
       throw new MissingDriverError(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
@@ -2353,7 +2405,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-ASP2THL2.js");
+      mod = await import("./stellar-2QT6YYKN.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -2365,7 +2417,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-DD7TJL5L.js");
+      mod = await import("./xrpl-UJL5J7CY.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -2377,7 +2429,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-BMCWN5SS.js");
+      mod = await import("./tron-AZDY7BMQ.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -2389,7 +2441,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-FZIKZNVI.js");
+      mod = await import("./sui-FV5L6WF5.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -2401,7 +2453,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-FZBUICCS.js");
+      mod = await import("./near-5PXTVQ47.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -2413,7 +2465,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-LY67Q6QF.js");
+      mod = await import("./aptos-DHOMTBLZ.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
@@ -2425,7 +2477,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-AA3WXKW4.js");
+      mod = await import("./algorand-6J3IABVF.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -3449,6 +3501,24 @@ var SpendLedger = class {
   }
 };
 
+// src/util/exactRecovery.ts
+function exactSettleCheckHint(family, payerFrom, nonce) {
+  switch (family) {
+    case "evm":
+      return `the EIP-3009 \`authorizationState(${payerFrom}, ${nonce})\` (or, on the Permit2 method, the Permit2 nonce bitmap)`;
+    case "solana":
+      return `the buyer's transaction signature (a duplicate signature is the chain's own replay guard; plus the SPL-Memo nonce when present)`;
+    case "algorand":
+      return `the atomic group / transaction id`;
+    case "aptos":
+      return `the sender's account sequence number`;
+    case "near":
+      return `the access-key nonce (\`${nonce}\`)`;
+    default:
+      return `the single-use marker (\`ref=${nonce}\`)`;
+  }
+}
+
 // src/client.ts
 var DEFAULT_SCHEMES = ["onchain-proof"];
 var RECIPIENT_FIX = {
@@ -4014,7 +4084,8 @@ var PipRailClient = class {
    *   before publishing, so retry with a brief backoff if a fresh listing is missing.
    * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
    *   `onchain-proof` rails by default, and standard `exact` rails too once you opt in
-   *   with `schemes: ['onchain-proof', 'exact']` (EVM EIP-3009/Permit2 + Solana SVM + Algorand).
+   *   with `schemes: ['onchain-proof', 'exact']` (EVM EIP-3009/Permit2 + Solana SVM + Algorand
+   *   + Aptos + NEAR).
    */
   async discover(opts = {}) {
     const found = await searchOpenIndexes({
@@ -4222,7 +4293,7 @@ var PipRailClient = class {
       );
       if (schemes.includes("exact") && exactOnNet && typeof net.payExact !== "function") {
         throw new UnsupportedSchemeError(
-          `This 402 offers a standard 'exact' rail on ${net.network}, but the ${net.family} family can't pay 'exact' (supported on EVM, Solana, Algorand + NEAR today), and no 'onchain-proof' rail was offered.`
+          `This 402 offers a standard 'exact' rail on ${net.network}, but the ${net.family} family can't pay 'exact' (supported on EVM, Solana, Algorand, Aptos + NEAR today), and no 'onchain-proof' rail was offered.`
         );
       }
       if (!schemes.includes("exact") && exactOnNet && typeof net.payExact === "function") {
@@ -4275,7 +4346,15 @@ var PipRailClient = class {
     if (schemes.includes("exact")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
+          (a) => a.scheme === "exact" && this.supportsNetwork(net, a.network) && typeof net.payExact === "function" && // `native` is never `exact`-payable on ANY family (exact = an EIP-3009/Permit2-style
+          // signed-authorization scheme a native coin can't support; every driver's payExact
+          // throws/returns-null for it). describeAsset('native') IS non-null (onchain-proof needs
+          // it), so without this guard a malformed 402 advertising a native `exact` rail would be
+          // gathered, planned `payable`, even chosen by autoRoute — then throw at pay time.
+          a.asset !== "native" && // the exact pay path (payExact → driver) reads `extra.assetTransferMethod`; a malformed
+          // 402 offering an exact rail for a RECOGNISED token but omitting `extra` would otherwise
+          // be planned payable then throw a raw TypeError mid-pay. Require it at gather time.
+          typeof a.extra?.assetTransferMethod === "string" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
           // signing it would build a NaN/garbage validBefore — drop it silently
           // (symmetric with an unrecognised token) rather than leak a raw SyntaxError.
           Number.isInteger(a.maxTimeoutSeconds) && a.maxTimeoutSeconds > 0
@@ -4285,7 +4364,8 @@ var PipRailClient = class {
     if (schemes.includes("upto")) {
       out.push(
         ...challenge.accepts.filter(
-          (a) => a.scheme === "upto" && this.supportsNetwork(net, a.network) && typeof net.payUpto === "function" && net.describeAsset(a.asset) != null && typeof a.extra?.facilitatorAddress === "string" && a.extra.facilitatorAddress.length > 0 && Number.isInteger(a.maxTimeoutSeconds) && a.maxTimeoutSeconds > 0
+          (a) => a.scheme === "upto" && this.supportsNetwork(net, a.network) && typeof net.payUpto === "function" && a.asset !== "native" && // native is not upto-payable either (same reason as exact)
+          net.describeAsset(a.asset) != null && typeof a.extra?.facilitatorAddress === "string" && a.extra.facilitatorAddress.length > 0 && Number.isInteger(a.maxTimeoutSeconds) && a.maxTimeoutSeconds > 0
         )
       );
     }
@@ -4760,7 +4840,7 @@ var PipRailClient = class {
   async payExactRail(net, wallet, accept, url, init, quote) {
     if (!net.payExact) {
       throw new UnsupportedSchemeError(
-        `the ${net.family} family can't pay a standard 'exact' rail (supported on EVM, Solana, Algorand + NEAR today).`
+        `the ${net.family} family can't pay a standard 'exact' rail (supported on EVM, Solana, Algorand, Aptos + NEAR today).`
       );
     }
     throwIfAborted(init?.signal);
@@ -4793,7 +4873,7 @@ var PipRailClient = class {
         response = await fetch(url, { ...init ?? {}, headers, signal });
       } catch (err) {
         throw new PaymentTimeoutError(
-          `exact: no response after submitting the authorization (nonce=${nonce}) to ${hostOf2(url)}. The facilitator may have already settled it \u2014 verify on-chain with authorizationState(${payerFrom}, ${nonce}) before re-presenting; do NOT re-pay.`,
+          `exact: no response after submitting the authorization (nonce=${nonce}) to ${hostOf2(url)}. The facilitator may have already settled it \u2014 verify on-chain via ${exactSettleCheckHint(net.family, payerFrom, nonce)} before re-presenting the SAME signed authorization; do NOT re-pay.`,
           { cause: err, ref: nonce }
         );
       } finally {
@@ -4809,7 +4889,7 @@ var PipRailClient = class {
         const receipt = parseReceipt(response);
         this.captureReceipt(response, url);
         this.safeEmit({ kind: "payment-settled", receipt, ...settle ? { settle } : {} });
-        const ref = settle?.transaction || receipt?.transaction || `eip3009-nonce:${nonce}`;
+        const ref = settle?.transaction || receipt?.transaction || `${net.family === "evm" ? "eip3009" : net.family}-nonce:${nonce}`;
         this.recordSpend(quote, ref);
         return response;
       }
@@ -4828,7 +4908,7 @@ var PipRailClient = class {
       ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
     });
     throw new MaxRetriesExceededError(
-      `exact: server still returned 402 after submitting the signed authorization (nonce=${nonce}). Last rejection: ${why}. Re-present the SAME authorization \u2014 do NOT re-sign a fresh nonce; verify authorizationState(${payerFrom}, ${nonce}) first. ref=${nonce}.`,
+      `exact: server still returned 402 after submitting the signed authorization (nonce=${nonce}). Last rejection: ${why}. Re-present the SAME authorization \u2014 do NOT re-sign a fresh nonce; verify on-chain via ${exactSettleCheckHint(net.family, payerFrom, nonce)} first. ref=${nonce}.`,
       { ref: nonce }
     );
   }
@@ -5499,8 +5579,8 @@ A 402 may offer up to three rails; you don't choose per payment \u2014 the clien
   (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.
 - exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose
   (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It
-  works on EVM, Solana + Algorand, and the on-chain method (EIP-3009 / Permit2 / SVM / Algorand
-  fee-pooled group) is picked automatically.
+  works on EVM, Solana, Algorand, Aptos + NEAR, and the on-chain method (EIP-3009 / Permit2 / SVM /
+  Algorand fee-pooled group / Aptos fee-payer / NEAR SignedDelegateAction) is picked automatically.
 - upto (the metered/variable x402 rail, opt-in, EVM): the amount you see is a MAXIMUM \u2014 you sign
   a ceiling, the server meters real usage and settles the ACTUAL (<= the max). BUDGET AGAINST THE MAX:
   the plan/policy treat the ceiling as the spend (a server may charge up to it), so a payable plan
@@ -6045,6 +6125,23 @@ function buildWellKnownX402(input) {
     ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { ownershipProofs: input.ownershipProofs } : {}
   };
 }
+function buildWellKnownX402Manifest(input) {
+  return {
+    x402Version: 2,
+    lastUpdated: input.lastUpdated ?? Math.floor(Date.now() / 1e3),
+    items: input.resources.map((r) => ({
+      resource: {
+        url: r.url,
+        ...r.description ? { description: r.description } : {},
+        ...r.mimeType ? { mimeType: r.mimeType } : {}
+      },
+      type: "http",
+      accepts: r.accepts,
+      input: { method: (r.method ?? "GET").toUpperCase() },
+      ...r.mimeType ? { output: { mimeType: r.mimeType } } : {}
+    }))
+  };
+}
 function buildX402DnsTxt(input) {
   const descriptor = input.descriptor ? `descriptor=${input.descriptor};` : "";
   return {
@@ -6775,7 +6872,7 @@ function createPaymentGate(options) {
     if (hasCustomStore) {
       return options.isUsed ? Boolean(await options.isUsed(ref)) : false;
     }
-    const key = ref.toLowerCase();
+    const key = ref.startsWith("pid:") ? ref : ref.toLowerCase();
     const now = Date.now();
     pruneUsed(now);
     if (localUsed.has(key)) return true;
@@ -6787,7 +6884,7 @@ function createPaymentGate(options) {
       if (ok && options.markUsed) await options.markUsed(ref);
       return;
     }
-    if (!ok) localUsed.delete(ref.toLowerCase());
+    if (!ok) localUsed.delete(ref.startsWith("pid:") ? ref : ref.toLowerCase());
   }
   function buildAccept(s, nonce) {
     return {
@@ -6860,6 +6957,7 @@ function createPaymentGate(options) {
     const specs = await ready();
     const nonce = genNonce();
     const bazaar = options.discovery ? { bazaar: buildBazaarExtension(options.discovery === true ? {} : options.discovery) } : void 0;
+    const paymentIdAd = options.paymentIdentifier ? buildPaymentIdentifierAdvertisement() : void 0;
     const accepts = buildAccepts(specs, nonce);
     const endpointInfo = buildEndpointInfo({
       ...options.description ? { description: options.description } : {},
@@ -6877,11 +6975,13 @@ function createPaymentGate(options) {
     const bodyPiprail = { ...selfDescribe ?? {}, ...rejectionPiprail };
     const bodyExtensions = {
       ...bazaar,
+      ...paymentIdAd,
       ...rejectionExt,
       ...Object.keys(bodyPiprail).length > 0 ? { piprail: bodyPiprail } : {}
     };
     const headerExtensions = {
       ...bazaar,
+      ...paymentIdAd,
       ...Object.keys(rejectionPiprail).length > 0 ? { piprail: rejectionPiprail } : {}
     };
     const challenge2 = {
@@ -7091,7 +7191,17 @@ function createPaymentGate(options) {
       await settleTx(ref, false);
       return rejection(result.error, result.detail);
     }
-    await settleTx(ref, true);
+    const verified = result.receipt.transaction;
+    if (verified && verified !== ref) {
+      if (await claimTx(verified)) {
+        await settleTx(ref, false);
+        return rejection("tx_already_used", `Payment ${verified} was already redeemed.`);
+      }
+      await settleTx(ref, false);
+      await settleTx(verified, true);
+    } else {
+      await settleTx(ref, true);
+    }
     await deliverOnPaid(spec, result.receipt);
     return await buildPaidResult(spec, result.receipt, sig.payload.nonce);
   }
@@ -7297,7 +7407,7 @@ function createPaymentGate(options) {
     if (result.kind === "invalid") await deliverOnFailed(result);
     return result;
   }
-  async function resolveVerdictObject(obj) {
+  async function routeVerdictObject(obj) {
     if (obj === void 0 || obj === null) return asChallenge();
     const sig = parseSignatureObject(obj);
     if (sig && sig.accepted && typeof sig.accepted.network === "string" && typeof sig.accepted.asset === "string") {
@@ -7309,6 +7419,44 @@ function createPaymentGate(options) {
     if (exact) return verifyExact(exact);
     return asChallenge();
   }
+  function echoPaymentIdentifier(result, id) {
+    try {
+      const decoded = decodeBase64Json(result.receiptHeader);
+      if (!decoded) return result;
+      const { extensions: existing, ...receiptOnly } = decoded;
+      const merged = {
+        ...existing ?? {},
+        [EXT_PAYMENT_IDENTIFIER]: { info: { required: false, id } }
+      };
+      return { ...result, receiptHeader: buildReceiptHeader(receiptOnly, merged) };
+    } catch {
+      return result;
+    }
+  }
+  async function resolveVerdictObject(obj) {
+    if (!options.paymentIdentifier) return routeVerdictObject(obj);
+    const id = readPaymentIdentifier(obj);
+    if (id !== null && typeof id === "object") {
+      return rejection("signature_invalid", `payment-identifier: ${id.invalid}.`);
+    }
+    if (id === null) return routeVerdictObject(obj);
+    const idKey = "pid:" + id;
+    if (await claimTx(idKey)) {
+      return rejection(
+        "tx_already_used",
+        `Idempotency id "${id}" is already bound to a settled payment; use a fresh id for a new payment.`
+      );
+    }
+    let result;
+    try {
+      result = await routeVerdictObject(obj);
+    } catch (err) {
+      await settleTx(idKey, false);
+      throw err;
+    }
+    await settleTx(idKey, result.kind === "paid");
+    return result.kind === "paid" ? echoPaymentIdentifier(result, id) : result;
+  }
   return { challenge, verify, verifyObject, describe, landingPage };
 }
 function requirePayment(options) {
@@ -7708,6 +7856,115 @@ function resourceUrlFromMessage(message) {
   }
   return "";
 }
+
+// src/transports/mcp-types.ts
+var MCP_PAYMENT_META_KEY = "x402/payment";
+var MCP_PAYMENT_RESPONSE_META_KEY = "x402/payment-response";
+
+// src/transports/mcp.ts
+function toMcpPaymentRequired(challenge) {
+  const text = JSON.stringify(challenge);
+  return {
+    isError: true,
+    structuredContent: challenge,
+    content: [{ type: "text", text }]
+  };
+}
+function toMcpPaymentResponse(content, receipt) {
+  return {
+    content,
+    _meta: {
+      [MCP_PAYMENT_RESPONSE_META_KEY]: {
+        success: true,
+        transaction: receipt.transaction,
+        network: receipt.network,
+        payer: receipt.payer
+      }
+    }
+  };
+}
+function fromMcpPayment(params) {
+  const meta = params?._meta?.[MCP_PAYMENT_META_KEY];
+  return meta == null ? null : meta;
+}
+function fromMcpPaymentRequired(result) {
+  if (!result || result.isError !== true) return null;
+  const sc = result.structuredContent;
+  if (sc && typeof sc === "object" && typeof sc.x402Version === "number") {
+    return sc;
+  }
+  const text = result.content?.[0]?.text;
+  if (typeof text === "string") {
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === "object" && typeof parsed.x402Version === "number") {
+        return parsed;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function isMcpPaymentRequired(result) {
+  return fromMcpPaymentRequired(result) != null;
+}
+function fromMcpPaymentResponse(result) {
+  const meta = result?._meta?.[MCP_PAYMENT_RESPONSE_META_KEY];
+  if (!meta || typeof meta !== "object") return null;
+  return meta;
+}
+function buildMcpPaymentMeta(input) {
+  return {
+    [MCP_PAYMENT_META_KEY]: {
+      x402Version: input.x402Version ?? 2,
+      ...input.resource ? { resource: input.resource } : {},
+      accepted: input.accepted,
+      payload: input.payload
+    }
+  };
+}
+function createMcpPaymentTool(options) {
+  const gate = options.gate ?? createPaymentGate(options);
+  function settlementFailed(code, detail) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `x402 settlement failed (${toA2AErrorCode(code)}): ${detail}. The buyer can retry, or pay the onchain-proof rail directly.`
+        }
+      ]
+    };
+  }
+  async function handleToolCall(params) {
+    const raw = fromMcpPayment(params);
+    if (raw == null) {
+      const { challenge } = await gate.challenge(options.resourceUrl ?? "");
+      return toMcpPaymentRequired(challenge);
+    }
+    let result;
+    try {
+      result = await gate.verifyObject(raw);
+    } catch (err) {
+      if (err instanceof SettlementError) return settlementFailed("settlement_failed", err.message);
+      throw err;
+    }
+    if (result.kind === "paid") {
+      try {
+        const content = await options.fulfill({ receipt: result.receipt, params });
+        return toMcpPaymentResponse(content, result.receipt);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return toMcpPaymentResponse(
+          [{ type: "text", text: `Payment settled (tx ${result.receipt.transaction}), but serving the result failed: ${detail}` }],
+          result.receipt
+        );
+      }
+    }
+    return toMcpPaymentRequired(result.challenge);
+  }
+  return { handleToolCall, gate };
+}
 export {
   A2A_ERROR_KEY,
   A2A_EXTENSIONS_HEADER,
@@ -7726,6 +7983,7 @@ export {
   EIP3009_TYPES,
   EXACT_NETWORK_SLUGS,
   EXT_OFFER_RECEIPT,
+  EXT_PAYMENT_IDENTIFIER,
   GENERATOR,
   HEADER_REQUIRED,
   HEADER_RESPONSE,
@@ -7735,6 +7993,8 @@ export {
   InsufficientFundsError,
   InvalidEnvelopeError,
   KNOWN_FACILITATORS,
+  MCP_PAYMENT_META_KEY,
+  MCP_PAYMENT_RESPONSE_META_KEY,
   MaxRetriesExceededError,
   MissingDriverError,
   MultiChainPayer,
@@ -7772,18 +8032,22 @@ export {
   buildEndpointInfo,
   buildExactAuthorization,
   buildExactSignatureHeader,
+  buildMcpPaymentMeta,
   buildOpenApi,
+  buildPaymentIdentifierAdvertisement,
   buildReceiptExtension,
   buildReceiptHeader,
   buildSelfDescription,
   buildSignatureHeader,
   buildUptoSignatureHeader,
   buildWellKnownX402,
+  buildWellKnownX402Manifest,
   buildX402DnsTxt,
   chainIdForExactNetwork,
   claim402IndexDomain,
   classifyChallenge,
   createA2APaymentHandler,
+  createMcpPaymentTool,
   createPaymentGate,
   decodeBase64Json,
   decorateOutcome,
@@ -7801,7 +8065,11 @@ export {
   formatSpendReport,
   fromA2APaymentPayload,
   fromA2APaymentRequired,
+  fromMcpPayment,
+  fromMcpPaymentRequired,
+  fromMcpPaymentResponse,
   getDirectoryInfo,
+  isMcpPaymentRequired,
   isPermit2ProxyChain,
   isUptoProxyChain,
   knownFacilitatorsFor,
@@ -7824,6 +8092,7 @@ export {
   planAcross,
   rankResources,
   readExactDomain,
+  readPaymentIdentifier,
   register402Index,
   registerDriver,
   registerX402Scan,
@@ -7840,5 +8109,7 @@ export {
   toA2APaymentRequired,
   toInsufficientFundsError,
   toInvalidBody,
+  toMcpPaymentRequired,
+  toMcpPaymentResponse,
   verify402IndexDomain
 };