agentic-wallet-mcp 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -8,6 +8,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Entries for 0.5.0 and earlier were reconstructed from commit history when this file was
 > introduced in 0.6.0, so they summarise each release rather than being exhaustive.
 
+## [0.10.0] — 14 September 2026
+
+### Added
+
+- **`credential_preflight` — a free readiness check to call before asking the user for anything.**
+  Reports the live fee and which side pays gas, the balances that matter, whether the spending
+  limit permits it, and (for a template credential) the attributes the template requires. Every
+  reason it is not ready is listed *together*, so one round of fixes is enough rather than
+  discovering a low balance and a too-low spending cap one failed payment at a time. It also
+  reports what it could **not** check, so a clean result is not mistaken for a guarantee — notably,
+  it cannot tell whether an agent name is still free, because that is decided at issuance.
+- **Quote-only mode for the Verified AI Birthcert**, so its price and gas model can be seen without
+  starting a session or paying.
+
+### Changed
+
+- **A dry run can no longer issue a credential.** `subscribe_and_issue({ dryRun: true })` now prices
+  through an endpoint that cannot issue, and stops before the call that can. Previously, against a
+  credential the issuer grants for free, asking what something cost *created it* — a real,
+  permanently-registered credential, which also displaced whatever the wallet already held for that
+  template. A dry run now signs nothing, issues nothing, and never touches the local credential
+  store.
+- **A credential that is currently free is no longer reported as unaffordable.** The issuer states
+  separately whether a quoted amount will actually be charged; both `credential_preflight` and the
+  dry run now read it. When issuance is free, the amount is reported as indicative rather than as a
+  charge, and neither the balance nor the spending cap blocks it. Network gas is unaffected and can
+  still block, because gas is not the credential fee.
+- **Where that answer is unknown it is reported as unknown, never as free** — an older issuer
+  deployment does not state it, and treating silence as "free" would under-report a real cost.
+- **The default spending cap now permits the credential fee on mainnet**, scoped to credential
+  issuance rather than widened generally.
+- **Balance reads during a preflight run concurrently**, so the fee balance and the native-gas
+  balance arrive together instead of one after the other.
+
+### Fixed
+
+- **The outbound `User-Agent` sent to payment facilitators no longer advertises a non-public
+  host.** It is transmitted to third parties on every prepare request; the underlying client
+  dependency has been updated to one that reports its public project URL.
+
+## [0.9.2] — 3 September 2026
+
+### Fixed
+
+- **`request_ai_birthcert_verification`'s sponsored-payment path no longer surfaces a facilitator
+  insufficient-funds rejection as an opaque, unhandled MCP tool error.** A `461407`
+  (`X402_INSUFFICIENT_FUNDS`) rejection from the facilitator's `/prepare` endpoint is now reshaped
+  into a clean `{ error }` result naming the asset and amount, instead of falling through every
+  error branch and throwing raw.
+- **That message now renders amounts in human units, not raw base units.** A raw base-unit count
+  next to a token symbol (e.g. "requires 1,000,000 of JMYR") reads as a million *whole* tokens —
+  for a 6-decimal asset the actual requirement was 1 JMYR, a 1,000,000x misreading that could lead
+  to a drastically oversized top-up. Amounts are now resolved through the same symbol/decimals
+  formatter the rest of the wallet already uses.
+- **The reported "current balance" is read from the facilitator's structured response field when
+  available**, falling back to parsing it out of the free-text error message only for an
+  older/unfixed facilitator — the free-text format was never a stable contract between the two
+  services.
+
 ## [0.9.1] — 28 August 2026
 
 ### Fixed

package/README.md

@@ -20,15 +20,16 @@ VC issuance → identity proof → pay-per-use).
 
 | Tool | Does | Input | Output (shape) |
 |---|---|---|---|
-| `wallet_status` | Report holder DID/address/network + held VCs (client-supplied, or the local cache); optionally a token balance | `{ heldCredentials?, token? }` | `{ holderDid, zetrixAddress, network, credentials, tokenBalance? }` |
+| `wallet_status` | Report holder DID/address/network + held VCs (client-supplied, or the local cache); optionally one token balance (`token`) or several in one call (`tokens`). Each balance carries `balance` (raw base units), `decimals` and `display` — the same amount in whole tokens with its symbol. Quote `display`; a raw count beside a ticker is wrong by orders of magnitude. A token may be named by ticker **or** contract address | `{ heldCredentials?, token?, tokens? }` | `{ holderDid, zetrixAddress, network, credentials, balances?, tokenBalance?, tokenBalances? }` |
+| `credential_preflight` | **Free.** The first call for any credential — composes the quote, the balances and the spending cap into one answer, before a single application field is collected. Spends nothing, starts nothing. `blockers` lists *every* reason the wallet is not ready, at once; `notChecked` lists what preflight cannot know — agent-name availability is decided by myid at issuance, after payment, so a `ready` result is never a reservation | `{ credential, templateId? }` | `{ credential, ready, fee?, balances, cap?, schema?, blockers, notChecked }` |
 | `prove_identity` | Answer an x401 `PROOF-REQUEST` → return the `PROOF-RESPONSE` header to replay | `{ proofRequest, vc?, revealAttribute?, issuerKeys? }` | `{ proofResponseHeader, verified, presentationId }` |
 | `pay_and_fetch` | Fetch a URL, auto-pay with x402 (self-pay via Wallet BE) on `402` | `{ url, method?, headers?, body? }` | `{ status, body, paymentMade, amountPaid, amountPaidHuman, asset }` |
 | `subscribe_and_issue` | Reuse a cached VC if still valid, else pay x402 → MBI issues → return the VC | `{ templateId, attributes, expirationDate?, dryRun?, forceReissue? }` | `{ issued, vcId, vc, txHash, fromCache?, schema?, originalPayment?, paymentAttempted?, recovery? }` |
 | `create_holder_account` | Onboarding: mint an HSM account (the MCP already auto-creates one at startup if `ZETRIX_ADDRESS` is omitted — see Environment below). Always checks for an existing account first — if one is active for this session, returns `{ alreadyExists: true, existing }` without creating anything; pass `confirmNew: true` (after asking the user) to mint a new one anyway | `{ password, label?, purpose?, confirmNew? }` | `{ created, alreadyExists, existing?, zetrixAddress?, holderDid?, publicKeyHex?, message }` |
 | `get_template_schema` | **Free** read of a VC template's declared attribute schema. Call before `subscribe_and_issue` to learn which attributes it requires | `{ templateId }` | `{ templateId, schema: { required, optional } }` or `{ templateId, error }` |
 | `query_contract` | Read-only query against any Zetrix contract — call an arbitrary method and return its raw result. No signing, no state change | `{ contractAddress, method, params? }` | `{ ok: true, result }` or `{ ok: false, error }` |
-| `request_ai_birthcert_verification` | Start a **Verified** AI Birthcert issuance session with myid (MyDigital ID owner verification) — distinct from `subscribe_and_issue`'s self-declared Basic AI Birthcert. Optional `gasPayer` (`"sponsored"` \| `"self"`) overrides the gas payer for this call only — precedence is per-call `gasPayer` > `GAS_PREFERENCE` config > `sponsored` hardcoded default. If a sponsored quote is refused before any money moved, the wallet automatically falls back to paying gas itself; it never falls back once payment is merely pending/indeterminate | `{ agentName, agentPurpose?, evidenceAssuranceLevel?, ownerType?, ownerVerified?, gasPayer? }` | `{ sessionId, verificationUrl, expiresAt }` |
-| `check_ai_birthcert_verification` | Poll the most recently requested Verified AI Birthcert session; on `status: "issued"`, also fetches, verifies, and caches the credential | (none) | `{ status: "pending" \| "issued" \| "no_session", vcId?, vc?, cacheError? }` |
+| `request_ai_birthcert_verification` | Start a **Verified** AI Birthcert issuance session with myid (MyDigital ID owner verification) — distinct from `subscribe_and_issue`'s self-declared Basic AI Birthcert. Optional `gasPayer` (`"sponsored"` \| `"self"`) overrides the gas payer for this call only — precedence is per-call `gasPayer` > `GAS_PREFERENCE` config > `sponsored` hardcoded default. If a sponsored quote is refused before any money moved, the wallet automatically falls back to paying gas itself; it never falls back once payment is merely pending/indeterminate. `dryRun: true` quotes instead of paying: it stops after the 402 challenge, pays nothing, creates no session, and returns `{ quote }` — the asset, the amount and which side pays gas. Quote and paid request send byte-identical signed bodies | `{ agentName, agentPurpose?, evidenceAssuranceLevel?, ownerType?, ownerVerified?, gasPayer?, dryRun? }` | `{ sessionId, verificationUrl, expiresAt }` or `{ quote: { asset, maxAmountRequired, payTo?, gasModel } }` |
+| `check_ai_birthcert_verification` | **Free.** Poll the most recently requested Verified AI Birthcert session; on `status: "issued"`, also fetches, verifies, and caches the credential. While the session is still open it replays the stored `verificationUrl` alongside SSIVC's live `expiresAt` — SSIVC issues the link only once, at creation, so this store is the only place it survives. That makes *"where is my link?"* answerable without touching the paid tool. No link is returned once `status` is `"issued"`: the link is spent | (none) | `{ status: "pending" \| "issued" \| "no_session", verificationUrl?, expiresAt?, vcId?, vc?, cacheError? }` |
 
 > **VCs are cached locally**, keyed by `templateId`, under `~/.agentic-wallet-mcp/vc-cache/`
 > (scoped per network + holder — different identities or networks never share a cache).
@@ -176,7 +177,7 @@ Node ≥ 18 required (built-in `fetch`).
 | `OID4VP_BASE_URL` | no | OID4VP verifier base URL override — auto-derived from `ZETRIX_NETWORK` by the x401 SDK when not set |
 | `ZETRIX_NODE_HOST` / `ZETRIX_NODE_PORT` | no | RPC node override (auto-derived from network) |
 | `ZID_RESOLVER_BASE_URL` | no | ZID resolver override (auto-derived from network: sandbox for testnet, prod for mainnet) |
-| `MAX_PAYMENT_AMOUNT` | no** | Per-asset x402 auto-pay cap — JSON `{ "<asset>": "<maxRawUnits>", "*": "<fallback>" }`. `pay_and_fetch`/`subscribe_and_issue` are asset-agnostic: the resource server's 402 challenge may quote the native ZETRIX token (asset code `ZTX`) **or** a ZTP20 token (e.g. `JMYR`) — cap whichever assets you expect. **Key by contract address, not symbol** — the challenge identifies a ZTP20 token by its contract address, so `{"JMYR":...}` never matches and falls through to `"*"`. e.g. `{"ZTX":"1000000000","ZTX3WeinXtt28YMyr4vUZ14ddTgEMGeuc1e6b":"5000000","*":"0"}`. **Defaults to `{"*":"0"}` — every payment is refused until you set this.** |
+| `MAX_PAYMENT_AMOUNT` | no** | Per-asset x402 auto-pay cap — JSON `{ "<asset>": "<maxRawUnits>", "*": "<fallback>" }`. `pay_and_fetch`/`subscribe_and_issue` are asset-agnostic: the resource server's 402 challenge may quote the native ZETRIX token (asset code `ZTX`) **or** a ZTP20 token (e.g. `JMYR`) — cap whichever assets you expect. **Either the ticker or the contract address works** — the challenge identifies a ZTP20 token by its contract address, and the wallet resolves a known ticker (e.g. `JMYR`) to it. If both are written for the same asset, the contract address wins. An unrecognised ticker still matches nothing and falls through to `"*"`. e.g. `{"ZTX":"1000000000","ZTX3WeinXtt28YMyr4vUZ14ddTgEMGeuc1e6b":"5000000","*":"0"}`. **Default when unset:** both networks allow exactly the AI Birthcert fee (1 JMYR), keyed to that network's JMYR contract, and refuse everything else. **The cap is per call, not cumulative** — so an unconfigured wallet, mainnet included, can pay that fee once per call with no overall ceiling. Set this explicitly to lock a wallet down. |
 | `ZETRIX_WALLET_STATE_DIR` | no | Where the wallet keeps `account.json` and its VC cache. Defaults to `~/.agentic-wallet-mcp` |
 | `SSIVC_BASE_URL` | no | myid's SSIVC API base URL, for the Verified AI Birthcert flow (`request_ai_birthcert_verification`/`check_ai_birthcert_verification`). **Auto-derived per network** — testnet `https://ssivc-api-uat.myegdev.com/api`, mainnet `https://verifyid-api.zetrix.com/api`. Override only if either changes |
 | `AI_BIRTHCERT_VERIFIED_TEMPLATE_ID` | no | The Verified AI Birthcert's on-chain `did:zid:...` template id. Auto-derived per network by default — **the mainnet default is unverified**, so override this explicitly once the mainnet template id is confirmed |

package/dist/server-bundle.cjs

@@ -12147,7 +12147,7 @@ var require_prepare_client = __commonJS({
             method: "POST",
             headers: {
               "Content-Type": "application/json",
-              "User-Agent": "x402-zetrix-js/1.0 (+https://git.myeg.com.my/genesis/x402/x402-zetrix-js)"
+              "User-Agent": "x402-zetrix-js/1.0 (+https://github.com/Zetrix-Chain/x402-zetrix-js)"
             },
             body: JSON.stringify(params),
             signal: controller.signal
@@ -12538,6 +12538,7 @@ var require_dist2 = __commonJS({
 var index_exports = {};
 __export(index_exports, {
   asPayRequest: () => asPayRequest,
+  buildPayers: () => buildPayers,
   buildToolList: () => buildToolList
 });
 module.exports = __toCommonJS(index_exports);
@@ -12549,7 +12550,7 @@ var import_node_path6 = require("node:path");
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.9.1",
+  version: "0.10.0",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -12592,7 +12593,7 @@ var package_default = {
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "x401-zetrix-client": "^0.2.1",
-    "x402-zetrix-client": "^0.2.2",
+    "x402-zetrix-client": "^0.2.4",
     "zetrix-sdk-nodejs": "^1.0.3"
   },
   devDependencies: {
@@ -21511,10 +21512,15 @@ var PaymentCapError = class extends Error {
     this.detail = detail;
   }
 };
+function formatCapRefusal(detail, renderRequired = detail.requiredRaw, renderCap = detail.capRaw) {
+  const asset = detail.asset || "(unknown asset)";
+  const base = `payment blocked: this call needs ${renderRequired} of asset "${asset}", but the limit that applies is ${renderCap}`;
+  return detail.matchedKey === detail.asset ? `${base}, set for that asset.` : `${base}. No limit is set for this asset, so the "*" fallback applies \u2014 set a limit keyed by "${asset}" to allow it.`;
+}
 function isNonNegativeIntegerString(v) {
   return /^\d+$/.test(v);
 }
-function parsePaymentCaps(json) {
+function parsePaymentCaps(json, opts = {}) {
   if (json === void 0) return void 0;
   let parsed;
   try {
@@ -21532,12 +21538,43 @@ function parsePaymentCaps(json) {
     }
     caps[asset] = raw;
   }
-  return caps;
+  return opts.resolveSymbol ? expandSymbolKeys(caps, opts.resolveSymbol, opts.onWarn) : caps;
+}
+function expandSymbolKeys(caps, resolveSymbol, onWarn) {
+  const out = {};
+  const pendingSymbols = [];
+  for (const [key, value] of Object.entries(caps)) {
+    const address = key === "*" || key === "ZTX" ? void 0 : resolveSymbol(key);
+    if (address === void 0) out[key] = value;
+    else pendingSymbols.push([key, address, value]);
+  }
+  for (const [symbol, address, value] of pendingSymbols) {
+    if (out[address] !== void 0) continue;
+    out[address] = value;
+    const previous = caps["*"] ?? "0";
+    if (BigInt(value) > BigInt(previous)) {
+      onWarn?.(
+        `MAX_PAYMENT_AMOUNT: the limit written as "${symbol}" now applies to ${address} and permits ${value}. Until this version a ticker matched nothing, so that asset was limited to ${previous}. If you did not intend to allow ${value}, change or remove the "${symbol}" entry.`
+      );
+    }
+  }
+  return out;
+}
+function describePaymentCap(asset, requiredRaw, caps) {
+  if (caps === void 0) return { asset, capRaw: null, matchedKey: null, wouldPass: true };
+  const { capRaw, matchedKey } = resolveCap(asset, caps);
+  if (capRaw === void 0) return { asset, capRaw: null, matchedKey: null, wouldPass: false };
+  const wouldPass = isNonNegativeIntegerString(requiredRaw) && BigInt(requiredRaw) <= BigInt(capRaw);
+  return { asset, capRaw, matchedKey, wouldPass };
+}
+function resolveCap(asset, caps) {
+  const explicit = caps[asset];
+  return explicit !== void 0 ? { capRaw: explicit, matchedKey: asset } : { capRaw: caps["*"], matchedKey: "*" };
 }
 function assertWithinPaymentCap(accept, caps) {
   if (caps === void 0) return;
   const asset = accept.asset ?? "";
-  const capRaw = caps[asset] ?? caps["*"];
+  const { capRaw, matchedKey } = resolveCap(asset, caps);
   if (capRaw === void 0) {
     throw new PaymentCapError(`payment blocked: no MAX_PAYMENT_AMOUNT entry for asset "${asset}" and no "*" fallback configured`);
   }
@@ -21548,10 +21585,13 @@ function assertWithinPaymentCap(accept, caps) {
   const required2 = BigInt(requiredRaw);
   const cap = BigInt(capRaw);
   if (required2 > cap) {
-    throw new PaymentCapError(
-      `payment blocked: requested ${required2} ${asset || "(unknown asset)"} exceeds configured MAX_PAYMENT_AMOUNT ${cap}`,
-      { asset, requiredRaw: required2.toString(), capRaw: cap.toString() }
-    );
+    const detail = {
+      asset,
+      requiredRaw: required2.toString(),
+      capRaw: cap.toString(),
+      matchedKey
+    };
+    throw new PaymentCapError(formatCapRefusal(detail), detail);
   }
 }
 
@@ -21583,10 +21623,22 @@ function deriveAiBirthcertVerifiedTemplateId(network) {
 var TOKEN_REGISTRY = {
   JMYR: { testnet: "ZTX3WeinXtt28YMyr4vUZ14ddTgEMGeuc1e6b", mainnet: "ZTX3NCkXBqbyJWjZZxciQez945Lu6tGAcjNJr" }
 };
+function defaultPaymentCaps(network) {
+  const jmyr = resolveTokenAddress("JMYR", network);
+  return isTestnet(network) && jmyr ? { [jmyr]: "1000000", "*": "0" } : { "*": "0" };
+}
+function defaultCredentialIssuanceCaps(network) {
+  const jmyr = resolveTokenAddress("JMYR", network);
+  return jmyr ? { [jmyr]: "1000000", "*": "0" } : { "*": "0" };
+}
+var KNOWN_NETWORKS = ["zetrix:testnet", "zetrix:mainnet"];
+function isTestnet(network) {
+  return network.includes("testnet");
+}
 function resolveTokenAddress(symbol, network) {
   const entry = TOKEN_REGISTRY[symbol.toUpperCase()];
   if (!entry) return void 0;
-  return network.includes("testnet") ? entry.testnet : entry.mainnet;
+  return isTestnet(network) ? entry.testnet : entry.mainnet;
 }
 function loadConfig(env) {
   const req = (key, hint) => {
@@ -21599,7 +21651,17 @@ function loadConfig(env) {
     return v && v.trim() ? v.trim() : void 0;
   };
   const network = opt("ZETRIX_NETWORK") ?? "zetrix:testnet";
+  if (!KNOWN_NETWORKS.includes(network)) {
+    throw new Error(
+      `agentic-wallet-mcp: unrecognised ZETRIX_NETWORK "${network}" \u2014 expected one of ${KNOWN_NETWORKS.join(", ")}. Values are matched exactly and are case-sensitive; anything unrecognised would otherwise resolve to MAINNET addresses and grant a real spending allowance.`
+    );
+  }
   const oid4vpBaseUrlOverride = opt("OID4VP_BASE_URL");
+  const explicitCaps = parsePaymentCaps(opt("MAX_PAYMENT_AMOUNT"), {
+    resolveSymbol: (symbol) => resolveTokenAddress(symbol, network),
+    onWarn: (message) => process.stderr.write(`agentic-wallet-mcp: ${message}
+`)
+  });
   return {
     walletBeUrl: stripTrailingSlash(opt("WALLET_BE_URL") ?? deriveWalletBeUrl(network)),
     oid4vpBaseUrl: oid4vpBaseUrlOverride ? stripTrailingSlash(oid4vpBaseUrlOverride) : void 0,
@@ -21619,7 +21681,11 @@ function loadConfig(env) {
     // Fail closed: an unset cap means "spend nothing", not "spend anything". A wallet that starts
     // with no configuration at all must not be able to auto-pay a hostile x402 challenge. Raising
     // it is a deliberate act.
-    maxPaymentAmount: parsePaymentCaps(opt("MAX_PAYMENT_AMOUNT")) ?? { "*": "0" },
+    //
+    // An explicit MAX_PAYMENT_AMOUNT governs BOTH caps below — a user who sets a limit means it
+    // everywhere. Only the defaults differ, and only because the two surfaces carry different risk.
+    maxPaymentAmount: explicitCaps ?? defaultPaymentCaps(network),
+    credentialIssuanceCaps: explicitCaps ?? defaultCredentialIssuanceCaps(network),
     ssivcBaseUrl: (() => {
       const v = opt("SSIVC_BASE_URL") ?? deriveSsivcBaseUrl(network);
       return v ? stripTrailingSlash(v) : void 0;
@@ -21738,27 +21804,42 @@ async function fetchZTP20BalanceStrict(contractAddress, address, query) {
   if (typeof balance !== "string") {
     throw new Error("balanceOf returned no balance field");
   }
+  if (!/^\d+$/.test(balance)) {
+    throw new Error(`balanceOf returned a non-numeric balance: ${JSON.stringify(balance)}`);
+  }
   return balance;
 }
+function looksLikeContractAddress(token) {
+  return /^ZTX[0-9A-Za-z]{30,}$/.test(token);
+}
 async function queryTokenBalance(deps, token) {
   const symbol = token.toUpperCase();
   if (symbol === "ZTX") {
     try {
-      return { token: symbol, balance: await deps.fetchNativeBalance(deps.address), decimals: ZTX_DECIMALS2 };
+      const balance2 = await deps.fetchNativeBalance(deps.address);
+      return { token: symbol, balance: balance2, decimals: ZTX_DECIMALS2, display: renderDisplay(balance2, ZTX_DECIMALS2, symbol) };
     } catch {
       return { token: symbol, error: "query_failed" };
     }
   }
-  const contractAddress = deps.resolveTokenAddress(symbol);
+  const registered = deps.resolveTokenAddress(symbol);
+  const byAddress = registered === null && looksLikeContractAddress(token);
+  const contractAddress = registered ?? (byAddress ? token : null);
   if (!contractAddress) return { token: symbol, error: "unknown_token" };
+  const asked = byAddress ? token : symbol;
   let balance;
   try {
     balance = await fetchZTP20BalanceStrict(contractAddress, deps.address, deps.query);
   } catch {
-    return { token: symbol, error: "query_failed" };
+    return { token: asked, error: "query_failed" };
   }
   const info = await fetchTokenInfo(contractAddress, deps.query);
-  return { token: symbol, balance, decimals: info?.decimals ?? null };
+  const label = byAddress ? info?.symbol ?? asked : symbol;
+  const decimals = info?.decimals ?? null;
+  return { token: label, balance, decimals, display: renderDisplay(balance, decimals, label) };
+}
+function renderDisplay(raw, decimals, label) {
+  return `${decimals === null ? raw : formatHumanAmount(raw, decimals)} ${label}`;
 }
 
 // src/clients/template-info-client.ts
@@ -22032,6 +22113,24 @@ var MbiClient = class _MbiClient {
     if (!res.ok) throw await this.error(res, "apply (phase 2) failed");
     return this.unwrap(res);
   }
+  /**
+   * POST /v1/vc/pay/quote — the price for a template, with no issuance and no payment record.
+   *
+   * Unlike `applyChallenge`, this cannot mint anything: MBI resolves the template, builds the
+   * canonical sign payload, and reads its configured price. Notably a FREE template does not
+   * short-circuit into synchronous issuance here, which is what makes this safe to call purely to
+   * find out a cost — `applyChallenge` is not (see its docstring).
+   *
+   * `data` is required to be non-empty by MBI's DTO but does not affect the price, which comes from
+   * MBI's own asset config keyed by the resolved template. A caller pricing a credential before it
+   * has collected any attribute therefore passes a throwaway value, and must not present it as
+   * anything the user supplied.
+   */
+  async quote(templateId, data) {
+    const res = await this.fetch("POST", "/v1/vc/pay/quote", { templateId, data });
+    if (!res.ok) throw await this.error(res, "quote failed");
+    return this.unwrap(res);
+  }
   /** Idempotent recovery — GET /v1/vc/pay/status/{paymentId}. */
   async getStatus(paymentId) {
     const res = await this.fetch("GET", `/v1/vc/pay/status/${encodeURIComponent(paymentId)}`);
@@ -22169,6 +22268,43 @@ function payAndFetch(payer, req) {
   return payer(req);
 }
 
+// src/accept-selection.ts
+function extraOf(accept) {
+  const extra = accept.extra;
+  if (!extra || typeof extra !== "object" || Array.isArray(extra)) return {};
+  return extra;
+}
+function assetOf(accept) {
+  return String(accept.asset ?? "");
+}
+function declaresFacilitator(accept) {
+  return extraOf(accept).gasModel === "facilitator";
+}
+function isSponsored(accept) {
+  if (!declaresFacilitator(accept)) return false;
+  const prepareEndpoint = extraOf(accept).prepareEndpoint;
+  if (typeof prepareEndpoint !== "string" || prepareEndpoint === "") return false;
+  const asset = assetOf(accept);
+  return asset !== "" && asset !== "ZTX";
+}
+function isUnusable(accept) {
+  return declaresFacilitator(accept) && !isSponsored(accept);
+}
+function orderAccepts(accepts, prefer) {
+  const usable = accepts.filter((a) => !isUnusable(a));
+  const sponsored = usable.filter(isSponsored);
+  const selfPay = usable.filter((a) => !isSponsored(a));
+  return prefer === "sponsored" ? [...sponsored, ...selfPay] : [...selfPay, ...sponsored];
+}
+function prepareBaseUrl(prepareEndpoint) {
+  return prepareEndpoint.replace(/\/+$/, "").replace(/\/prepare$/, "");
+}
+function needsNativeGasCheck(accept) {
+  const asset = String(accept.asset ?? "");
+  if (asset === "" || asset === "ZTX") return false;
+  return !isSponsored(accept);
+}
+
 // src/zetrix-hex.ts
 function zetrixHexStringToBytes(s) {
   const up = s.toUpperCase();
@@ -22359,6 +22495,45 @@ async function subscribeAndIssue(deps, opts) {
       };
     }
   }
+  if (opts.dryRun) {
+    if (!deps.mbi.quote) {
+      return {
+        issued: false,
+        reason: "dry run unavailable \u2014 this wallet has no MBI quote client, and pricing any other way risks issuing the credential",
+        ...schema ? { schema } : {}
+      };
+    }
+    let quoted;
+    try {
+      quoted = await deps.mbi.quote(opts.templateId, attributes);
+    } catch (err) {
+      if (err instanceof MbiError) {
+        return { issued: false, reason: err.message, httpStatus: err.httpStatus, ...schema ? { schema } : {} };
+      }
+      throw err;
+    }
+    const quotedAccept = quoted.accepts?.[0];
+    if (!quotedAccept) {
+      return { issued: false, reason: "MBI quoted no payment options", ...schema ? { schema } : {} };
+    }
+    const quotedRaw = String(quotedAccept.asset ?? "");
+    const quotedAsset = deps.resolveSymbol ? await deps.resolveSymbol(quotedRaw) : quotedRaw;
+    const reason = quoted.paymentRequired === false ? "dry run \u2014 issuance is free right now, no payment required" : quoted.paymentRequired === true ? "dry run \u2014 quoted only, no payment made" : "dry run \u2014 quoted only, no payment made. This MBI does not report whether issuance is free, so the quoted amount may not actually be charged.";
+    return {
+      issued: false,
+      reason,
+      quote: {
+        asset: quotedAsset,
+        maxAmountRequired: quotedAccept.maxAmountRequired,
+        payTo: quotedAccept.payTo,
+        // credential_preflight reads a missing gasModel as self-pay (preflight.ts), so a
+        // sponsored template credential must say so explicitly rather than fall through as absent.
+        gasModel: isSponsored(quotedAccept) ? "sponsored" : "self",
+        ...quoted.paymentRequired === void 0 ? {} : { paymentRequired: quoted.paymentRequired }
+      },
+      ...schema ? { schema } : {}
+    };
+  }
   const data = JSON.stringify([{ templateId: opts.templateId, metadata: attributes }]);
   const blob = zetrixHexStringToBytes(data).toString("hex");
   const { signBlob: signData, publicKey } = await deps.sign(blob);
@@ -22394,26 +22569,11 @@ async function subscribeAndIssue(deps, opts) {
       txHash: issued2.txHash,
       paidAsset: "none",
       amountPaid: "0",
-      ...schema ? { schema } : {},
-      ...opts.dryRun ? { reason: "this template requires no payment \u2014 MBI issues synchronously at phase 1, so dryRun could not prevent this issuance" } : {}
+      ...schema ? { schema } : {}
     };
   }
   const accept = challenge.accepts[0];
   if (!accept) return { issued: false, reason: "MBI 402 returned no payment options", ...schema ? { schema } : {} };
-  if (opts.dryRun) {
-    const quotedRaw = String(accept.asset ?? "");
-    const quotedAsset = deps.resolveSymbol ? await deps.resolveSymbol(quotedRaw) : quotedRaw;
-    return {
-      issued: false,
-      reason: "dry run \u2014 quoted only, no payment made",
-      quote: {
-        asset: quotedAsset,
-        maxAmountRequired: accept.maxAmountRequired,
-        payTo: accept.payTo
-      },
-      ...schema ? { schema } : {}
-    };
-  }
   let xPayment;
   try {
     xPayment = await deps.pay(accept);
@@ -22874,6 +23034,102 @@ function validateTemplateAttributes(templateId, network, attributes) {
   return errors;
 }
 
+// src/orchestrator/preflight.ts
+var VERIFIED_AI_BIRTHCERT = "verified_ai_birthcert";
+var NATIVE = "ZTX";
+function placeholderAgentName() {
+  return `preflight-quote-only-${Date.now()}`;
+}
+async function credentialPreflight(deps, input) {
+  const blockers = [];
+  const notChecked = [];
+  const isVerified = input.credential === VERIFIED_AI_BIRTHCERT;
+  const quoted = isVerified ? await deps.quoteVerified({ agentName: input.agentName?.trim() || placeholderAgentName(), dryRun: true }) : await deps.quoteTemplate(input.credential);
+  const quote = quoted.quote;
+  const schema = quoted.schema;
+  if (!quote) {
+    const why = String(quoted.error ?? quoted.reason ?? "the price could not be read");
+    return {
+      credential: input.credential,
+      ready: false,
+      balances: [],
+      ...schema ? { schema } : {},
+      blockers: [`Could not price this credential: ${why}`],
+      notChecked: uncheckable(isVerified)
+    };
+  }
+  const asset = String(quote.asset ?? "");
+  const requiredRaw = String(quote.maxAmountRequired ?? "0");
+  const gasModel = quote.gasModel === "sponsored" || quote.gasModel === "self" ? quote.gasModel : void 0;
+  const selfPaysGas = gasModel !== "sponsored";
+  const wanted = asset === NATIVE || !selfPaysGas ? [asset] : [asset, NATIVE];
+  const balances = await Promise.all(wanted.map((token) => deps.queryTokenBalance(token)));
+  const isFree = quote.paymentRequired === false;
+  const feeBalance = balances[0];
+  if ("error" in feeBalance) {
+    blockers.push(`Could not read the ${asset} balance (${feeBalance.error}) \u2014 retry before paying.`);
+  } else if (!isFree && BigInt(feeBalance.balance) < BigInt(requiredRaw)) {
+    blockers.push(`Not enough ${feeBalance.token}: the fee is ${renderAmount(requiredRaw, feeBalance)}, the balance is ${feeBalance.display}.`);
+  }
+  if (selfPaysGas && asset !== NATIVE) {
+    const gas = balances[1];
+    if (gas && "error" in gas) {
+      blockers.push(`Could not read the ZTX balance (${gas.error}) \u2014 ZTX pays network gas and is separate from the fee.`);
+    } else if (gas && BigInt(gas.balance) === 0n) {
+      blockers.push(`No ZTX for network gas. ZTX is separate from the ${feeBalance.token ?? asset} fee and is needed for every transaction.`);
+    }
+  }
+  const cap = describePaymentCap(asset, requiredRaw, deps.caps);
+  if (!cap.wouldPass && !isFree) blockers.push(renderCapBlocker(cap, requiredRaw));
+  return {
+    credential: input.credential,
+    ready: blockers.length === 0,
+    fee: {
+      asset,
+      maxAmountRequired: requiredRaw,
+      ...quote.payTo ? { payTo: String(quote.payTo) } : {},
+      ...gasModel ? { gasModel } : {},
+      ..."error" in feeBalance ? {} : { display: renderAmount(requiredRaw, feeBalance) },
+      ...quote.paymentRequired === void 0 ? {} : { paymentRequired: quote.paymentRequired }
+    },
+    balances,
+    cap,
+    ...schema ? { schema } : {},
+    blockers,
+    notChecked: uncheckable(isVerified, isFree)
+  };
+}
+function renderAmount(raw, balance) {
+  if ("error" in balance || balance.decimals === null) return raw;
+  const d = BigInt(10) ** BigInt(balance.decimals);
+  const whole = BigInt(raw) / d;
+  const frac = (BigInt(raw) % d).toString().padStart(balance.decimals, "0").replace(/0+$/, "");
+  return `${whole}${frac ? `.${frac}` : ""} ${balance.token}`;
+}
+function renderCapBlocker(cap, requiredRaw) {
+  if (cap.capRaw === null) {
+    return `No spending limit applies to ${cap.asset}, and limits are configured \u2014 so this payment would be refused. Set a limit keyed by "${cap.asset}".`;
+  }
+  const misKeyed = cap.matchedKey !== cap.asset;
+  return misKeyed ? `The spending limit that applies is ${cap.capRaw} (from the "*" fallback \u2014 no limit is set for ${cap.asset}), and this needs ${requiredRaw}.` : `The spending limit for ${cap.asset} is ${cap.capRaw}, and this needs ${requiredRaw}.`;
+}
+function uncheckable(isVerified, isFree = false) {
+  const items = [
+    "Whether the wallet address is activated on chain \u2014 a never-funded address fails differently from a low balance."
+  ];
+  if (isVerified) {
+    items.unshift(
+      "Whether the agent name is still free. myid checks uniqueness at issuance, not now, so a name in use still prices normally and is only refused after payment."
+    );
+  }
+  if (isFree) {
+    items.unshift(
+      "Whether issuance is still free at apply time \u2014 `paymentRequired` is a service-wide MBI setting and can change between this quote and issuance."
+    );
+  }
+  return items;
+}
+
 // src/mcp-tools.ts
 async function loadValidCachedCredentials(cache) {
   if (!cache) return [];
@@ -22882,10 +23138,15 @@ async function loadValidCachedCredentials(cache) {
 }
 var AI_BIRTHCERT_NOT_CONFIGURED_ERROR = "AI Birthcert verification is not configured on this wallet. On mainnet this is expected until SSIVC_BASE_URL is set explicitly (the mainnet host was never confirmed reachable \u2014 APP-M04); on testnet it means verifyAiBirthcert was not wired at all.";
 function createTools(deps) {
-  return {
+  const tools = {
     async wallet_status(input = {}) {
       const balances = deps.getBalances ? await deps.getBalances() : void 0;
       const tokenBalance = input.token && deps.queryTokenBalance ? await deps.queryTokenBalance(input.token) : void 0;
+      let tokenBalances;
+      if (input.tokens?.length && deps.queryTokenBalance) {
+        tokenBalances = [];
+        for (const t of input.tokens) tokenBalances.push(await deps.queryTokenBalance(t));
+      }
       const credentials = input.heldCredentials ?? (await loadValidCachedCredentials(deps.cache)).map((entry) => entry.vc);
       return {
         holderDid: deps.config.holderDid,
@@ -22893,7 +23154,8 @@ function createTools(deps) {
         network: deps.config.network,
         credentials,
         ...balances !== void 0 ? { balances } : {},
-        ...tokenBalance !== void 0 ? { tokenBalance } : {}
+        ...tokenBalance !== void 0 ? { tokenBalance } : {},
+        ...tokenBalances !== void 0 ? { tokenBalances } : {}
       };
     },
     async prove_identity(input) {
@@ -22990,6 +23252,38 @@ function createTools(deps) {
       }
       return deps.verifyAiBirthcert.request(input);
     },
+    /**
+     * One read-only answer to "can this wallet buy this, and what does it cost?", before any
+     * application field is collected. Composes the free pieces that already exist — a phase-1 quote,
+     * balances, the spending cap — into a single verdict, so the balance and the cap stop being two
+     * sequential dead ends.
+     */
+    async credential_preflight(input) {
+      if (input.credential === VERIFIED_AI_BIRTHCERT && !deps.verifyAiBirthcert) {
+        return { credential: input.credential, ready: false, balances: [], blockers: [AI_BIRTHCERT_NOT_CONFIGURED_ERROR], notChecked: [] };
+      }
+      if (!deps.queryTokenBalance) {
+        return {
+          credential: input.credential,
+          ready: false,
+          balances: [],
+          blockers: ["This wallet cannot read balances, so readiness cannot be confirmed."],
+          notChecked: []
+        };
+      }
+      return credentialPreflight(
+        {
+          quoteVerified: (q) => deps.verifyAiBirthcert.request(q),
+          quoteTemplate: async (templateId) => {
+            const resolved = resolveTemplateAlias(templateId, deps.config.network) ?? templateId;
+            return priceTemplate(deps, tools, resolved);
+          },
+          queryTokenBalance: deps.queryTokenBalance,
+          caps: deps.paymentCaps
+        },
+        input
+      );
+    },
     check_ai_birthcert_verification() {
       if (!deps.verifyAiBirthcert) {
         return { error: AI_BIRTHCERT_NOT_CONFIGURED_ERROR };
@@ -22997,6 +23291,42 @@ function createTools(deps) {
       return deps.verifyAiBirthcert.check();
     }
   };
+  return tools;
+}
+async function priceTemplate(deps, tools, templateId) {
+  const schemaResult = await tools.get_template_schema({ templateId });
+  const schema = schemaResult.schema;
+  if (!schema && schemaResult.error) {
+    return { reason: schemaResult.error };
+  }
+  const quoteFn = deps.subscribeDeps.mbi.quote;
+  if (!quoteFn) {
+    return { reason: "this wallet cannot price template credentials (MBI quote unavailable)", ...schema ? { schema } : {} };
+  }
+  let accepts;
+  let paymentRequired;
+  try {
+    ;
+    ({ accepts, paymentRequired } = await quoteFn.call(deps.subscribeDeps.mbi, templateId, { preflight: "quote-only" }));
+  } catch (err) {
+    return { reason: err.message, ...schema ? { schema } : {} };
+  }
+  const accept = accepts?.[0];
+  if (!accept) return { reason: "MBI quoted no payment options for this template", ...schema ? { schema } : {} };
+  return {
+    quote: {
+      asset: accept.asset,
+      maxAmountRequired: accept.maxAmountRequired,
+      payTo: accept.payTo,
+      // Stated either way: preflight reads a missing gasModel as self-pay, so silence here would be
+      // indistinguishable from a deliberate "you pay the gas".
+      gasModel: isSponsored(accept) ? "sponsored" : "self",
+      // Carried through: this is the only thing in the response that
+      // says whether `maxAmountRequired` will actually be charged, and preflight gates on it.
+      ...paymentRequired === void 0 ? {} : { paymentRequired }
+    },
+    ...schema ? { schema } : {}
+  };
 }
 
 // src/orchestrator/resolve-holder.ts
@@ -23338,43 +23668,6 @@ function canonicalizeJson(value) {
   return JSON.stringify(value);
 }
 
-// src/accept-selection.ts
-function extraOf(accept) {
-  const extra = accept.extra;
-  if (!extra || typeof extra !== "object" || Array.isArray(extra)) return {};
-  return extra;
-}
-function assetOf(accept) {
-  return String(accept.asset ?? "");
-}
-function declaresFacilitator(accept) {
-  return extraOf(accept).gasModel === "facilitator";
-}
-function isSponsored(accept) {
-  if (!declaresFacilitator(accept)) return false;
-  const prepareEndpoint = extraOf(accept).prepareEndpoint;
-  if (typeof prepareEndpoint !== "string" || prepareEndpoint === "") return false;
-  const asset = assetOf(accept);
-  return asset !== "" && asset !== "ZTX";
-}
-function isUnusable(accept) {
-  return declaresFacilitator(accept) && !isSponsored(accept);
-}
-function orderAccepts(accepts, prefer) {
-  const usable = accepts.filter((a) => !isUnusable(a));
-  const sponsored = usable.filter(isSponsored);
-  const selfPay = usable.filter((a) => !isSponsored(a));
-  return prefer === "sponsored" ? [...sponsored, ...selfPay] : [...selfPay, ...sponsored];
-}
-function prepareBaseUrl(prepareEndpoint) {
-  return prepareEndpoint.replace(/\/+$/, "").replace(/\/prepare$/, "");
-}
-function needsNativeGasCheck(accept) {
-  const asset = String(accept.asset ?? "");
-  if (asset === "" || asset === "ZTX") return false;
-  return !isSponsored(accept);
-}
-
 // src/orchestrator/verify-ai-birthcert.ts
 function subjectMatches(vc, holderDid) {
   if (typeof vc !== "object" || vc === null) return false;
@@ -23496,6 +23789,7 @@ var DEFINITIVE_PREPARE_REFUSALS = /* @__PURE__ */ new Set([
   461415
   // X402_UNSUPPORTED_ASSET    — sponsorship is ZTP-20 only
 ]);
+var FACILITATOR_INSUFFICIENT_FUNDS_CODE = 461407;
 function facilitatorErrorCode(err) {
   const m = /"errorCode"\s*:\s*(\d{6})/.exec(err instanceof Error ? err.message : String(err));
   return m ? Number(m[1]) : void 0;
@@ -23515,6 +23809,41 @@ function isDefinitiveSponsorshipFailure(err) {
   if (code === void 0) return false;
   return DEFINITIVE_PREPARE_REFUSALS.has(code);
 }
+var FacilitatorInsufficientFundsError = class extends Error {
+  constructor(requiredHuman, availableHuman, rawMessage) {
+    super(
+      `insufficient funds: the sponsored payment requires ${requiredHuman}` + (availableHuman !== void 0 ? ` \u2014 this wallet currently holds ${availableHuman}` : " and this wallet does not hold enough of it") + ` (facilitator: ${rawMessage})`
+    );
+    this.name = "FacilitatorInsufficientFundsError";
+  }
+};
+function extractFacilitatorBalance(rawMessage) {
+  const braceIdx = rawMessage.indexOf("{");
+  if (braceIdx !== -1) {
+    try {
+      const body = JSON.parse(rawMessage.slice(braceIdx));
+      const detail = body.messages?.[0]?.detail;
+      if (Array.isArray(detail) && detail.length >= 3 && detail[2] !== null && detail[2] !== void 0) {
+        return String(detail[2]);
+      }
+    } catch {
+    }
+  }
+  const m = /insufficient_funds \[[^,]+,\s*[^,]+,\s*([^\]]+)\]/.exec(rawMessage);
+  return m ? m[1].trim() : void 0;
+}
+async function toFacilitatorInsufficientFundsError(err, accept, formatAssetAmount) {
+  if (!(err instanceof PrepareStageError)) return err;
+  if (facilitatorErrorCode(err.cause) !== FACILITATOR_INSUFFICIENT_FUNDS_CODE) return err;
+  const asset = accept.asset ?? "";
+  const maxAmountRequired = accept.maxAmountRequired ?? "";
+  if (!asset || !maxAmountRequired) return err;
+  const rawMessage = err.cause instanceof Error ? err.cause.message : String(err.cause);
+  const requiredHuman = formatAssetAmount ? await formatAssetAmount(asset, maxAmountRequired) : `${maxAmountRequired} of asset "${asset}"`;
+  const availableRaw = extractFacilitatorBalance(rawMessage);
+  const availableHuman = availableRaw !== void 0 && formatAssetAmount ? await formatAssetAmount(asset, availableRaw) : availableRaw;
+  return new FacilitatorInsufficientFundsError(requiredHuman, availableHuman, rawMessage);
+}
 async function attemptCandidate(deps, accept, buildBody, onQueued) {
   let xPayment;
   try {
@@ -23534,8 +23863,9 @@ async function payAndCreateSession(deps, buildBody, onQueued) {
     return await attemptCandidate(deps, primary, buildBody, onQueued);
   } catch (err) {
     const fallback = candidates[1];
-    if (!fallback || !isSponsored(primary) || isSponsored(fallback)) throw err;
-    if (!isDefinitiveSponsorshipFailure(err)) throw err;
+    if (!fallback || !isSponsored(primary) || isSponsored(fallback) || !isDefinitiveSponsorshipFailure(err)) {
+      throw await toFacilitatorInsufficientFundsError(err, primary, deps.formatAssetAmount);
+    }
     return await attemptCandidate(deps, fallback, buildBody, onQueued);
   }
 }
@@ -23544,29 +23874,48 @@ async function requestAiBirthcertVerification(deps, input) {
     throw new Error("requestAiBirthcertVerification: agentName is required");
   }
   const agentName = input.agentName.trim();
+  if (input.dryRun) return quoteVerification(deps, agentName, input);
   return withRequestLock(() => requestAiBirthcertVerificationLocked(deps, agentName, input));
 }
+async function buildSessionBody(deps, agentName, input) {
+  const fields = {
+    publicKey: deps.publicKeyHex,
+    address: deps.address,
+    timestamp: isoSeconds(deps.now()),
+    agentName,
+    id: agentName,
+    ownerReference: deps.holderDid
+  };
+  if (input.agentPurpose) fields.agentPurpose = input.agentPurpose;
+  if (input.evidenceAssuranceLevel) fields.evidenceAssuranceLevel = input.evidenceAssuranceLevel;
+  if (input.ownerType) fields.ownerType = input.ownerType;
+  if (input.ownerVerified) fields.ownerVerified = input.ownerVerified;
+  const digestHex = (0, import_node_crypto4.createHash)("sha256").update(canonicalizeJson(fields), "utf8").digest("hex");
+  const { signBlob: signedData } = await deps.signHexBlob(digestHex);
+  return { ...fields, signedData };
+}
+async function quoteVerification(deps, agentName, input) {
+  const requestedGasPayer = input.gasPayer === "self" || input.gasPayer === "sponsored" ? input.gasPayer : void 0;
+  const body = await buildSessionBody(deps, agentName, input);
+  const challenge = await deps.ssivc.createSessionChallenge(body);
+  const chosen = orderAccepts(challenge.accepts, requestedGasPayer ?? deps.gasPreference ?? "sponsored")[0];
+  if (!chosen) return { error: "SSIVC 402 returned no usable payment options" };
+  return {
+    quote: {
+      asset: String(chosen.asset ?? ""),
+      maxAmountRequired: String(chosen.maxAmountRequired ?? ""),
+      ...chosen.payTo ? { payTo: String(chosen.payTo) } : {},
+      // Report the option that would actually be paid, not merely what was offered — the ranking
+      // already discards a sponsored quote we could not act on.
+      gasModel: isSponsored(chosen) ? "sponsored" : "self"
+    }
+  };
+}
 async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
   const decision = await decidePriorSession(deps, agentName);
   if (decision.kind === "still_pending") return decision.result;
   if (decision.kind === "blocked") return { error: decision.message };
-  const buildBody = async () => {
-    const fields = {
-      publicKey: deps.publicKeyHex,
-      address: deps.address,
-      timestamp: isoSeconds(deps.now()),
-      agentName,
-      id: agentName,
-      ownerReference: deps.holderDid
-    };
-    if (input.agentPurpose) fields.agentPurpose = input.agentPurpose;
-    if (input.evidenceAssuranceLevel) fields.evidenceAssuranceLevel = input.evidenceAssuranceLevel;
-    if (input.ownerType) fields.ownerType = input.ownerType;
-    if (input.ownerVerified) fields.ownerVerified = input.ownerVerified;
-    const digestHex = (0, import_node_crypto4.createHash)("sha256").update(canonicalizeJson(fields), "utf8").digest("hex");
-    const { signBlob: signedData } = await deps.signHexBlob(digestHex);
-    return { ...fields, signedData };
-  };
+  const buildBody = () => buildSessionBody(deps, agentName, input);
   const persistQueuedReceipt = async (receipt) => {
     try {
       await deps.sessionStore.set({
@@ -23602,9 +23951,10 @@ async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
     }
   } catch (rawErr) {
     const err = rawErr instanceof PrepareStageError ? rawErr.cause : rawErr;
-    if (err instanceof PaymentReadinessError) return { error: `insufficient funds: ${err.message}` };
-    if (err instanceof PaymentCapError) return { error: err.message };
+    if (err instanceof PaymentReadinessError) return { error: `insufficient funds: ${err.message}`, insufficientFunds: err.shortfall };
+    if (err instanceof PaymentCapError) return { error: err.message, ...err.detail ? { paymentCap: err.detail } : {} };
     if (err instanceof NoPaymentOptionsError) return { error: err.message };
+    if (err instanceof FacilitatorInsufficientFundsError) return { error: err.message };
     if (err instanceof SettlementStillQueuedError) {
       try {
         await deps.sessionStore.set({
@@ -23655,6 +24005,9 @@ async function checkAiBirthcertVerification(deps) {
     };
   }
   const status = await deps.ssivc.getSession(stored.sessionId);
+  if (status.status !== "issued" && stored.verificationUrl) {
+    return { ...status, verificationUrl: stored.verificationUrl };
+  }
   if (status.status !== "issued" || !status.vcId) return status;
   if (deps.verifiedTemplateId && deps.cache) {
     const cached2 = await deps.cache.get(deps.verifiedTemplateId);
@@ -23724,7 +24077,8 @@ function buildToolList() {
         type: "object",
         properties: {
           heldCredentials: { type: "array", items: { type: "object" }, description: "VCs the client holds. Omit to report whatever the wallet has cached locally from prior subscribe_and_issue calls instead." },
-          token: { type: "string", description: `Optional token symbol (e.g. "ZTX", "JMYR") to check its balance for the active network, alongside the usual status fields. Returns { balance, decimals } where balance is in the asset's raw base units \u2014 divide by 10^decimals for the human amount (e.g. balance "473999900" with decimals 6 is 473.9999 JMYR). A failed lookup reports { error: "query_failed" } rather than a zero balance.` }
+          token: { type: "string", description: 'Optional token symbol (e.g. "ZTX", "JMYR") OR a ZTP20 contract address, to check its balance for the active network alongside the usual status fields. Returns { balance, decimals, display } \u2014 `balance` is in the asset\'s raw base units and `display` is the same amount in whole tokens with its symbol (e.g. balance "473999900", decimals 6, display "473.9999 JMYR"). Quote a `display` value to the user, never a bare `balance`. A failed lookup reports { error: "query_failed" } rather than a zero balance; an unrecognised name reports { error: "unknown_token" }.' },
+          tokens: { type: "array", items: { type: "string" }, description: 'Several tokens (symbols and/or ZTP20 contract addresses) in one call, returned as `tokenBalances` in the order asked. Prefer this over repeated single-token calls when checking affordability: a credential fee and the native ZTX needed for gas are separate balances, and asking one at a time is how "you hold the token but no gas" is discovered only after the first shortfall was already fixed. Each entry carries its own result or error, so one failure does not hide the rest.' }
         }
       }
     },
@@ -23807,7 +24161,7 @@ function buildToolList() {
           expirationDate: { type: "string" },
           dryRun: {
             type: "boolean",
-            description: "Stop after MBI's free phase-1 quote and return { quote: { asset, maxAmountRequired, payTo }, schema: { required, optional } } without paying or issuing \u2014 use this to check the payment requirement AND the template's full attribute schema (read from chain) before spending funds. Still validates required attributes locally first \u2014 a missing one blocks before any MBI call."
+            description: "Price the credential without paying, signing, or issuing anything. Returns { quote: { asset, maxAmountRequired, payTo, gasModel, paymentRequired? }, schema: { required, optional } }. Priced via MBI's /quote endpoint, which cannot issue \u2014 so this is safe even on a template that issues for free (such a template mints synchronously on the real path, which is why pricing never goes through it). Never writes the VC cache, so it cannot displace a credential you already hold. `quote.paymentRequired` is the authoritative free-vs-paid answer: false means issuance is currently free and `maxAmountRequired` will not be charged. When the field is ABSENT the MBI predates it and the amount is unconfirmed \u2014 report it as a possible charge, never as certainly free. Still validates required attributes locally first \u2014 a missing one blocks before any MBI call."
           },
           forceReissue: {
             type: "boolean",
@@ -23819,7 +24173,7 @@ function buildToolList() {
     },
     {
       name: "request_ai_birthcert_verification",
-      description: `Start a Verified AI Birthcert issuance session with myid (MyDigital ID owner verification). Returns { sessionId, verificationUrl, expiresAt } \u2014 show verificationUrl to the human owner and ask them to open it and complete MyDigital ID verification (typically finishes in seconds). Once they confirm they are done, call check_ai_birthcert_verification to see whether the credential was issued. IMPORTANT: agentName must be unique \u2014 if this exact name has already been used to request a Verified AI Birthcert, issuance will fail. Before calling, ask the human owner whether they want to supply any of the optional fields \u2014 agentPurpose, evidenceAssuranceLevel, ownerType, ownerVerified \u2014 do not silently omit them; they only need to say no. Calling this again with the SAME agentName while a prior session is still pending returns that same session unchanged \u2014 no new session is started and nothing is paid again. This tool spends real funds: it self-pays an x402 challenge, subject to the wallet's configured MAX_PAYMENT_AMOUNT cap, the same as pay_and_fetch/subscribe_and_issue. It can return { error: "..." } instead of a session if that payment fails (insufficient funds, or the payment cap blocked it) \u2014 nothing is created in that case. If the user did NOT ask for a "verified" credential specifically, they most likely want the self-declared, non-verified Basic AI Birthcert instead \u2014 use subscribe_and_issue for that.`,
+      description: `Start a Verified AI Birthcert issuance session with myid (MyDigital ID owner verification). Returns { sessionId, verificationUrl, expiresAt } \u2014 show verificationUrl to the human owner and ask them to open it and complete MyDigital ID verification (typically finishes in seconds). Once they confirm they are done, call check_ai_birthcert_verification to see whether the credential was issued. IMPORTANT: agentName must be unique \u2014 if this exact name has already been used to request a Verified AI Birthcert, issuance will fail. Before calling, ask the human owner whether they want to supply any of the optional fields \u2014 agentPurpose, evidenceAssuranceLevel, ownerType, ownerVerified \u2014 do not silently omit them; they only need to say no. Calling this again with the SAME agentName while a prior session is still pending returns that same session unchanged \u2014 no new session is started and nothing is paid again. This tool spends real funds: it self-pays an x402 challenge, subject to the same credential-issuance payment cap as subscribe_and_issue \u2014 a separate, narrower cap than pay_and_fetch's, which defaults to refusing everything on mainnet. Set MAX_PAYMENT_AMOUNT to override either. It can return { error: "..." } instead of a session if that payment fails (insufficient funds, or the payment cap blocked it) \u2014 nothing is created in that case. If the user did NOT ask for a "verified" credential specifically, they most likely want the self-declared, non-verified Basic AI Birthcert instead \u2014 use subscribe_and_issue for that.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -23835,14 +24189,36 @@ function buildToolList() {
             type: "string",
             enum: ["sponsored", "self"],
             description: `Who pays network gas. "sponsored" (default) asks the platform paymaster to cover gas, so this wallet needs no ZTX. "self" pays gas from this wallet's own ZTX balance. Omit to use the configured default.`
+          },
+          dryRun: {
+            type: "boolean",
+            description: "Ask the price WITHOUT paying. Returns { quote: { asset, maxAmountRequired, payTo, gasModel } } and spends nothing, creates no session, and starts no verification \u2014 so you can tell the user the cost before collecting anything. `maxAmountRequired` is in the asset's RAW base units; resolve decimals (wallet_status returns `display`) before quoting a figure to a human. A quote does NOT reserve the name and does NOT check whether it is already taken \u2014 myid checks uniqueness only at issuance, so a name already in use still quotes cleanly. `agentName` is still required because the server rejects a request without one, but the fee does not depend on it."
           }
         },
         required: ["agentName"]
       }
     },
+    {
+      name: "credential_preflight",
+      description: "FREE readiness check \u2014 call this FIRST, before collecting ANY application detail from the user, whenever they ask for a credential. Spends nothing, signs no transaction, creates no session. Returns { ready, fee, balances, cap, schema?, blockers, notChecked }: the live fee and which side pays gas, the balances that matter, whether the spending limit permits it, and \u2014 for a template credential \u2014 the attributes it requires. `blockers` lists EVERY reason it is not ready at once (a low balance and a too-low spending limit are different problems and both appear together), so one round of fixes is enough rather than discovering them one failed payment at a time. ALWAYS relay `notChecked` too: a clean result is not a guarantee. In particular it does NOT check whether an agent name is free \u2014 myid decides that at issuance, after payment. Report `fee.display` and each balance's `display` to the user, never the raw base-unit numbers. `fee.paymentRequired: false` means issuance is currently FREE \u2014 `fee.display` is then only what it WOULD cost if payment were switched back on, so do not ask the user to fund it and do not present that amount as a charge. Gas is separate and can still block a free credential. When the field is ABSENT the cost is unknown (an older MBI), and it is treated as chargeable \u2014 never report absent as free.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          credential: {
+            type: "string",
+            description: 'Which credential to price: "verified_ai_birthcert" for the MyDigital-ID-verified AI Birthcert, or a template id (did:zid:...) / known template name (e.g. "AI Birthcert") for a template-issued one.'
+          },
+          agentName: {
+            type: "string",
+            description: 'Optional, and only used for "verified_ai_birthcert". The fee does not depend on it, so omit it when pricing before the user has chosen a name \u2014 the wallet substitutes a placeholder purely to satisfy the server. Never present that placeholder as the name that will be used.'
+          }
+        },
+        required: ["credential"]
+      }
+    },
     {
       name: "check_ai_birthcert_verification",
-      description: 'Check the status of the most recently requested Verified AI Birthcert session (see request_ai_birthcert_verification). Returns { status: "pending" } while the owner has not yet completed MyDigital ID verification, or { status: "issued", vcId } once myid has minted the credential \u2014 myid returns vcId ONLY when status is "issued", never otherwise. On { status: "issued" }, the wallet also fetches the credential from MBI, verifies it, and caches it locally, returning it as `vc` \u2014 it is then also visible via wallet_status and usable by prove_identity without any further call. If `cacheError` is present instead of `vc`, the credential WAS issued successfully but could not be fetched/verified/cached yet (e.g. a transient MBI error) \u2014 this is NOT the same as issuance failing, so do not retry request_ai_birthcert_verification; call check_ai_birthcert_verification again instead. Returns { status: "no_session" } if request_ai_birthcert_verification has never been called.',
+      description: 'Check the status of the most recently requested Verified AI Birthcert session (see request_ai_birthcert_verification). FREE \u2014 spends nothing and starts nothing. Use this, not request_ai_birthcert_verification, whenever the user asks where their verification link is, what happened to their session, or whether their credential is ready. While the session is still open the result carries `verificationUrl` (the same link issued at creation) and `expiresAt` \u2014 give the user both, so they know how long it is good for. Returns { status: "pending" } while the owner has not yet completed MyDigital ID verification, or { status: "issued", vcId } once myid has minted the credential \u2014 myid returns vcId ONLY when status is "issued", never otherwise. On { status: "issued" }, the wallet also fetches the credential from MBI, verifies it, and caches it locally, returning it as `vc` \u2014 it is then also visible via wallet_status and usable by prove_identity without any further call. If `cacheError` is present instead of `vc`, the credential WAS issued successfully but could not be fetched/verified/cached yet (e.g. a transient MBI error) \u2014 this is NOT the same as issuance failing, so do not retry request_ai_birthcert_verification; call check_ai_birthcert_verification again instead. Returns { status: "no_session" } if request_ai_birthcert_verification has never been called.',
       inputSchema: { type: "object", properties: {} }
     },
     {
@@ -23862,6 +24238,13 @@ function buildToolList() {
     }
   ];
 }
+function buildPayers(config2, makePay) {
+  return {
+    pay: makePay(config2.maxPaymentAmount),
+    payForCredential: makePay(config2.credentialIssuanceCaps),
+    preflightCaps: config2.credentialIssuanceCaps
+  };
+}
 function asPayRequest(accept) {
   const extra = accept.extra ?? {};
   const prepareEndpoint = extra.prepareEndpoint;
@@ -23954,15 +24337,19 @@ async function main() {
     const human = formatHumanAmount(raw, decimals);
     return human === raw ? `${raw} ${label}` : `${raw} (${human} ${label})`;
   };
-  const pay = async (accept) => {
+  const makePay = (caps) => async (accept) => {
     const rawAsset = String(accept.asset ?? "");
     try {
-      assertWithinPaymentCap(accept, config2.maxPaymentAmount);
+      assertWithinPaymentCap(accept, caps);
     } catch (err) {
       if (err instanceof PaymentCapError && err.detail) {
         const { asset, requiredRaw, capRaw } = err.detail;
         throw new PaymentCapError(
-          `payment blocked: requested ${await formatAssetAmount(asset, requiredRaw)} exceeds configured MAX_PAYMENT_AMOUNT ${await formatAssetAmount(asset, capRaw)}`,
+          formatCapRefusal(
+            err.detail,
+            await formatAssetAmount(asset, requiredRaw),
+            await formatAssetAmount(asset, capRaw)
+          ),
           err.detail
         );
       }
@@ -23996,6 +24383,7 @@ async function main() {
       throw err;
     }
   };
+  const { pay, payForCredential, preflightCaps } = buildPayers(config2, makePay);
   const verifyAiBirthcert = config2.ssivcBaseUrl ? (() => {
     const ssivcSessionStore = createFsSsivcSessionStore((0, import_node_path6.join)(config2.stateDir, "ssivc-session.json"));
     const downloadQuarantine = createFsDownloadQuarantineStore((0, import_node_path6.join)(config2.stateDir, "ssivc-download-quarantine"));
@@ -24005,7 +24393,7 @@ async function main() {
       signHexBlob: walletBeSignerFn,
       messageSigner,
       mbi,
-      pay,
+      pay: payForCredential,
       publicKeyHex,
       address: zetrixAddress,
       holderDid,
@@ -24015,7 +24403,8 @@ async function main() {
       cache: vcCache,
       quarantine: downloadQuarantine,
       gasPreference: config2.gasPreference,
-      maxSettlementAttempts: config2.maxSettlementAttempts
+      maxSettlementAttempts: config2.maxSettlementAttempts,
+      formatAssetAmount
     };
     return {
       request: (input) => requestAiBirthcertVerification(verifyAiBirthcertDeps, input),
@@ -24066,9 +24455,13 @@ async function main() {
     config: { holderDid, zetrixAddress, network: config2.network },
     makeWallet,
     payer,
-    subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
+    subscribeDeps: { mbi, sign: subscribeSign, pay: payForCredential, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
     queryContract: (input) => queryContract(input, contractQuery),
     queryTokenBalance: queryTokenBalance2,
+    // Read-only, for credential_preflight's cap headroom. Preflight only ever prices credentials,
+    // so it must report against the issuance cap — the same map payForCredential enforces, or
+    // preflight and the guard would disagree about what is permitted.
+    paymentCaps: preflightCaps,
     // The session password is bound here, in the wiring, so it never crosses into the tool
     // layer — create_holder_account has no password parameter for a model to be asked for.
     createAccount: (label, purpose) => be.createAccount(hsmPassword, label, purpose),
@@ -24111,5 +24504,6 @@ if (process.env.NODE_ENV !== "test") {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   asPayRequest,
+  buildPayers,
   buildToolList
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": [
     "mcp",
@@ -43,7 +43,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "x401-zetrix-client": "^0.2.1",
-    "x402-zetrix-client": "^0.2.2",
+    "x402-zetrix-client": "^0.2.4",
     "zetrix-sdk-nodejs": "^1.0.3"
   },
   "devDependencies": {