agentic-wallet-mcp 0.4.2 → 0.5.0

package/README.md

@@ -23,7 +23,7 @@ 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? }` |
+| `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/`
@@ -38,6 +38,15 @@ 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 always checks first whether an account is already
 > active for this session; if so, it returns `{ alreadyExists: true, existing }` and creates

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");
           }
         }
       },
@@ -12547,7 +12547,7 @@ var import_node_path3 = require("node:path");
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.4.2",
+  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
@@ -22035,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)) {
@@ -22058,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 } : {}
       };
     }
   }
@@ -22073,7 +22162,15 @@ 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) {
@@ -22095,11 +22192,12 @@ async function subscribeAndIssue(deps, opts) {
       txHash: issued2.txHash,
       paidAsset: "none",
       amountPaid: "0",
+      ...schema ? { schema } : {},
       ...opts.dryRun ? { reason: "this template requires no payment \u2014 MBI issues synchronously at phase 1, so dryRun could not prevent this issuance" } : {}
     };
   }
   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;
@@ -22109,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 ?? "");
@@ -22137,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();
@@ -22158,31 +22285,383 @@ async function createHolderAccount(deps, input) {
       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 } = await deps.create(input.password, input.label, input.purpose);
+  const { zetrixAddress, publicKeyHex, activated } = await deps.create(input.password, input.label, input.purpose);
   const holderDid = deriveHolderDid(publicKeyHex);
   await deps.saveAccount({ zetrixAddress, holderDid, hsmPassword: input.password, label: input.label, purpose: input.purpose });
-  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).`;
-  return { created: true, alreadyExists: Boolean(existing), zetrixAddress, holderDid, publicKeyHex, message };
+  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) {
@@ -22194,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) {
@@ -22226,16 +22707,36 @@ 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(
         {
           create: deps.createAccount,
           getExistingAccount: () => Promise.resolve(deps.config.zetrixAddress ? { zetrixAddress: deps.config.zetrixAddress, holderDid: deps.config.holderDid } : null),
-          saveAccount: deps.saveAccount
+          saveAccount: deps.saveAccount,
+          checkActivationStatus: deps.checkActivationStatus,
+          sleep: deps.sleep
         },
         input
       );
@@ -22246,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);
@@ -22289,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.' }
         }
       }
     },
@@ -22328,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: {
@@ -22345,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",
@@ -22388,10 +22911,13 @@ async function main() {
   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 }
   );
@@ -22410,6 +22936,12 @@ async function main() {
   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.
 `
     );
   }
@@ -22420,6 +22952,25 @@ 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);
@@ -22427,7 +22978,10 @@ async function main() {
   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 };
@@ -22438,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 {
@@ -22468,8 +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.2",
+  "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",