agentic-wallet-mcp 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -8,6 +8,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Entries for 0.5.0 and earlier were reconstructed from commit history when this file was
 > introduced in 0.6.0, so they summarise each release rather than being exhaustive.
 
+## [0.7.0] — 4 August 2026
+
+**Read the breaking change before upgrading if you make x402 payments.** This release lets the wallet
+provision itself, so it can start with no configuration at all — which is what makes an OpenClaw plugin
+install possible, and also why the payment cap now has to default to zero.
+
+### Changed (breaking)
+
+- **`MAX_PAYMENT_AMOUNT` now defaults to `{"*":"0"}` instead of being unset.** An unconfigured wallet
+  refuses every x402 payment rather than allowing any amount. Previously an unset cap disabled the
+  ceiling entirely, which was defensible only while every install required hand-written environment
+  variables; a wallet that can now start with no configuration must not be able to auto-pay a hostile
+  challenge. To keep paying, set the cap explicitly, e.g.
+  `MAX_PAYMENT_AMOUNT={"ZTX":"1000000000","*":"0"}`.
+
+- **`create_holder_account` no longer takes a `password` parameter.** The wallet uses the password
+  already active for the session, so a model can neither be asked for one nor supply one. A
+  `password` still passed by an old caller is **silently ignored** rather than rejected, because the
+  tool schema permits extra properties. Consequence: a newly minted account now inherits the session
+  password instead of taking a different one.
+
+### Added
+
+- **The wallet provisions itself.** `HSM_PASSWORD` and `ZETRIX_NETWORK` are both optional now.
+  With neither set, the wallet defaults to testnet, generates a random HSM password, creates a
+  holder account, and stores address, DID and password in its own state directory — so it starts
+  with no configuration at all. An explicit env var still wins over every other source, so an
+  existing `.mcp.json` behaves exactly as before.
+- **`npx agentic-wallet-mcp export-credentials`** prints the address, DID and HSM password for
+  backup. A generated password is the only thing that can authorize signing for the account, so
+  losing the state directory means losing the account. Interactive terminals only, and deliberately
+  not an MCP tool, so an agent can never read it.
+- **`--config <path>`** reads settings from a JSON file instead of the environment, for hosts that
+  cannot set env vars. It carries no secret: a `hsmPassword` key is a hard error, and so is any
+  unknown key, so a typo cannot silently start the wallet on the wrong network.
+- **`ZETRIX_WALLET_STATE_DIR`** moves `account.json` and the VC cache out of the home directory.
+  The default is unchanged.
+- `pay_and_fetch` and `subscribe_and_issue` now report a `not_activated` shortfall when the holder
+  address is not yet on chain, instead of reporting it as a low balance — the remedy is to send it
+  gas, not to top up a token.
+
+### Fixed
+
+- **A zero ZTX balance no longer reports `query_failed`.** The node omits the `balance` field
+  entirely when it is zero, and `wallet_status({ token: "ZTX" })` treated its absence as a failed
+  read — so every account holding no ZTX looked like a broken lookup. A successful RPC that omits a
+  zero-valued field is now read as `0`. A non-zero `errorCode`, or a response with no `result` at
+  all, still fails loudly rather than reporting a fabricated zero.
+
+## [0.6.1] — 2026-07-29
+
+**Upgrade if you use testnet.** The testnet Wallet BE and MBI endpoints have moved to the Zetrix
+sandbox hosts. No API, tool or config surface changed — this is an endpoint migration only.
+
+### Changed
+
+- **Testnet default endpoints moved to the Zetrix sandbox hosts.** `ZETRIX_NETWORK=zetrix:testnet`
+  now derives `https://wallet-api-sandbox.zetrix.com/server` (was
+  `https://wallet-api.myegdev.com/server`) and `https://mbi-vc-sandbox.zetrix.com` (was
+  `https://mbi-vc.myegdev.com`). Anyone on testnet relying on the built-in defaults should upgrade
+  to follow the platform; mainnet defaults are unchanged, and an explicit `WALLET_BE_URL` /
+  `MBI_BASE_URL` still wins over the network default, so anyone pinning those is unaffected.
+  Note the Wallet BE base keeps its `/server` path suffix — verified against the new host, which
+  returns nginx `404` without it.
+
 ## [0.6.0] — 2026-07-28
 
 This release is about the wallet never misstating what a call cost. Four reporting defects were

package/README.md

@@ -165,8 +165,8 @@ Node ≥ 18 required (built-in `fetch`).
 
 | Variable | Required | Description |
 |---|---|---|
-| `ZETRIX_NETWORK` | yes | `zetrix:testnet` or `zetrix:mainnet` — also selects the default `WALLET_BE_URL`/`MBI_BASE_URL`/`OID4VP_BASE_URL`/`ZID_RESOLVER_BASE_URL` below |
-| `HSM_PASSWORD` | yes* | HSM password |
+| `ZETRIX_NETWORK` | no | `zetrix:testnet` or `zetrix:mainnet` — also selects the default `WALLET_BE_URL`/`MBI_BASE_URL`/`OID4VP_BASE_URL`/`ZID_RESOLVER_BASE_URL` below. **Defaults to `zetrix:testnet`**; mainnet is always a deliberate choice |
+| `HSM_PASSWORD` | no* | HSM password. Omit it and the wallet generates one on first run and stores it in its own state directory — see "Onboarding" below |
 | `ZETRIX_ADDRESS` | no | Holder Zetrix address (the HSM account). Omit on first run — see "Onboarding" below |
 | `HOLDER_DID` | no | Holder DID. Omit and the MCP derives it automatically — see "Onboarding" below |
 | `WALLET_BE_URL` | no | Wallet BE base URL override (HSM `/wallet/hsm/sign-blob`) — auto-derived from `ZETRIX_NETWORK` when not set |
@@ -174,22 +174,25 @@ Node ≥ 18 required (built-in `fetch`).
 | `OID4VP_BASE_URL` | no | OID4VP verifier base URL override — auto-derived from `ZETRIX_NETWORK` by the x401 SDK when not set |
 | `ZETRIX_NODE_HOST` / `ZETRIX_NODE_PORT` | no | RPC node override (auto-derived from network) |
 | `ZID_RESOLVER_BASE_URL` | no | ZID resolver override (auto-derived from network: sandbox for testnet, prod for mainnet) |
-| `MAX_PAYMENT_AMOUNT` | no** | Per-asset x402 auto-pay cap — JSON `{ "<asset>": "<maxRawUnits>", "*": "<fallback>" }`. `pay_and_fetch`/`subscribe_and_issue` are asset-agnostic: the resource server's 402 challenge may quote the native ZETRIX token (asset code `ZTX`) **or** a ZTP20 token (e.g. `JMYR`) — cap whichever assets you expect, e.g. `{"ZTX":"1000000000","JMYR":"5000000","*":"0"}`. Unset = no cap enforced. |
+| `MAX_PAYMENT_AMOUNT` | no** | Per-asset x402 auto-pay cap — JSON `{ "<asset>": "<maxRawUnits>", "*": "<fallback>" }`. `pay_and_fetch`/`subscribe_and_issue` are asset-agnostic: the resource server's 402 challenge may quote the native ZETRIX token (asset code `ZTX`) **or** a ZTP20 token (e.g. `JMYR`) — cap whichever assets you expect, e.g. `{"ZTX":"1000000000","JMYR":"5000000","*":"0"}`. **Defaults to `{"*":"0"}` — every payment is refused until you set this.** |
+| `ZETRIX_WALLET_STATE_DIR` | no | Where the wallet keeps `account.json` and its VC cache. Defaults to `~/.agentic-wallet-mcp` |
 
-\* sensitive — never logged.
+\* sensitive — never logged, never returned in a tool result, and never a tool parameter.
 
 ### Onboarding: two ways to set up your holder identity
 
 `ZETRIX_ADDRESS` and `HOLDER_DID` are both optional — the MCP resolves your holder identity at
 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, 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.
+1. **First-time user — nothing set at all, or 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. If you did not set `HSM_PASSWORD`, it generates one for you first. 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.
+
+   **If the wallet generated your password, back it up — see below.**
 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
@@ -201,13 +204,28 @@ startup, in one of two ways:
 Either way, `wallet_status` always reports the resolved `zetrixAddress`/`holderDid` for the
 running session, so you can confirm what the MCP resolved to at any time.
 
-\*\* **strongly recommended before pointing this wallet at mainnet/real funds.** `pay_and_fetch`
-and `subscribe_and_issue` auto-pay whatever `maxAmountRequired` a remote server's 402 challenge
-demands, with no built-in ceiling — a prompt-injected or misled agent calling either tool against
-a hostile endpoint would pay whatever that endpoint asks for, bounded only by the HSM account
-balance. `MAX_PAYMENT_AMOUNT` is a hard, code-enforced cap that holds regardless of what the
-calling agent decides. Once set, it becomes an allowlist: an asset with no entry and no `"*"`
-fallback is **denied**, not passed through uncapped.
+### Backing up a self-provisioned wallet
+
+If you never set `HSM_PASSWORD`, the wallet generated one and stored it in
+`~/.agentic-wallet-mcp/account.json`. You never have to type it — but it is the only thing that
+can authorize signing for your account. Wallet BE holds the key and will not use it without this
+password, so if you lose the file the account cannot be recovered and any funds in it are gone.
+Back it up with:
+
+```bash
+npx agentic-wallet-mcp export-credentials
+```
+
+This only runs in an interactive terminal, so it can't be piped into a file or a log, and it is
+deliberately **not** available as an MCP tool — an AI agent can never read your password.
+
+\*\* **You must set this before the wallet will pay for anything.** It defaults to `{"*":"0"}`,
+which refuses every payment. `pay_and_fetch` and `subscribe_and_issue` auto-pay whatever
+`maxAmountRequired` a remote server's 402 challenge demands, so without a ceiling a prompt-injected
+or misled agent calling either tool against a hostile endpoint would pay whatever that endpoint
+asks for, bounded only by the account balance. `MAX_PAYMENT_AMOUNT` is a hard, code-enforced cap
+that holds regardless of what the calling agent decides. It is also an allowlist: an asset with no
+entry and no `"*"` fallback is **denied**, not passed through uncapped.
 
 You don't need to look up or fill in `WALLET_BE_URL`/`MBI_BASE_URL`/`OID4VP_BASE_URL`/
 `ZID_RESOLVER_BASE_URL` yourself — just pick `zetrix:testnet` or `zetrix:mainnet` for
@@ -216,11 +234,11 @@ network:
 
 | Network | `WALLET_BE_URL` default | `MBI_BASE_URL` default | `OID4VP_BASE_URL` default | `ZID_RESOLVER_BASE_URL` default |
 |---|---|---|---|---|
-| `zetrix:testnet` | `https://wallet-api.myegdev.com/server` | `https://mbi-vc.myegdev.com` | `https://zid-oid4vp-sandbox.zetrix.com/api` | `https://zid-resolver-sandbox.zetrix.com` |
+| `zetrix:testnet` | `https://wallet-api-sandbox.zetrix.com/server` | `https://mbi-vc-sandbox.zetrix.com` | `https://zid-oid4vp-sandbox.zetrix.com/api` | `https://zid-resolver-sandbox.zetrix.com` |
 | `zetrix:mainnet` | `https://wallet-api.zetrix.com/server` | `https://mbi-vc.zetrix.com` | `https://zid-oid4vp.zetrix.com/api` | `https://zid-resolver.zetrix.com` |
 
 Only set any of the four explicitly if you run your own instance of that service instead of the
-default one — an explicit value always wins over the network default. The `*.myegdev.com`
+default one — an explicit value always wins over the network default. The `*-sandbox.zetrix.com`
 (testnet) hosts are public endpoints — no VPN needed; if you're on a corporate VPN and one of
 them times out, disconnecting it is more likely to fix that than connecting it. See "Network
 reachability & troubleshooting" below.
@@ -323,17 +341,25 @@ Independent of Phases 2/3 — no VC or identity proof involved, just a fresh pay
 
 ## Network reachability & troubleshooting
 
-The `*.myegdev.com` testnet endpoints are public — no VPN needed to reach them. One dependency
-sits behind a CDN edge (see the ZID resolver row below). When something that worked before
-suddenly times out or 403s, check this table before assuming a code regression.
+The `*-sandbox.zetrix.com` testnet endpoints are public — no VPN needed to reach them. Reachability
+differs per host, and this is the first thing to check when something that worked before suddenly
+times out or 403s, before assuming a code regression.
+
+- **`wallet-api-sandbox.zetrix.com` / `mbi-vc-sandbox.zetrix.com`** — direct origin IPs
+  (`124.243.148.237` / `111.119.237.222` as of 2026-07-29), **not** CDN-fronted, unlike the ZID
+  hosts and the mainnet endpoints. Being off-CDN is why the **corporate VPN blocks them
+  specifically** while `test-node.zetrix.com` and the mainnet hosts keep working over the same
+  VPN — so a failure here looks like a total outage while everything else looks healthy.
+  Disconnect the VPN. Verified reachable over a plain internet path on 2026-07-29.
+- **ZID resolver** sits behind a CDN edge with a managed challenge — see its row below.
 
 | Symptom | Cause | Fix / status |
 |---|---|---|
-| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc.myegdev.com`) | Transient network issue, or (if you're on a corporate VPN) the VPN routing away from the public internet | If you're on a VPN, try disconnecting it and retrying. Verify reachability directly: `curl -I https://wallet-api.myegdev.com/server` |
+| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc-sandbox.zetrix.com`) | Corporate VPN routing away from the public internet — it blocks these two direct-origin hosts specifically (observed 2026-07-29), or a transient network issue | **Disconnect the VPN and retry.** Verify reachability directly: `curl -sS -o /dev/null -w '%{http_code}\n' "https://wallet-api-sandbox.zetrix.com/server/wallet/hsm/account/activate/status?address=<yourAddress>"` — `200` (with an `errorCode: 0` body) is healthy; `000` means the TCP connect never completed, so it's a network path problem, not a code problem |
 | `VP derivation failed <- ZID resolver HTTP 403 ... cf-mitigated: challenge` | ZID resolver (`zid-resolver-sandbox.zetrix.com`) sitting behind a Cloudflare **managed challenge** that blocks plain server-to-server `fetch` | Server-to-server access to the resolver must be allowlisted so it returns `200` directly. If the challenge is active, `prove_identity`'s `issuerKeys` input is the fallback — fetch the DID document via a real browser (it clears the JS challenge) and pass its `verificationMethod` entries' `publicKeyMultibase` (BBS+) / `publicKeyHex` (Ed25519) directly. |
 | `OID4VP backend returned a malformed presentation definition` | Historical SDK bug: the live sandbox's `GET /v1/presentation/{id}` response has no `expires_at` field, but the SDK guard required one | **Fixed** in `x401-zetrix-client` — `expiresAt` is now optional on `PresentationDefinition`. If you see this, you're on a stale cached `npx` install — clear it (`npx clear-npx-cache` or bump the version) to pick up the current published `agentic-wallet-mcp`. |
 | `SUBMIT_FAILED: OID4VP backend returned 401 ... Missing X-Wallet-Public-Key header` | Historical SDK gap: `POST /v1/presentation/submit` requires wallet-auth headers (`X-Wallet-Public-Key` / `X-Wallet-Signed-Data`, holder signs their own address) that the SDK didn't send | **Fixed** — `X401Wallet` now accepts an injected `submitAuth` provider and the wallet wires it automatically; nothing to configure. |
-| `MBI /vp/ext/submit did not return vp` | MBI's `includeVp` opt-in not deployed on the target instance | Deployed on the sandbox (`mbi-vc.myegdev.com`). If you see this against a different MBI instance, that instance needs the same rollout. |
+| `MBI /vp/ext/submit did not return vp` | MBI's `includeVp` opt-in not deployed on the target instance | Deployed on the sandbox (`mbi-vc-sandbox.zetrix.com`). If you see this against a different MBI instance, that instance needs the same rollout. |
 
 ## Security notes
 

package/dist/server-bundle.cjs

@@ -12540,14 +12540,15 @@ __export(index_exports, {
   buildToolList: () => buildToolList
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_crypto2 = require("node:crypto");
-var import_node_os = require("node:os");
-var import_node_path3 = require("node:path");
+var import_node_crypto3 = require("node:crypto");
+var import_node_fs = require("node:fs");
+var import_node_os2 = require("node:os");
+var import_node_path4 = require("node:path");
 
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.6.0",
+  version: "0.7.0",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -21489,6 +21490,10 @@ var X401Wallet = class {
 // src/index.ts
 var import_zetrix_sdk_nodejs = __toESM(require("zetrix-sdk-nodejs"), 1);
 
+// src/config.ts
+var import_node_os = require("node:os");
+var import_node_path = require("node:path");
+
 // src/payment-guard.ts
 var PaymentCapError = class extends Error {
   constructor(message) {
@@ -21548,10 +21553,10 @@ function deriveZidResolverBaseUrl(network) {
   return network.includes("testnet") ? "https://zid-resolver-sandbox.zetrix.com" : "https://zid-resolver.zetrix.com";
 }
 function deriveWalletBeUrl(network) {
-  return network.includes("testnet") ? "https://wallet-api.myegdev.com/server" : "https://wallet-api.zetrix.com/server";
+  return network.includes("testnet") ? "https://wallet-api-sandbox.zetrix.com/server" : "https://wallet-api.zetrix.com/server";
 }
 function deriveMbiBaseUrl(network) {
-  return network.includes("testnet") ? "https://mbi-vc.myegdev.com" : "https://mbi-vc.zetrix.com";
+  return network.includes("testnet") ? "https://mbi-vc-sandbox.zetrix.com" : "https://mbi-vc.zetrix.com";
 }
 function deriveTemplateRegistryAddress(network) {
   return network.includes("testnet") ? "ZTX3JszqPgRUx743SAp7q7zURfjvkWuH2FMEz" : "ZTX3GqJM1U6ifMPonwD4fGvrgoTKJua7b2cKX";
@@ -21574,24 +21579,28 @@ function loadConfig(env) {
     const v = env[key];
     return v && v.trim() ? v.trim() : void 0;
   };
-  const network = req("ZETRIX_NETWORK");
+  const network = opt("ZETRIX_NETWORK") ?? "zetrix:testnet";
   const oid4vpBaseUrlOverride = opt("OID4VP_BASE_URL");
   return {
     walletBeUrl: stripTrailingSlash(opt("WALLET_BE_URL") ?? deriveWalletBeUrl(network)),
     oid4vpBaseUrl: oid4vpBaseUrlOverride ? stripTrailingSlash(oid4vpBaseUrlOverride) : void 0,
     mbiBaseUrl: stripTrailingSlash(opt("MBI_BASE_URL") ?? deriveMbiBaseUrl(network)),
     network,
+    stateDir: stripTrailingSlash(opt("ZETRIX_WALLET_STATE_DIR") ?? (0, import_node_path.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp")),
     zetrixAddress: opt("ZETRIX_ADDRESS"),
     holderDid: opt("HOLDER_DID"),
     hsmPassword: req(
       "HSM_PASSWORD",
-      "set your own HSM password in the MCP config before starting the server \u2014 this MCP never generates, invents, or infers a password on your behalf"
+      "the server is normally started through main(), which generates a password when none exists \u2014 reaching this error means loadConfig was called directly without one"
     ),
     nodeHost: opt("ZETRIX_NODE_HOST") ?? deriveNodeHost(network),
     nodePort: opt("ZETRIX_NODE_PORT") ?? "",
     templateRegistryAddress: opt("ZETRIX_TEMPLATE_REGISTRY_ADDRESS") ?? deriveTemplateRegistryAddress(network),
     zidResolverBaseUrl: stripTrailingSlash(opt("ZID_RESOLVER_BASE_URL") ?? deriveZidResolverBaseUrl(network)),
-    maxPaymentAmount: parsePaymentCaps(opt("MAX_PAYMENT_AMOUNT"))
+    // Fail closed: an unset cap means "spend nothing", not "spend anything". A wallet that
+    // starts with no configuration at all (plugin install, see docs/openclaw) must not be
+    // able to auto-pay a hostile x402 challenge. Raising it is a deliberate act.
+    maxPaymentAmount: parsePaymentCaps(opt("MAX_PAYMENT_AMOUNT")) ?? { "*": "0" }
   };
 }
 
@@ -21654,6 +21663,15 @@ async function queryContract(input, query) {
 
 // src/clients/token-balance-client.ts
 var ZTX_DECIMALS = 6;
+function parseNativeBalance(res) {
+  if (res?.errorCode !== 0) throw new Error(`getInfo failed with errorCode ${res?.errorCode}`);
+  if (res.result === void 0 || res.result === null) throw new Error("getInfo returned no result");
+  const balance = res.result.balance;
+  if (typeof balance === "string") return balance;
+  if (typeof balance === "number" && Number.isFinite(balance)) return String(balance);
+  if (balance === void 0 || balance === null) return "0";
+  throw new Error(`getInfo returned an unusable balance of type ${typeof balance}`);
+}
 async function fetchZTP20BalanceStrict(contractAddress, address, query) {
   const result = await query({
     contractAddress,
@@ -22109,7 +22127,7 @@ function zetrixHexStringToBytes(s) {
 // src/clients/vc-cache.ts
 var import_node_crypto = require("node:crypto");
 var import_promises = require("node:fs/promises");
-var import_node_path = require("node:path");
+var import_node_path2 = require("node:path");
 function cacheFileName(templateId) {
   return `${(0, import_node_crypto.createHash)("sha256").update(templateId).digest("hex")}.json`;
 }
@@ -22120,7 +22138,7 @@ function createFsVcCache(baseDir) {
   return {
     async get(templateId) {
       try {
-        const raw = await (0, import_promises.readFile)((0, import_node_path.join)(baseDir, cacheFileName(templateId)), "utf8");
+        const raw = await (0, import_promises.readFile)((0, import_node_path2.join)(baseDir, cacheFileName(templateId)), "utf8");
         const parsed = JSON.parse(raw);
         return isCachedVcShape(parsed) ? parsed : null;
       } catch {
@@ -22129,7 +22147,7 @@ function createFsVcCache(baseDir) {
     },
     async set(templateId, entry) {
       await (0, import_promises.mkdir)(baseDir, { recursive: true, mode: 448 });
-      await (0, import_promises.writeFile)((0, import_node_path.join)(baseDir, cacheFileName(templateId)), JSON.stringify(entry), { encoding: "utf8", mode: 384 });
+      await (0, import_promises.writeFile)((0, import_node_path2.join)(baseDir, cacheFileName(templateId)), JSON.stringify(entry), { encoding: "utf8", mode: 384 });
     },
     async list() {
       let files;
@@ -22141,7 +22159,7 @@ function createFsVcCache(baseDir) {
       const entries = await Promise.all(
         files.filter((f) => f.endsWith(".json")).map(async (f) => {
           try {
-            const parsed = JSON.parse(await (0, import_promises.readFile)((0, import_node_path.join)(baseDir, f), "utf8"));
+            const parsed = JSON.parse(await (0, import_promises.readFile)((0, import_node_path2.join)(baseDir, f), "utf8"));
             return isCachedVcShape(parsed) ? parsed : null;
           } catch {
             return null;
@@ -22189,8 +22207,14 @@ var PaymentReadinessError = class extends Error {
     this.shortfall = shortfall;
   }
 };
-function toPaymentReadinessError(err, requestedAsset) {
+function toPaymentReadinessError(err, requestedAsset, activated) {
   if (!(err instanceof import_x402_zetrix_client.InsufficientBalanceError)) return null;
+  if (activated === false) {
+    return new PaymentReadinessError(
+      `payment blocked: this wallet's address has not been activated on chain yet \u2014 send ZTX to it from a funded account, then retry`,
+      { asset: err.asset, required: err.required, available: err.available, reason: "not_activated" }
+    );
+  }
   const reason = err.asset === "ZTX" && requestedAsset !== "ZTX" ? "gas" : "resource_payment";
   return new PaymentReadinessError(err.message, {
     asset: err.asset,
@@ -22199,11 +22223,11 @@ function toPaymentReadinessError(err, requestedAsset) {
     reason
   });
 }
-async function payWithReadinessCheck(requestedAsset, rawPay) {
+async function payWithReadinessCheck(requestedAsset, rawPay, activated) {
   try {
     return await rawPay();
   } catch (err) {
-    const readinessError = toPaymentReadinessError(err, requestedAsset);
+    const readinessError = toPaymentReadinessError(err, requestedAsset, activated);
     if (readinessError) throw readinessError;
     throw err;
   }
@@ -22412,9 +22436,9 @@ 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, activated } = await deps.create(input.password, input.label, input.purpose);
+  const { zetrixAddress, publicKeyHex, activated } = await deps.create(input.label, input.purpose);
   const holderDid = deriveHolderDid(publicKeyHex);
-  await deps.saveAccount({ zetrixAddress, holderDid, hsmPassword: input.password, label: input.label, purpose: input.purpose });
+  await deps.saveAccount({ zetrixAddress, holderDid, 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 };
@@ -22922,9 +22946,123 @@ async function resolveHolder(deps, input) {
   return { zetrixAddress: input.zetrixAddress, holderDid: derivedDid, created: false, didMismatch };
 }
 
+// src/startup-env.ts
+function resolveStartupEnv(input) {
+  const env = { ...input.fileEnv, ...input.processEnv };
+  const stored = input.storedAccount;
+  if (!env.ZETRIX_ADDRESS && stored) env.ZETRIX_ADDRESS = stored.zetrixAddress;
+  if (!env.HOLDER_DID && stored) env.HOLDER_DID = stored.holderDid;
+  if (!env.HSM_PASSWORD && stored) env.HSM_PASSWORD = stored.hsmPassword;
+  let passwordGenerated = false;
+  if (!env.HSM_PASSWORD) {
+    env.HSM_PASSWORD = input.generatePassword();
+    passwordGenerated = true;
+  }
+  return { env, passwordGenerated };
+}
+
+// src/config-file.ts
+var KEY_TO_ENV = {
+  network: "ZETRIX_NETWORK",
+  zetrixAddress: "ZETRIX_ADDRESS",
+  holderDid: "HOLDER_DID",
+  maxPaymentAmount: "MAX_PAYMENT_AMOUNT",
+  stateDir: "ZETRIX_WALLET_STATE_DIR",
+  walletBeUrl: "WALLET_BE_URL",
+  mbiBaseUrl: "MBI_BASE_URL"
+};
+var FORBIDDEN_KEYS = ["hsmPassword", "password", "HSM_PASSWORD"];
+function configPathFrom(argv) {
+  const inline = argv.find((a) => a.startsWith("--config="));
+  if (inline) {
+    const path2 = inline.slice("--config=".length);
+    if (!path2) throw new Error("agentic-wallet-mcp: --config requires a file path");
+    return path2;
+  }
+  const i = argv.indexOf("--config");
+  if (i === -1) return null;
+  const path = argv[i + 1];
+  if (!path || path.startsWith("--")) throw new Error("agentic-wallet-mcp: --config requires a file path");
+  return path;
+}
+function loadConfigFileEnv(argv, readFile3) {
+  const path = configPathFrom(argv);
+  if (path === null) return {};
+  let raw;
+  try {
+    raw = readFile3(path);
+  } catch (e) {
+    throw new Error(`agentic-wallet-mcp: cannot read config file ${path}: ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`agentic-wallet-mcp: config file ${path} is not valid JSON: ${e.message}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`agentic-wallet-mcp: config file ${path} must contain a JSON object`);
+  }
+  const env = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (FORBIDDEN_KEYS.includes(key)) {
+      throw new Error(
+        `agentic-wallet-mcp: config file ${path} must not contain a secret ("${key}") \u2014 the wallet generates and stores its own HSM password; see docs/openclaw/DEPLOYMENT_DESIGN.md`
+      );
+    }
+    const envKey = KEY_TO_ENV[key];
+    if (!envKey) {
+      throw new Error(
+        `agentic-wallet-mcp: unknown config key "${key}" in ${path} \u2014 allowed: ${Object.keys(KEY_TO_ENV).join(", ")}`
+      );
+    }
+    env[envKey] = typeof value === "string" ? value : JSON.stringify(value);
+  }
+  return env;
+}
+
+// src/hsm-password.ts
+var import_node_crypto2 = require("node:crypto");
+function generateHsmPassword() {
+  return (0, import_node_crypto2.randomBytes)(24).toString("base64url");
+}
+
+// src/export-credentials.ts
+async function exportCredentials(deps) {
+  if (!deps.isTty) {
+    deps.writeErr(
+      "agentic-wallet-mcp: export-credentials only runs in an interactive terminal, so the password cannot be piped into a file or a log. Run it directly in your shell.\n"
+    );
+    return { exitCode: 1 };
+  }
+  const account = await deps.getAccount();
+  if (!account) {
+    deps.writeErr(
+      "agentic-wallet-mcp: no account has been created yet \u2014 start the wallet once to provision one, then run this again.\n"
+    );
+    return { exitCode: 1 };
+  }
+  deps.write(
+    `
+Zetrix Agentic Wallet \u2014 credentials for backup
+
+  Address:      ${account.zetrixAddress}
+  Holder DID:   ${account.holderDid}
+  HSM password: ${account.hsmPassword}
+
+Store these somewhere safe and private, such as a password manager.
+The HSM password is the only thing that can authorize signing for this wallet. If you lose it
+and lose this machine's wallet state, the account cannot be recovered and any funds in it are
+permanently inaccessible.
+
+`
+  );
+  return { exitCode: 0 };
+}
+
 // src/clients/account-store.ts
 var import_promises2 = require("node:fs/promises");
-var import_node_path2 = require("node:path");
+var import_node_path3 = require("node:path");
 function isStoredAccountShape(value) {
   return typeof value === "object" && value !== null && typeof value.zetrixAddress === "string" && typeof value.holderDid === "string" && typeof value.hsmPassword === "string";
 }
@@ -22940,7 +23078,7 @@ function createFsAccountStore(filePath) {
       }
     },
     async set(account) {
-      await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(filePath), { recursive: true, mode: 448 });
+      await (0, import_promises2.mkdir)((0, import_node_path3.dirname)(filePath), { recursive: true, mode: 448 });
       await (0, import_promises2.writeFile)(filePath, JSON.stringify(account, null, 2), { encoding: "utf8", mode: 384 });
     }
   };
@@ -23052,19 +23190,17 @@ function buildToolList() {
     },
     {
       name: "create_holder_account",
-      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.",
+      description: "Create a new holder HSM account on Wallet BE (onboarding). 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. The wallet manages its own credentials; you neither need nor can supply any. 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" },
           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"]
+        }
       }
     }
   ];
@@ -23074,12 +23210,25 @@ function asPayRequest(accept) {
   return { ...accept, extra: { gasModel: "client", ...extra } };
 }
 async function main() {
-  const accountStore = createFsAccountStore((0, import_node_path3.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "account.json"));
+  const fileEnv = loadConfigFileEnv(process.argv, (p) => (0, import_node_fs.readFileSync)(p, "utf8"));
+  const stateDir = (process.env.ZETRIX_WALLET_STATE_DIR ?? fileEnv.ZETRIX_WALLET_STATE_DIR ?? (0, import_node_path4.join)((0, import_node_os2.homedir)(), ".agentic-wallet-mcp")).replace(/\/+$/, "");
+  const accountStore = createFsAccountStore((0, import_node_path4.join)(stateDir, "account.json"));
+  if (process.argv[2] === "export-credentials") {
+    const { exitCode } = await exportCredentials({
+      getAccount: () => accountStore.get(),
+      isTty: Boolean(process.stdout.isTTY),
+      write: (s) => process.stdout.write(s),
+      writeErr: (s) => process.stderr.write(s)
+    });
+    process.exit(exitCode);
+  }
   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 { env, passwordGenerated } = resolveStartupEnv({
+    processEnv: process.env,
+    storedAccount,
+    fileEnv,
+    generatePassword: generateHsmPassword
+  });
   const config2 = loadConfig(env);
   const hsmPassword = config2.hsmPassword;
   const be = new WalletBeClient(config2.walletBeUrl);
@@ -23096,8 +23245,9 @@ async function main() {
   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).
-`
+      `agentic-wallet-mcp: no ZETRIX_ADDRESS was set \u2014 created a new HSM account and saved it 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).` + (passwordGenerated ? ` An HSM password was generated for this account \u2014 you never need to enter it, but it is the ONLY thing that can authorize signing for this wallet. If this file is lost the account cannot be recovered. Back it up with: npx agentic-wallet-mcp export-credentials
+` : `
+`)
     );
   } else if (storedAccount && config2.zetrixAddress === storedAccount.zetrixAddress) {
     process.stderr.write(
@@ -23124,13 +23274,7 @@ 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 fetchNativeBalance = async (address) => {
-    const res = await sdk.account.getInfo(address);
-    if (res.errorCode !== 0) throw new Error(`getInfo failed with errorCode ${res.errorCode}`);
-    const balance = res.result?.balance;
-    if (typeof balance !== "string") throw new Error("getInfo returned no balance");
-    return balance;
-  };
+  const fetchNativeBalance = async (address) => parseNativeBalance(await sdk.account.getInfo(address));
   const tokenBalanceDeps = {
     address: zetrixAddress,
     fetchNativeBalance,
@@ -23141,13 +23285,14 @@ async function main() {
   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_path3.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "vc-cache", cacheScope));
+  const cacheScope = (0, import_node_crypto3.createHash)("sha256").update(`${config2.network}:${zetrixAddress}`).digest("hex");
+  const vcCache = createFsVcCache((0, import_node_path4.join)(config2.stateDir, "vc-cache", cacheScope));
   const pay = (accept) => {
     assertWithinPaymentCap(accept, config2.maxPaymentAmount);
     return payWithReadinessCheck(
       String(accept.asset ?? ""),
-      () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn)
+      () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn),
+      activated
     );
   };
   const payer = async (req) => {
@@ -23199,8 +23344,10 @@ async function main() {
     subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
     queryContract: (input) => queryContract(input, contractQuery),
     queryTokenBalance: queryTokenBalance2,
-    createAccount: (password, label, purpose) => be.createAccount(password, label, purpose),
-    saveAccount: (account) => accountStore.set({ ...account, createdAt: (/* @__PURE__ */ new Date()).toISOString() }),
+    // The session password is bound here, in the wiring, so it never crosses into the tool
+    // layer — create_holder_account has no password parameter for a model to be asked for.
+    createAccount: (label, purpose) => be.createAccount(hsmPassword, label, purpose),
+    saveAccount: (account) => accountStore.set({ ...account, hsmPassword, createdAt: (/* @__PURE__ */ new Date()).toISOString() }),
     checkActivationStatus: (address) => be.checkActivationStatus(address),
     sleep,
     cache: vcCache

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "agentic-wallet-mcp",
-  "version": "0.6.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",
-  "author": "MyEG Services Berhad",
-  "homepage": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet/issues"
-  },
-  "type": "module",
-  "engines": {
-    "node": ">=18"
-  },
-  "bin": {
-    "agentic-wallet-mcp": "dist/server-bundle.cjs"
-  },
-  "files": [
-    "dist/server-bundle.cjs",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc --noEmit && esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --external:zetrix-sdk-nodejs --outfile=dist/server-bundle.cjs",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "x401-zetrix-client": "^0.2.1",
-    "x402-zetrix-client": "^0.2.2",
-    "zetrix-sdk-nodejs": "^1.0.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "esbuild": "^0.24.0",
-    "typescript": "^5.9.0",
-    "vitest": "^1.6.0"
-  }
-}
+{
+  "name": "agentic-wallet-mcp",
+  "version": "0.7.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",
+  "author": "MyEG Services Berhad",
+  "homepage": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "agentic-wallet-mcp": "dist/server-bundle.cjs"
+  },
+  "files": [
+    "dist/server-bundle.cjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --external:zetrix-sdk-nodejs --outfile=dist/server-bundle.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "x401-zetrix-client": "^0.2.1",
+    "x402-zetrix-client": "^0.2.2",
+    "zetrix-sdk-nodejs": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.9.0",
+    "vitest": "^1.6.0"
+  }
+}