agentic-wallet-mcp 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -8,6 +8,55 @@ 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.9.0] — 24 August 2026
+
+### Added
+
+- **Paymaster-sponsored gas for `request_ai_birthcert_verification`.** When the resource server
+  offers a sponsored payment option (`extra.gasModel: "facilitator"`), the wallet now prefers it by
+  default — the ms-zetrix paymaster covers network gas, so a wallet holding the payment token but
+  zero ZTX can still complete the flow. Handles the server's asynchronous `202 Accepted` settlement
+  response: the wallet retries with the returned payment receipt (never re-sending the original
+  payment header) until the settlement confirms or the retry budget is exhausted, without ever
+  losing the receipt to a mid-retry crash or transient error.
+- **Automatic self-pay fallback.** If sponsorship is refused before any money moved (the
+  paymaster pool is exhausted, rate-limited, or the network/asset isn't sponsorable), the wallet
+  falls back to self-pay automatically. It never falls back on an indeterminate outcome — a
+  payment that may still be settling is never retried as a fresh payment, which would risk paying
+  twice.
+- **`gasPayer` parameter** on `request_ai_birthcert_verification` (`"sponsored"` | `"self"`) —
+  overrides the deployment default for a single call. An unrecognised value is treated as absent
+  rather than silently forcing self-pay.
+- **`GAS_PREFERENCE`** env var (default `sponsored`) — deployment-wide default gas payer.
+- **`MAX_SETTLEMENT_ATTEMPTS`** env var (default `20`) — cap on retry attempts while polling a
+  queued sponsored settlement.
+
+### Changed
+
+- Existing self-pay behaviour is unchanged — a resource server that only quotes self-pay (no
+  sponsored option) behaves identically to before this release.
+
+## [0.8.1] — 19 August 2026
+
+### Fixed
+
+- **A payment blocked by the spending cap, or rejected for insufficient balance, now names the
+  real token and shows a human-readable amount** — e.g. `10000 (0.01 JMYR)` instead of a bare raw
+  integer that got mislabeled as ZTX once relayed. Affects `pay_and_fetch`, `subscribe_and_issue`,
+  and `request_ai_birthcert_verification`, since all three share the same payment step.
+- **A wallet holding a ZTP20 token (e.g. JMYR) but zero ZTX no longer fails with a raw, opaque
+  error when trying to pay.** The wallet now checks its own ZTX gas balance before attempting the
+  payment and reports a clear "send some ZTX first" message — working around a bug in
+  `x402-zetrix-client` where its own gas check runs after an on-chain call that can itself fail
+  unhelpfully on a zero-gas account.
+
+### Changed
+
+- The known-but-never-confirmed mainnet SSIVC host is now a named, exported constant
+  (`UNVERIFIED_MAINNET_SSIVC_BASE_URL`) instead of only living in a comment — still not wired in by
+  default (`SSIVC_BASE_URL` remains the way to enable it on mainnet), but easier to flip on once
+  confirmed reachable.
+
 ## [0.8.0] — 17 August 2026
 
 ### Added

package/README.md

@@ -27,7 +27,7 @@ VC issuance → identity proof → pay-per-use).
 | `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 | `{ agentName, agentPurpose?, evidenceAssuranceLevel?, ownerType?, ownerVerified? }` | `{ sessionId, verificationUrl, expiresAt }` |
+| `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? }` |
 
 > **VCs are cached locally**, keyed by `templateId`, under `~/.agentic-wallet-mcp/vc-cache/`
@@ -180,6 +180,8 @@ Node ≥ 18 required (built-in `fetch`).
 | `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 |
+| `GAS_PREFERENCE` | no | `sponsored` or `self` — the default gas payer for the Verified AI Birthcert flow (`request_ai_birthcert_verification`). **Defaults to `sponsored`; any unrecognised value also falls back to `sponsored`** rather than throwing. Sponsorship only actually engages when the resource server's x402 quote offers a sponsored option (`extra.gasModel: "facilitator"`) — a server that only quotes self-pay behaves unchanged. **Sponsorship is testnet-only today**; override per-call with the tool's `gasPayer` parameter |
+| `MAX_SETTLEMENT_ATTEMPTS` | no | Cap on retry attempts while polling a sponsored payment for settlement after SSIVC returns `202 Accepted` (queued). **Defaults to `20`; a non-positive or unparseable value also falls back to `20`** |
 
 \* sensitive — never logged, never returned in a tool result, and never a tool parameter.
 

package/dist/server-bundle.cjs

@@ -12537,6 +12537,7 @@ var require_dist2 = __commonJS({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  asPayRequest: () => asPayRequest,
   buildToolList: () => buildToolList
 });
 module.exports = __toCommonJS(index_exports);
@@ -12548,7 +12549,7 @@ var import_node_path6 = require("node:path");
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.8.0",
+  version: "0.9.0",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -21496,9 +21497,18 @@ var import_node_path = require("node:path");
 
 // src/payment-guard.ts
 var PaymentCapError = class extends Error {
-  constructor(message) {
+  /**
+   * Set only when the failure is "requested amount exceeds the configured cap" — carries the raw
+   * asset identifier and raw base-unit amounts so a caller with symbol/decimals resolution (e.g.
+   * index.ts's `pay`) can rebuild a human-readable message without re-deriving these numbers.
+   * Undefined for configuration-shaped failures (missing cap entry, malformed input), which have
+   * no amount to render more legibly.
+   */
+  detail;
+  constructor(message, detail) {
     super(message);
     this.name = "PaymentCapError";
+    this.detail = detail;
   }
 };
 function isNonNegativeIntegerString(v) {
@@ -21538,7 +21548,10 @@ 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}`);
+    throw new PaymentCapError(
+      `payment blocked: requested ${required2} ${asset || "(unknown asset)"} exceeds configured MAX_PAYMENT_AMOUNT ${cap}`,
+      { asset, requiredRaw: required2.toString(), capRaw: cap.toString() }
+    );
   }
 }
 
@@ -21611,7 +21624,14 @@ function loadConfig(env) {
       const v = opt("SSIVC_BASE_URL") ?? deriveSsivcBaseUrl(network);
       return v ? stripTrailingSlash(v) : void 0;
     })(),
-    aiBirthcertVerifiedTemplateId: opt("AI_BIRTHCERT_VERIFIED_TEMPLATE_ID") ?? deriveAiBirthcertVerifiedTemplateId(network)
+    aiBirthcertVerifiedTemplateId: opt("AI_BIRTHCERT_VERIFIED_TEMPLATE_ID") ?? deriveAiBirthcertVerifiedTemplateId(network),
+    // Unrecognised values fall back to the default rather than throwing — a typo here must not
+    // brick startup, and 'sponsored' is always attemptable thanks to Task 5's self-pay fallback.
+    gasPreference: env.GAS_PREFERENCE === "self" ? "self" : "sponsored",
+    maxSettlementAttempts: (() => {
+      const attempts = Number(env.MAX_SETTLEMENT_ATTEMPTS);
+      return Number.isInteger(attempts) && attempts > 0 ? attempts : 20;
+    })()
   };
 }
 
@@ -21645,6 +21665,23 @@ async function resolveAssetSymbol(asset, query) {
   const info = await fetchTokenInfo(asset, query);
   return info?.symbol ?? asset;
 }
+var ZTX_DECIMALS = 6;
+async function resolveAssetInfo(asset, query) {
+  if (asset === "ZTX") return { symbol: "ZTX", decimals: ZTX_DECIMALS };
+  if (asset === "") return { symbol: "", decimals: 0 };
+  const info = await fetchTokenInfo(asset, query);
+  return info ?? { symbol: asset, decimals: 0 };
+}
+function formatHumanAmount(raw, decimals) {
+  if (!/^\d+$/.test(raw) || decimals <= 0) return raw;
+  const base = 10n ** BigInt(decimals);
+  const value = BigInt(raw);
+  const wholePart = value / base;
+  const fracPart = value % base;
+  if (fracPart === 0n) return wholePart.toString();
+  const fracStr = fracPart.toString().padStart(decimals, "0").replace(/0+$/, "");
+  return `${wholePart}.${fracStr}`;
+}
 
 // src/clients/contract-query-client.ts
 async function queryContract(input, query) {
@@ -21673,7 +21710,7 @@ async function queryContract(input, query) {
 }
 
 // src/clients/token-balance-client.ts
-var ZTX_DECIMALS = 6;
+var ZTX_DECIMALS2 = 6;
 function parseNativeBalance(res) {
   if (res?.errorCode !== 0) throw new Error(`getInfo failed with errorCode ${res?.errorCode}`);
   if (res.result === void 0 || res.result === null) throw new Error("getInfo returned no result");
@@ -21707,7 +21744,7 @@ async function queryTokenBalance(deps, token) {
   const symbol = token.toUpperCase();
   if (symbol === "ZTX") {
     try {
-      return { token: symbol, balance: await deps.fetchNativeBalance(deps.address), decimals: ZTX_DECIMALS };
+      return { token: symbol, balance: await deps.fetchNativeBalance(deps.address), decimals: ZTX_DECIMALS2 };
     } catch {
       return { token: symbol, error: "query_failed" };
     }
@@ -23135,6 +23172,7 @@ var SsivcError = class extends Error {
     this.kind = kind;
   }
 };
+var DEFAULT_RETRY_AFTER_SECONDS = 15;
 var SESSIONS_PATH = "/v2/verify/ai-birthcert/sessions";
 var SsivcClient = class {
   baseUrl;
@@ -23159,16 +23197,22 @@ var SsivcClient = class {
   async createSessionPaid(body, paymentHeader) {
     const res = await this.fetch("POST", SESSIONS_PATH, body, paymentHeader);
     if (!res.ok) throw await this.error(res, "createSession (paid) failed");
+    const paymentReceipt = res.headers.get("x-payment-response");
+    if (!paymentReceipt) {
+      throw new SsivcError("SSIVC createSession succeeded (2xx) but returned no X-Payment-Response settlement receipt header", res.status);
+    }
+    if (res.status === 202) {
+      const header = Number(res.headers.get("retry-after"));
+      const retryAfterSeconds = Number.isFinite(header) && header > 0 ? header : DEFAULT_RETRY_AFTER_SECONDS;
+      return { kind: "queued", paymentReceipt, retryAfterSeconds };
+    }
     const env = await res.json();
     const data = env.data;
     if (!data || typeof data !== "object" || !data.sessionId || !data.verification_url || !data.expiresAt) {
       throw new SsivcError("SSIVC createSession succeeded (2xx) but returned a malformed data envelope", res.status);
     }
-    const paymentReceipt = res.headers.get("x-payment-response");
-    if (!paymentReceipt) {
-      throw new SsivcError("SSIVC createSession succeeded (2xx) but returned no X-Payment-Response settlement receipt header", res.status);
-    }
     return {
+      kind: "settled",
       session: { sessionId: data.sessionId, verificationUrl: data.verification_url, expiresAt: data.expiresAt },
       paymentReceipt
     };
@@ -23294,6 +23338,43 @@ 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;
@@ -23321,6 +23402,7 @@ async function getConfirmedStatus(deps, sessionId) {
 async function decidePriorSession(deps, agentName) {
   const stored = await deps.sessionStore.get();
   if (!stored) return { kind: "pay_fresh" };
+  if (stored.sessionId === "") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
   if (stored.agentName !== agentName) {
     const otherStatus = await getConfirmedStatus(deps, stored.sessionId);
     if (otherStatus === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
@@ -23356,12 +23438,107 @@ function withRequestLock(fn) {
 }
 var NoPaymentOptionsError = class extends Error {
 };
-async function payAndCreateSession(deps, body) {
-  const challenge = await deps.ssivc.createSessionChallenge(body);
-  const accept = challenge.accepts[0];
-  if (!accept) throw new NoPaymentOptionsError("SSIVC 402 returned no payment options");
-  const xPayment = await deps.pay(accept);
-  return deps.ssivc.createSessionSettle(body, xPayment);
+var DEFAULT_MAX_SETTLEMENT_ATTEMPTS = 20;
+var MAX_RETRY_DELAY_MS = 6e4;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var SettlementStillQueuedError = class extends Error {
+  constructor(message, paymentReceipt) {
+    super(message);
+    this.paymentReceipt = paymentReceipt;
+    this.name = "SettlementStillQueuedError";
+  }
+};
+var SettlementOutcomeUnknownError = class extends Error {
+  constructor(message, paymentReceipt) {
+    super(message);
+    this.paymentReceipt = paymentReceipt;
+    this.name = "SettlementOutcomeUnknownError";
+  }
+};
+async function resolveSettlement(deps, buildBody, initialOutcome, onQueued) {
+  const sleep = deps.sleep ?? defaultSleep;
+  const maxAttempts = deps.maxSettlementAttempts ?? DEFAULT_MAX_SETTLEMENT_ATTEMPTS;
+  let outcome = initialOutcome;
+  let lastPersistedReceipt;
+  if (outcome.kind === "queued") {
+    lastPersistedReceipt = outcome.paymentReceipt;
+    await onQueued(outcome.paymentReceipt);
+  }
+  for (let attempt = 0; outcome.kind === "queued" && attempt < maxAttempts; attempt++) {
+    const delayMs = Math.min(outcome.retryAfterSeconds * 1e3, MAX_RETRY_DELAY_MS);
+    await sleep(delayMs);
+    const receiptSent = outcome.paymentReceipt;
+    try {
+      outcome = await deps.ssivc.createSessionWithReceipt(await buildBody(), receiptSent);
+    } catch (err) {
+      throw new SettlementOutcomeUnknownError(
+        `the settlement outcome for payment receipt ${receiptSent} could not be determined \u2014 the receipt-retry call itself failed (${err instanceof Error ? err.message : String(err)})`,
+        receiptSent
+      );
+    }
+    if (outcome.kind === "queued" && outcome.paymentReceipt !== lastPersistedReceipt) {
+      lastPersistedReceipt = outcome.paymentReceipt;
+      await onQueued(outcome.paymentReceipt);
+    }
+  }
+  if (outcome.kind === "queued") {
+    throw new SettlementStillQueuedError(
+      "the sponsored payment is being processed and has not settled yet \u2014 no funds are lost and the receipt has been kept; run request_ai_birthcert_verification again shortly to resume",
+      outcome.paymentReceipt
+    );
+  }
+  return { session: outcome.session, paymentReceipt: outcome.paymentReceipt };
+}
+var DEFINITIVE_PREPARE_REFUSALS = /* @__PURE__ */ new Set([
+  461411,
+  // X402_UNSUPPORTED_NETWORK  — this network is not sponsored
+  461414,
+  // X402_RATE_LIMIT_EXCEEDED  — pool rate limit, or the per-address active-prepare cap (default 5)
+  461415
+  // X402_UNSUPPORTED_ASSET    — sponsorship is ZTP-20 only
+]);
+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;
+}
+var PrepareStageError = class extends Error {
+  constructor(cause) {
+    super("prepare stage failed");
+    this.cause = cause;
+    this.name = "PrepareStageError";
+  }
+};
+function isDefinitiveSponsorshipFailure(err) {
+  if (!(err instanceof PrepareStageError)) return false;
+  const cause = err.cause;
+  if (cause instanceof SettlementStillQueuedError) return false;
+  const code = facilitatorErrorCode(cause);
+  if (code === void 0) return false;
+  return DEFINITIVE_PREPARE_REFUSALS.has(code);
+}
+async function attemptCandidate(deps, accept, buildBody, onQueued) {
+  let xPayment;
+  try {
+    xPayment = await deps.pay(accept);
+  } catch (err) {
+    throw new PrepareStageError(err);
+  }
+  const initialOutcome = await deps.ssivc.createSessionSettle(await buildBody(), xPayment);
+  return resolveSettlement(deps, buildBody, initialOutcome, onQueued);
+}
+async function payAndCreateSession(deps, buildBody, onQueued) {
+  const challenge = await deps.ssivc.createSessionChallenge(await buildBody());
+  const candidates = orderAccepts(challenge.accepts, deps.gasPreference ?? "sponsored");
+  const primary = candidates[0];
+  if (!primary) throw new NoPaymentOptionsError("SSIVC 402 returned no usable payment options");
+  try {
+    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;
+    return await attemptCandidate(deps, fallback, buildBody, onQueued);
+  }
 }
 async function requestAiBirthcertVerification(deps, input) {
   if (!input.agentName || !input.agentName.trim()) {
@@ -23374,31 +23551,85 @@ 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 fields = {
-    publicKey: deps.publicKeyHex,
-    address: deps.address,
-    timestamp: isoSeconds(deps.now()),
-    agentName,
-    id: agentName,
-    ownerReference: deps.holderDid
+  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 persistQueuedReceipt = async (receipt) => {
+    try {
+      await deps.sessionStore.set({
+        sessionId: "",
+        agentName,
+        createdAt: deps.now().toISOString(),
+        verificationUrl: "",
+        paymentReceipt: receipt
+      });
+    } catch {
+    }
   };
-  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);
-  const body = { ...fields, signedData };
+  const requestedGasPayer = input.gasPayer === "self" || input.gasPayer === "sponsored" ? input.gasPayer : void 0;
   let paid;
   try {
-    paid = decision.kind === "replay_receipt" ? await deps.ssivc.createSessionWithReceipt(body, decision.receipt) : await payAndCreateSession(deps, body);
-  } catch (err) {
+    if (decision.kind === "replay_receipt") {
+      let initialOutcome;
+      try {
+        initialOutcome = await deps.ssivc.createSessionWithReceipt(await buildBody(), decision.receipt);
+      } catch (err) {
+        throw new SettlementOutcomeUnknownError(
+          `the settlement outcome for payment receipt ${decision.receipt} could not be determined \u2014 the receipt-replay call itself failed (${err instanceof Error ? err.message : String(err)})`,
+          decision.receipt
+        );
+      }
+      paid = await resolveSettlement(deps, buildBody, initialOutcome, persistQueuedReceipt);
+    } else {
+      paid = await payAndCreateSession(
+        { ...deps, gasPreference: requestedGasPayer ?? deps.gasPreference },
+        buildBody,
+        persistQueuedReceipt
+      );
+    }
+  } 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 NoPaymentOptionsError) return { error: err.message };
+    if (err instanceof SettlementStillQueuedError) {
+      try {
+        await deps.sessionStore.set({
+          sessionId: "",
+          agentName,
+          createdAt: deps.now().toISOString(),
+          verificationUrl: "",
+          paymentReceipt: err.paymentReceipt
+        });
+      } catch {
+        return {
+          error: err.message + ` (could not save the receipt locally \u2014 keep this value to resume manually: ${err.paymentReceipt})`
+        };
+      }
+      return { error: err.message };
+    }
     if (err instanceof SsivcError && err.kind === "blob_already_settled") {
       return { error: `payment already settled for this attempt: ${err.message}` };
     }
+    if (err instanceof SettlementOutcomeUnknownError) {
+      return {
+        error: `could not determine whether the sponsored settlement succeeded or failed for payment receipt ${err.paymentReceipt} (${err.message}) \u2014 this is NOT a confirmed failure, so the receipt has been kept as-is and no new payment has been attempted; this requires manual investigation by an operator before retrying, rather than calling request_ai_birthcert_verification again`
+      };
+    }
     throw err;
   }
   await deps.sessionStore.set({
@@ -23418,6 +23649,12 @@ async function checkAiBirthcertVerification(deps) {
       message: "No verification session found for this wallet \u2014 call request_ai_birthcert_verification first."
     };
   }
+  if (stored.sessionId === "") {
+    return {
+      status: "no_session",
+      message: "a sponsored payment is still settling and no verification session exists yet \u2014 the payment receipt has been kept, so calling request_ai_birthcert_verification again resumes it and will not pay twice."
+    };
+  }
   const status = await deps.ssivc.getSession(stored.sessionId);
   if (status.status !== "issued" || !status.vcId) return status;
   if (deps.verifiedTemplateId && deps.cache) {
@@ -23594,7 +23831,12 @@ function buildToolList() {
           agentPurpose: { type: "string", description: 'Optional \u2014 what this agent does, e.g. "Negotiate and settle supplier invoices".' },
           evidenceAssuranceLevel: { type: "string", description: 'Optional \u2014 assurance level of the identity evidence, e.g. "high".' },
           ownerType: { type: "string", description: `Optional \u2014 the owner's type, e.g. "Individual".` },
-          ownerVerified: { type: "string", description: 'Optional \u2014 whether the owner is already verified, as the string "true" or "false".' }
+          ownerVerified: { type: "string", description: 'Optional \u2014 whether the owner is already verified, as the string "true" or "false".' },
+          gasPayer: {
+            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.`
+          }
         },
         required: ["agentName"]
       }
@@ -23623,7 +23865,9 @@ function buildToolList() {
 }
 function asPayRequest(accept) {
   const extra = accept.extra ?? {};
-  return { ...accept, extra: { gasModel: "client", ...extra } };
+  const prepareEndpoint = extra.prepareEndpoint;
+  const normalizedExtra = typeof prepareEndpoint === "string" && prepareEndpoint !== "" ? { ...extra, prepareEndpoint: prepareBaseUrl(prepareEndpoint) } : extra;
+  return { ...accept, extra: { gasModel: "client", ...normalizedExtra } };
 }
 async function main() {
   const fileEnv = loadConfigFileEnv(process.argv, (p) => (0, import_node_fs.readFileSync)(p, "utf8"));
@@ -23705,13 +23949,53 @@ async function main() {
   const vcCache = createFsVcCache((0, import_node_path6.join)(config2.stateDir, "vc-cache", cacheScope));
   const mbi = new MbiClient(config2.mbiBaseUrl);
   const messageSigner = (message) => be.signMessage(message, zetrixAddress, hsmPassword);
-  const pay = (accept) => {
-    assertWithinPaymentCap(accept, config2.maxPaymentAmount);
-    return payWithReadinessCheck(
-      String(accept.asset ?? ""),
-      () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn),
-      activated
-    );
+  const formatAssetAmount = async (asset, raw) => {
+    const { symbol, decimals } = await resolveAssetInfo(asset, contractQuery);
+    const label = symbol || "(unknown asset)";
+    const human = formatHumanAmount(raw, decimals);
+    return human === raw ? `${raw} ${label}` : `${raw} (${human} ${label})`;
+  };
+  const pay = async (accept) => {
+    const rawAsset = String(accept.asset ?? "");
+    try {
+      assertWithinPaymentCap(accept, config2.maxPaymentAmount);
+    } 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)}`,
+          err.detail
+        );
+      }
+      throw err;
+    }
+    if (needsNativeGasCheck(accept)) {
+      const gasBalance = await fetchNativeBalance(zetrixAddress).catch(() => null);
+      if (gasBalance === "0") {
+        const { symbol } = await resolveAssetInfo(rawAsset, contractQuery);
+        throw new PaymentReadinessError(
+          `this wallet has 0 ZTX to pay network gas \u2014 the ${symbol || rawAsset} balance is separate from gas, and every transaction costs a small amount of ZTX regardless of which token is being paid. Send some ZTX to ${zetrixAddress} first, then retry.`,
+          { asset: "ZTX", required: "unknown", available: "0", reason: "gas" }
+        );
+      }
+    }
+    try {
+      return await payWithReadinessCheck(
+        rawAsset,
+        () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn),
+        activated
+      );
+    } catch (err) {
+      if (err instanceof PaymentReadinessError && err.shortfall.reason !== "not_activated") {
+        const { asset, required: required2, available, reason } = err.shortfall;
+        const label = reason === "gas" ? "ZTX for gas" : (await resolveAssetInfo(asset, contractQuery)).symbol || asset;
+        throw new PaymentReadinessError(
+          `insufficient ${label} \u2014 required ${await formatAssetAmount(asset, required2)}, available ${await formatAssetAmount(asset, available)}`,
+          err.shortfall
+        );
+      }
+      throw err;
+    }
   };
   const verifyAiBirthcert = config2.ssivcBaseUrl ? (() => {
     const ssivcSessionStore = createFsSsivcSessionStore((0, import_node_path6.join)(config2.stateDir, "ssivc-session.json"));
@@ -23730,7 +24014,9 @@ async function main() {
       sessionStore: ssivcSessionStore,
       verifiedTemplateId: config2.aiBirthcertVerifiedTemplateId,
       cache: vcCache,
-      quarantine: downloadQuarantine
+      quarantine: downloadQuarantine,
+      gasPreference: config2.gasPreference,
+      maxSettlementAttempts: config2.maxSettlementAttempts
     };
     return {
       request: (input) => requestAiBirthcertVerification(verifyAiBirthcertDeps, input),
@@ -23825,5 +24111,6 @@ if (process.env.NODE_ENV !== "test") {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  asPayRequest,
   buildToolList
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": [
     "mcp",