@piprail/sdk 2.13.1 → 2.14.0

package/dist/index.js

@@ -31,7 +31,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-O32N6MFN.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-VYLWFNAH.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-NNKQFQ6U.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-KBR4V77T.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-37E23W53.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-W2D5PQXV.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-BXHB6D3W.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-VDATC5AV.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-RYQOSFBQ.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-TQCYK2XT.js");
+      mod = await import("./algorand-6J3IABVF.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -4032,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({
@@ -4240,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") {
@@ -4293,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
@@ -4303,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
         )
       );
     }
@@ -5517,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
@@ -6063,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 {
@@ -6793,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;
@@ -6805,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 {
@@ -6878,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 } : {},
@@ -6895,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 = {
@@ -7109,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);
   }
@@ -7315,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") {
@@ -7327,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) {
@@ -7726,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,
@@ -7744,6 +7983,7 @@ export {
   EIP3009_TYPES,
   EXACT_NETWORK_SLUGS,
   EXT_OFFER_RECEIPT,
+  EXT_PAYMENT_IDENTIFIER,
   GENERATOR,
   HEADER_REQUIRED,
   HEADER_RESPONSE,
@@ -7753,6 +7993,8 @@ export {
   InsufficientFundsError,
   InvalidEnvelopeError,
   KNOWN_FACILITATORS,
+  MCP_PAYMENT_META_KEY,
+  MCP_PAYMENT_RESPONSE_META_KEY,
   MaxRetriesExceededError,
   MissingDriverError,
   MultiChainPayer,
@@ -7790,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,
@@ -7819,7 +8065,11 @@ export {
   formatSpendReport,
   fromA2APaymentPayload,
   fromA2APaymentRequired,
+  fromMcpPayment,
+  fromMcpPaymentRequired,
+  fromMcpPaymentResponse,
   getDirectoryInfo,
+  isMcpPaymentRequired,
   isPermit2ProxyChain,
   isUptoProxyChain,
   knownFacilitatorsFor,
@@ -7842,6 +8092,7 @@ export {
   planAcross,
   rankResources,
   readExactDomain,
+  readPaymentIdentifier,
   register402Index,
   registerDriver,
   registerX402Scan,
@@ -7858,5 +8109,7 @@ export {
   toA2APaymentRequired,
   toInsufficientFundsError,
   toInvalidBody,
+  toMcpPaymentRequired,
+  toMcpPaymentResponse,
   verify402IndexDomain
 };

package/dist/{ledger-mF_SoiDB.d.ts → ledger-uFtXlIHY.d.cts}

@@ -210,6 +210,13 @@ interface X402PaymentSignature {
         nonce: string;
         txHash: string;
     };
+    /**
+     * Optional v2 extensions the client attaches to its payload — e.g. the
+     * `payment-identifier` idempotency id at `extensions['payment-identifier'].info.id`
+     * (read by the gate via {@link readPaymentIdentifier}). A standard reader ignores it,
+     * and omitting it keeps the payload byte-identical.
+     */
+    extensions?: Record<string, unknown>;
 }
 /**
  * The EIP-3009 authorization a payer signs for a standard `exact` rail. All
@@ -590,6 +597,29 @@ declare function buildReceiptExtension(bundle: {
     decimals?: number;
     attestation?: SignedReceipt;
 }): Record<string, unknown>;
+/** The x402 extension key for the optional idempotency identifier (the official
+ *  `payment-identifier` extension). A client MAY attach a stable `id` so the server dedupes
+ *  retries and rejects a reused id bound to a DIFFERENT payment. */
+declare const EXT_PAYMENT_IDENTIFIER = "payment-identifier";
+/**
+ * Advertise the `payment-identifier` extension on a 402 challenge — PURE JSON, viem-free. The
+ * v2 `{ info, schema }` shape: `info.required:false` (PipRail never MANDATES an id) plus a
+ * JSON-Schema bound of {@link PAYMENT_ID_MIN}–{@link PAYMENT_ID_MAX} chars. A client reads this
+ * from the challenge and MAY echo an `id` back on its payload; the gate dedupes it on its
+ * existing used-proof set. The gate merges this into the challenge `extensions` (a sibling key,
+ * never inside `extensions.piprail`).
+ */
+declare function buildPaymentIdentifierAdvertisement(): Record<string, unknown>;
+/**
+ * Read + validate an inbound `payment-identifier` id from a decoded payment-payload object
+ * (`payload.extensions['payment-identifier'].info.id`). PURE, NEVER throws. Returns:
+ *  - the `id` string when present + valid (16–128 chars, `[A-Za-z0-9_-]`),
+ *  - `null` when ABSENT (the id is OPTIONAL — the gate proceeds exactly as without the feature),
+ *  - `{ invalid }` when PRESENT but malformed (the gate re-challenges so the buyer can fix it).
+ */
+declare function readPaymentIdentifier(payload: unknown): string | null | {
+    invalid: string;
+};
 declare function buildSignatureHeader(signature: X402PaymentSignature): string;
 /**
  * Build the v2 PAYMENT-SIGNATURE header value for a standard x402 `exact` payment:
@@ -928,4 +958,4 @@ declare class SpendLedger {
     summary(): SpendSummary;
 }
 
-export { parseSignatureObject as $, type AddressId as A, type X402PaymentSignature as B, type Caip2 as C, type X402Receipt as D, EXT_OFFER_RECEIPT as E, type X402ResourceObject as F, type X402UptoAcceptEntry as G, HEADER_REQUIRED as H, buildChallengeHeader as I, buildExactSignatureHeader as J, buildReceiptExtension as K, buildReceiptHeader as L, buildSignatureHeader as M, buildUptoSignatureHeader as N, decodeBase64Json as O, type PaidReceipt as P, memorySpendStore as Q, parseChallenge as R, type SettleOutcome as S, parseExactObject as T, parseExactPaymentHeader as U, type VerifyErrorCode as V, parseReceipt as W, type X402AcceptEntry as X, parseReceiptExtension as Y, parseSettleResponse as Z, parseSignatureHeader as _, type AssetId as a, parseUptoObject as a0, parseUptoPaymentHeader as a1, pickAccept as a2, type ExactAuthorizationWire as b, type ExactPaymentPayload as c, type ExactPaymentPayloadAny as d, HEADER_RESPONSE as e, HEADER_RESPONSE_V1 as f, HEADER_SIGNATURE as g, HEADER_SIGNATURE_V1 as h, type ParsedExactPayment as i, type ParsedUptoPayment as j, type Permit2Authorization as k, type Permit2PaymentPayload as l, type Permit2UptoAuthorization as m, type Permit2UptoPaymentPayload as n, type PipRailReceipt as o, type SignedReceipt as p, type SpendAssetTotal as q, type SpendDenomTotal as r, SpendLedger as s, type SpendRecord as t, type SpendStore as u, type SpendSummary as v, type VerifyResult as w, type X402AnyAccept as x, type X402Challenge as y, type X402ExactAcceptEntry as z };
+export { parseSettleResponse as $, type AddressId as A, type X402ExactAcceptEntry as B, type Caip2 as C, type X402PaymentSignature as D, EXT_OFFER_RECEIPT as E, type X402Receipt as F, type X402ResourceObject as G, HEADER_REQUIRED as H, type X402UptoAcceptEntry as I, buildChallengeHeader as J, buildExactSignatureHeader as K, buildPaymentIdentifierAdvertisement as L, buildReceiptExtension as M, buildReceiptHeader as N, buildSignatureHeader as O, type PaidReceipt as P, buildUptoSignatureHeader as Q, decodeBase64Json as R, type SettleOutcome as S, memorySpendStore as T, parseChallenge as U, type VerifyErrorCode as V, parseExactObject as W, type X402AcceptEntry as X, parseExactPaymentHeader as Y, parseReceipt as Z, parseReceiptExtension as _, type AssetId as a, parseSignatureHeader as a0, parseSignatureObject as a1, parseUptoObject as a2, parseUptoPaymentHeader as a3, pickAccept as a4, readPaymentIdentifier as a5, EXT_PAYMENT_IDENTIFIER as b, type ExactAuthorizationWire as c, type ExactPaymentPayload as d, type ExactPaymentPayloadAny as e, HEADER_RESPONSE as f, HEADER_RESPONSE_V1 as g, HEADER_SIGNATURE as h, HEADER_SIGNATURE_V1 as i, type ParsedExactPayment as j, type ParsedUptoPayment as k, type Permit2Authorization as l, type Permit2PaymentPayload as m, type Permit2UptoAuthorization as n, type Permit2UptoPaymentPayload as o, type PipRailReceipt as p, type SignedReceipt as q, type SpendAssetTotal as r, type SpendDenomTotal as s, SpendLedger as t, type SpendRecord as u, type SpendStore as v, type SpendSummary as w, type VerifyResult as x, type X402AnyAccept as y, type X402Challenge as z };