@piprail/sdk 2.9.0 → 2.10.0

package/dist/index.js

@@ -1,6 +1,9 @@
 import {
   memorySpendStore
 } from "./chunk-SK3CB7UA.js";
+import {
+  signReceiptEvm
+} from "./chunk-3SBTJKAG.js";
 import {
   ConfirmationTimeoutError,
   InsufficientFundsError,
@@ -71,7 +74,7 @@ function resolveNetwork(opts) {
 }
 
 // src/drivers/evm/index.ts
-import { BaseError, createPublicClient, erc20Abi as erc20Abi4, getAddress as getAddress4, http as http2, isAddress } from "viem";
+import { BaseError, createPublicClient, erc20Abi as erc20Abi4, getAddress as getAddress5, http as http2, isAddress } from "viem";
 
 // src/drivers/evm/chains.ts
 import { defineChain } from "viem";
@@ -1357,6 +1360,361 @@ async function verifyAndSettlePermit2Evm(input) {
   };
 }
 
+// src/drivers/evm/upto.ts
+import {
+  getAddress as getAddress4,
+  recoverTypedDataAddress as recoverTypedDataAddress3
+} from "viem";
+var X402_UPTO_PERMIT2_PROXY = "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002";
+var UPTO_PROXY_CHAIN_IDS = /* @__PURE__ */ new Set([
+  1,
+  // Ethereum
+  8453,
+  // Base
+  42161,
+  // Arbitrum
+  10,
+  // Optimism
+  137,
+  // Polygon
+  56
+  // BNB
+]);
+function isUptoProxyChain(chainId) {
+  return UPTO_PROXY_CHAIN_IDS.has(chainId);
+}
+var PERMIT2_UPTO_WITNESS_TYPES = {
+  PermitWitnessTransferFrom: PERMIT2_WITNESS_TYPES.PermitWitnessTransferFrom,
+  TokenPermissions: PERMIT2_WITNESS_TYPES.TokenPermissions,
+  Witness: [
+    { name: "to", type: "address" },
+    { name: "facilitator", type: "address" },
+    { name: "validAfter", type: "uint256" }
+  ]
+};
+var x402UptoProxyAbi = [
+  {
+    type: "function",
+    name: "settle",
+    stateMutability: "nonpayable",
+    outputs: [],
+    inputs: [
+      {
+        name: "permit",
+        type: "tuple",
+        components: [
+          {
+            name: "permitted",
+            type: "tuple",
+            components: [
+              { name: "token", type: "address" },
+              { name: "amount", type: "uint256" }
+            ]
+          },
+          { name: "nonce", type: "uint256" },
+          { name: "deadline", type: "uint256" }
+        ]
+      },
+      { name: "amount", type: "uint256" },
+      { name: "owner", type: "address" },
+      {
+        name: "witness",
+        type: "tuple",
+        components: [
+          { name: "to", type: "address" },
+          { name: "facilitator", type: "address" },
+          { name: "validAfter", type: "uint256" }
+        ]
+      },
+      { name: "signature", type: "bytes" }
+    ]
+  }
+];
+function shorten3(msg) {
+  const oneLine = msg.replace(/\s+/g, " ").trim();
+  return oneLine.length > 200 ? `${oneLine.slice(0, 200)}\u2026` : oneLine;
+}
+function randomPermit2Nonce2() {
+  const g = globalThis.crypto;
+  if (!g?.getRandomValues) {
+    throw new UnsupportedSchemeError(
+      "this runtime lacks Web Crypto (globalThis.crypto.getRandomValues); the upto rail needs a CSPRNG nonce."
+    );
+  }
+  const raw = new Uint8Array(32);
+  g.getRandomValues(raw);
+  return BigInt(`0x${[...raw].map((b) => b.toString(16).padStart(2, "0")).join("")}`);
+}
+async function payUptoEvm(input) {
+  const { publicClient, walletClient, account, chainId, chain, accept } = input;
+  let code;
+  try {
+    code = await publicClient.getCode({ address: account.address });
+  } catch {
+    code = void 0;
+  }
+  if (code && code !== "0x") {
+    throw new UnsupportedSchemeError(
+      `upto buyer rail requires an EOA signer; ${account.address} is a contract / EIP-1271 / EIP-7702-delegated account. Pay via onchain-proof.`
+    );
+  }
+  const facilitatorAddress = accept.extra?.facilitatorAddress;
+  if (typeof facilitatorAddress !== "string" || facilitatorAddress.length === 0) {
+    throw new UnsupportedSchemeError(
+      `upto: the rail carries no extra.facilitatorAddress to bind into witness.facilitator \u2014 refusing to sign.`
+    );
+  }
+  const token = getAddress4(accept.asset);
+  const payTo = getAddress4(accept.payTo);
+  const facilitator = getAddress4(facilitatorAddress);
+  const value = BigInt(accept.amount);
+  const approvalTx = await ensurePermit2Allowance({
+    publicClient,
+    walletClient,
+    account,
+    chain,
+    token,
+    amount: value
+  });
+  const nonce = randomPermit2Nonce2();
+  const deadline = BigInt(Math.floor(Date.now() / 1e3) + accept.maxTimeoutSeconds);
+  const validAfter = 0n;
+  const spender = getAddress4(X402_UPTO_PERMIT2_PROXY);
+  const from = account.address;
+  const signature = await walletClient.signTypedData({
+    account,
+    domain: { name: "Permit2", chainId, verifyingContract: PERMIT2_ADDRESS },
+    types: PERMIT2_UPTO_WITNESS_TYPES,
+    primaryType: "PermitWitnessTransferFrom",
+    message: {
+      permitted: { token, amount: value },
+      spender,
+      nonce,
+      deadline,
+      witness: { to: payTo, facilitator, validAfter }
+    }
+  });
+  const permit2Authorization = {
+    permitted: { token, amount: value.toString() },
+    from,
+    spender,
+    nonce: nonce.toString(),
+    deadline: deadline.toString(),
+    witness: { to: payTo, facilitator, validAfter: validAfter.toString() }
+  };
+  return {
+    payload: { signature, permit2Authorization },
+    payerFrom: from,
+    nonce: nonce.toString(),
+    ...approvalTx ? { approvalTx } : {}
+  };
+}
+function resolveUptoRailEvm(input) {
+  const { asset, relayerAddress, proxySupported, domain } = input;
+  if (asset === "native") return null;
+  if (!proxySupported()) return null;
+  const extra = { facilitatorAddress: getAddress4(relayerAddress) };
+  if (domain) {
+    extra.name = domain.name;
+    extra.version = domain.version;
+  }
+  return { method: "permit2-upto", extra };
+}
+async function verifyAndSettleUptoEvm(input) {
+  const { publicClient, walletClient, account, chain, payload, accept, settleAmount } = input;
+  const token = getAddress4(accept.asset);
+  const payTo = getAddress4(accept.payTo);
+  const maxAmount = BigInt(accept.amount);
+  const proxy = getAddress4(X402_UPTO_PERMIT2_PROXY);
+  const relayerAddress = getAddress4(account.address);
+  let from;
+  let spender;
+  let permittedToken;
+  let witnessTo;
+  let witnessFacilitator;
+  let permittedAmount;
+  let nonce;
+  let deadline;
+  let validAfter;
+  const signature = payload.signature;
+  try {
+    const pa = payload.permit2Authorization;
+    from = getAddress4(pa.from);
+    spender = getAddress4(pa.spender);
+    permittedToken = getAddress4(pa.permitted.token);
+    witnessTo = getAddress4(pa.witness.to);
+    witnessFacilitator = getAddress4(pa.witness.facilitator);
+    permittedAmount = BigInt(pa.permitted.amount);
+    nonce = BigInt(pa.nonce);
+    deadline = BigInt(pa.deadline);
+    validAfter = BigInt(pa.witness.validAfter);
+    if (!/^0x[0-9a-fA-F]+$/.test(signature)) throw new Error("signature must be hex");
+  } catch (err) {
+    return {
+      ok: false,
+      error: "signature_invalid",
+      detail: `Malformed upto authorization: ${err instanceof Error ? err.message : String(err)}.`
+    };
+  }
+  if (witnessTo !== payTo) {
+    return { ok: false, error: "wrong_recipient", detail: `Authorization pays witness.to ${witnessTo}, not ${payTo}.` };
+  }
+  if (permittedToken !== token) {
+    return { ok: false, error: "signature_invalid", detail: `Authorization permits token ${permittedToken}, not the rail's ${token}.` };
+  }
+  if (spender !== proxy) {
+    return { ok: false, error: "signature_invalid", detail: `Authorization spender ${spender} is not the x402UptoPermit2Proxy ${proxy}; it can't be settled here.` };
+  }
+  if (witnessFacilitator !== relayerAddress) {
+    return { ok: false, error: "signature_invalid", detail: `Authorization binds facilitator ${witnessFacilitator}, not this relayer ${relayerAddress}; only the bound facilitator can settle.` };
+  }
+  if (permittedAmount < maxAmount) {
+    return { ok: false, error: "amount_too_low", detail: `Permitted (signed MAX) ${permittedAmount} is below the rail max ${maxAmount}.` };
+  }
+  if (permittedAmount > maxAmount) {
+    return { ok: false, error: "upto_settle_exceeds_max", detail: `Permitted (signed MAX) ${permittedAmount} exceeds the advertised rail max ${maxAmount}; sign exactly the ceiling.` };
+  }
+  if (settleAmount < 0n) {
+    return { ok: false, error: "upto_settle_exceeds_max", detail: `Settle amount ${settleAmount} is negative.` };
+  }
+  if (settleAmount > permittedAmount) {
+    return { ok: false, error: "upto_settle_exceeds_max", detail: `Settle amount ${settleAmount} exceeds the signed MAX ${permittedAmount}.` };
+  }
+  const now = BigInt(Math.floor(Date.now() / 1e3));
+  if (deadline <= now) {
+    return { ok: false, error: "payment_expired", detail: `Permit2 deadline ${deadline} <= now ${now}.` };
+  }
+  let fromCode;
+  try {
+    fromCode = await publicClient.getCode({ address: from });
+  } catch {
+    return { ok: false, error: "tx_not_found", detail: `Could not read code at ${from} (transient RPC) \u2014 retry.` };
+  }
+  if (!(fromCode && fromCode !== "0x")) {
+    let recovered;
+    try {
+      recovered = await recoverTypedDataAddress3({
+        domain: { name: "Permit2", chainId: chain.id, verifyingContract: PERMIT2_ADDRESS },
+        types: PERMIT2_UPTO_WITNESS_TYPES,
+        primaryType: "PermitWitnessTransferFrom",
+        message: {
+          permitted: { token: permittedToken, amount: permittedAmount },
+          spender,
+          nonce,
+          deadline,
+          witness: { to: witnessTo, facilitator: witnessFacilitator, validAfter }
+        },
+        signature
+      });
+    } catch (err) {
+      return { ok: false, error: "signature_invalid", detail: `Not a valid EIP-712 signature: ${shorten3(err instanceof Error ? err.message : String(err))}.` };
+    }
+    if (recovered !== from) {
+      return { ok: false, error: "signature_invalid", detail: `Signature recovered to ${recovered}, not the authorizer ${from}.` };
+    }
+  }
+  if (settleAmount === 0n) {
+    return {
+      ok: true,
+      receipt: {
+        scheme: "upto",
+        success: true,
+        network: accept.network,
+        transaction: "",
+        asset: accept.asset,
+        amount: "0",
+        payer: from,
+        payTo: accept.payTo,
+        verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
+  }
+  try {
+    const word = nonce >> 8n;
+    const bit = nonce & 0xffn;
+    const bitmap = await publicClient.readContract({
+      address: PERMIT2_ADDRESS,
+      abi: permit2NonceBitmapAbi,
+      functionName: "nonceBitmap",
+      args: [from, word]
+    });
+    if ((bitmap >> bit & 1n) === 1n) {
+      return { ok: false, error: "tx_already_used", detail: `Permit2 nonce ${nonce} already used or invalidated for ${from}.` };
+    }
+  } catch {
+    return { ok: false, error: "tx_not_found", detail: "Could not read the Permit2 nonce bitmap (transient RPC) \u2014 retry." };
+  }
+  const settleArgs = [
+    { permitted: { token: permittedToken, amount: permittedAmount }, nonce, deadline },
+    settleAmount,
+    from,
+    { to: witnessTo, facilitator: witnessFacilitator, validAfter },
+    signature
+  ];
+  try {
+    await publicClient.simulateContract({
+      account,
+      address: proxy,
+      abi: x402UptoProxyAbi,
+      functionName: "settle",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      args: settleArgs
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/nonce|invalidated|used/i.test(msg)) return { ok: false, error: "tx_already_used", detail: "Permit2 nonce is used or invalidated." };
+    if (/expired|deadline|too early|not yet/i.test(msg)) return { ok: false, error: "payment_expired", detail: shorten3(msg) };
+    if (/exceeds.*permitted|AmountExceeds/i.test(msg)) return { ok: false, error: "upto_settle_exceeds_max", detail: shorten3(msg) };
+    if (/facilitator|Unauthorized/i.test(msg)) return { ok: false, error: "signature_invalid", detail: shorten3(msg) };
+    if (/signature/i.test(msg)) return { ok: false, error: "signature_invalid", detail: shorten3(msg) };
+    return { ok: false, error: "tx_reverted", detail: `upto settle would revert: ${shorten3(msg)}` };
+  }
+  let txHash;
+  try {
+    txHash = await walletClient.writeContract({
+      account,
+      chain,
+      address: proxy,
+      abi: x402UptoProxyAbi,
+      functionName: "settle",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      args: settleArgs
+    });
+  } catch (err) {
+    throw new SettlementError(
+      `upto settle: the merchant relayer failed to broadcast the proxy settle (${shorten3(err instanceof Error ? err.message : String(err))}). The payer's signature is still valid and its nonce unused \u2014 fund/fix the relayer and the payer can retry.`,
+      { cause: err }
+    );
+  }
+  try {
+    const confirmations = accept.extra.minConfirmations ?? 1;
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash, confirmations });
+    if (receipt.status !== "success") {
+      return { ok: false, error: "tx_reverted", detail: `Settlement tx ${txHash} reverted on-chain.` };
+    }
+  } catch (err) {
+    throw new SettlementError(
+      `upto settle: broadcast ${txHash} but couldn't confirm it (${shorten3(err instanceof Error ? err.message : String(err))}).`,
+      { cause: err }
+    );
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "upto",
+      success: true,
+      network: accept.network,
+      transaction: txHash,
+      asset: accept.asset,
+      // The ACTUAL settled amount (≤ max) — what the buyer reads back to record metered spend.
+      amount: settleAmount.toString(),
+      payer: from,
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+
 // src/x402.ts
 var HEADER_REQUIRED = "payment-required";
 var HEADER_SIGNATURE = "payment-signature";
@@ -1390,6 +1748,9 @@ function fromBase64Json(b64) {
     return null;
   }
 }
+function decodeBase64Json(value) {
+  return fromBase64Json(value);
+}
 function toBase64Json(value) {
   return encodeBase64(JSON.stringify(value));
 }
@@ -1405,8 +1766,15 @@ function chainIdFromNetwork(network) {
 function buildChallengeHeader(challenge) {
   return toBase64Json(challenge);
 }
-function buildReceiptHeader(receipt) {
-  return toBase64Json(receipt);
+function buildReceiptHeader(receipt, extensions) {
+  return toBase64Json(extensions ? { ...receipt, extensions } : receipt);
+}
+var EXT_OFFER_RECEIPT = "offer-receipt";
+function buildReceiptExtension(bundle) {
+  const info = { settlement: bundle.receipt, resource: bundle.resource };
+  if (typeof bundle.decimals === "number") info.decimals = bundle.decimals;
+  if (bundle.attestation) info.receipt = bundle.attestation;
+  return { [EXT_OFFER_RECEIPT]: { info } };
 }
 function buildSignatureHeader(signature) {
   return toBase64Json(signature);
@@ -1414,6 +1782,9 @@ function buildSignatureHeader(signature) {
 function buildExactSignatureHeader(input) {
   return toBase64Json({ x402Version: 2, accepted: input.accepted, payload: input.payload });
 }
+function buildUptoSignatureHeader(input) {
+  return toBase64Json({ x402Version: 2, accepted: input.accepted, payload: input.payload });
+}
 async function parseChallenge(response) {
   const headerValue = response.headers.get(HEADER_REQUIRED);
   if (headerValue) {
@@ -1433,6 +1804,27 @@ function parseReceipt(response) {
   const parsed = fromBase64Json(headerValue);
   return isValidReceipt(parsed) ? parsed : null;
 }
+function parseReceiptExtension(response) {
+  const headerValue = response.headers.get(HEADER_RESPONSE) ?? response.headers.get(HEADER_RESPONSE_V1);
+  if (!headerValue) return null;
+  const parsed = fromBase64Json(headerValue);
+  if (!parsed || typeof parsed !== "object") return null;
+  const ext = parsed.extensions;
+  const block = ext?.[EXT_OFFER_RECEIPT];
+  const info = block?.info;
+  if (!info) return null;
+  const settlement = isValidReceipt(info.settlement) ? info.settlement : isValidReceipt(info.receipt) ? info.receipt : void 0;
+  if (!settlement) return null;
+  const attestation = info.receipt && info.receipt !== settlement ? info.receipt : void 0;
+  const res = info.resource;
+  return {
+    piprail: "1",
+    receipt: settlement,
+    resource: { url: res && typeof res.url === "string" ? res.url : "" },
+    ...typeof info.decimals === "number" ? { decimals: info.decimals } : {},
+    ...attestation ? { attestation } : {}
+  };
+}
 function parseSettleResponse(response) {
   const headerValue = response.headers.get(HEADER_RESPONSE) ?? response.headers.get(HEADER_RESPONSE_V1);
   if (!headerValue) return null;
@@ -1443,11 +1835,13 @@ function parseSettleResponse(response) {
     ...typeof parsed.transaction === "string" ? { transaction: parsed.transaction } : {},
     ...typeof parsed.network === "string" ? { network: parsed.network } : {},
     ...typeof parsed.payer === "string" ? { payer: parsed.payer } : {},
-    ...typeof parsed.errorReason === "string" ? { errorReason: parsed.errorReason } : {}
+    ...typeof parsed.errorReason === "string" ? { errorReason: parsed.errorReason } : {},
+    // The upto SettleResponse's REQUIRED `amount` (actual settled atomic units) — string
+    // passthrough so the upto buyer records ACTUAL, not MAX. Absent on onchain-proof/exact.
+    ...typeof parsed.amount === "string" ? { amount: parsed.amount } : {}
   };
 }
-function parseSignatureHeader(value) {
-  const parsed = fromBase64Json(value);
+function parseSignatureObject(parsed) {
   if (!parsed || typeof parsed !== "object") return null;
   const v = parsed;
   const accepted = v.accepted;
@@ -1459,8 +1853,13 @@ function parseSignatureHeader(value) {
   }
   return parsed;
 }
+function parseSignatureHeader(value) {
+  return parseSignatureObject(fromBase64Json(value));
+}
 function parseExactPaymentHeader(value) {
-  const parsed = fromBase64Json(value);
+  return parseExactObject(fromBase64Json(value));
+}
+function parseExactObject(parsed) {
   if (!parsed || typeof parsed !== "object") return null;
   const v = parsed;
   const accepted = v.accepted ?? null;
@@ -1525,6 +1924,42 @@ function parseExactPaymentHeader(value) {
   }
   return null;
 }
+function parseUptoPaymentHeader(value) {
+  return parseUptoObject(fromBase64Json(value));
+}
+function parseUptoObject(parsed) {
+  if (!parsed || typeof parsed !== "object") return null;
+  const v = parsed;
+  const accepted = v.accepted ?? null;
+  const scheme = accepted?.scheme ?? v.scheme;
+  if (scheme !== "upto") return null;
+  const network = accepted?.network ?? v.network;
+  if (typeof network !== "string") return null;
+  const payload = v.payload;
+  if (!payload || typeof payload !== "object") return null;
+  const signature = payload.signature;
+  if (typeof signature !== "string") return null;
+  const p2 = payload.permit2Authorization;
+  if (!p2 || typeof p2 !== "object") return null;
+  const permitted = p2.permitted;
+  const witness = p2.witness;
+  if (!permitted || typeof permitted !== "object" || !witness || typeof witness !== "object") return null;
+  if (typeof permitted.token !== "string" || typeof permitted.amount !== "string") return null;
+  if (typeof witness.to !== "string" || typeof witness.facilitator !== "string" || typeof witness.validAfter !== "string") {
+    return null;
+  }
+  for (const k of ["from", "spender", "nonce", "deadline"]) {
+    if (typeof p2[k] !== "string") return null;
+  }
+  const x402Version = typeof v.x402Version === "number" ? v.x402Version : 2;
+  const asset = accepted && typeof accepted.asset === "string" ? accepted.asset : void 0;
+  const base2 = { x402Version, network, ...asset ? { asset } : {}, raw: v };
+  return {
+    ...base2,
+    method: "permit2-upto",
+    payload: { signature, permit2Authorization: p2 }
+  };
+}
 function isValidChallenge(value) {
   if (!value || typeof value !== "object") return false;
   const v = value;
@@ -1537,7 +1972,7 @@ function isValidChallenge(value) {
 function isValidReceipt(value) {
   if (!value || typeof value !== "object") return false;
   const v = value;
-  if (v.scheme !== "onchain-proof" && v.scheme !== "exact") return false;
+  if (v.scheme !== "onchain-proof" && v.scheme !== "exact" && v.scheme !== "upto") return false;
   if (typeof v.transaction !== "string" && typeof v.txHash !== "string") return false;
   if (typeof v.payer !== "string") return false;
   return true;
@@ -1615,12 +2050,12 @@ function makeEvmNetwork(resolved) {
       }
       let normalized;
       try {
-        normalized = getAddress4(asset);
+        normalized = getAddress5(asset);
       } catch {
         return null;
       }
       for (const info of Object.values(resolved.tokens)) {
-        if (getAddress4(info.address) === normalized) {
+        if (getAddress5(info.address) === normalized) {
           return { symbol: info.symbol, decimals: info.decimals };
         }
       }
@@ -1720,7 +2155,7 @@ function makeEvmNetwork(resolved) {
       let token = null;
       try {
         token = await publicClient.readContract({
-          address: getAddress4(asset),
+          address: getAddress5(asset),
           abi: erc20Abi4,
           functionName: "balanceOf",
           args: [owner]
@@ -1745,6 +2180,12 @@ function makeEvmNetwork(resolved) {
         signMessage: (message) => a.walletClient.signMessage({ account: a.account, message })
       };
     },
+    // Tier-2 service-delivery attestation (EVM-only) — sign the official offer-receipt
+    // EIP-712 RECEIPT_TYPES with the bound (payTo) wallet. Chain-independent (domain
+    // chainId is hardcoded 1); viem lives in ./receipt.ts (a lazy chunk).
+    signReceipt(wallet, input) {
+      return signReceiptEvm(wallet, input);
+    },
     async verify(ref, accept) {
       return verifyEvm({
         publicClient,
@@ -1828,6 +2269,43 @@ function makeEvmNetwork(resolved) {
         payload,
         accept
       });
+    },
+    // Standard x402 `upto` (metered) rail — EVM-Permit2 ONLY. The metered sibling of the
+    // exact trio. resolveUptoRail advertises (Permit2-only, proxy-gated, relayer = facilitator);
+    // payUpto signs the MAX with witness.facilitator bound; settleUptoSelf self-settles the actual.
+    async resolveUptoRail({ asset, relayer }) {
+      const relayerAddress = relayer._native.account.address;
+      const domain = asset === "native" ? null : await readExactDomain(publicClient, asset).catch(() => null);
+      return resolveUptoRailEvm({
+        asset,
+        relayerAddress,
+        proxySupported: () => isUptoProxyChain(resolved.chainId),
+        domain
+      });
+    },
+    async payUpto(wallet, accept) {
+      const a = wallet._native;
+      const { payload, payerFrom, nonce } = await payUptoEvm({
+        publicClient,
+        walletClient: a.walletClient,
+        account: a.account,
+        chainId: resolved.chainId,
+        chain: resolved.chain,
+        accept
+      });
+      return { payload, accepted: accept, payerFrom, nonce };
+    },
+    async settleUptoSelf({ relayer, payload, accept, settleAmount }) {
+      const a = relayer._native;
+      return verifyAndSettleUptoEvm({
+        publicClient,
+        walletClient: a.walletClient,
+        account: a.account,
+        chain: resolved.chain,
+        payload,
+        accept,
+        settleAmount
+      });
     }
   };
 }
@@ -1868,7 +2346,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-BEMT7UYF.js");
+      mod = await import("./stellar-ASP2THL2.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -1892,7 +2370,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-ZZZS3FNN.js");
+      mod = await import("./tron-BMCWN5SS.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -1904,7 +2382,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-F5JQ2N6I.js");
+      mod = await import("./sui-FZIKZNVI.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -2970,6 +3448,7 @@ var RECIPIENT_FIX = {
   NOT_OPTED_IN: "the recipient must opt into this asset once (a 0-amount self-transfer)",
   INACTIVE: "the recipient account doesn't exist yet \u2014 fund it with the chain's base reserve to activate it"
 };
+var RECEIPT_VERIFY_WINDOW_SECONDS = 100 * 365 * 24 * 60 * 60;
 var PipRailClient = class {
   opts;
   maxRetries;
@@ -2986,6 +3465,10 @@ var PipRailClient = class {
   // Resolved lazily on first request — this is what lets Solana (and future
   // families) auto-mount with no setup call.
   bound;
+  // The verifiable receipt from the most recent settled fetch (null if the server emitted
+  // none). Captured pure (no chain read) and surfaced via lastReceipt(); the resource URL is
+  // stamped from the URL this client actually fetched (authoritative over the gate's default).
+  lastReceiptValue = null;
   constructor(opts) {
     this.opts = opts;
     this.maxRetries = Math.max(1, opts.maxPaymentRetries ?? 3);
@@ -3132,6 +3615,129 @@ var PipRailClient = class {
     } catch {
     }
   }
+  /**
+   * Capture the verifiable receipt from a settled response (pure — no chain read), stamping
+   * the resource URL this client actually fetched (authoritative over the gate's default ''). A
+   * settled fetch with no receipt extension sets it to `null` so {@link lastReceipt} reflects the
+   * latest fetch. Never throws — a malformed header just yields `null`.
+   */
+  captureReceipt(response, url) {
+    try {
+      const parsed = parseReceiptExtension(response);
+      this.lastReceiptValue = parsed ? { ...parsed, resource: { url } } : null;
+    } catch {
+      this.lastReceiptValue = null;
+    }
+  }
+  /**
+   * The verifiable {@link PipRailReceipt} from the most recent settled `fetch` — the
+   * self-contained record the buyer KEEPS and anyone re-verifies against the chain
+   * (see {@link PipRailClient.verifyReceipt}). `null` when the last settled fetch carried
+   * no receipt (the gate's `receipts` option was off) or no payment has settled yet. Pure.
+   */
+  lastReceipt() {
+    return this.lastReceiptValue;
+  }
+  /**
+   * Re-verify ANY {@link PipRailReceipt} against the chain — the anyone-can-run primitive.
+   * Re-reads `receipt.transaction` via the receipt's own network driver and re-derives
+   * `payTo`/`asset`/`payer` from the tx, **never trusting the receipt's claims**: a forged
+   * `payTo`/`asset`/over-stated `amount` makes the driver's `verify()` fail (`ok:false`); a
+   * forged `payer` surfaces as `matchesClaims:false`. Static + WALLET-FREE — a third party
+   * verifies with only a chain + RPC, no PipRail account. **Never throws** (an RPC error or a
+   * malformed receipt → `{ ok:false, error }`). Viem-free here — the chain read happens inside
+   * the lazily-mounted family driver (the protocol layer pulls no chain libs). Durable for
+   * digest-bound families; recency-bounded for the account-watch families (see
+   * {@link ReceiptVerification}).
+   */
+  static async verifyReceipt(receipt, opts) {
+    const r = receipt?.receipt;
+    if (!r || typeof r !== "object") {
+      return { ok: false, onChain: { payTo: "", asset: "", amount: "", payer: "" }, matchesClaims: false, ageSeconds: 0, error: "tx_not_found" };
+    }
+    const claimed = { payTo: r.payTo ?? "", asset: r.asset ?? "", amount: r.amount ?? "", payer: r.payer ?? "" };
+    const ageSeconds = receiptAgeSeconds(r.verifiedAt);
+    try {
+      const chain = chainSelectorForNetwork(r.network, opts?.rpcUrl);
+      const net = await resolveNetwork2({
+        chain,
+        ...opts?.rpcUrl ? { rpcUrl: opts.rpcUrl } : {}
+      });
+      const accept = {
+        scheme: "onchain-proof",
+        network: r.network,
+        amount: r.amount,
+        asset: r.asset,
+        payTo: r.payTo,
+        maxTimeoutSeconds: RECEIPT_VERIFY_WINDOW_SECONDS,
+        extra: {
+          nonce: r.nonce ?? "",
+          // the challenge/memo nonce — REQUIRED for Template-A re-verify
+          decimals: receipt.decimals ?? 6,
+          // B10c — Stellar/XRPL/TON re-scale by it; 6 = USDC fallback
+          minConfirmations: 0,
+          amountFormatted: ""
+        }
+      };
+      const ref = familyForChain(chain) === "near" ? `${r.payer}:${r.transaction}` : r.transaction;
+      const result = await net.verify(ref, accept);
+      if (!result.ok) {
+        return { ok: false, onChain: claimed, matchesClaims: false, ageSeconds, error: result.error };
+      }
+      const oc = result.receipt;
+      const onChain = { payTo: oc.payTo, asset: oc.asset, amount: oc.amount, payer: oc.payer };
+      const matchesClaims = sameAddress(oc.payer, r.payer);
+      return { ok: true, onChain, matchesClaims, ageSeconds };
+    } catch {
+      return { ok: false, onChain: claimed, matchesClaims: false, ageSeconds, error: "tx_not_found" };
+    }
+  }
+  /**
+   * Verify the OPTIONAL Tier-2 service-delivery attestation on a {@link PipRailReceipt}
+   * — the merchant's signed proof that the resource was actually SERVED (the one thing
+   * the chain can't attest). For an EVM EIP-712 attestation this re-recovers the signer
+   * from the signature over the official `offer-receipt` typed data and checks
+   * `recover === receipt.payTo` (spec §4.5.1 / §5.5) — the classic EIP-712 footgun made
+   * safe (`recoverTypedDataAddress` returns a WRONG address rather than throwing on a bad
+   * signature, so the equality check is the real verification). A tampered signature →
+   * `{ ok:false }`, never a throw.
+   *
+   * Static + wallet-free. **Never throws** (a malformed/absent attestation, an unsupported
+   * format, or a recovery fault → `{ ok:false, reason }`). Viem-free HERE — the recover runs
+   * inside the lazily-imported EVM receipt driver (a lazy chunk), so the protocol layer pulls
+   * no chain libs. The JWS format defers to R3 (`{ ok:false, reason:'jws-not-loaded' }`).
+   */
+  static async verifyAttestation(receipt) {
+    const att = receipt?.attestation;
+    if (!att || typeof att !== "object" || typeof att.signature !== "string") {
+      return { ok: false, reason: "no-attestation" };
+    }
+    if (att.format === "jws") {
+      return { ok: false, reason: "jws-not-loaded" };
+    }
+    const r = receipt.receipt;
+    if (!r || typeof r !== "object") return { ok: false, reason: "no-receipt" };
+    const payload = att.payload ?? {};
+    const network = typeof payload.network === "string" ? payload.network : r.network;
+    const resourceUrl = typeof payload.resourceUrl === "string" ? payload.resourceUrl : receipt.resource?.url ?? "";
+    const payer = typeof payload.payer === "string" ? payload.payer : r.payer;
+    const issuedAt = typeof payload.issuedAt === "number" ? payload.issuedAt : receiptIssuedAtSeconds(r.verifiedAt);
+    const transaction = typeof payload.transaction === "string" ? payload.transaction : r.transaction ?? "";
+    try {
+      const { verifyReceiptAttestationEvm } = await import("./receipt-NNEID77X.js");
+      return await verifyReceiptAttestationEvm({
+        payTo: r.payTo,
+        network,
+        resourceUrl,
+        payer,
+        issuedAt,
+        transaction,
+        signature: att.signature
+      });
+    } catch {
+      return { ok: false, reason: "verify-failed" };
+    }
+  }
   /** Auto-mount the chain's driver, resolve the network, and bind the wallet — once. */
   ensure() {
     return this.bound ??= (async () => {
@@ -3211,9 +3817,14 @@ var PipRailClient = class {
   async estimateCost(url, init) {
     const res = await fetch(url, { ...init ?? {}, method: init?.method ?? "GET" });
     if (res.status !== 402) return null;
-    const { net, accept, quote } = await this.resolveChallenge(url, res, this.resolveSchemes());
-    const cost = await net.estimateCost(accept);
-    return { quote, cost };
+    try {
+      const { net, accept, quote } = await this.resolveChallenge(url, res, this.resolveSchemes());
+      const cost = await net.estimateCost(accept);
+      return { quote, cost };
+    } catch (err) {
+      if (err instanceof InvalidEnvelopeError) return null;
+      throw err;
+    }
   }
   /** Aggregated snapshot of every payment this client has settled — total
    *  count, cumulative spend per token, cumulative spend per denomination (the
@@ -3565,9 +4176,17 @@ var PipRailClient = class {
     }
     this.safeEmit({ kind: "payment-required", challenge, accept });
     await this.authorize(quote);
+    if (accept.scheme === "upto") {
+      return this.payUptoRail(net, wallet, accept, url, init, quote);
+    }
     if (accept.scheme === "exact") {
       return this.payExactRail(net, wallet, accept, url, init, quote);
     }
+    if (accept.scheme !== "onchain-proof") {
+      throw new UnsupportedSchemeError(
+        `internal: unrouted accept scheme '${accept.scheme}' reached the onchain-proof pay path.`
+      );
+    }
     const { ref, confirmed } = await this.payAndConfirm(net, wallet, accept);
     const response = await this.retryWithProof(url, init, accept, ref, confirmed);
     this.recordSpend(quote, ref);
@@ -3654,6 +4273,13 @@ 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
+        )
+      );
+    }
     return out;
   }
   /** Build the full {@link PaymentPlan} from an already-parsed challenge + bound
@@ -3675,11 +4301,11 @@ var PipRailClient = class {
         ...session ? { session } : {}
       };
     }
-    const analysed = await Promise.all(
+    const analysed = (await Promise.all(
       candidates.map(
-        (accept) => this.analyzeRail(net, wallet, accept, url, challenge.resource.description)
+        (accept) => this.analyzeRail(net, wallet, accept, url, challenge.resource.description).catch(() => null)
       )
-    );
+    )).filter((o) => o !== null);
     const options = rankOptions(analysed);
     const best = options.find((o) => o.state === "payable") ?? null;
     const status = best ? "ready" : options.some((o) => o.state === "unknown") ? "unknown" : "blocked";
@@ -3703,7 +4329,7 @@ var PipRailClient = class {
     const rr = await net.recipientReady(accept.payTo, accept.asset).catch(() => ({ ready: "unknown" }));
     const amount = BigInt(accept.amount);
     const fee = safeBig(cost.fee);
-    const isExact = accept.scheme === "exact";
+    const isExact = accept.scheme === "exact" || accept.scheme === "upto";
     const isNative = accept.asset === "native";
     const blockers = [];
     const warnings = [];
@@ -3909,16 +4535,41 @@ var PipRailClient = class {
    *  denomination it counts toward in the grand total). Then fire the `onSpend` callback
    *  with the record + the post-payment budget, and emit any `warnAtFraction` thresholds
    *  this payment just crossed. All observability is isolated — a throwing hook never
-   *  affects the (already-settled) payment. */
-  recordSpend(quote, ref) {
+   *  affects the (already-settled) payment.
+   *
+   *  `settledAmountBase` is the SINGLE upto ledger-reconciliation seam: the quote (and thus
+   *  the policy/budget) gates on the MAX, and for the metered `upto` rail the budgeted amount
+   *  RECORDED is ALSO the authorized MAX — the only buyer-provable bound. The merchant's
+   *  claimed actual is UNTRUSTED (a malicious merchant can settle the MAX on-chain yet report
+   *  a tiny `SettleOutcome.amount`); recording it would let an under-report silently loosen a
+   *  cumulative cap (`maxTotal`/`maxTotalPerDenom`/`windowTotal`) past the buyer's real on-chain
+   *  spend (POL-1). So the cap-bearing `amountBase` is the MAX; the clamped actual is surfaced
+   *  separately on `settledBase`/`settledFormatted` for transparency (it equals the receipt's
+   *  amount). When absent (onchain-proof/exact) this is byte-identical to before. */
+  recordSpend(quote, ref, settledAmountBase) {
     const denom = denomOf(quote.symbol, quote.asset, this.opts.policy);
+    const amountBase = quote.amount;
+    const amountFormatted = quote.amountFormatted;
+    let settledBase;
+    let settledFormatted;
+    if (settledAmountBase !== void 0 && /^\d+$/.test(settledAmountBase)) {
+      try {
+        const claimed = BigInt(settledAmountBase);
+        const max = BigInt(quote.amount);
+        const shown = claimed < max ? claimed : max;
+        settledBase = shown.toString();
+        settledFormatted = formatUnits(shown, quote.decimals);
+      } catch {
+      }
+    }
     const record = {
       url: quote.url,
       host: hostOf2(quote.url),
       network: quote.network,
       asset: quote.asset,
-      amountBase: quote.amount,
-      amountFormatted: quote.amountFormatted,
+      amountBase,
+      amountFormatted,
+      ...settledBase !== void 0 ? { settledBase, settledFormatted } : {},
       ...quote.symbol ? { symbol: quote.symbol } : {},
       decimals: quote.decimals,
       ...denom ? { denom } : {},
@@ -4062,6 +4713,7 @@ var PipRailClient = class {
       }
       if (lastResponse.status !== 402) {
         const receipt = parseReceipt(lastResponse);
+        this.captureReceipt(lastResponse, url);
         this.safeEmit({ kind: "payment-settled", receipt });
         return lastResponse;
       }
@@ -4146,6 +4798,7 @@ var PipRailClient = class {
       }
       if (response.ok && !(settle && settle.success === false)) {
         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}`;
         this.recordSpend(quote, ref);
@@ -4170,6 +4823,91 @@ var PipRailClient = class {
       { ref: nonce }
     );
   }
+  /**
+   * The standard `upto` (metered) buyer path — a near-clone of {@link payExactRail} with TWO
+   * deltas: (1) it signs a Permit2-upto authorization for the MAX via `payUpto` + frames it
+   * with `buildUptoSignatureHeader`; (2) it records the ACTUAL settled amount (read off the
+   * SettleResponse's required `amount` field, via `recordSpend(quote, ref, settle.amount)`) in
+   * the ledger — the budget gated on the MAX, the ledger records the ACTUAL. A server that omits
+   * `settle.amount` FAILS SAFE to the MAX (over-counts, never under-counts). The buyer SIGNS, the
+   * merchant self-settles — the buyer never broadcasts.
+   */
+  async payUptoRail(net, wallet, accept, url, init, quote) {
+    if (!net.payUpto) {
+      throw new UnsupportedSchemeError(
+        `the ${net.family} family can't pay a standard 'upto' rail (EVM-Permit2 only today).`
+      );
+    }
+    throwIfAborted(init?.signal);
+    const { payload, accepted, payerFrom, nonce } = await net.payUpto(wallet, accept);
+    const headers = new Headers(init?.headers);
+    headers.set(HEADER_SIGNATURE, buildUptoSignatureHeader({ accepted, payload }));
+    const rejectDefinitive = (why2) => {
+      this.safeEmit({ kind: "payment-failed", reason: `upto: facilitator rejected nonce=${nonce} (${why2})`, code: why2 });
+      throw new MaxRetriesExceededError(
+        `upto: the server rejected the payment (${why2}). Fix the cause, then re-present the SAME signed authorization (nonce=${nonce}) \u2014 do NOT re-sign a fresh nonce. ref=${nonce}.`,
+        { ref: nonce }
+      );
+    };
+    const deadline = Date.now() + Math.max(1, Math.floor(accept.maxTimeoutSeconds / 2)) * 1e3;
+    const maxAttempts = Math.min(this.maxRetries, 3);
+    let lastReason = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      if (attempt > 0) {
+        if (Date.now() >= deadline) break;
+        await new Promise((r) => setTimeout(r, Math.min(2e3, 400 * 2 ** (attempt - 1))));
+      }
+      throwIfAborted(init?.signal);
+      const budget = Math.min(this.retryTimeoutMs, deadline - Date.now());
+      if (budget <= 0) break;
+      const timeoutController = new AbortController();
+      const timeoutId = setTimeout(() => timeoutController.abort(), budget);
+      const signal = init?.signal && typeof AbortSignal.any === "function" ? AbortSignal.any([timeoutController.signal, init.signal]) : timeoutController.signal;
+      let response;
+      try {
+        response = await fetch(url, { ...init ?? {}, headers, signal });
+      } catch (err) {
+        throw new PaymentTimeoutError(
+          `upto: no response after submitting the authorization (nonce=${nonce}) to ${hostOf2(url)}. The merchant may have already settled it \u2014 verify on-chain before re-presenting; do NOT re-pay.`,
+          { cause: err, ref: nonce }
+        );
+      } finally {
+        clearTimeout(timeoutId);
+      }
+      const settle = parseSettleResponse(response);
+      if (response.status === 402) {
+        if (settle && settle.success === false) rejectDefinitive(settle.errorReason ?? "the server reported success:false");
+        lastReason = await readInvalidReason(response) ?? lastReason;
+        continue;
+      }
+      if (response.ok && !(settle && settle.success === false)) {
+        const receipt = parseReceipt(response);
+        this.captureReceipt(response, url);
+        this.safeEmit({ kind: "payment-settled", receipt, ...settle ? { settle } : {} });
+        const ref = settle?.transaction || receipt?.transaction || `upto-nonce:${nonce}`;
+        const settledAmount = settle?.amount ?? receipt?.amount;
+        this.recordSpend(quote, ref, settledAmount);
+        return response;
+      }
+      if (response.status >= 500) {
+        this.safeEmit({ kind: "payment-failed", reason: `upto: server ${response.status} \u2014 authorization nonce=${nonce} not settled` });
+        return response;
+      }
+      if (settle && settle.success === false) rejectDefinitive(settle.errorReason ?? "the server reported success:false");
+      this.safeEmit({ kind: "payment-failed", reason: `upto: server ${response.status} \u2014 authorization nonce=${nonce} not settled` });
+      return response;
+    }
+    const why = lastReason ? `${lastReason.error}${lastReason.detail ? ` \u2014 ${lastReason.detail}` : ""}` : "server gave no reason";
+    this.safeEmit({
+      kind: "payment-failed",
+      reason: `upto: 402 after submitting authorization nonce=${nonce} (${why})`,
+      ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
+    });
+    throw new MaxRetriesExceededError(
+      `upto: 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. ref=${nonce}.`,
+      { ref: nonce }
+    );
+  }
 };
 function throwIfAborted(signal) {
   if (signal?.aborted) {
@@ -4350,6 +5088,38 @@ async function readInvalidReason(response) {
   if (settle?.errorReason) return { error: settle.errorReason, detail: "" };
   return null;
 }
+var EVM_PRESET_FOR_CHAINID = {
+  1: "ethereum",
+  8453: "base",
+  137: "polygon",
+  42161: "arbitrum",
+  10: "optimism",
+  43114: "avalanche",
+  56: "bnb"
+};
+function chainSelectorForNetwork(network, rpcUrl) {
+  const chainId = chainIdFromNetwork(network);
+  if (chainId !== null) {
+    const preset = EVM_PRESET_FOR_CHAINID[chainId];
+    if (preset) return preset;
+    return { id: chainId, rpcUrl: rpcUrl ?? "" };
+  }
+  const namespace = network.split(":")[0] ?? "";
+  return namespace === "tvm" ? "ton" : namespace;
+}
+function receiptAgeSeconds(verifiedAt) {
+  const t = Date.parse(verifiedAt);
+  if (Number.isNaN(t)) return 0;
+  return Math.max(0, Math.round((Date.now() - t) / 1e3));
+}
+function receiptIssuedAtSeconds(verifiedAt) {
+  const t = Date.parse(verifiedAt);
+  if (Number.isNaN(t)) return 0;
+  return Math.floor(t / 1e3);
+}
+function sameAddress(a, b) {
+  return typeof a === "string" && typeof b === "string" && a.toLowerCase() === b.toLowerCase();
+}
 
 // src/payer.ts
 var MultiChainPayer = class _MultiChainPayer {
@@ -4582,7 +5352,13 @@ var BRAND = {
 };
 var WHAT = 'This is an x402 "402 Payment Required" endpoint. Pay one of the offered rails to access it.';
 function howFor(scheme) {
-  return scheme === "exact" ? "Standard x402 exact rail \u2014 sign an EIP-3009 / Permit2 / SVM authorization; any stock x402 client (e.g. @x402/fetch) can pay this." : "Pay this amount on-chain to payTo, then resubmit with a payment-signature header carrying the proof ref + nonce. Easiest with @piprail/sdk (see sdk.install).";
+  if (scheme === "exact") {
+    return "Standard x402 exact rail \u2014 sign an EIP-3009 / Permit2 / SVM authorization; any stock x402 client (e.g. @x402/fetch) can pay this.";
+  }
+  if (scheme === "upto") {
+    return "Standard x402 upto (metered) rail \u2014 sign a Permit2 authorization for the MAX amount; the server settles the ACTUAL (\u2264 max) after serving. BUDGET AGAINST THE MAX \u2014 the server MAY fully charge it. EVM-Permit2 only; enable with schemes:['upto'].";
+  }
+  return "Pay this amount on-chain to payTo, then resubmit with a payment-signature header carrying the proof ref + nonce. Easiest with @piprail/sdk (see sdk.install).";
 }
 function railOf(a) {
   const extra = a.extra ?? {};
@@ -4609,6 +5385,7 @@ function buildSelfDescription(input) {
     mcp: { run: BRAND.mcpRun, tool: "piprail_pay_request" },
     docs: { home: BRAND.home, agents: BRAND.docs, pay: BRAND.payDocs },
     discovery: { openapi: "/openapi.json", wellKnown: "/.well-known/x402" },
+    ...input.verifiableReceipts ? { verifiableReceipts: true } : {},
     ...input.instruction ? { instruction: input.instruction } : {}
   };
 }
@@ -4708,17 +5485,21 @@ and pay with the tools below.
 Always plan before you pay so you never commit to a payment you cannot finish.
 
 ## Gasless \u2014 the exact rail (zero gas for you)
-A 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:
+A 402 may offer up to three rails; you don't choose per payment \u2014 the client does, automatically:
 - onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas
   (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.
+- 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
+  means the MAX fits your budget; the settled actual is recorded for reconciliation.
 When the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest
 settleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is
-identical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);
-you can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).
+identical. The exact/upto schemes are OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact,upto);
+you can't enable them yourself, but you can report when a 402 needs one (see UNSUPPORTED_SCHEME below).
 
 ## Reading a refusal \u2014 never crash, never double-spend
 A failed pay returns a STRUCTURED object, never a thrown error you must catch:
@@ -5001,11 +5782,13 @@ function paymentTools(client) {
             }
             res = await client.fetch(url, { method, headers, body });
           }
+          const verifiable = parseReceiptExtension(res);
           return {
             status: res.status,
             ok: res.ok,
             body: await readBody(res),
-            receipt: parseReceipt(res)
+            receipt: parseReceipt(res),
+            ...verifiable ? { verifiableReceipt: { ...verifiable, resource: { url } } } : {}
           };
         } catch (err) {
           if (err instanceof PipRailError) {
@@ -5125,6 +5908,38 @@ function paymentTools(client) {
       },
       parameters: { type: "object", properties: {}, additionalProperties: false },
       invoke: async () => ({ guide: PIPRAIL_AGENT_GUIDE })
+    },
+    {
+      name: "piprail_verify_receipt",
+      description: "Re-verify a PipRail VERIFIABLE RECEIPT against the chain \u2014 confirm a payment REALLY settled (the funds provably moved to payTo for AT LEAST the stated amount) WITHOUT trusting whoever handed you the receipt. Read-only and WALLET-FREE: pass the PipRailReceipt JSON (from a prior piprail_pay_request `verifiableReceipt`, or any third party). Returns { ok, onChain:{payTo,asset,amount,payer}, matchesClaims, ageSeconds, error? }: `ok` = the chain confirms the settlement; `onChain.payer` is RE-DERIVED from the tx and `matchesClaims:false` means the receipt forged the payer; `amount` is a verified lower bound. Pass `rpcUrl` for a chain outside the common presets.",
+      annotations: {
+        title: "Verify a payment receipt",
+        readOnlyHint: true,
+        // re-reads the chain; moves nothing, needs no wallet
+        idempotentHint: true,
+        openWorldHint: true
+        // reads an on-chain tx via RPC
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          receipt: {
+            type: "object",
+            description: "The PipRailReceipt JSON ({ piprail, receipt, resource, decimals? }) to re-verify."
+          },
+          rpcUrl: {
+            type: "string",
+            description: "Optional RPC URL for the receipt's chain (required for chains outside the common presets)."
+          }
+        },
+        required: ["receipt"],
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        const receipt = args.receipt;
+        const opts = args.rpcUrl ? { rpcUrl: String(args.rpcUrl) } : void 0;
+        return await PipRailClient.verifyReceipt(receipt, opts);
+      }
     }
   ];
 }
@@ -5774,17 +6589,40 @@ function normaliseExactOption(exact) {
   return exact;
 }
 var TRANSIENT_VERIFY_CODES = /* @__PURE__ */ new Set(["tx_not_found", "insufficient_confirmations"]);
+function nowUnixSeconds(verifiedAt) {
+  if (verifiedAt) {
+    const t = Date.parse(verifiedAt);
+    if (!Number.isNaN(t)) return Math.floor(t / 1e3);
+  }
+  return Math.floor(Date.now() / 1e3);
+}
 function createPaymentGate(options) {
   const minConfirmations = options.minConfirmations ?? 1;
   const maxTimeoutSeconds = options.maxTimeoutSeconds ?? 600;
   const genNonce = options.generateNonce ?? (() => globalThis.crypto.randomUUID());
   const exactOption = normaliseExactOption(options.exact);
+  const receiptsOn = options.receipts !== void 0 && options.receipts !== false;
+  const receiptOpt = typeof options.receipts === "object" ? options.receipts : {};
+  const receiptIncludeTxHash = receiptOpt.includeTxHash !== false;
+  const receiptResourceUrl = receiptOpt.resource ?? "";
+  const attestWallet = receiptOpt.attest && "wallet" in receiptOpt.attest ? receiptOpt.attest.wallet : void 0;
+  const attestJws = receiptOpt.attest && "jws" in receiptOpt.attest;
+  let attestWarned = false;
+  function warnAttestDegrade(reason) {
+    if (attestWarned) return;
+    attestWarned = true;
+    try {
+      console.warn(`[piprail] receipts.attest ${reason}; emitting an unsigned Tier-1 receipt instead.`);
+    } catch {
+    }
+  }
   let resolved;
   function ready() {
     if (resolved) return resolved;
     const p = (async () => {
       const accepts = normaliseAccepts(options);
       const exactSkips = [];
+      const uptoSkips = [];
       const specs = await Promise.all(
         accepts.map(async (a) => {
           const net = await resolveNetwork2({ chain: a.chain, rpcUrl: a.rpcUrl ?? options.rpcUrl });
@@ -5803,9 +6641,19 @@ function createPaymentGate(options) {
             if (outcome.rail) spec.exact = outcome.rail;
             else if (outcome.skipReason) exactSkips.push(outcome.skipReason);
           }
+          if (options.upto) {
+            const upto = await resolveUptoRail(net, asset);
+            if (upto) spec.upto = upto;
+            else uptoSkips.push(`${net.network}/${asset}`);
+          }
           return spec;
         })
       );
+      if (options.upto && !specs.some((s) => s.upto)) {
+        throw new Error(
+          `requirePayment: \`upto\` (the metered rail) was requested but none of the offered rails support it (tried: ${uptoSkips.join(", ") || "none"}). The \`upto\` scheme is EVM-Permit2 ONLY \u2014 an ERC-20 on a chain with the x402UptoPermit2Proxy deployed (Ethereum/Base/Arbitrum/Optimism/Polygon/BNB), NOT a native coin, NOT a non-EVM family. (Native coins + non-Permit2 chains can never carry \`upto\`.)`
+        );
+      }
       if (exactOption && !specs.some((s) => s.exact)) {
         const why = exactSkips.length > 0 ? exactSkips.join(" ") : "The standard `exact` rail is EVM ERC-20 (EIP-3009 \u2014 USDC / EURC \u2014 or Permit2, e.g. Binance-Peg USDC on BNB) or a Solana SPL token (SVM) \u2014 NOT native coins, NOT families without a standard `exact` scheme.";
         if (exactOption.settle === "keyless") {
@@ -5885,7 +6733,27 @@ function createPaymentGate(options) {
     };
     return { rail: { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode } };
   }
-  const hasCustomStore = Boolean(options.isUsed || options.markUsed);
+  async function resolveUptoRail(net, asset) {
+    const cfg = options.upto;
+    if (!net.resolveUptoRail) return null;
+    if (cfg.relayer === void 0) {
+      throw new Error(
+        "requirePayment: `upto` needs a `relayer` wallet (the gas-paying key that self-settles the metered actual AND is the bound witness.facilitator), e.g. upto: { relayer: { key }, settleAmount }."
+      );
+    }
+    const relayer = net.bindWallet(cfg.relayer);
+    const info = await net.resolveUptoRail({ asset, relayer });
+    if (!info) return null;
+    return { method: info.method, ...info.extra ? { extra: info.extra } : {}, relayer };
+  }
+  const hasIsUsed = typeof options.isUsed === "function";
+  const hasMarkUsed = typeof options.markUsed === "function";
+  if (hasIsUsed !== hasMarkUsed) {
+    throw new Error(
+      "requirePayment/createPaymentGate: `isUsed` and `markUsed` must be provided TOGETHER \u2014 a custom replay store needs both a read and a write. Supplying only " + (hasIsUsed ? "`isUsed`" : "`markUsed`") + " silently disables replay protection (double-spend). Provide both, or neither (the built-in in-memory store)."
+    );
+  }
+  const hasCustomStore = hasIsUsed && hasMarkUsed;
   const localUsed = /* @__PURE__ */ new Map();
   const replayWindowMs = maxTimeoutSeconds * 1e3;
   function pruneUsed(now) {
@@ -5948,10 +6816,33 @@ function createPaymentGate(options) {
       }
     };
   }
+  function buildUptoAccept(s) {
+    const rail = s.upto;
+    return {
+      scheme: "upto",
+      network: s.net.network,
+      amount: s.amountBase.toString(),
+      // the authorized MAX (base units)
+      asset: s.asset,
+      payTo: s.payTo,
+      maxTimeoutSeconds,
+      extra: {
+        assetTransferMethod: "permit2-upto",
+        // facilitatorAddress comes from rail.extra; the spread below carries it (+ name/version).
+        facilitatorAddress: rail.extra?.facilitatorAddress ?? "",
+        minConfirmations,
+        decimals: s.decimals,
+        amountFormatted: s.amountFormatted,
+        ...s.symbol ? { symbol: s.symbol } : {},
+        ...rail.extra
+      }
+    };
+  }
   function buildAccepts(specs, nonce) {
     const out = [];
     for (const s of specs) {
       if (s.exact) out.push(buildExactAccept(s));
+      if (s.upto) out.push(buildUptoAccept(s));
       out.push(buildAccept(s, nonce));
     }
     return out;
@@ -5969,7 +6860,8 @@ function createPaymentGate(options) {
     const selfDescribe = options.selfDescribe === false ? void 0 : buildSelfDescription({
       accepts,
       instruction: describeChallenge({ x402Version: 2, resource: { url: resourceUrl }, accepts }),
-      ...endpointInfo ? { endpoint: endpointInfo } : {}
+      ...endpointInfo ? { endpoint: endpointInfo } : {},
+      ...receiptsOn ? { verifiableReceipts: true } : {}
     });
     const rejectionExt = opts?.extensions ?? {};
     const rejectionPiprail = rejectionExt.piprail ?? {};
@@ -6058,6 +6950,55 @@ function createPaymentGate(options) {
     if (options.awaitOnPaid) await fireOnPaid(paid);
     else void fireOnPaid(paid);
   }
+  async function buildPaidResult(spec, receipt, nonce) {
+    if (!receiptsOn) {
+      return { kind: "paid", receipt, receiptHeader: buildReceiptHeader(receipt) };
+    }
+    try {
+      const stamped = {
+        ...receipt,
+        ...nonce ? { nonce } : {},
+        // §5.3: a suppressed tx is the empty string on the wire, never a missing key.
+        ...receiptIncludeTxHash ? {} : { transaction: "" }
+      };
+      const attestation = await maybeSignAttestation(spec, stamped);
+      const extensions = buildReceiptExtension({
+        receipt: stamped,
+        resource: { url: receiptResourceUrl },
+        decimals: spec.decimals,
+        ...attestation ? { attestation } : {}
+      });
+      return { kind: "paid", receipt: stamped, receiptHeader: buildReceiptHeader(stamped, extensions) };
+    } catch {
+      return { kind: "paid", receipt, receiptHeader: buildReceiptHeader(receipt) };
+    }
+  }
+  async function maybeSignAttestation(spec, stamped) {
+    if (attestJws) {
+      warnAttestDegrade("JWS attestation is not yet implemented (R3)");
+      return void 0;
+    }
+    if (attestWallet === void 0) return void 0;
+    if (typeof spec.net.signReceipt !== "function") {
+      warnAttestDegrade(`is EVM-only; the ${spec.net.family} rail can't sign an EIP-712 attestation`);
+      return void 0;
+    }
+    try {
+      const wallet = spec.net.bindWallet(attestWallet);
+      return await spec.net.signReceipt(wallet, {
+        payTo: spec.payTo,
+        network: spec.net.network,
+        resourceUrl: receiptResourceUrl,
+        payer: stamped.payer,
+        issuedAt: nowUnixSeconds(stamped.verifiedAt),
+        // §5.3: the signed message carries the empty string for a suppressed tx, never omitted.
+        transaction: receiptIncludeTxHash ? stamped.transaction : ""
+      });
+    } catch {
+      warnAttestDegrade("signing failed");
+      return void 0;
+    }
+  }
   function reportOnFailedError(error, failure) {
     if (!options.onFailedError) return;
     try {
@@ -6084,6 +7025,14 @@ function createPaymentGate(options) {
     if (options.awaitOnFailed) await fireOnFailed(failure);
     else void fireOnFailed(failure);
   }
+  function railExtra(full) {
+    const out = {};
+    for (const k of ["assetTransferMethod", "facilitatorAddress", "name", "version"]) {
+      const v = full[k];
+      if (v !== void 0 && v !== "") out[k] = v;
+    }
+    return Object.keys(out).length > 0 ? { extra: out } : {};
+  }
   async function describe(resourceUrl = "") {
     const specs = await ready();
     const accepts = [];
@@ -6098,7 +7047,8 @@ function createPaymentGate(options) {
         maxTimeoutSeconds,
         ...s.symbol ? { symbol: s.symbol } : {}
       };
-      if (s.exact) accepts.push({ scheme: "exact", ...base2 });
+      if (s.exact) accepts.push({ scheme: "exact", ...base2, ...railExtra(buildExactAccept(s).extra) });
+      if (s.upto) accepts.push({ scheme: "upto", ...base2, ...railExtra(buildUptoAccept(s).extra) });
       accepts.push({ scheme: "onchain-proof", ...base2 });
     }
     return {
@@ -6134,7 +7084,7 @@ function createPaymentGate(options) {
     }
     await settleTx(ref, true);
     await deliverOnPaid(spec, result.receipt);
-    return { kind: "paid", receipt: result.receipt, receiptHeader: buildReceiptHeader(result.receipt) };
+    return await buildPaidResult(spec, result.receipt, sig.payload.nonce);
   }
   async function verifyExact(exact) {
     const specs = await ready();
@@ -6244,27 +7194,122 @@ function createPaymentGate(options) {
     }
     await settleTx(nonce, true);
     await deliverOnPaid(spec, result.receipt);
-    return { kind: "paid", receipt: result.receipt, receiptHeader: buildReceiptHeader(result.receipt) };
+    return await buildPaidResult(spec, result.receipt);
+  }
+  function resolveSettleAmount(raw, maxAmount, decimals) {
+    if (typeof raw === "bigint") return raw < 0n ? null : raw;
+    const s = raw.trim();
+    if (s.length === 0) return null;
+    try {
+      if (s.endsWith("%")) {
+        const pct = s.slice(0, -1).trim();
+        if (!/^\d+(\.\d+)?$/.test(pct)) return null;
+        const pctScaled = floorUnits(pct, 4);
+        return maxAmount * pctScaled / (100n * 10n ** 4n);
+      }
+      if (s.startsWith("$")) {
+        const amt = s.slice(1).trim();
+        return floorUnits(amt, decimals);
+      }
+      if (/^\d+$/.test(s)) return BigInt(s);
+      return floorUnits(s, decimals);
+    } catch {
+      return null;
+    }
+  }
+  async function verifyUpto(upto) {
+    const specs = await ready();
+    const uptoSpecs = specs.filter((s) => s.upto);
+    if (uptoSpecs.length === 0) {
+      return rejection("transfer_not_found", "This resource offers no standard `upto` (metered) rail.");
+    }
+    const isCaip = upto.network.includes(":");
+    let candidates = isCaip ? uptoSpecs.filter((s) => s.net.network === upto.network) : uptoSpecs;
+    if (upto.asset) {
+      candidates = candidates.filter((s) => s.asset.toLowerCase() === upto.asset.toLowerCase());
+    }
+    let spec = candidates[0];
+    if (!isCaip && !upto.asset && uptoSpecs.length > 1) spec = void 0;
+    if (!spec && !isCaip && !upto.asset && uptoSpecs.length === 1) spec = uptoSpecs[0];
+    if (!spec || !spec.upto) {
+      return rejection(
+        "transfer_not_found",
+        `No \`upto\` rail offered for ${upto.network}${upto.asset ? `/${upto.asset}` : ""} (offered: ${uptoSpecs.map((s) => `${s.asset}@${s.net.network}`).join(", ")}).`
+      );
+    }
+    const nonce = upto.payload.permit2Authorization.nonce;
+    if (await claimTx(nonce)) {
+      return rejection("tx_already_used", `Authorization nonce ${nonce} was already redeemed.`);
+    }
+    const accept = buildUptoAccept(spec);
+    const relayer = spec.upto.relayer;
+    let result;
+    try {
+      const rawAmount = await options.upto.settleAmount({
+        maxAmount: spec.amountBase,
+        asset: spec.asset,
+        network: spec.net.network,
+        decimals: spec.decimals,
+        ...upto.raw ? { request: upto.raw } : {}
+      });
+      const settleAmount = resolveSettleAmount(rawAmount, spec.amountBase, spec.decimals);
+      if (settleAmount === null) {
+        await settleTx(nonce, false);
+        return rejection(
+          "upto_settle_exceeds_max",
+          `The settleAmount callback returned an unparseable amount (${String(rawAmount)}). Return a bigint, a raw/"NN%"/"$X" string, or 0.`
+        );
+      }
+      result = await spec.net.settleUptoSelf({ relayer, payload: upto.payload, accept, settleAmount });
+    } catch (err) {
+      await settleTx(nonce, false);
+      if (err instanceof SettlementError) throw err;
+      return rejection(
+        "tx_reverted",
+        `upto: metering/settle failed (${err instanceof Error ? err.message : String(err)}).`
+      );
+    }
+    if (!result.ok) {
+      await settleTx(nonce, false);
+      return rejection(result.error, result.detail);
+    }
+    await settleTx(nonce, true);
+    await deliverOnPaid(spec, result.receipt);
+    return await buildPaidResult(spec, result.receipt);
   }
   async function verify(paymentSignature) {
-    const result = await resolveVerdict(paymentSignature);
+    const raw = normaliseHeader(paymentSignature);
+    const result = await resolveVerdictObject(raw === void 0 ? void 0 : decodeBase64Json(raw));
     if (result.kind === "invalid") await deliverOnFailed(result);
     return result;
   }
-  async function resolveVerdict(paymentSignature) {
-    const raw = normaliseHeader(paymentSignature);
-    if (!raw) return asChallenge();
-    const sig = parseSignatureHeader(raw);
+  async function verifyObject(payload) {
+    const result = await resolveVerdictObject(payload);
+    if (result.kind === "invalid") await deliverOnFailed(result);
+    return result;
+  }
+  async function resolveVerdictObject(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") {
       return verifyOnchainProof(sig);
     }
-    const exact = parseExactPaymentHeader(raw);
+    const upto = parseUptoObject(obj);
+    if (upto) return verifyUpto(upto);
+    const exact = parseExactObject(obj);
     if (exact) return verifyExact(exact);
     return asChallenge();
   }
-  return { challenge, verify, describe, landingPage };
+  return { challenge, verify, verifyObject, describe, landingPage };
 }
 function requirePayment(options) {
+  if (options.upto) {
+    throw new class extends PipRailError {
+      code = "UNSUPPORTED_SCHEME";
+    }(
+      "requirePayment: the 'upto' (metered) rail is unsupported through the Express middleware \u2014 it settles before the route handler serves, so metered usage is unknown at settle time. Call gate.verify() directly (createPaymentGate) and meter inside settleAmount; see docs/accepting-payments/upto-rail-seller.md."
+    );
+  }
   const gate = createPaymentGate(options);
   return async (req, res, next) => {
     let result;
@@ -6410,7 +7455,252 @@ async function deliverReceipt(receipt, options) {
     ...lastError ? { error: lastError } : {}
   };
 }
+
+// src/transports/a2a.ts
+var A2A_X402_EXTENSION_URI_V01 = "https://github.com/google-a2a/a2a-x402/v0.1";
+var A2A_X402_EXTENSION_URI_V02 = "https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2";
+var A2A_STATUS_KEY = "x402.payment.status";
+var A2A_REQUIRED_KEY = "x402.payment.required";
+var A2A_PAYLOAD_KEY = "x402.payment.payload";
+var A2A_RECEIPTS_KEY = "x402.payment.receipts";
+var A2A_ERROR_KEY = "x402.payment.error";
+var A2A_EXTENSIONS_HEADER = "X-A2A-Extensions";
+var MAX_TASK_RECEIPTS = 64;
+var VERIFY_CODE_TO_A2A_ERROR = {
+  payment_expired: "EXPIRED_PAYMENT",
+  tx_already_used: "DUPLICATE_NONCE",
+  amount_too_low: "INVALID_AMOUNT",
+  upto_settle_exceeds_max: "INVALID_AMOUNT",
+  signature_invalid: "INVALID_SIGNATURE",
+  transfer_not_found: "INVALID_AMOUNT",
+  wrong_recipient: "INVALID_AMOUNT",
+  tx_reverted: "SETTLEMENT_FAILED",
+  tx_not_found: "EXPIRED_PAYMENT",
+  insufficient_confirmations: "EXPIRED_PAYMENT",
+  no_meta: "INVALID_SIGNATURE",
+  // The settlement-side throw code the handler emits for a SettlementError (the merchant's
+  // relayer/facilitator never moved funds) — maps to the spec's SETTLEMENT_FAILED.
+  settlement_failed: "SETTLEMENT_FAILED"
+};
+function toA2AErrorCode(code) {
+  return VERIFY_CODE_TO_A2A_ERROR[code] ?? code;
+}
+function toA2APaymentRequired(taskId, challenge, parts) {
+  const metadata = {
+    [A2A_STATUS_KEY]: "payment-required",
+    [A2A_REQUIRED_KEY]: challenge
+  };
+  return {
+    kind: "task",
+    id: taskId,
+    status: {
+      state: "input-required",
+      message: { kind: "message", role: "agent", taskId, ...parts ? { parts } : {}, metadata }
+    }
+  };
+}
+function toA2APaymentReceipts(receipts) {
+  return { [A2A_RECEIPTS_KEY]: receipts };
+}
+function toA2APaymentFailed(code, detail, receipts = [], network) {
+  const entry = {
+    success: false,
+    transaction: "",
+    ...network ? { network } : {},
+    errorReason: `${code}: ${detail}`
+  };
+  return {
+    [A2A_STATUS_KEY]: "payment-failed",
+    [A2A_ERROR_KEY]: toA2AErrorCode(code),
+    [A2A_RECEIPTS_KEY]: [...receipts, entry]
+  };
+}
+function fromA2APaymentRequired(task) {
+  const meta = task.status?.message?.metadata;
+  const required = meta?.[A2A_REQUIRED_KEY];
+  if (!required || typeof required !== "object") return null;
+  return required;
+}
+function fromA2APaymentPayload(message) {
+  const raw = message.metadata?.[A2A_PAYLOAD_KEY];
+  if (raw === void 0 || raw === null) return null;
+  return { raw, taskId: message.taskId ?? "" };
+}
+function defaultTaskStore() {
+  const map = /* @__PURE__ */ new Map();
+  function prune(now) {
+    for (const [key, { expiry }] of map) {
+      if (expiry > now) break;
+      map.delete(key);
+    }
+  }
+  return {
+    get(taskId) {
+      const now = Date.now();
+      prune(now);
+      const hit = map.get(taskId);
+      return hit && hit.expiry > now ? hit.record : void 0;
+    },
+    set(taskId, value, ttlMs) {
+      const now = Date.now();
+      prune(now);
+      map.delete(taskId);
+      map.set(taskId, { record: value, expiry: now + ttlMs });
+    }
+  };
+}
+function createA2APaymentHandler(options) {
+  const gate = options.gate ?? createPaymentGate(options);
+  const maxTimeoutSeconds = options.maxTimeoutSeconds ?? 600;
+  const ttlMs = options.taskTtlMs ?? maxTimeoutSeconds * 1e3;
+  const store = options.taskStore ?? defaultTaskStore();
+  function appendReceipt(taskId, entry) {
+    const prior = store.get(taskId)?.receipts ?? [];
+    const isDup = "success" in entry && entry.success === true && prior.some((r) => "transaction" in r && r.transaction === entry.transaction);
+    const next = isDup ? prior : [...prior, entry];
+    const receipts = next.length > MAX_TASK_RECEIPTS ? next.slice(-MAX_TASK_RECEIPTS) : next;
+    store.set(taskId, { receipts }, ttlMs);
+    return receipts;
+  }
+  function completedTask(taskId, receipts, artifacts, status = "payment-completed") {
+    const metadata = { [A2A_STATUS_KEY]: status, ...toA2APaymentReceipts(receipts) };
+    return {
+      kind: "task",
+      id: taskId,
+      status: { state: "completed", message: { kind: "message", role: "agent", taskId, metadata } },
+      ...artifacts.length > 0 ? { artifacts } : {}
+    };
+  }
+  function reChallengeTask(taskId, result, attempted) {
+    if (result.kind !== "invalid") {
+      const metadata2 = {
+        [A2A_STATUS_KEY]: "payment-required",
+        [A2A_REQUIRED_KEY]: result.challenge
+      };
+      return {
+        kind: "task",
+        id: taskId,
+        status: { state: "input-required", message: { kind: "message", role: "agent", taskId, metadata: metadata2 } }
+      };
+    }
+    const network = attempted ?? singleNetworkOf(result.challenge);
+    const receipts = appendReceiptFailed(taskId, result.error, result.detail, network);
+    const metadata = {
+      [A2A_STATUS_KEY]: "payment-rejected",
+      [A2A_ERROR_KEY]: toA2AErrorCode(result.error),
+      [A2A_REQUIRED_KEY]: result.challenge,
+      ...toA2APaymentReceipts(receipts)
+    };
+    return {
+      kind: "task",
+      id: taskId,
+      status: { state: "input-required", message: { kind: "message", role: "agent", taskId, metadata } }
+    };
+  }
+  function failedTask(taskId, code, detail, network) {
+    const receipts = appendReceiptFailed(taskId, code, detail, network);
+    const metadata = {
+      [A2A_STATUS_KEY]: "payment-failed",
+      [A2A_ERROR_KEY]: toA2AErrorCode(code),
+      ...toA2APaymentReceipts(receipts)
+    };
+    return {
+      kind: "task",
+      id: taskId,
+      status: { state: "failed", message: { kind: "message", role: "agent", taskId, metadata } }
+    };
+  }
+  function appendReceiptFailed(taskId, code, detail, network) {
+    return appendReceipt(taskId, {
+      success: false,
+      transaction: "",
+      ...network ? { network } : {},
+      errorReason: `${code}: ${detail}`
+    });
+  }
+  async function handleMessage(message, taskId) {
+    const id = taskId ?? message.taskId ?? newTaskId();
+    const inbound = fromA2APaymentPayload(message);
+    if (!inbound) {
+      const { challenge } = await gate.challenge(resourceUrlFromMessage(message));
+      store.set(id, { receipts: [] }, ttlMs);
+      return toA2APaymentRequired(id, challenge);
+    }
+    const attempted = networkFromPayload(inbound.raw);
+    let result;
+    try {
+      result = await gate.verifyObject(inbound.raw);
+    } catch (err) {
+      if (err instanceof SettlementError) {
+        return failedTask(id, "settlement_failed", err.message, attempted);
+      }
+      const detail = err instanceof Error ? err.message : String(err);
+      return failedTask(id, "tx_reverted", detail, attempted);
+    }
+    switch (result.kind) {
+      case "challenge":
+        return reChallengeTask(id, result, attempted);
+      case "invalid":
+        return reChallengeTask(id, result, attempted);
+      case "paid": {
+        const receipts = appendReceipt(id, result.receipt);
+        let artifacts = [];
+        if (options.fulfill) {
+          try {
+            artifacts = await options.fulfill({ taskId: id, receipt: result.receipt, message }) ?? [];
+          } catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            const annotation = {
+              name: "fulfillment-error",
+              metadata: { "x402.fulfillment.error": detail, "x402.fulfillment.settled": true },
+              parts: [{ kind: "text", text: `Payment settled, but serving the result failed: ${detail}` }]
+            };
+            return completedTask(id, receipts, [annotation]);
+          }
+        }
+        return completedTask(id, receipts, artifacts);
+      }
+    }
+  }
+  function agentCardExtension(opts) {
+    const uri = opts?.version === "v0.2" ? A2A_X402_EXTENSION_URI_V02 : A2A_X402_EXTENSION_URI_V01;
+    return {
+      uri,
+      description: "Supports payments using the x402 protocol for on-chain settlement.",
+      ...opts?.required ? { required: true } : {}
+    };
+  }
+  return { handleMessage, agentCardExtension, gate };
+}
+function singleNetworkOf(challenge) {
+  const nets = new Set((challenge.accepts ?? []).map((a) => a.network).filter(Boolean));
+  return nets.size === 1 ? [...nets][0] : void 0;
+}
+function networkFromPayload(raw) {
+  const v = raw;
+  if (v && typeof v.accepted?.network === "string") return v.accepted.network;
+  if (v && typeof v.network === "string") return v.network;
+  return void 0;
+}
+function newTaskId() {
+  return `task-${globalThis.crypto.randomUUID()}`;
+}
+function resourceUrlFromMessage(message) {
+  for (const part of message.parts ?? []) {
+    const data = part.data;
+    if (data && typeof data.url === "string") return data.url;
+  }
+  return "";
+}
 export {
+  A2A_ERROR_KEY,
+  A2A_EXTENSIONS_HEADER,
+  A2A_PAYLOAD_KEY,
+  A2A_RECEIPTS_KEY,
+  A2A_REQUIRED_KEY,
+  A2A_STATUS_KEY,
+  A2A_X402_EXTENSION_URI_V01,
+  A2A_X402_EXTENSION_URI_V02,
   BRAND,
   BUILTIN_DENOMS,
   CHAINS,
@@ -6419,6 +7709,7 @@ export {
   DIRECTORY_INFO,
   EIP3009_TYPES,
   EXACT_NETWORK_SLUGS,
+  EXT_OFFER_RECEIPT,
   GENERATOR,
   HEADER_REQUIRED,
   HEADER_RESPONSE,
@@ -6435,6 +7726,7 @@ export {
   NonReplayableBodyError,
   PERMIT2_ADDRESS,
   PERMIT2_PROXY_CHAIN_IDS,
+  PERMIT2_UPTO_WITNESS_TYPES,
   PERMIT2_WITNESS_TYPES,
   PIPRAIL_AGENT_GUIDE,
   POWERED_BY,
@@ -6446,13 +7738,16 @@ export {
   RecipientNotReadyError,
   SettlementError,
   SpendLedger,
+  UPTO_PROXY_CHAIN_IDS,
   UnknownTokenError,
   UnsupportedNetworkError,
   UnsupportedSchemeError,
+  VERIFY_CODE_TO_A2A_ERROR,
   WalletRequiredError,
   WrongChainError,
   WrongFamilyError,
   X402_EXACT_PERMIT2_PROXY,
+  X402_UPTO_PERMIT2_PROXY,
   agentGuide,
   appendAttribution,
   appendKeywords,
@@ -6462,15 +7757,19 @@ export {
   buildExactAuthorization,
   buildExactSignatureHeader,
   buildOpenApi,
+  buildReceiptExtension,
   buildReceiptHeader,
   buildSelfDescription,
   buildSignatureHeader,
+  buildUptoSignatureHeader,
   buildWellKnownX402,
   buildX402DnsTxt,
   chainIdForExactNetwork,
   claim402IndexDomain,
   classifyChallenge,
+  createA2APaymentHandler,
   createPaymentGate,
+  decodeBase64Json,
   decorateOutcome,
   deliverReceipt,
   denomOf,
@@ -6484,18 +7783,26 @@ export {
   fetchAcross,
   firstKeylessFacilitator,
   formatSpendReport,
+  fromA2APaymentPayload,
+  fromA2APaymentRequired,
   getDirectoryInfo,
   isPermit2ProxyChain,
+  isUptoProxyChain,
   knownFacilitatorsFor,
   memorySpendStore,
   normalizeNetwork,
   parseChallenge,
+  parseExactObject,
   parseExactPaymentHeader,
   parseExactRequirements,
   parseFacilitatorSupported,
   parseReceipt,
+  parseReceiptExtension,
   parseSettleResponse,
   parseSignatureHeader,
+  parseSignatureObject,
+  parseUptoObject,
+  parseUptoPaymentHeader,
   paymentTools,
   pickAccept,
   planAcross,
@@ -6511,6 +7818,10 @@ export {
   searchOpenIndexes,
   settleViaFacilitator,
   summarizePlan,
+  toA2AErrorCode,
+  toA2APaymentFailed,
+  toA2APaymentReceipts,
+  toA2APaymentRequired,
   toInsufficientFundsError,
   toInvalidBody,
   verify402IndexDomain