agentic-wallet-mcp 0.8.1 → 0.9.1

package/CHANGELOG.md

@@ -8,6 +8,46 @@ 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.1] — 28 August 2026
+
+### Fixed
+
+- **`request_ai_birthcert_verification` no longer blocks retrying an expired session.** If the
+  owner never completed MyDigital ID verification before a Verified AI Birthcert session's TTL
+  elapsed (`status: "expired"`), retrying previously threw an "unrecognized prior session status"
+  error and left the flow stuck — even though the settlement receipt was already safely persisted
+  locally and unconsumed. Any confirmed terminal session status other than `"issued"` (the only
+  status that consumes the receipt) is now treated the same as the existing 404/"gone" handling:
+  the receipt is replayed and a fresh verification session is opened, with no new payment made.
+
+## [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

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.1",
+  version: "0.9.1",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -21623,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;
+    })()
   };
 }
 
@@ -23164,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;
@@ -23188,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
     };
@@ -23323,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;
@@ -23350,16 +23402,18 @@ 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 };
-    if (otherStatus.status !== "issued") {
+    if (otherStatus.status === "pending") {
       return {
         kind: "blocked",
-        message: `a verification session for a different agent ("${stored.agentName}") is still in progress (status: "${otherStatus.status}") and its payment has not been consumed yet \u2014 starting a new session for "${agentName}" would lose track of it. Call check_ai_birthcert_verification to resolve or confirm it first.`
+        message: `a verification session for a different agent ("${stored.agentName}") is still in progress (status: "pending") and its payment has not been consumed yet \u2014 starting a new session for "${agentName}" would lose track of it. Call check_ai_birthcert_verification to resolve or confirm it first.`
       };
     }
-    return { kind: "pay_fresh" };
+    if (otherStatus.status === "issued") return { kind: "pay_fresh" };
+    return { kind: "replay_receipt", receipt: stored.paymentReceipt };
   }
   const status = await getConfirmedStatus(deps, stored.sessionId);
   if (status === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
@@ -23370,9 +23424,7 @@ async function decidePriorSession(deps, agentName) {
     };
   }
   if (status.status === "issued") return { kind: "pay_fresh" };
-  throw new Error(
-    `requestAiBirthcertVerification: unrecognized prior session status "${status.status}" for session ${stored.sessionId} \u2014 refusing to guess whether its settlement receipt is safe to replay (see SPEC.md D8)`
-  );
+  return { kind: "replay_receipt", receipt: stored.paymentReceipt };
 }
 var requestQueue = Promise.resolve();
 function withRequestLock(fn) {
@@ -23385,12 +23437,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()) {
@@ -23403,31 +23550,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({
@@ -23447,6 +23648,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) {
@@ -23623,7 +23830,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"]
       }
@@ -23652,7 +23864,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"));
@@ -23754,7 +23968,7 @@ async function main() {
       }
       throw err;
     }
-    if (rawAsset !== "" && rawAsset !== "ZTX") {
+    if (needsNativeGasCheck(accept)) {
       const gasBalance = await fetchNativeBalance(zetrixAddress).catch(() => null);
       if (gasBalance === "0") {
         const { symbol } = await resolveAssetInfo(rawAsset, contractQuery);
@@ -23799,7 +24013,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),
@@ -23894,5 +24110,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.1",
+  "version": "0.9.1",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": [
     "mcp",