agentic-wallet-mcp 0.4.0 → 0.5.0

package/README.md

@@ -23,8 +23,8 @@ VC issuance → identity proof → pay-per-use).
 | `wallet_status` | Report holder DID/address/network + held VCs (client-supplied, or the local cache) | `{ heldCredentials? }` | `{ holderDid, zetrixAddress, network, credentials }` |
 | `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? }` |
-| `create_holder_account` | Onboarding: manually mint an additional/replacement HSM account (the MCP already auto-creates one at startup if `ZETRIX_ADDRESS` is omitted — see Environment below) | `{ password, label?, purpose? }` | `{ zetrixAddress, holderDid, publicKeyHex, message }` |
+| `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? }` |
+| `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 }` |
 
 > **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).
@@ -38,10 +38,25 @@ VC issuance → identity proof → pay-per-use).
 > back to the `expirationDate` requested at issuance; a VC with neither is cached indefinitely.
 > All Ed25519 signing still goes through Wallet BE HSM; no plaintext private keys.
 
+> `subscribe_and_issue` also returns `schema: { required, optional }` — the template's full
+> declared attribute list, read from chain — on every outcome (issued, dry-run quote, or a
+> missing-attribute error), so you always see the complete field list rather than only what went
+> wrong. Attributes the wallet auto-fills for you (e.g. `agentDid`, or a template-declared derived
+> key like the `AI Birthcert` template's `id` ← `agentUsername`) are omitted from `schema` since
+> you never need to supply them. Some templates also declare format validators for optional
+> attributes (e.g. `AI Birthcert`'s `dob` must be `YYYY-MM-DD`, `countryOfOrigin` must be a valid
+> ISO 3166 code or name) — an invalid value is rejected locally before any payment or MBI call.
+
 > `create_holder_account` mints a **brand-new** keypair — Wallet BE's `/account/create` has no
-> way to provision a pre-chosen address. It returns the new `zetrixAddress`/`holderDid` for you
-> to paste into `ZETRIX_ADDRESS`/`HSM_PASSWORD` yourself (`HOLDER_DID` is optional — see
-> Environment below); the tool never writes your MCP config or restarts the server for you.
+> way to provision a pre-chosen address. It always checks first whether an account is already
+> active for this session; if so, it returns `{ alreadyExists: true, existing }` and creates
+> nothing — ask the user whether to keep the existing account or replace it, then call again
+> with `confirmNew: true` only if they want a new one. A freshly minted account (address, DID,
+> **and** password) is saved to this MCP's own local account store
+> (`~/.agentic-wallet-mcp/account.json`, owner-only) and reused automatically on the next
+> restart — no manual config edit needed. An explicit `ZETRIX_ADDRESS`/`HSM_PASSWORD` still set
+> in your MCP config always overrides the saved account (see Environment below); the tool never
+> writes the MCP host's own config file or restarts the server for you.
 
 > `revealAttribute` on `prove_identity` is optional and usually should stay that way. Omitted,
 > it's derived automatically from the challenge's DCQL `credential_requirements` — each claim path
@@ -100,9 +115,11 @@ startup, in one of two ways:
 
 1. **First-time user — only `HSM_PASSWORD` set.** The MCP creates a brand-new HSM account on
    Wallet BE (`POST /wallet/hsm/account/create`) and derives the DID from the returned public
-   key. It logs the new `ZETRIX_ADDRESS` (and `HOLDER_DID`) to stderr on startup — copy it into
-   your MCP config for next time, since nothing is persisted to disk between runs (env vars only
-   load once, at process start).
+   key. It logs the new `ZETRIX_ADDRESS` (and `HOLDER_DID`) to stderr on startup, and saves the
+   address, DID, and password to a local account store
+   (`~/.agentic-wallet-mcp/account.json`, owner-only) — it's reused automatically next run, no
+   config edit required. An explicit `ZETRIX_ADDRESS`/`HSM_PASSWORD` set later in your MCP
+   config still overrides the saved account.
 2. **Existing user — `ZETRIX_ADDRESS` + `HSM_PASSWORD` set, `HOLDER_DID` optional.** The MCP
    always self-signs the address via the existing `POST /wallet/hsm/sign-message` call and
    derives the DID from the `publicKey` the response carries — no separate lookup endpoint
@@ -171,8 +188,9 @@ the `<...>` placeholders (don't commit a filled copy; `mcp.local.json` is gitign
 ```
 
 > First run, no account yet? Omit `ZETRIX_ADDRESS` (and `HOLDER_DID`) entirely — the MCP creates
-> one for you at startup and logs it to stderr; copy it back into `env` for next time. See
-> "Onboarding" under Environment above.
+> one for you at startup, logs it to stderr, and saves it (address, DID, password) to
+> `~/.agentic-wallet-mcp/account.json` for automatic reuse next run. See "Onboarding" under
+> Environment above.
 
 > Working on this repo locally instead of the published package? Point `command`/`args` at the
 > local build directly: `"command": "node"`, `"args": ["/absolute/path/to/zetrix-agentic-wallet/dist/server-bundle.cjs"]`.
@@ -190,7 +208,7 @@ the `<...>` placeholders (don't commit a filled copy; `mcp.local.json` is gitign
 - *"I got a 401 with this PROOF-REQUEST header — prove my identity and give me the PROOF-RESPONSE to replay."* → `prove_identity`
 - *"Fetch `https://api.example/data` and pay automatically if it asks."* → `pay_and_fetch`
 - *"Apply for the agent-identity credential with these attributes and pay for it."* → `subscribe_and_issue`
-- *"My wallet_status call is failing — I don't have a holder account yet. Set one up."* → `create_holder_account` (asks you for a password, then returns the new address/DID to save)
+- *"My wallet_status call is failing — I don't have a holder account yet. Set one up."* → `create_holder_account` (asks you for a password; if an account already exists it reports that instead of creating — confirm with the user, then re-call with `confirmNew: true` to replace it)
 
 For the full ordered script (onboarding → check → issue → prove → pay), see [`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md).
 
@@ -200,9 +218,12 @@ Full narrative version with example prompts: [`docs/USAGE_FLOW.md`](docs/USAGE_F
 
 **Step 0 — onboarding (once).** Only if `ZETRIX_ADDRESS` isn't set yet: the MCP creates an HSM
 account automatically at startup from `HSM_PASSWORD` alone (see "Onboarding" under Environment
-above) — copy the logged `zetrixAddress` into your MCP config for next time. Alternatively, call
-`create_holder_account { password }` manually and paste the returned `zetrixAddress` in yourself;
-either way, restart the server afterward (env vars load once, at process start).
+above) and saves it locally for automatic reuse. Alternatively, call `create_holder_account
+{ password }` manually — it always checks for an existing account first and reports it instead
+of creating (pass `confirmNew: true`, after asking the user, to replace it anyway). Either way,
+the account is saved to `~/.agentic-wallet-mcp/account.json` and picked up automatically on the
+next restart; no manual config edit needed unless your MCP config also sets `ZETRIX_ADDRESS`/
+`HSM_PASSWORD` via env, in which case those still take precedence and should be updated too.
 
 **Phase 1 — `wallet_status` — pre-check.** Pass any VCs the caller already holds via
 `heldCredentials`; the response tells you whether the agent-identity credential you need is

package/dist/server-bundle.cjs

@@ -2233,8 +2233,8 @@ var require_resolve = __commonJS({
       }
       return count;
     }
-    function getFullPath(resolver, id = "", normalize2) {
-      if (normalize2 !== false)
+    function getFullPath(resolver, id = "", normalize3) {
+      if (normalize3 !== false)
         id = normalizeId(id);
       const p = resolver.parse(id);
       return _getFullPath(resolver, p);
@@ -3630,7 +3630,7 @@ var require_fast_uri = __commonJS({
     "use strict";
     var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
-    function normalize2(uri, options) {
+    function normalize3(uri, options) {
       if (typeof uri === "string") {
         uri = /** @type {T} */
         normalizeString(uri, options);
@@ -3897,7 +3897,7 @@ var require_fast_uri = __commonJS({
     }
     var fastUri = {
       SCHEMES,
-      normalize: normalize2,
+      normalize: normalize3,
       resolve,
       resolveComponent,
       equal,
@@ -8541,13 +8541,13 @@ var require_path = __commonJS({
         return /^(?:\/|\w+:)/.test(path2);
       }
     );
-    var normalize2 = (
+    var normalize3 = (
       /**
        * Normalizes the specified path.
        * @param {string} path Path to normalize
        * @returns {string} Normalized path
        */
-      path.normalize = function normalize3(path2) {
+      path.normalize = function normalize4(path2) {
         path2 = path2.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
         var parts = path2.split("/"), absolute = isAbsolute(path2), prefix = "";
         if (absolute)
@@ -8570,12 +8570,12 @@ var require_path = __commonJS({
     );
     path.resolve = function resolve(originPath, includePath, alreadyNormalized) {
       if (!alreadyNormalized)
-        includePath = normalize2(includePath);
+        includePath = normalize3(includePath);
       if (isAbsolute(includePath))
         return includePath;
       if (!alreadyNormalized)
-        originPath = normalize2(originPath);
-      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize2(originPath + "/" + includePath) : includePath;
+        originPath = normalize3(originPath);
+      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize3(originPath + "/" + includePath) : includePath;
     };
   }
 });
@@ -12192,7 +12192,7 @@ var require_payment_engine = __commonJS({
     var blob_decoder_1 = require_blob_decoder();
     var prepare_client_1 = require_prepare_client();
     var _sdkCtor = require("zetrix-sdk-nodejs");
-    var InsufficientBalanceError = class _InsufficientBalanceError extends Error {
+    var InsufficientBalanceError2 = class _InsufficientBalanceError extends Error {
       constructor(message, required2, available, asset) {
         super(message);
         this.required = required2;
@@ -12202,7 +12202,7 @@ var require_payment_engine = __commonJS({
         Object.setPrototypeOf(this, _InsufficientBalanceError.prototype);
       }
     };
-    exports2.InsufficientBalanceError = InsufficientBalanceError;
+    exports2.InsufficientBalanceError = InsufficientBalanceError2;
     exports2.PaymentEngine = {
       /**
        * Create a Zetrix SDK instance for the given node config.
@@ -12295,20 +12295,20 @@ var require_payment_engine = __commonJS({
           const { balance } = await exports2.PaymentEngine.fetchAccountInfo(wallet.address, node);
           const required2 = amount + fee;
           if (BigInt(balance) < required2) {
-            throw new InsufficientBalanceError(`Insufficient ZTX: required ${required2}, available ${balance}`, String(required2), balance, "ZTX");
+            throw new InsufficientBalanceError2(`Insufficient ZTX: required ${required2}, available ${balance}`, String(required2), balance, "ZTX");
           }
           return;
         }
         if (!opts.skipTokenCheck) {
           const { balance: tokenBal } = await exports2.PaymentEngine.fetchZTP20Balance(req.asset, wallet.address, node);
           if (BigInt(tokenBal) < amount) {
-            throw new InsufficientBalanceError(`Insufficient ${req.asset}: required ${req.maxAmountRequired}, available ${tokenBal}`, req.maxAmountRequired, tokenBal, req.asset);
+            throw new InsufficientBalanceError2(`Insufficient ${req.asset}: required ${req.maxAmountRequired}, available ${tokenBal}`, req.maxAmountRequired, tokenBal, req.asset);
           }
         }
         if (fee > 0n) {
           const { balance: ztxBal } = await exports2.PaymentEngine.fetchAccountInfo(wallet.address, node);
           if (BigInt(ztxBal) < fee) {
-            throw new InsufficientBalanceError(`Insufficient ZTX for gas: required ${feeLimit}, available ${ztxBal}`, feeLimit, ztxBal, "ZTX");
+            throw new InsufficientBalanceError2(`Insufficient ZTX for gas: required ${feeLimit}, available ${ztxBal}`, feeLimit, ztxBal, "ZTX");
           }
         }
       },
@@ -12542,12 +12542,12 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto2 = require("node:crypto");
 var import_node_os = require("node:os");
-var import_node_path2 = require("node:path");
+var import_node_path3 = require("node:path");
 
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.4.0",
+  version: "0.5.0",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: ["mcp", "model-context-protocol", "zetrix", "wallet", "x401", "x402", "blockchain"],
   license: "MIT",
@@ -21159,7 +21159,7 @@ var StdioServerTransport = class {
 };
 
 // src/index.ts
-var import_x402_zetrix_client = __toESM(require_dist2(), 1);
+var import_x402_zetrix_client2 = __toESM(require_dist2(), 1);
 
 // node_modules/x401-zetrix-client/dist/config.js
 var ZETRIX_OID4VP_URLS = {
@@ -21547,6 +21547,14 @@ function deriveMbiBaseUrl(network) {
 function deriveTemplateRegistryAddress(network) {
   return network.includes("testnet") ? "ZTX3JszqPgRUx743SAp7q7zURfjvkWuH2FMEz" : "ZTX3GqJM1U6ifMPonwD4fGvrgoTKJua7b2cKX";
 }
+var TOKEN_REGISTRY = {
+  JMYR: { testnet: "ZTX3WeinXtt28YMyr4vUZ14ddTgEMGeuc1e6b", mainnet: "ZTX3NCkXBqbyJWjZZxciQez945Lu6tGAcjNJr" }
+};
+function resolveTokenAddress(symbol, network) {
+  const entry = TOKEN_REGISTRY[symbol.toUpperCase()];
+  if (!entry) return void 0;
+  return network.includes("testnet") ? entry.testnet : entry.mainnet;
+}
 function loadConfig(env) {
   const req = (key, hint) => {
     const v = env[key];
@@ -21609,6 +21617,32 @@ async function resolveAssetSymbol(asset, query) {
   return info?.symbol ?? asset;
 }
 
+// src/clients/contract-query-client.ts
+async function queryContract(input, query) {
+  let response;
+  try {
+    response = await query({
+      contractAddress: input.contractAddress,
+      input: JSON.stringify({ method: input.method, params: input.params ?? {} }),
+      optType: 2
+    });
+  } catch (e) {
+    return { ok: false, error: `query_contract: RPC call failed \u2014 ${e.message}` };
+  }
+  if (response.errorCode !== 0) {
+    return { ok: false, error: `query_contract: contract call failed with errorCode ${response.errorCode}` };
+  }
+  const raw = response.result?.query_rets?.[0]?.result?.value;
+  if (raw === void 0) {
+    return { ok: false, error: "query_contract: no result value returned" };
+  }
+  try {
+    return { ok: true, result: JSON.parse(raw) };
+  } catch {
+    return { ok: true, result: raw };
+  }
+}
+
 // src/clients/template-info-client.ts
 async function fetchTemplateFields(templateId, registryAddress, nodeBaseUrl, query) {
   const key = `template__${templateId}`;
@@ -21667,6 +21701,10 @@ var WalletBeClient = class {
   createAccount(password, label, purpose) {
     return this.post("/wallet/hsm/account/create", { password, label, purpose });
   }
+  /** GET /wallet/hsm/account/activate/status — ground-truth on-chain activation check (no local state). */
+  checkActivationStatus(address) {
+    return this.get("/wallet/hsm/account/activate/status", { address });
+  }
   async post(path, body) {
     const url = `${this.baseUrl}${path}`;
     let res;
@@ -21694,6 +21732,25 @@ var WalletBeClient = class {
     }
     return env.data;
   }
+  async get(path, query) {
+    const url = `${this.baseUrl}${path}?${new URLSearchParams(query).toString()}`;
+    let res;
+    try {
+      res = await fetch(url, { headers: { Accept: "application/json" } });
+    } catch (e) {
+      throw new WalletBeError(`Wallet BE ${path} request failed`, void 0, e);
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new WalletBeError(`Wallet BE ${path} HTTP ${res.status}: ${text}`);
+    }
+    const env = await res.json();
+    if (env.errorCode !== 0) {
+      const detail = env.data?.errorList?.length ? ` \u2014 ${env.data.errorList.join("; ")}` : "";
+      throw new WalletBeError(`Wallet BE ${path} errorCode ${env.errorCode}: ${env.message ?? "error"}${detail}`, env.errorCode);
+    }
+    return env.data;
+  }
 };
 
 // src/signer.ts
@@ -21809,14 +21866,22 @@ var MbiError = class extends Error {
     this.httpStatus = httpStatus;
   }
 };
-var MbiClient = class {
+var MbiClient = class _MbiClient {
   baseUrl;
   constructor(baseUrl) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
   }
-  /** Phase 1 — POST /v1/vc/pay/apply without X-PAYMENT; expects the 402 challenge. */
+  /**
+   * Phase 1 — POST /v1/vc/pay/apply without X-PAYMENT; expects the 402 challenge.
+   * A free template short-circuits this: MBI issues the VC synchronously and returns
+   * 200 instead, with no phase-2 settle to follow — surfaced via the `issued` field.
+   */
   async applyChallenge(body) {
     const res = await this.fetch("POST", "/v1/vc/pay/apply", body);
+    if (res.status === 200) {
+      const issued = await this.unwrap(res);
+      return { x402Version: 1, accepts: [], issued };
+    }
     if (res.status !== 402) {
       throw await this.error(res, "apply (phase 1) expected 402");
     }
@@ -21864,12 +21929,14 @@ var MbiClient = class {
     const body = await res.json();
     return body.data;
   }
+  static ERROR_BODY_MAX_LEN = 500;
   async error(res, context) {
     const text = await res.text().catch(() => "");
     let msg = text;
     try {
       const j = JSON.parse(text);
-      msg = j.message ?? j.error ?? text;
+      const truncated = text.length > _MbiClient.ERROR_BODY_MAX_LEN ? `${text.slice(0, _MbiClient.ERROR_BODY_MAX_LEN)}\u2026 (truncated, ${text.length} bytes total)` : text;
+      msg = `${j.message ?? j.error ?? text} | full body: ${truncated}`;
     } catch {
     }
     return new MbiError(`MBI ${context} \u2014 HTTP ${res.status}: ${msg}`, res.status);
@@ -22025,6 +22092,36 @@ function extractValidUntil(vc, fallback) {
   return fallback;
 }
 
+// src/payment-readiness.ts
+var import_x402_zetrix_client = __toESM(require_dist2(), 1);
+var PaymentReadinessError = class extends Error {
+  shortfall;
+  constructor(message, shortfall) {
+    super(message);
+    this.name = "PaymentReadinessError";
+    this.shortfall = shortfall;
+  }
+};
+function toPaymentReadinessError(err, requestedAsset) {
+  if (!(err instanceof import_x402_zetrix_client.InsufficientBalanceError)) return null;
+  const reason = err.asset === "ZTX" && requestedAsset !== "ZTX" ? "gas" : "resource_payment";
+  return new PaymentReadinessError(err.message, {
+    asset: err.asset,
+    required: err.required,
+    available: err.available,
+    reason
+  });
+}
+async function payWithReadinessCheck(requestedAsset, rawPay) {
+  try {
+    return await rawPay();
+  } catch (err) {
+    const readinessError = toPaymentReadinessError(err, requestedAsset);
+    if (readinessError) throw readinessError;
+    throw err;
+  }
+}
+
 // src/orchestrator/subscribe.ts
 async function subscribeAndIssue(deps, opts) {
   if (!/^did:zid:/.test(opts.templateId)) {
@@ -22048,13 +22145,15 @@ async function subscribeAndIssue(deps, opts) {
   const { agentDid, ...rest } = opts.attributes ?? {};
   const shouldAutoFillAgentDid = !agentDid && fields !== null && fields.allKeys.includes("agentDid");
   const attributes = shouldAutoFillAgentDid ? { agentDid: deps.holderDid, ...rest } : opts.attributes ?? {};
-  if (!opts.dryRun && fields) {
+  const schema = fields ? { required: fields.required, optional: fields.allKeys.filter((k) => !fields.required.includes(k)) } : void 0;
+  if (fields) {
     const attrs = attributes;
     const missing = fields.required.filter((k) => attrs[k] === void 0 || attrs[k] === null || attrs[k] === "");
     if (missing.length > 0) {
       return {
         issued: false,
-        reason: `template requires attribute(s) not supplied: ${missing.join(", ")} \u2014 no payment made`
+        reason: `template requires attribute(s) not supplied: ${missing.join(", ")} \u2014 no payment made`,
+        ...schema ? { schema } : {}
       };
     }
   }
@@ -22063,9 +22162,42 @@ async function subscribeAndIssue(deps, opts) {
   const { signBlob: signData, publicKey } = await deps.sign(blob);
   const body = { data, signData, publicKey };
   if (opts.expirationDate) body.expirationDate = opts.expirationDate;
-  const challenge = await deps.mbi.applyChallenge(body);
+  let challenge;
+  try {
+    challenge = await deps.mbi.applyChallenge(body);
+  } catch (err) {
+    if (err instanceof MbiError) {
+      return { issued: false, reason: err.message, httpStatus: err.httpStatus, ...schema ? { schema } : {} };
+    }
+    throw err;
+  }
+  if (challenge.issued) {
+    const issued2 = challenge.issued;
+    if (deps.cache) {
+      await deps.cache.set(opts.templateId, {
+        templateId: opts.templateId,
+        vc: issued2.verifiableCredential,
+        vcId: issued2.vcId,
+        txHash: issued2.txHash,
+        paidAsset: "none",
+        amountPaid: "0",
+        issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        validUntil: extractValidUntil(issued2.verifiableCredential, opts.expirationDate)
+      });
+    }
+    return {
+      issued: true,
+      vcId: issued2.vcId,
+      vc: issued2.verifiableCredential,
+      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" } : {}
+    };
+  }
   const accept = challenge.accepts[0];
-  if (!accept) return { issued: false, reason: "MBI 402 returned no payment options" };
+  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;
@@ -22075,13 +22207,29 @@ async function subscribeAndIssue(deps, opts) {
       quote: {
         asset: quotedAsset,
         maxAmountRequired: accept.maxAmountRequired,
-        payTo: accept.payTo,
-        ...fields ? { requiredAttributes: fields.required } : {}
-      }
+        payTo: accept.payTo
+      },
+      ...schema ? { schema } : {}
     };
   }
-  const xPayment = await deps.pay(accept);
-  const issued = await deps.mbi.applySettle({ ...body, paymentId: challenge.paymentId }, xPayment);
+  let xPayment;
+  try {
+    xPayment = await deps.pay(accept);
+  } catch (err) {
+    if (err instanceof PaymentReadinessError) {
+      return { issued: false, reason: `insufficient funds: ${err.message}`, insufficientFunds: err.shortfall };
+    }
+    throw err;
+  }
+  let issued;
+  try {
+    issued = await deps.mbi.applySettle({ ...body, paymentId: challenge.paymentId }, xPayment);
+  } catch (err) {
+    if (err instanceof MbiError) {
+      return { issued: false, reason: err.message, httpStatus: err.httpStatus, ...schema ? { schema } : {} };
+    }
+    throw err;
+  }
   const rawAsset = String(accept.asset ?? "");
   const paidAsset = deps.resolveSymbol ? await deps.resolveSymbol(rawAsset) : rawAsset;
   const amountPaid = String(accept.maxAmountRequired ?? "");
@@ -22103,10 +22251,23 @@ async function subscribeAndIssue(deps, opts) {
     vc: issued.verifiableCredential,
     txHash: issued.txHash,
     paidAsset,
-    amountPaid
+    amountPaid,
+    ...schema ? { schema } : {}
   };
 }
 
+// src/orchestrator/wait-for-activation.ts
+async function waitForActivation(check, address, sleep, opts = {}) {
+  const attempts = opts.attempts ?? 3;
+  const delayMs = opts.delayMs ?? 3e3;
+  for (let i = 0; i < attempts; i++) {
+    await sleep(delayMs);
+    const { activated } = await check(address);
+    if (activated) return true;
+  }
+  return false;
+}
+
 // src/orchestrator/onboard.ts
 function deriveHolderDid(publicKeyHex) {
   const hex = publicKeyHex.trim();
@@ -22114,31 +22275,393 @@ function deriveHolderDid(publicKeyHex) {
   if (hex.length === 76 && hex.slice(0, 4).toLowerCase() === "b001") return `did:zid:${hex.slice(4, 68)}`;
   throw new Error(`onboard: unrecognized public key hex format (length ${hex.length})`);
 }
-async function createHolderAccount(create, input) {
-  const { zetrixAddress, publicKeyHex } = await create(input.password, input.label, input.purpose);
+async function createHolderAccount(deps, input) {
+  const existing = await deps.getExistingAccount();
+  if (existing && !input.confirmNew) {
+    return {
+      created: false,
+      alreadyExists: true,
+      existing,
+      message: `An account already exists for this wallet (zetrixAddress=${existing.zetrixAddress}, holderDid=${existing.holderDid}). Ask the user whether to keep using it or create a brand-new one \u2014 call create_holder_account again with confirmNew:true to mint a new account.`
+    };
+  }
+  const { zetrixAddress, publicKeyHex, activated } = await deps.create(input.password, input.label, input.purpose);
   const holderDid = deriveHolderDid(publicKeyHex);
-  const message = `New holder HSM account created. Update your MCP config and restart the server: ZETRIX_ADDRESS=${zetrixAddress}, HSM_PASSWORD=<the password you just provided>. (HOLDER_DID=${holderDid} is optional \u2014 omit it and the MCP re-derives it from the account's public key at startup.)`;
-  return { zetrixAddress, holderDid, publicKeyHex, message };
+  await deps.saveAccount({ zetrixAddress, holderDid, hsmPassword: input.password, label: input.label, purpose: input.purpose });
+  const finalActivated = activated || await waitForActivation(deps.checkActivationStatus, zetrixAddress, deps.sleep);
+  const message = `New holder HSM account created \u2014 address, DID, and password saved to the wallet's local account store. Both will be used automatically on the next server restart; no manual config edit needed. If your MCP config also sets ZETRIX_ADDRESS/HSM_PASSWORD via environment variables, update or remove those too: an explicit env ZETRIX_ADDRESS/HSM_PASSWORD always takes precedence over the saved account. ZETRIX_ADDRESS=${zetrixAddress} (HOLDER_DID=${holderDid} is optional \u2014 it re-derives automatically).` + (finalActivated ? "" : ` Note: on-chain activation has not completed yet \u2014 balance/on-chain calls for this address may fail until it does; check again later.`);
+  return { created: true, alreadyExists: Boolean(existing), zetrixAddress, holderDid, publicKeyHex, activated: finalActivated, message };
+}
+
+// src/iso3166.ts
+var COUNTRIES = [
+  { alpha2: "AD", alpha3: "AND", name: "Andorra" },
+  { alpha2: "AE", alpha3: "ARE", name: "United Arab Emirates" },
+  { alpha2: "AF", alpha3: "AFG", name: "Afghanistan" },
+  { alpha2: "AG", alpha3: "ATG", name: "Antigua and Barbuda" },
+  { alpha2: "AI", alpha3: "AIA", name: "Anguilla" },
+  { alpha2: "AL", alpha3: "ALB", name: "Albania" },
+  { alpha2: "AM", alpha3: "ARM", name: "Armenia" },
+  { alpha2: "AO", alpha3: "AGO", name: "Angola" },
+  { alpha2: "AQ", alpha3: "ATA", name: "Antarctica" },
+  { alpha2: "AR", alpha3: "ARG", name: "Argentina" },
+  { alpha2: "AS", alpha3: "ASM", name: "American Samoa" },
+  { alpha2: "AT", alpha3: "AUT", name: "Austria" },
+  { alpha2: "AU", alpha3: "AUS", name: "Australia" },
+  { alpha2: "AW", alpha3: "ABW", name: "Aruba" },
+  { alpha2: "AX", alpha3: "ALA", name: "\xC5land Islands" },
+  { alpha2: "AZ", alpha3: "AZE", name: "Azerbaijan" },
+  { alpha2: "BA", alpha3: "BIH", name: "Bosnia and Herzegovina" },
+  { alpha2: "BB", alpha3: "BRB", name: "Barbados" },
+  { alpha2: "BD", alpha3: "BGD", name: "Bangladesh" },
+  { alpha2: "BE", alpha3: "BEL", name: "Belgium" },
+  { alpha2: "BF", alpha3: "BFA", name: "Burkina Faso" },
+  { alpha2: "BG", alpha3: "BGR", name: "Bulgaria" },
+  { alpha2: "BH", alpha3: "BHR", name: "Bahrain" },
+  { alpha2: "BI", alpha3: "BDI", name: "Burundi" },
+  { alpha2: "BJ", alpha3: "BEN", name: "Benin" },
+  { alpha2: "BL", alpha3: "BLM", name: "Saint Barth\xE9lemy" },
+  { alpha2: "BM", alpha3: "BMU", name: "Bermuda" },
+  { alpha2: "BN", alpha3: "BRN", name: "Brunei Darussalam" },
+  { alpha2: "BO", alpha3: "BOL", name: "Bolivia (Plurinational State of)" },
+  { alpha2: "BQ", alpha3: "BES", name: "Bonaire, Sint Eustatius and Saba" },
+  { alpha2: "BR", alpha3: "BRA", name: "Brazil" },
+  { alpha2: "BS", alpha3: "BHS", name: "Bahamas" },
+  { alpha2: "BT", alpha3: "BTN", name: "Bhutan" },
+  { alpha2: "BV", alpha3: "BVT", name: "Bouvet Island" },
+  { alpha2: "BW", alpha3: "BWA", name: "Botswana" },
+  { alpha2: "BY", alpha3: "BLR", name: "Belarus" },
+  { alpha2: "BZ", alpha3: "BLZ", name: "Belize" },
+  { alpha2: "CA", alpha3: "CAN", name: "Canada" },
+  { alpha2: "CC", alpha3: "CCK", name: "Cocos (Keeling) Islands" },
+  { alpha2: "CD", alpha3: "COD", name: "Congo, Democratic Republic of the" },
+  { alpha2: "CF", alpha3: "CAF", name: "Central African Republic" },
+  { alpha2: "CG", alpha3: "COG", name: "Congo" },
+  { alpha2: "CH", alpha3: "CHE", name: "Switzerland" },
+  { alpha2: "CI", alpha3: "CIV", name: "C\xF4te d'Ivoire" },
+  { alpha2: "CK", alpha3: "COK", name: "Cook Islands" },
+  { alpha2: "CL", alpha3: "CHL", name: "Chile" },
+  { alpha2: "CM", alpha3: "CMR", name: "Cameroon" },
+  { alpha2: "CN", alpha3: "CHN", name: "China" },
+  { alpha2: "CO", alpha3: "COL", name: "Colombia" },
+  { alpha2: "CR", alpha3: "CRI", name: "Costa Rica" },
+  { alpha2: "CU", alpha3: "CUB", name: "Cuba" },
+  { alpha2: "CV", alpha3: "CPV", name: "Cabo Verde" },
+  { alpha2: "CW", alpha3: "CUW", name: "Cura\xE7ao" },
+  { alpha2: "CX", alpha3: "CXR", name: "Christmas Island" },
+  { alpha2: "CY", alpha3: "CYP", name: "Cyprus" },
+  { alpha2: "CZ", alpha3: "CZE", name: "Czechia" },
+  { alpha2: "DE", alpha3: "DEU", name: "Germany" },
+  { alpha2: "DJ", alpha3: "DJI", name: "Djibouti" },
+  { alpha2: "DK", alpha3: "DNK", name: "Denmark" },
+  { alpha2: "DM", alpha3: "DMA", name: "Dominica" },
+  { alpha2: "DO", alpha3: "DOM", name: "Dominican Republic" },
+  { alpha2: "DZ", alpha3: "DZA", name: "Algeria" },
+  { alpha2: "EC", alpha3: "ECU", name: "Ecuador" },
+  { alpha2: "EE", alpha3: "EST", name: "Estonia" },
+  { alpha2: "EG", alpha3: "EGY", name: "Egypt" },
+  { alpha2: "EH", alpha3: "ESH", name: "Western Sahara" },
+  { alpha2: "ER", alpha3: "ERI", name: "Eritrea" },
+  { alpha2: "ES", alpha3: "ESP", name: "Spain" },
+  { alpha2: "ET", alpha3: "ETH", name: "Ethiopia" },
+  { alpha2: "FI", alpha3: "FIN", name: "Finland" },
+  { alpha2: "FJ", alpha3: "FJI", name: "Fiji" },
+  { alpha2: "FK", alpha3: "FLK", name: "Falkland Islands (Malvinas)" },
+  { alpha2: "FM", alpha3: "FSM", name: "Micronesia (Federated States of)" },
+  { alpha2: "FO", alpha3: "FRO", name: "Faroe Islands" },
+  { alpha2: "FR", alpha3: "FRA", name: "France" },
+  { alpha2: "GA", alpha3: "GAB", name: "Gabon" },
+  { alpha2: "GB", alpha3: "GBR", name: "United Kingdom of Great Britain and Northern Ireland" },
+  { alpha2: "GD", alpha3: "GRD", name: "Grenada" },
+  { alpha2: "GE", alpha3: "GEO", name: "Georgia" },
+  { alpha2: "GF", alpha3: "GUF", name: "French Guiana" },
+  { alpha2: "GG", alpha3: "GGY", name: "Guernsey" },
+  { alpha2: "GH", alpha3: "GHA", name: "Ghana" },
+  { alpha2: "GI", alpha3: "GIB", name: "Gibraltar" },
+  { alpha2: "GL", alpha3: "GRL", name: "Greenland" },
+  { alpha2: "GM", alpha3: "GMB", name: "Gambia" },
+  { alpha2: "GN", alpha3: "GIN", name: "Guinea" },
+  { alpha2: "GP", alpha3: "GLP", name: "Guadeloupe" },
+  { alpha2: "GQ", alpha3: "GNQ", name: "Equatorial Guinea" },
+  { alpha2: "GR", alpha3: "GRC", name: "Greece" },
+  { alpha2: "GS", alpha3: "SGS", name: "South Georgia and the South Sandwich Islands" },
+  { alpha2: "GT", alpha3: "GTM", name: "Guatemala" },
+  { alpha2: "GU", alpha3: "GUM", name: "Guam" },
+  { alpha2: "GW", alpha3: "GNB", name: "Guinea-Bissau" },
+  { alpha2: "GY", alpha3: "GUY", name: "Guyana" },
+  { alpha2: "HK", alpha3: "HKG", name: "Hong Kong" },
+  { alpha2: "HM", alpha3: "HMD", name: "Heard Island and McDonald Islands" },
+  { alpha2: "HN", alpha3: "HND", name: "Honduras" },
+  { alpha2: "HR", alpha3: "HRV", name: "Croatia" },
+  { alpha2: "HT", alpha3: "HTI", name: "Haiti" },
+  { alpha2: "HU", alpha3: "HUN", name: "Hungary" },
+  { alpha2: "ID", alpha3: "IDN", name: "Indonesia" },
+  { alpha2: "IE", alpha3: "IRL", name: "Ireland" },
+  { alpha2: "IL", alpha3: "ISR", name: "Israel" },
+  { alpha2: "IM", alpha3: "IMN", name: "Isle of Man" },
+  { alpha2: "IN", alpha3: "IND", name: "India" },
+  { alpha2: "IO", alpha3: "IOT", name: "British Indian Ocean Territory" },
+  { alpha2: "IQ", alpha3: "IRQ", name: "Iraq" },
+  { alpha2: "IR", alpha3: "IRN", name: "Iran (Islamic Republic of)" },
+  { alpha2: "IS", alpha3: "ISL", name: "Iceland" },
+  { alpha2: "IT", alpha3: "ITA", name: "Italy" },
+  { alpha2: "JE", alpha3: "JEY", name: "Jersey" },
+  { alpha2: "JM", alpha3: "JAM", name: "Jamaica" },
+  { alpha2: "JO", alpha3: "JOR", name: "Jordan" },
+  { alpha2: "JP", alpha3: "JPN", name: "Japan" },
+  { alpha2: "KE", alpha3: "KEN", name: "Kenya" },
+  { alpha2: "KG", alpha3: "KGZ", name: "Kyrgyzstan" },
+  { alpha2: "KH", alpha3: "KHM", name: "Cambodia" },
+  { alpha2: "KI", alpha3: "KIR", name: "Kiribati" },
+  { alpha2: "KM", alpha3: "COM", name: "Comoros" },
+  { alpha2: "KN", alpha3: "KNA", name: "Saint Kitts and Nevis" },
+  { alpha2: "KP", alpha3: "PRK", name: "Korea (Democratic People's Republic of)" },
+  { alpha2: "KR", alpha3: "KOR", name: "Korea, Republic of" },
+  { alpha2: "KW", alpha3: "KWT", name: "Kuwait" },
+  { alpha2: "KY", alpha3: "CYM", name: "Cayman Islands" },
+  { alpha2: "KZ", alpha3: "KAZ", name: "Kazakhstan" },
+  { alpha2: "LA", alpha3: "LAO", name: "Lao People's Democratic Republic" },
+  { alpha2: "LB", alpha3: "LBN", name: "Lebanon" },
+  { alpha2: "LC", alpha3: "LCA", name: "Saint Lucia" },
+  { alpha2: "LI", alpha3: "LIE", name: "Liechtenstein" },
+  { alpha2: "LK", alpha3: "LKA", name: "Sri Lanka" },
+  { alpha2: "LR", alpha3: "LBR", name: "Liberia" },
+  { alpha2: "LS", alpha3: "LSO", name: "Lesotho" },
+  { alpha2: "LT", alpha3: "LTU", name: "Lithuania" },
+  { alpha2: "LU", alpha3: "LUX", name: "Luxembourg" },
+  { alpha2: "LV", alpha3: "LVA", name: "Latvia" },
+  { alpha2: "LY", alpha3: "LBY", name: "Libya" },
+  { alpha2: "MA", alpha3: "MAR", name: "Morocco" },
+  { alpha2: "MC", alpha3: "MCO", name: "Monaco" },
+  { alpha2: "MD", alpha3: "MDA", name: "Moldova, Republic of" },
+  { alpha2: "ME", alpha3: "MNE", name: "Montenegro" },
+  { alpha2: "MF", alpha3: "MAF", name: "Saint Martin (French part)" },
+  { alpha2: "MG", alpha3: "MDG", name: "Madagascar" },
+  { alpha2: "MH", alpha3: "MHL", name: "Marshall Islands" },
+  { alpha2: "MK", alpha3: "MKD", name: "North Macedonia" },
+  { alpha2: "ML", alpha3: "MLI", name: "Mali" },
+  { alpha2: "MM", alpha3: "MMR", name: "Myanmar" },
+  { alpha2: "MN", alpha3: "MNG", name: "Mongolia" },
+  { alpha2: "MO", alpha3: "MAC", name: "Macao" },
+  { alpha2: "MP", alpha3: "MNP", name: "Northern Mariana Islands" },
+  { alpha2: "MQ", alpha3: "MTQ", name: "Martinique" },
+  { alpha2: "MR", alpha3: "MRT", name: "Mauritania" },
+  { alpha2: "MS", alpha3: "MSR", name: "Montserrat" },
+  { alpha2: "MT", alpha3: "MLT", name: "Malta" },
+  { alpha2: "MU", alpha3: "MUS", name: "Mauritius" },
+  { alpha2: "MV", alpha3: "MDV", name: "Maldives" },
+  { alpha2: "MW", alpha3: "MWI", name: "Malawi" },
+  { alpha2: "MX", alpha3: "MEX", name: "Mexico" },
+  { alpha2: "MY", alpha3: "MYS", name: "Malaysia" },
+  { alpha2: "MZ", alpha3: "MOZ", name: "Mozambique" },
+  { alpha2: "NA", alpha3: "NAM", name: "Namibia" },
+  { alpha2: "NC", alpha3: "NCL", name: "New Caledonia" },
+  { alpha2: "NE", alpha3: "NER", name: "Niger" },
+  { alpha2: "NF", alpha3: "NFK", name: "Norfolk Island" },
+  { alpha2: "NG", alpha3: "NGA", name: "Nigeria" },
+  { alpha2: "NI", alpha3: "NIC", name: "Nicaragua" },
+  { alpha2: "NL", alpha3: "NLD", name: "Netherlands" },
+  { alpha2: "NO", alpha3: "NOR", name: "Norway" },
+  { alpha2: "NP", alpha3: "NPL", name: "Nepal" },
+  { alpha2: "NR", alpha3: "NRU", name: "Nauru" },
+  { alpha2: "NU", alpha3: "NIU", name: "Niue" },
+  { alpha2: "NZ", alpha3: "NZL", name: "New Zealand" },
+  { alpha2: "OM", alpha3: "OMN", name: "Oman" },
+  { alpha2: "PA", alpha3: "PAN", name: "Panama" },
+  { alpha2: "PE", alpha3: "PER", name: "Peru" },
+  { alpha2: "PF", alpha3: "PYF", name: "French Polynesia" },
+  { alpha2: "PG", alpha3: "PNG", name: "Papua New Guinea" },
+  { alpha2: "PH", alpha3: "PHL", name: "Philippines" },
+  { alpha2: "PK", alpha3: "PAK", name: "Pakistan" },
+  { alpha2: "PL", alpha3: "POL", name: "Poland" },
+  { alpha2: "PM", alpha3: "SPM", name: "Saint Pierre and Miquelon" },
+  { alpha2: "PN", alpha3: "PCN", name: "Pitcairn" },
+  { alpha2: "PR", alpha3: "PRI", name: "Puerto Rico" },
+  { alpha2: "PS", alpha3: "PSE", name: "Palestine, State of" },
+  { alpha2: "PT", alpha3: "PRT", name: "Portugal" },
+  { alpha2: "PW", alpha3: "PLW", name: "Palau" },
+  { alpha2: "PY", alpha3: "PRY", name: "Paraguay" },
+  { alpha2: "QA", alpha3: "QAT", name: "Qatar" },
+  { alpha2: "RE", alpha3: "REU", name: "R\xE9union" },
+  { alpha2: "RO", alpha3: "ROU", name: "Romania" },
+  { alpha2: "RS", alpha3: "SRB", name: "Serbia" },
+  { alpha2: "RU", alpha3: "RUS", name: "Russian Federation" },
+  { alpha2: "RW", alpha3: "RWA", name: "Rwanda" },
+  { alpha2: "SA", alpha3: "SAU", name: "Saudi Arabia" },
+  { alpha2: "SB", alpha3: "SLB", name: "Solomon Islands" },
+  { alpha2: "SC", alpha3: "SYC", name: "Seychelles" },
+  { alpha2: "SD", alpha3: "SDN", name: "Sudan" },
+  { alpha2: "SE", alpha3: "SWE", name: "Sweden" },
+  { alpha2: "SG", alpha3: "SGP", name: "Singapore" },
+  { alpha2: "SH", alpha3: "SHN", name: "Saint Helena, Ascension and Tristan da Cunha" },
+  { alpha2: "SI", alpha3: "SVN", name: "Slovenia" },
+  { alpha2: "SJ", alpha3: "SJM", name: "Svalbard and Jan Mayen" },
+  { alpha2: "SK", alpha3: "SVK", name: "Slovakia" },
+  { alpha2: "SL", alpha3: "SLE", name: "Sierra Leone" },
+  { alpha2: "SM", alpha3: "SMR", name: "San Marino" },
+  { alpha2: "SN", alpha3: "SEN", name: "Senegal" },
+  { alpha2: "SO", alpha3: "SOM", name: "Somalia" },
+  { alpha2: "SR", alpha3: "SUR", name: "Suriname" },
+  { alpha2: "SS", alpha3: "SSD", name: "South Sudan" },
+  { alpha2: "ST", alpha3: "STP", name: "Sao Tome and Principe" },
+  { alpha2: "SV", alpha3: "SLV", name: "El Salvador" },
+  { alpha2: "SX", alpha3: "SXM", name: "Sint Maarten (Dutch part)" },
+  { alpha2: "SY", alpha3: "SYR", name: "Syrian Arab Republic" },
+  { alpha2: "SZ", alpha3: "SWZ", name: "Eswatini" },
+  { alpha2: "TC", alpha3: "TCA", name: "Turks and Caicos Islands" },
+  { alpha2: "TD", alpha3: "TCD", name: "Chad" },
+  { alpha2: "TF", alpha3: "ATF", name: "French Southern Territories" },
+  { alpha2: "TG", alpha3: "TGO", name: "Togo" },
+  { alpha2: "TH", alpha3: "THA", name: "Thailand" },
+  { alpha2: "TJ", alpha3: "TJK", name: "Tajikistan" },
+  { alpha2: "TK", alpha3: "TKL", name: "Tokelau" },
+  { alpha2: "TL", alpha3: "TLS", name: "Timor-Leste" },
+  { alpha2: "TM", alpha3: "TKM", name: "Turkmenistan" },
+  { alpha2: "TN", alpha3: "TUN", name: "Tunisia" },
+  { alpha2: "TO", alpha3: "TON", name: "Tonga" },
+  { alpha2: "TR", alpha3: "TUR", name: "T\xFCrkiye" },
+  { alpha2: "TT", alpha3: "TTO", name: "Trinidad and Tobago" },
+  { alpha2: "TV", alpha3: "TUV", name: "Tuvalu" },
+  { alpha2: "TW", alpha3: "TWN", name: "Taiwan, Province of China" },
+  { alpha2: "TZ", alpha3: "TZA", name: "Tanzania, United Republic of" },
+  { alpha2: "UA", alpha3: "UKR", name: "Ukraine" },
+  { alpha2: "UG", alpha3: "UGA", name: "Uganda" },
+  { alpha2: "UM", alpha3: "UMI", name: "United States Minor Outlying Islands" },
+  { alpha2: "US", alpha3: "USA", name: "United States of America" },
+  { alpha2: "UY", alpha3: "URY", name: "Uruguay" },
+  { alpha2: "UZ", alpha3: "UZB", name: "Uzbekistan" },
+  { alpha2: "VA", alpha3: "VAT", name: "Holy See" },
+  { alpha2: "VC", alpha3: "VCT", name: "Saint Vincent and the Grenadines" },
+  { alpha2: "VE", alpha3: "VEN", name: "Venezuela (Bolivarian Republic of)" },
+  { alpha2: "VG", alpha3: "VGB", name: "Virgin Islands (British)" },
+  { alpha2: "VI", alpha3: "VIR", name: "Virgin Islands (U.S.)" },
+  { alpha2: "VN", alpha3: "VNM", name: "Viet Nam" },
+  { alpha2: "VU", alpha3: "VUT", name: "Vanuatu" },
+  { alpha2: "WF", alpha3: "WLF", name: "Wallis and Futuna" },
+  { alpha2: "WS", alpha3: "WSM", name: "Samoa" },
+  { alpha2: "YE", alpha3: "YEM", name: "Yemen" },
+  { alpha2: "YT", alpha3: "MYT", name: "Mayotte" },
+  { alpha2: "ZA", alpha3: "ZAF", name: "South Africa" },
+  { alpha2: "ZM", alpha3: "ZMB", name: "Zambia" },
+  { alpha2: "ZW", alpha3: "ZWE", name: "Zimbabwe" }
+];
+var COMMON_ALIASES = {
+  usa: "US",
+  america: "US",
+  unitedstates: "US",
+  uk: "GB",
+  unitedkingdom: "GB",
+  britain: "GB",
+  greatbritain: "GB",
+  southkorea: "KR",
+  northkorea: "KP",
+  russia: "RU",
+  vietnam: "VN",
+  laos: "LA",
+  syria: "SY",
+  iran: "IR",
+  ivorycoast: "CI",
+  czechrepublic: "CZ",
+  swaziland: "SZ",
+  burma: "MM",
+  capeverde: "CV",
+  easttimor: "TL",
+  taiwan: "TW",
+  macedonia: "MK",
+  vatican: "VA",
+  vaticancity: "VA",
+  holland: "NL",
+  moldova: "MD",
+  bolivia: "BO",
+  tanzania: "TZ",
+  venezuela: "VE",
+  palestine: "PS",
+  brunei: "BN"
+};
+function normalize(s) {
+  return s.toLowerCase().trim().replace(/[^a-z0-9]/g, "");
+}
+function isValidCountry(input) {
+  const trimmed = input.trim();
+  if (/^[A-Za-z]{2}$/.test(trimmed)) {
+    return COUNTRIES.some((c) => c.alpha2 === trimmed.toUpperCase());
+  }
+  if (/^[A-Za-z]{3}$/.test(trimmed)) {
+    return COUNTRIES.some((c) => c.alpha3 === trimmed.toUpperCase());
+  }
+  const normalized = normalize(trimmed);
+  if (COMMON_ALIASES[normalized]) return true;
+  return COUNTRIES.some((c) => normalize(c.name) === normalized);
 }
 
 // src/template-aliases.ts
+function validateDob(value) {
+  if (typeof value !== "string") return "dob must be a string in YYYY-MM-DD format";
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return `dob must match the format YYYY-MM-DD, got "${value}"`;
+  const [year, month, day] = value.split("-").map(Number);
+  const date3 = new Date(Date.UTC(year, month - 1, day));
+  const isRealCalendarDate = date3.getUTCFullYear() === year && date3.getUTCMonth() === month - 1 && date3.getUTCDate() === day;
+  if (!isRealCalendarDate) return `dob is not a valid calendar date: "${value}"`;
+  return void 0;
+}
+function validateCountryOfOrigin(value) {
+  if (typeof value !== "string" || !value.trim()) return "countryOfOrigin must be a non-empty string";
+  if (!isValidCountry(value)) return `countryOfOrigin must be an ISO 3166 country code or name, got "${value}"`;
+  return void 0;
+}
 var TEMPLATE_ALIASES = [
   {
     match: "birthcert",
-    testnet: "did:zid:d6b783559acf6ba0f7ef6e1365bdaf0774d622d8d22728ca6323677f49ee94f8",
-    mainnet: "did:zid:032cb99be3577beccfc6252783c49c83673af38f8456d73462043654d7764e83"
+    testnet: "did:zid:3c0fb79adff08e14e06dcd6e3243205010dd65f533434a3d96c55575d1d3d959",
+    mainnet: "did:zid:19091d19049abb8869b4b8e2f4a887bd1d1d86e5f5ebd0c8297000255f67765b",
+    deriveAttributes: { id: "agentUsername" },
+    validateAttributes: { dob: validateDob, countryOfOrigin: validateCountryOfOrigin }
   }
 ];
-function normalize(s) {
+function normalize2(s) {
   return s.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
+function findEntry(templateId, network) {
+  if (/^did:zid:/.test(templateId)) {
+    const key = network.includes("testnet") ? "testnet" : "mainnet";
+    return TEMPLATE_ALIASES.find((e) => e[key] === templateId);
+  }
+  const normalized = normalize2(templateId);
+  return TEMPLATE_ALIASES.find((e) => normalized.includes(e.match));
+}
 function resolveTemplateAlias(input, network) {
   if (/^did:zid:/.test(input)) return void 0;
-  const normalized = normalize(input);
-  const entry = TEMPLATE_ALIASES.find((e) => normalized.includes(e.match));
+  const entry = findEntry(input, network);
   if (!entry) return void 0;
   return network.includes("testnet") ? entry.testnet : entry.mainnet;
 }
+function deriveTemplateAttributes(templateId, network, attributes) {
+  const entry = findEntry(templateId, network);
+  if (!entry?.deriveAttributes) return attributes;
+  const result = { ...attributes };
+  for (const [target, source] of Object.entries(entry.deriveAttributes)) {
+    if ((result[target] === void 0 || result[target] === null || result[target] === "") && result[source] !== void 0) {
+      result[target] = result[source];
+    }
+  }
+  return result;
+}
+function derivedAttributeKeys(templateId, network) {
+  const entry = findEntry(templateId, network);
+  return entry?.deriveAttributes ? Object.keys(entry.deriveAttributes) : [];
+}
+function validateTemplateAttributes(templateId, network, attributes) {
+  const entry = findEntry(templateId, network);
+  if (!entry?.validateAttributes) return [];
+  const errors = [];
+  for (const [key, validate] of Object.entries(entry.validateAttributes)) {
+    const value = attributes[key];
+    if (value === void 0 || value === null || value === "") continue;
+    const error2 = validate(value);
+    if (error2) errors.push(error2);
+  }
+  return errors;
+}
 
 // src/mcp-tools.ts
 async function loadValidCachedCredentials(cache) {
@@ -22150,13 +22673,15 @@ function createTools(deps) {
   return {
     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;
       const credentials = input.heldCredentials ?? (await loadValidCachedCredentials(deps.cache)).map((entry) => entry.vc);
       return {
         holderDid: deps.config.holderDid,
         zetrixAddress: deps.config.zetrixAddress,
         network: deps.config.network,
         credentials,
-        ...balances !== void 0 ? { balances } : {}
+        ...balances !== void 0 ? { balances } : {},
+        ...tokenBalance !== void 0 ? { tokenBalance } : {}
       };
     },
     async prove_identity(input) {
@@ -22182,12 +22707,39 @@ function createTools(deps) {
     pay_and_fetch(input) {
       return payAndFetch(deps.payer, input);
     },
-    subscribe_and_issue(input) {
+    async subscribe_and_issue(input) {
       const resolved = resolveTemplateAlias(input.templateId, deps.config.network);
-      return subscribeAndIssue(deps.subscribeDeps, resolved ? { ...input, templateId: resolved } : input);
+      const templateId = resolved ?? input.templateId;
+      const attributes = deriveTemplateAttributes(templateId, deps.config.network, input.attributes ?? {});
+      const errors = validateTemplateAttributes(templateId, deps.config.network, attributes);
+      if (errors.length > 0) {
+        return { issued: false, reason: errors.join("; ") };
+      }
+      const result = await subscribeAndIssue(deps.subscribeDeps, { ...input, templateId, attributes });
+      if (!result.schema) return result;
+      const hidden = /* @__PURE__ */ new Set(["agentDid", ...derivedAttributeKeys(templateId, deps.config.network)]);
+      return {
+        ...result,
+        schema: {
+          required: result.schema.required.filter((k) => !hidden.has(k)),
+          optional: result.schema.optional.filter((k) => !hidden.has(k))
+        }
+      };
+    },
+    query_contract(input) {
+      return deps.queryContract(input);
     },
     create_holder_account(input) {
-      return createHolderAccount(deps.createAccount, input);
+      return createHolderAccount(
+        {
+          create: deps.createAccount,
+          getExistingAccount: () => Promise.resolve(deps.config.zetrixAddress ? { zetrixAddress: deps.config.zetrixAddress, holderDid: deps.config.holderDid } : null),
+          saveAccount: deps.saveAccount,
+          checkActivationStatus: deps.checkActivationStatus,
+          sleep: deps.sleep
+        },
+        input
+      );
     }
   };
 }
@@ -22195,8 +22747,16 @@ function createTools(deps) {
 // src/orchestrator/resolve-holder.ts
 async function resolveHolder(deps, input) {
   if (!input.zetrixAddress) {
-    const { zetrixAddress, publicKeyHex } = await deps.createAccount(input.hsmPassword);
-    return { zetrixAddress, holderDid: deriveHolderDid(publicKeyHex), created: true, didMismatch: false };
+    const { zetrixAddress, publicKeyHex, activated } = await deps.createAccount(input.hsmPassword);
+    let finalActivated = activated;
+    if (!finalActivated) {
+      try {
+        finalActivated = await waitForActivation(deps.checkActivationStatus, zetrixAddress, deps.sleep);
+      } catch {
+        finalActivated = false;
+      }
+    }
+    return { zetrixAddress, holderDid: deriveHolderDid(publicKeyHex), created: true, didMismatch: false, activated: finalActivated };
   }
   const { publicKey } = await deps.signMessage(input.zetrixAddress, input.zetrixAddress, input.hsmPassword);
   const derivedDid = deriveHolderDid(publicKey);
@@ -22204,6 +22764,30 @@ async function resolveHolder(deps, input) {
   return { zetrixAddress: input.zetrixAddress, holderDid: derivedDid, created: false, didMismatch };
 }
 
+// src/clients/account-store.ts
+var import_promises2 = require("node:fs/promises");
+var import_node_path2 = require("node:path");
+function isStoredAccountShape(value) {
+  return typeof value === "object" && value !== null && typeof value.zetrixAddress === "string" && typeof value.holderDid === "string" && typeof value.hsmPassword === "string";
+}
+function createFsAccountStore(filePath) {
+  return {
+    async get() {
+      try {
+        const raw = await (0, import_promises2.readFile)(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return isStoredAccountShape(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+    async set(account) {
+      await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(filePath), { recursive: true, mode: 448 });
+      await (0, import_promises2.writeFile)(filePath, JSON.stringify(account, null, 2), { encoding: "utf8", mode: 384 });
+    }
+  };
+}
+
 // src/index.ts
 var packageVersion = package_default.version;
 function buildToolList() {
@@ -22214,7 +22798,8 @@ function buildToolList() {
       inputSchema: {
         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." }
+          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.' }
         }
       }
     },
@@ -22253,9 +22838,22 @@ function buildToolList() {
         required: ["url"]
       }
     },
+    {
+      name: "query_contract",
+      description: 'Read-only query against a Zetrix contract or account \u2014 call an arbitrary contract method (e.g. "balanceOf", "contractInfo") and return its raw result. No signing, no state change.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          contractAddress: { type: "string", description: "Zetrix contract address to query." },
+          method: { type: "string", description: 'Contract method name, e.g. "balanceOf", "contractInfo".' },
+          params: { type: "object", description: 'Method parameters, e.g. { "address": "ZTX..." } for balanceOf.' }
+        },
+        required: ["contractAddress", "method"]
+      }
+    },
     {
       name: "subscribe_and_issue",
-      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. If a still-valid credential for this templateId is already cached locally, it is returned directly with no payment (fromCache: true) \u2014 pass forceReissue:true to pay and issue fresh regardless. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay.",
+      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. If a still-valid credential for this templateId is already cached locally, it is returned directly with no payment (fromCache: true) \u2014 pass forceReissue:true to pay and issue fresh regardless. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay. Every response (success, dry-run, or a missing-attribute error) also includes { schema: { required, optional } } \u2014 the template's full declared attribute schema read from chain \u2014 so you always see the complete field list, not just what went wrong.",
       inputSchema: {
         type: "object",
         properties: {
@@ -22270,7 +22868,7 @@ function buildToolList() {
           expirationDate: { type: "string" },
           dryRun: {
             type: "boolean",
-            description: "Stop after MBI's free phase-1 quote and return { quote: { asset, maxAmountRequired, payTo, requiredAttributes? } } without paying or issuing \u2014 use this to check the payment requirement AND the template's required attributes (read from chain) before spending funds."
+            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."
           },
           forceReissue: {
             type: "boolean",
@@ -22282,13 +22880,17 @@ function buildToolList() {
     },
     {
       name: "create_holder_account",
-      description: "Create a new holder HSM account on Wallet BE (onboarding, when ZETRIX_ADDRESS is not yet provisioned). Ask the user for a password first \u2014 never invent one. Returns the new address/DID for the user to save into their MCP config and restart the server; this tool does not persist anything itself.",
+      description: "Create a new holder HSM account on Wallet BE (onboarding). Ask the user for a password first \u2014 never invent one. ALWAYS check first: if an account already exists for this session, this returns { alreadyExists: true, existing: {...} } WITHOUT creating anything \u2014 ask the user whether to keep using the existing account or create a new one, then call again with confirmNew:true only if they choose new. A freshly created account is saved to this MCP's local account store and reused automatically on the next restart; an explicit ZETRIX_ADDRESS in the MCP config still overrides it.",
       inputSchema: {
         type: "object",
         properties: {
           password: { type: "string", description: "HSM password to protect the new account. Must come from the user." },
           label: { type: "string" },
-          purpose: { type: "string" }
+          purpose: { type: "string" },
+          confirmNew: {
+            type: "boolean",
+            description: "Set true to mint a new account even though one already exists for this session \u2014 only after the user has confirmed they want a new one."
+          }
         },
         required: ["password"]
       }
@@ -22300,25 +22902,46 @@ function asPayRequest(accept) {
   return { ...accept, extra: { gasModel: "client", ...extra } };
 }
 async function main() {
-  const config2 = loadConfig(process.env);
+  const accountStore = createFsAccountStore((0, import_node_path3.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "account.json"));
+  const storedAccount = process.env.ZETRIX_ADDRESS ? null : await accountStore.get();
+  const env = { ...process.env };
+  if (!env.ZETRIX_ADDRESS && storedAccount) env.ZETRIX_ADDRESS = storedAccount.zetrixAddress;
+  if (!env.HOLDER_DID && storedAccount) env.HOLDER_DID = storedAccount.holderDid;
+  if (!env.HSM_PASSWORD && storedAccount) env.HSM_PASSWORD = storedAccount.hsmPassword;
+  const config2 = loadConfig(env);
   const hsmPassword = config2.hsmPassword;
   const be = new WalletBeClient(config2.walletBeUrl);
-  const { zetrixAddress, holderDid, created, didMismatch } = await resolveHolder(
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const { zetrixAddress, holderDid, created, didMismatch, activated } = await resolveHolder(
     {
       createAccount: (password) => be.createAccount(password),
-      signMessage: (message, address, password) => be.signMessage(message, address, password)
+      signMessage: (message, address, password) => be.signMessage(message, address, password),
+      checkActivationStatus: (address) => be.checkActivationStatus(address),
+      sleep
     },
     { zetrixAddress: config2.zetrixAddress, holderDid: config2.holderDid, hsmPassword }
   );
   if (created) {
+    await accountStore.set({ zetrixAddress, holderDid, hsmPassword, createdAt: (/* @__PURE__ */ new Date()).toISOString() });
+    process.stderr.write(
+      `agentic-wallet-mcp: no ZETRIX_ADDRESS was set \u2014 created a new HSM account and saved it (address, DID, and password) to ~/.agentic-wallet-mcp/account.json; it will be reused automatically next run. ZETRIX_ADDRESS=${zetrixAddress} (HOLDER_DID=${holderDid} is optional; it re-derives automatically).
+`
+    );
+  } else if (storedAccount && config2.zetrixAddress === storedAccount.zetrixAddress) {
     process.stderr.write(
-      `agentic-wallet-mcp: no ZETRIX_ADDRESS was set \u2014 created a new HSM account. Save this for next run: ZETRIX_ADDRESS=${zetrixAddress} (HOLDER_DID=${holderDid} is optional; it re-derives automatically).
+      `agentic-wallet-mcp: using the holder account saved in ~/.agentic-wallet-mcp/account.json (ZETRIX_ADDRESS=${zetrixAddress}) \u2014 no ZETRIX_ADDRESS/HSM_PASSWORD was set in the MCP config.
 `
     );
   }
   if (didMismatch) {
     process.stderr.write(
       `agentic-wallet-mcp: configured HOLDER_DID=${config2.holderDid} does not match the account's actual public key \u2014 using the derived HOLDER_DID=${holderDid} instead. Update your MCP config.
+`
+    );
+  }
+  if (created && !activated) {
+    process.stderr.write(
+      `agentic-wallet-mcp: the newly created HSM account (ZETRIX_ADDRESS=${zetrixAddress}) has not completed on-chain activation yet \u2014 balance/on-chain calls for this address may fail until it does.
 `
     );
   }
@@ -22329,14 +22952,36 @@ async function main() {
   const sdk = new import_zetrix_sdk_nodejs.default({ host: config2.nodeHost, port: config2.nodePort });
   const contractQuery = (a) => sdk.contract.call(a);
   const resolveSymbol = (asset) => resolveAssetSymbol(asset, contractQuery);
+  const queryTokenBalance = async (token) => {
+    const symbol = token.toUpperCase();
+    if (symbol === "ZTX") {
+      try {
+        const { balance } = await import_x402_zetrix_client2.PaymentEngine.fetchAccountInfo(zetrixAddress, node);
+        return { token: symbol, balance };
+      } catch {
+        return { token: symbol, error: "query_failed" };
+      }
+    }
+    const contractAddress = resolveTokenAddress(symbol, config2.network);
+    if (!contractAddress) return { token: symbol, error: "unknown_token" };
+    try {
+      const { balance } = await import_x402_zetrix_client2.PaymentEngine.fetchZTP20Balance(contractAddress, zetrixAddress, node);
+      return { token: symbol, balance };
+    } catch {
+      return { token: symbol, error: "query_failed" };
+    }
+  };
   const nodeBaseUrl = `https://${config2.nodeHost}${config2.nodePort ? `:${config2.nodePort}` : ""}`;
   const nodeMetaQuery = (url) => fetch(url, { headers: { Accept: "application/json" } }).then((r) => r.json());
   const resolveTemplateFields = (templateId) => fetchTemplateFields(templateId, config2.templateRegistryAddress, nodeBaseUrl, nodeMetaQuery);
   const cacheScope = (0, import_node_crypto2.createHash)("sha256").update(`${config2.network}:${zetrixAddress}`).digest("hex");
-  const vcCache = createFsVcCache((0, import_node_path2.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "vc-cache", cacheScope));
+  const vcCache = createFsVcCache((0, import_node_path3.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "vc-cache", cacheScope));
   const pay = (accept) => {
     assertWithinPaymentCap(accept, config2.maxPaymentAmount);
-    return import_x402_zetrix_client.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn);
+    return payWithReadinessCheck(
+      String(accept.asset ?? ""),
+      () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn)
+    );
   };
   const payer = async (req) => {
     const init = { method: req.method ?? "GET", headers: req.headers, body: req.body };
@@ -22347,7 +22992,15 @@ async function main() {
     const parsed = await res.json();
     const accept = parsed.accepts?.[0];
     if (!accept) throw new Error("pay_and_fetch: 402 had no accepts[]");
-    const xPayment = await pay(accept);
+    let xPayment;
+    try {
+      xPayment = await pay(accept);
+    } catch (err) {
+      if (err instanceof PaymentReadinessError) {
+        return { status: 402, body: "", paymentMade: false, amountPaid: "", amountPaidHuman: "", asset: "", insufficientFunds: err.shortfall };
+      }
+      throw err;
+    }
     const retry = await fetch(req.url, { ...init, headers: { ...req.headers ?? {}, "x-payment": xPayment } });
     const asset = await resolveSymbol(String(accept.asset ?? ""));
     return {
@@ -22377,7 +23030,12 @@ async function main() {
     makeWallet,
     payer,
     subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
+    queryContract: (input) => queryContract(input, contractQuery),
+    queryTokenBalance,
     createAccount: (password, label, purpose) => be.createAccount(password, label, purpose),
+    saveAccount: (account) => accountStore.set({ ...account, createdAt: (/* @__PURE__ */ new Date()).toISOString() }),
+    checkActivationStatus: (address) => be.checkActivationStatus(address),
+    sleep,
     cache: vcCache
   };
   const tools = createTools(deps);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": ["mcp", "model-context-protocol", "zetrix", "wallet", "x401", "x402", "blockchain"],
   "license": "MIT",