@piprail/sdk 2.13.1 → 2.14.1

package/dist/index.js

@@ -7,6 +7,7 @@ import {
 import {
   ConfirmationTimeoutError,
   InsufficientFundsError,
+  InvalidConfigError,
   InvalidEnvelopeError,
   MAX_DECIMALS,
   MaxRetriesExceededError,
@@ -31,7 +32,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-O32N6MFN.js";
+} from "./chunk-NUPCFNC5.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -1780,6 +1781,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 +1838,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 +1871,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 +1891,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 +2038,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 +2087,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 +2174,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 +2382,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-VYLWFNAH.js");
+      mod = await import("./solana-V2TGLHJ4.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 +2394,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-NNKQFQ6U.js");
+      mod = await import("./ton-PEBYBNWJ.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 +2406,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-KBR4V77T.js");
+      mod = await import("./stellar-J7VE7QP7.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -2365,7 +2418,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-37E23W53.js");
+      mod = await import("./xrpl-P2D6TS6I.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -2377,7 +2430,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-W2D5PQXV.js");
+      mod = await import("./tron-ZYJHHROT.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -2389,7 +2442,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-BXHB6D3W.js");
+      mod = await import("./sui-GMRQAAJH.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -2401,7 +2454,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-VDATC5AV.js");
+      mod = await import("./near-L2OWD7M6.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -2413,7 +2466,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-RYQOSFBQ.js");
+      mod = await import("./aptos-2FIRTMQX.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
@@ -2425,7 +2478,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-TQCYK2XT.js");
+      mod = await import("./algorand-RM7MP4PK.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -2458,7 +2511,7 @@ async function resolveNetwork2(opts) {
 }
 
 // src/indexes.ts
-var DIRECTORY_INFO = {
+var DIRECTORY_INFO = Object.freeze({
   "402index": {
     source: "402index",
     review: "probe-sync",
@@ -2486,7 +2539,7 @@ var DIRECTORY_INFO = {
     readByDiscover: true,
     caveat: "CDP Bazaar has no register endpoint \u2014 it catalogs a resource only when its own facilitator settles a payment. PipRail verifies locally with no facilitator, so a PipRail resource cannot be listed here (you can still READ Bazaar to find others). List on 402 Index or x402scan instead."
   }
-};
+});
 function getDirectoryInfo(source) {
   return DIRECTORY_INFO[source];
 }
@@ -4032,7 +4085,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({
@@ -4240,7 +4294,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") {
@@ -4293,7 +4347,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
@@ -4303,7 +4365,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
         )
       );
     }
@@ -5474,14 +5537,15 @@ function formatSpendReport(summary) {
   return `${perAsset} \u2014 grand total: ${grand}`;
 }
 function describeChallenge(challenge) {
-  const first = challenge.accepts[0];
+  const accepts = Array.isArray(challenge?.accepts) ? challenge.accepts : [];
+  const first = accepts[0];
   if (!first) {
     return `${BRAND.name} x402 payment endpoint. Pay with @piprail/sdk (${BRAND.sdkInstall}). Docs: ${BRAND.home}.`;
   }
   const extra = first.extra ?? {};
   const amount = extra.amountFormatted ?? first.amount;
   const token = extra.symbol ?? first.asset;
-  const hasExact = challenge.accepts.some((a) => a.scheme === "exact");
+  const hasExact = accepts.some((a) => a.scheme === "exact");
   const standard = hasExact ? "; or any standard x402 client (an exact rail is offered)" : "";
   return `${BRAND.name} x402 payment endpoint \u2014 pay ${amount} ${token} on ${first.network} to ${first.payTo}. Programmatic: ${BRAND.sdkInstall} then client.fetch(url)${standard}. Docs: ${BRAND.home}.`;
 }
@@ -5517,8 +5581,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
@@ -5973,12 +6037,14 @@ function paymentTools(client) {
 
 // src/classify.ts
 function classifyChallenge(challenge, opts) {
-  const accepts = challenge.accepts ?? [];
+  const accepts = Array.isArray(challenge?.accepts) ? challenge.accepts : [];
+  const network = opts?.network;
+  const schemes = opts?.schemes ?? [];
   const offeredSchemes = [...new Set(accepts.map((a) => a.scheme))];
   const offeredNetworks = [...new Set(accepts.map((a) => a.network))];
-  const onClientChain = accepts.some((a) => a.network === opts.network);
+  const onClientChain = accepts.some((a) => a.network === network);
   const payableScheme = accepts.some(
-    (a) => a.network === opts.network && opts.schemes.includes(a.scheme)
+    (a) => a.network === network && schemes.includes(a.scheme)
   );
   const verdict = accepts.length === 0 ? "NO_RAIL" : payableScheme ? "PAYABLE_RAIL" : onClientChain ? "UNPAYABLE_SCHEME" : "WRONG_CHAIN";
   return { onClientChain, payableScheme, offeredSchemes, offeredNetworks, verdict };
@@ -6063,6 +6129,29 @@ function buildWellKnownX402(input) {
     ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { ownershipProofs: input.ownershipProofs } : {}
   };
 }
+function buildWellKnownX402Manifest(input) {
+  if (!Array.isArray(input?.resources)) {
+    throw new InvalidConfigError(
+      "buildWellKnownX402Manifest: `resources` must be an array of ResourceDescription."
+    );
+  }
+  const lastUpdated = typeof input.lastUpdated === "number" && Number.isFinite(input.lastUpdated) ? input.lastUpdated : Math.floor(Date.now() / 1e3);
+  return {
+    x402Version: 2,
+    lastUpdated,
+    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 {
@@ -6655,7 +6744,7 @@ function createPaymentGate(options) {
           const net = await resolveNetwork2({ chain: a.chain, rpcUrl: a.rpcUrl ?? options.rpcUrl });
           const payTo = a.payTo ?? options.payTo;
           if (!payTo) {
-            throw new Error(
+            throw new InvalidConfigError(
               `requirePayment: no payTo for chain ${net.network}. Set it on the accept entry or pass a top-level payTo.`
             );
           }
@@ -6793,7 +6882,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;
@@ -6805,7 +6894,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 {
@@ -6878,6 +6967,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 } : {},
@@ -6895,11 +6985,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 = {
@@ -7109,7 +7201,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);
   }
@@ -7315,7 +7417,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") {
@@ -7327,6 +7429,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) {
@@ -7726,6 +7866,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,
@@ -7744,6 +7993,7 @@ export {
   EIP3009_TYPES,
   EXACT_NETWORK_SLUGS,
   EXT_OFFER_RECEIPT,
+  EXT_PAYMENT_IDENTIFIER,
   GENERATOR,
   HEADER_REQUIRED,
   HEADER_RESPONSE,
@@ -7751,8 +8001,11 @@ export {
   HEADER_SIGNATURE,
   HEADER_SIGNATURE_V1,
   InsufficientFundsError,
+  InvalidConfigError,
   InvalidEnvelopeError,
   KNOWN_FACILITATORS,
+  MCP_PAYMENT_META_KEY,
+  MCP_PAYMENT_RESPONSE_META_KEY,
   MaxRetriesExceededError,
   MissingDriverError,
   MultiChainPayer,
@@ -7790,18 +8043,22 @@ export {
   buildEndpointInfo,
   buildExactAuthorization,
   buildExactSignatureHeader,
+  buildMcpPaymentMeta,
   buildOpenApi,
+  buildPaymentIdentifierAdvertisement,
   buildReceiptExtension,
   buildReceiptHeader,
   buildSelfDescription,
   buildSignatureHeader,
   buildUptoSignatureHeader,
   buildWellKnownX402,
+  buildWellKnownX402Manifest,
   buildX402DnsTxt,
   chainIdForExactNetwork,
   claim402IndexDomain,
   classifyChallenge,
   createA2APaymentHandler,
+  createMcpPaymentTool,
   createPaymentGate,
   decodeBase64Json,
   decorateOutcome,
@@ -7819,7 +8076,11 @@ export {
   formatSpendReport,
   fromA2APaymentPayload,
   fromA2APaymentRequired,
+  fromMcpPayment,
+  fromMcpPaymentRequired,
+  fromMcpPaymentResponse,
   getDirectoryInfo,
+  isMcpPaymentRequired,
   isPermit2ProxyChain,
   isUptoProxyChain,
   knownFacilitatorsFor,
@@ -7842,6 +8103,7 @@ export {
   planAcross,
   rankResources,
   readExactDomain,
+  readPaymentIdentifier,
   register402Index,
   registerDriver,
   registerX402Scan,
@@ -7858,5 +8120,7 @@ export {
   toA2APaymentRequired,
   toInsufficientFundsError,
   toInvalidBody,
+  toMcpPaymentRequired,
+  toMcpPaymentResponse,
   verify402IndexDomain
 };