@keyban/agent-wallet-mcp 0.2.0 → 0.2.2

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Keyban
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,117 @@
+# @keyban/agent-wallet-mcp
+
+Give an AI agent its own blockchain wallet: balances, USDC transfers and
+[x402](https://x402.org) payments, under a spending policy the agent cannot
+change.
+
+Registry name: `io.keyban.prod.mcp/agent-wallet`.
+
+The server runs locally over stdio, next to your MCP client. It holds one share
+of a FROST threshold key in your OS keyring; Keyban holds the other. No single
+side can move funds alone, and the model never sees either share or your API
+key.
+
+## You need a Keyban wallet first
+
+**This server drives a wallet Keyban provisions. It does not create one, and it
+has nothing to drive without one** — installing the package on its own gets you
+a server offering a single `setup_instructions` tool, which points back here. The
+threshold key is the reason: one share lives here, the other lives with us, so
+there is a Keyban side to every wallet by construction and no configuration can
+replace it.
+
+So the order is:
+
+1. **Get a Keyban account** at <https://keyban.io>.
+2. **Create an agent wallet** in the admin app. It provisions the wallet, its
+   API key, and a one-shot invite key that authorises this client as a signer.
+3. **Take the configuration it hands you** — either the environment block for
+   the table below, or a ready-to-install `.mcpb` bundle with the values already
+   in it.
+4. **Then** install, with those values in the environment.
+
+## Install
+
+Once you have the credentials from step 3:
+
+```bash
+npx -y @keyban/agent-wallet-mcp
+```
+
+With Claude Code:
+
+```bash
+claude mcp add agent-wallet \
+  -e KEYBAN_API_KEY=… \
+  -e KEYBAN_APP_ID=… \
+  -e KEYBAN_INVITE_KEY=0x… \
+  -e KEYBAN_WALLET_ADDRESS=0x… \
+  -e KEYBAN_NETWORK=… \
+  -- npx -y @keyban/agent-wallet-mcp
+```
+
+On first boot the server runs a key generation, keeps its share in your OS
+keyring, and registers itself on chain as a signer of that wallet using the
+invite key. That happens once per machine; the invite key is spent by it.
+
+## Configuration
+
+The five required values all come from step 2 — none of them is something you
+can pick yourself.
+
+| Variable | Required | What it is |
+|---|---|---|
+| `KEYBAN_API_KEY` | yes | API key of the application the wallet belongs to. Never exposed to the model. |
+| `KEYBAN_APP_ID` | yes | Identifier of the Keyban application. |
+| `KEYBAN_INVITE_KEY` | yes | One-shot ECDSA private key authorizing this client's first-boot registration as a signer. |
+| `KEYBAN_WALLET_ADDRESS` | yes | Address of the account this server drives. |
+| `KEYBAN_NETWORK` | yes | Network the wallet operates on, e.g. `base` or `xdc`. |
+| `KEYBAN_BASE_URL` | no | Backend base URL, or one of `dev`, `testing`, `staging`, `prod`, `sandbox`. Defaults to `https://api.prod.keyban.io`. |
+| `KEYBAN_DKG_BLOB` | no | Pre-generated signer share, base64 JSON. For runtimes with no OS keyring; it does not replace the invite key. |
+| `MCP_LOG_FILE` | no | Path the server writes its log to. |
+| `MCP_LOG_LEVEL` | no | `debug`, `info`, `warn` or `error`. Defaults to `info`. |
+
+## Tools
+
+Read-only:
+
+| Tool | What it does |
+|---|---|
+| `api_status` | Check Keyban API status |
+| `get_account_info` | Get wallet account info |
+| `balance` | Check wallet balance |
+| `list_expense_transactions` | List wallet transactions |
+| `expense_stats` | Get spending statistics |
+| `wait_for_intent` | Wait for approval decisions |
+| `x402_info` | Inspect the x402 price of a URL |
+| `discover_x402_services` | Search the x402 service directory |
+
+Writing:
+
+| Tool | What it does |
+|---|---|
+| `sign_message` | Sign a message |
+| `cancel_intent` | Cancel a pending payment intent |
+| `transfer_usdc` | Transfer USDC — moves funds |
+| `x402_pay` | Pay for an x402 resource — moves funds |
+
+Every tool carries a `title` and the applicable `readOnlyHint` or
+`destructiveHint`, so a client can tell the two groups apart before calling
+anything.
+
+## Spending policy
+
+Transfers and x402 payments are checked against the wallet's policy on the
+Keyban side. A call the policy will not clear on its own does not fail
+silently: it comes back naming a payment intent that needs a human decision.
+`wait_for_intent` blocks until the owner approves or declines, and the agent
+retries once it is approved. The policy lives with the wallet, not with this
+process, so editing this server's configuration cannot widen it.
+
+## Documentation
+
+<https://docs.keyban.io/>
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/index.mjs

@@ -79491,78 +79491,78 @@ ${errors.map((e) => `  - ${e.message}`).join("\n")}`;
         return 0;
       }
     };
-    var import_zod16 = require_zod();
+    var import_zod17 = require_zod();
     var import_zod22 = require_zod();
-    var NonEmptyString2 = import_zod16.z.string().min(1);
-    var Any2 = import_zod16.z.record(import_zod16.z.unknown());
-    var OptionalAny2 = import_zod16.z.record(import_zod16.z.unknown()).optional().nullable();
+    var NonEmptyString2 = import_zod17.z.string().min(1);
+    var Any2 = import_zod17.z.record(import_zod17.z.unknown());
+    var OptionalAny2 = import_zod17.z.record(import_zod17.z.unknown()).optional().nullable();
     var NetworkSchemaV12 = NonEmptyString2;
-    var NetworkSchemaV22 = import_zod16.z.string().min(3).refine((val) => val.includes(":"), {
+    var NetworkSchemaV22 = import_zod17.z.string().min(3).refine((val) => val.includes(":"), {
       message: "Network must be in CAIP-2 format (e.g., 'eip155:84532')"
     });
-    var NetworkSchema2 = import_zod16.z.union([NetworkSchemaV12, NetworkSchemaV22]);
-    var ResourceInfoSchema2 = import_zod16.z.object({
+    var NetworkSchema2 = import_zod17.z.union([NetworkSchemaV12, NetworkSchemaV22]);
+    var ResourceInfoSchema2 = import_zod17.z.object({
       url: NonEmptyString2,
-      description: import_zod16.z.string().optional(),
-      mimeType: import_zod16.z.string().optional()
+      description: import_zod17.z.string().optional(),
+      mimeType: import_zod17.z.string().optional()
     });
-    var PaymentRequirementsV1Schema2 = import_zod16.z.object({
+    var PaymentRequirementsV1Schema2 = import_zod17.z.object({
       scheme: NonEmptyString2,
       network: NetworkSchemaV12,
       maxAmountRequired: NonEmptyString2,
       resource: NonEmptyString2,
       // URL string in V1
-      description: import_zod16.z.string(),
-      mimeType: import_zod16.z.string().optional(),
+      description: import_zod17.z.string(),
+      mimeType: import_zod17.z.string().optional(),
       outputSchema: Any2.optional().nullable(),
       payTo: NonEmptyString2,
-      maxTimeoutSeconds: import_zod16.z.number().positive(),
+      maxTimeoutSeconds: import_zod17.z.number().positive(),
       asset: NonEmptyString2,
       extra: OptionalAny2
     });
-    var PaymentRequiredV1Schema2 = import_zod16.z.object({
-      x402Version: import_zod16.z.literal(1),
-      error: import_zod16.z.string().optional(),
-      accepts: import_zod16.z.array(PaymentRequirementsV1Schema2).min(1)
+    var PaymentRequiredV1Schema2 = import_zod17.z.object({
+      x402Version: import_zod17.z.literal(1),
+      error: import_zod17.z.string().optional(),
+      accepts: import_zod17.z.array(PaymentRequirementsV1Schema2).min(1)
     });
-    var PaymentPayloadV1Schema2 = import_zod16.z.object({
-      x402Version: import_zod16.z.literal(1),
+    var PaymentPayloadV1Schema2 = import_zod17.z.object({
+      x402Version: import_zod17.z.literal(1),
       scheme: NonEmptyString2,
       network: NetworkSchemaV12,
       payload: Any2
     });
-    var PaymentRequirementsV2Schema2 = import_zod16.z.object({
+    var PaymentRequirementsV2Schema2 = import_zod17.z.object({
       scheme: NonEmptyString2,
       network: NetworkSchemaV22,
       amount: NonEmptyString2,
       asset: NonEmptyString2,
       payTo: NonEmptyString2,
-      maxTimeoutSeconds: import_zod16.z.number().positive(),
+      maxTimeoutSeconds: import_zod17.z.number().positive(),
       extra: OptionalAny2
     });
-    var PaymentRequiredV2Schema2 = import_zod16.z.object({
-      x402Version: import_zod16.z.literal(2),
-      error: import_zod16.z.string().optional(),
+    var PaymentRequiredV2Schema2 = import_zod17.z.object({
+      x402Version: import_zod17.z.literal(2),
+      error: import_zod17.z.string().optional(),
       resource: ResourceInfoSchema2,
-      accepts: import_zod16.z.array(PaymentRequirementsV2Schema2).min(1),
+      accepts: import_zod17.z.array(PaymentRequirementsV2Schema2).min(1),
       extensions: OptionalAny2
     });
-    var PaymentPayloadV2Schema2 = import_zod16.z.object({
-      x402Version: import_zod16.z.literal(2),
+    var PaymentPayloadV2Schema2 = import_zod17.z.object({
+      x402Version: import_zod17.z.literal(2),
       resource: ResourceInfoSchema2.optional(),
       accepted: PaymentRequirementsV2Schema2,
       payload: Any2,
       extensions: OptionalAny2
     });
-    var PaymentRequirementsSchema2 = import_zod16.z.union([
+    var PaymentRequirementsSchema2 = import_zod17.z.union([
       PaymentRequirementsV1Schema2,
       PaymentRequirementsV2Schema2
     ]);
-    var PaymentRequiredSchema2 = import_zod16.z.discriminatedUnion("x402Version", [
+    var PaymentRequiredSchema2 = import_zod17.z.discriminatedUnion("x402Version", [
       PaymentRequiredV1Schema2,
       PaymentRequiredV2Schema2
     ]);
-    var PaymentPayloadSchema2 = import_zod16.z.discriminatedUnion("x402Version", [
+    var PaymentPayloadSchema2 = import_zod17.z.discriminatedUnion("x402Version", [
       PaymentPayloadV1Schema2,
       PaymentPayloadV2Schema2
     ]);
@@ -79977,78 +79977,78 @@ var require_schemas = __commonJS({
       z: () => import_zod22.z
     });
     module.exports = __toCommonJS2(schemas_exports2);
-    var import_zod16 = require_zod();
+    var import_zod17 = require_zod();
     var import_zod22 = require_zod();
-    var NonEmptyString2 = import_zod16.z.string().min(1);
-    var Any2 = import_zod16.z.record(import_zod16.z.unknown());
-    var OptionalAny2 = import_zod16.z.record(import_zod16.z.unknown()).optional().nullable();
+    var NonEmptyString2 = import_zod17.z.string().min(1);
+    var Any2 = import_zod17.z.record(import_zod17.z.unknown());
+    var OptionalAny2 = import_zod17.z.record(import_zod17.z.unknown()).optional().nullable();
     var NetworkSchemaV12 = NonEmptyString2;
-    var NetworkSchemaV22 = import_zod16.z.string().min(3).refine((val) => val.includes(":"), {
+    var NetworkSchemaV22 = import_zod17.z.string().min(3).refine((val) => val.includes(":"), {
       message: "Network must be in CAIP-2 format (e.g., 'eip155:84532')"
     });
-    var NetworkSchema2 = import_zod16.z.union([NetworkSchemaV12, NetworkSchemaV22]);
-    var ResourceInfoSchema2 = import_zod16.z.object({
+    var NetworkSchema2 = import_zod17.z.union([NetworkSchemaV12, NetworkSchemaV22]);
+    var ResourceInfoSchema2 = import_zod17.z.object({
       url: NonEmptyString2,
-      description: import_zod16.z.string().optional(),
-      mimeType: import_zod16.z.string().optional()
+      description: import_zod17.z.string().optional(),
+      mimeType: import_zod17.z.string().optional()
     });
-    var PaymentRequirementsV1Schema2 = import_zod16.z.object({
+    var PaymentRequirementsV1Schema2 = import_zod17.z.object({
       scheme: NonEmptyString2,
       network: NetworkSchemaV12,
       maxAmountRequired: NonEmptyString2,
       resource: NonEmptyString2,
       // URL string in V1
-      description: import_zod16.z.string(),
-      mimeType: import_zod16.z.string().optional(),
+      description: import_zod17.z.string(),
+      mimeType: import_zod17.z.string().optional(),
       outputSchema: Any2.optional().nullable(),
       payTo: NonEmptyString2,
-      maxTimeoutSeconds: import_zod16.z.number().positive(),
+      maxTimeoutSeconds: import_zod17.z.number().positive(),
       asset: NonEmptyString2,
       extra: OptionalAny2
     });
-    var PaymentRequiredV1Schema2 = import_zod16.z.object({
-      x402Version: import_zod16.z.literal(1),
-      error: import_zod16.z.string().optional(),
-      accepts: import_zod16.z.array(PaymentRequirementsV1Schema2).min(1)
+    var PaymentRequiredV1Schema2 = import_zod17.z.object({
+      x402Version: import_zod17.z.literal(1),
+      error: import_zod17.z.string().optional(),
+      accepts: import_zod17.z.array(PaymentRequirementsV1Schema2).min(1)
     });
-    var PaymentPayloadV1Schema2 = import_zod16.z.object({
-      x402Version: import_zod16.z.literal(1),
+    var PaymentPayloadV1Schema2 = import_zod17.z.object({
+      x402Version: import_zod17.z.literal(1),
       scheme: NonEmptyString2,
       network: NetworkSchemaV12,
       payload: Any2
     });
-    var PaymentRequirementsV2Schema2 = import_zod16.z.object({
+    var PaymentRequirementsV2Schema2 = import_zod17.z.object({
       scheme: NonEmptyString2,
       network: NetworkSchemaV22,
       amount: NonEmptyString2,
       asset: NonEmptyString2,
       payTo: NonEmptyString2,
-      maxTimeoutSeconds: import_zod16.z.number().positive(),
+      maxTimeoutSeconds: import_zod17.z.number().positive(),
       extra: OptionalAny2
     });
-    var PaymentRequiredV2Schema2 = import_zod16.z.object({
-      x402Version: import_zod16.z.literal(2),
-      error: import_zod16.z.string().optional(),
+    var PaymentRequiredV2Schema2 = import_zod17.z.object({
+      x402Version: import_zod17.z.literal(2),
+      error: import_zod17.z.string().optional(),
       resource: ResourceInfoSchema2,
-      accepts: import_zod16.z.array(PaymentRequirementsV2Schema2).min(1),
+      accepts: import_zod17.z.array(PaymentRequirementsV2Schema2).min(1),
       extensions: OptionalAny2
     });
-    var PaymentPayloadV2Schema2 = import_zod16.z.object({
-      x402Version: import_zod16.z.literal(2),
+    var PaymentPayloadV2Schema2 = import_zod17.z.object({
+      x402Version: import_zod17.z.literal(2),
       resource: ResourceInfoSchema2.optional(),
       accepted: PaymentRequirementsV2Schema2,
       payload: Any2,
       extensions: OptionalAny2
     });
-    var PaymentRequirementsSchema2 = import_zod16.z.union([
+    var PaymentRequirementsSchema2 = import_zod17.z.union([
       PaymentRequirementsV1Schema2,
       PaymentRequirementsV2Schema2
     ]);
-    var PaymentRequiredSchema2 = import_zod16.z.discriminatedUnion("x402Version", [
+    var PaymentRequiredSchema2 = import_zod17.z.discriminatedUnion("x402Version", [
       PaymentRequiredV1Schema2,
       PaymentRequiredV2Schema2
     ]);
-    var PaymentPayloadSchema2 = import_zod16.z.discriminatedUnion("x402Version", [
+    var PaymentPayloadSchema2 = import_zod17.z.discriminatedUnion("x402Version", [
       PaymentPayloadV1Schema2,
       PaymentPayloadV2Schema2
     ]);
@@ -111151,6 +111151,145 @@ function resolveURL(value) {
   return ENV_URLS[value] ?? value;
 }
 
+// src/lib/session.ts
+var VALID_NETWORKS = [
+  "EthereumAnvil",
+  "BaseSepolia",
+  "BaseMainnet",
+  "XdcApothem",
+  "XdcMainnet",
+  "StellarQuickstart",
+  "StellarTestnet",
+  "StellarMainnet"
+];
+function createSession() {
+  return {
+    baseURL: ENV_URLS.prod,
+    apiKey: "",
+    appId: "",
+    network: "",
+    inviteKey: "",
+    walletAddress: "",
+    seededDkgBlob: null,
+    nodeApi: null,
+    signer: null,
+    account: null,
+    frostVerifierAddress: null,
+    initPromise: null,
+    pendingX402: /* @__PURE__ */ new Map()
+  };
+}
+function validateNetwork(network) {
+  if (!network || !VALID_NETWORKS.includes(network)) {
+    throw new Error(`Invalid or missing network "${network}". Must be one of: ${VALID_NETWORKS.join(", ")}. Set it via the KEYBAN_NETWORK env var.`);
+  }
+}
+function requireCredentials(session) {
+  if (!session.apiKey) {
+    throw new Error("No API key configured. Set the KEYBAN_API_KEY environment variable.");
+  }
+  if (!session.appId) {
+    throw new Error("No application ID configured. Set the KEYBAN_APP_ID environment variable.");
+  }
+  if (!session.inviteKey) {
+    throw new Error(
+      "No invite key configured. Set the KEYBAN_INVITE_KEY environment variable (admin-provisioned wallets only)."
+    );
+  }
+  if (!session.walletAddress) {
+    throw new Error(
+      "No wallet address configured. Set the KEYBAN_WALLET_ADDRESS environment variable (admin-provisioned wallets only)."
+    );
+  }
+}
+function requireAccount(session) {
+  requireCredentials(session);
+  if (!session.account || !session.signer || !session.nodeApi || !session.frostVerifierAddress) {
+    throw new Error("Account not initialized. Call the initialize tool first.");
+  }
+}
+function buildApiKeyHeaders(session) {
+  return {
+    "X-Api-Key": session.apiKey
+  };
+}
+
+// src/lib/configuration.ts
+var HEX_64 = /^0x[a-fA-F0-9]{64}$/;
+var HEX_40 = /^0x[a-fA-F0-9]{40}$/;
+var REQUIRED_VARIABLES = [
+  {
+    name: "KEYBAN_API_KEY",
+    what: "API key of the application the wallet belongs to"
+  },
+  {
+    name: "KEYBAN_APP_ID",
+    what: "identifier of the Keyban application"
+  },
+  {
+    name: "KEYBAN_WALLET_ADDRESS",
+    what: "address of the account this server drives",
+    reject: (value) => HEX_40.test(value) ? null : "must be 0x followed by 40 hex characters"
+  },
+  {
+    name: "KEYBAN_INVITE_KEY",
+    what: "one-shot key authorizing this client as a signer, on first boot",
+    reject: (value) => HEX_64.test(value) ? null : "must be 0x followed by 64 hex characters"
+  },
+  {
+    name: "KEYBAN_NETWORK",
+    what: "network the wallet operates on",
+    reject: (value) => VALID_NETWORKS.includes(value) ? null : `must be one of: ${VALID_NETWORKS.join(", ")}`
+  }
+];
+function findConfigurationProblems(env = process.env) {
+  const problems = [];
+  for (const { name, what, reject } of REQUIRED_VARIABLES) {
+    const value = env[name];
+    if (!value) {
+      problems.push({ name, what, reason: "missing" });
+      continue;
+    }
+    const rejected = reject?.(value);
+    if (rejected) problems.push({ name, what, reason: rejected });
+  }
+  return problems;
+}
+var WIZARD_URL = "https://keyban.io";
+var README_URL = "https://www.npmjs.com/package/@keyban/agent-wallet-mcp";
+function describeConfigurationProblems(problems) {
+  const list = problems.map(
+    ({ name, what, reason }) => reason === "missing" ? `- ${name} \u2014 not set. It is the ${what}.` : `- ${name} \u2014 set, but ${reason}. It is the ${what}.`
+  ).join("\n");
+  return [
+    "This server drives a blockchain wallet that Keyban provisions. It cannot create",
+    "one, and it will not work until it is given the credentials of an existing one.",
+    "",
+    "What is wrong right now:",
+    "",
+    list,
+    "",
+    "These are not values to invent: the wallet is held by a threshold key whose other",
+    "share stays with Keyban, so every wallet has a Keyban side and no local",
+    "configuration can stand in for it.",
+    "",
+    "How to get them:",
+    "",
+    `1. Create a Keyban account at ${WIZARD_URL}`,
+    "2. Create an agent wallet in the admin app. It provisions the wallet, its API",
+    "   key, and a one-shot invite key that authorizes this client as a signer.",
+    "3. Copy the configuration it hands you \u2014 either the environment block, or a",
+    "   ready-to-install .mcpb bundle with the values already in it.",
+    "4. Restart this server with those values in its environment.",
+    "",
+    `The README covers the same ground: ${README_URL}`
+  ].join("\n");
+}
+function summarizeConfigurationProblems(problems) {
+  const names = problems.map((p) => p.name).join(", ");
+  return `Keyban agent wallet MCP server \u2014 NOT USABLE YET. It drives a wallet that Keyban provisions, and its configuration is incomplete: ${names}. None of the wallet tools are available until that is fixed. Tell the user to create an agent wallet at ${WIZARD_URL}, and call setup_instructions for the steps.`;
+}
+
 // src/lib/logger.ts
 import { appendFileSync } from "node:fs";
 var LOG_LEVELS = {
@@ -111227,69 +111366,6 @@ function createLogger(context, minLevel) {
 }
 var logger = createLogger("agent-wallet-mcp");
 
-// src/lib/session.ts
-var VALID_NETWORKS = [
-  "EthereumAnvil",
-  "BaseSepolia",
-  "BaseMainnet",
-  "XdcApothem",
-  "XdcMainnet",
-  "StellarQuickstart",
-  "StellarTestnet",
-  "StellarMainnet"
-];
-function createSession() {
-  return {
-    baseURL: ENV_URLS.prod,
-    apiKey: "",
-    appId: "",
-    network: "",
-    inviteKey: "",
-    walletAddress: "",
-    seededDkgBlob: null,
-    nodeApi: null,
-    signer: null,
-    account: null,
-    frostVerifierAddress: null,
-    initPromise: null,
-    pendingX402: /* @__PURE__ */ new Map()
-  };
-}
-function validateNetwork(network) {
-  if (!network || !VALID_NETWORKS.includes(network)) {
-    throw new Error(`Invalid or missing network "${network}". Must be one of: ${VALID_NETWORKS.join(", ")}. Set it via the KEYBAN_NETWORK env var.`);
-  }
-}
-function requireCredentials(session) {
-  if (!session.apiKey) {
-    throw new Error("No API key configured. Set the KEYBAN_API_KEY environment variable.");
-  }
-  if (!session.appId) {
-    throw new Error("No application ID configured. Set the KEYBAN_APP_ID environment variable.");
-  }
-  if (!session.inviteKey) {
-    throw new Error(
-      "No invite key configured. Set the KEYBAN_INVITE_KEY environment variable (admin-provisioned wallets only)."
-    );
-  }
-  if (!session.walletAddress) {
-    throw new Error(
-      "No wallet address configured. Set the KEYBAN_WALLET_ADDRESS environment variable (admin-provisioned wallets only)."
-    );
-  }
-}
-function requireAccount(session) {
-  requireCredentials(session);
-  if (!session.account || !session.signer || !session.nodeApi || !session.frostVerifierAddress) {
-    throw new Error("Account not initialized. Call the initialize tool first.");
-  }
-}
-function buildApiKeyHeaders(session) {
-  return {
-    "X-Api-Key": session.apiKey
-  };
-}
-
 // src/lib/tool-registry.ts
 function registerTool(server, tool) {
   server.registerTool(
@@ -124422,6 +124498,20 @@ function createListExpenseTransactionsTool(session) {
   };
 }
 
+// src/tools/setup-instructions.ts
+var setupInstructionsSchema = external_exports.object({});
+function createSetupInstructionsTool(problems) {
+  const names = problems.map((p) => p.name).join(", ");
+  return {
+    name: "setup_instructions",
+    title: "How to finish setting up this wallet",
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    description: `This Keyban agent wallet has no wallet to drive yet, so none of its usual tools are available. Incomplete configuration: ${names}. Call this tool for the steps to obtain those values from keyban.io.`,
+    inputSchema: setupInstructionsSchema,
+    handler: async (_input) => describeConfigurationProblems(problems)
+  };
+}
+
 // src/index.ts
 var SERVER_NAME = "agent-wallet-mcp";
 var SERVER_VERSION = "0.0.0";
@@ -124436,27 +124526,16 @@ async function main() {
     if (process.env.KEYBAN_NETWORK) session.network = process.env.KEYBAN_NETWORK;
     logger.info("API key configured from environment");
   }
-  const envInviteKey = process.env.KEYBAN_INVITE_KEY;
-  const envWalletAddress = process.env.KEYBAN_WALLET_ADDRESS;
-  if (!envInviteKey) {
-    throw new Error(
-      "KEYBAN_INVITE_KEY is required (one-shot ECDSA private key, 0x + 64 hex)."
-    );
-  }
-  if (!envWalletAddress) {
-    throw new Error(
-      "KEYBAN_WALLET_ADDRESS is required (deployed SchnorrAccount address, 0x + 40 hex)."
-    );
-  }
-  if (!/^0x[a-fA-F0-9]{64}$/.test(envInviteKey)) {
-    throw new Error("KEYBAN_INVITE_KEY must be 0x followed by 64 hex characters.");
-  }
-  if (!/^0x[a-fA-F0-9]{40}$/.test(envWalletAddress)) {
-    throw new Error("KEYBAN_WALLET_ADDRESS must be 0x followed by 40 hex characters.");
+  const configurationProblems = findConfigurationProblems();
+  const unconfigured = configurationProblems.length > 0;
+  if (unconfigured) {
+    const summary = configurationProblems.map((p) => `${p.name} (${p.reason})`).join(", ");
+    logger.warn(`Incomplete configuration: ${summary}`);
+  } else {
+    session.inviteKey = process.env.KEYBAN_INVITE_KEY ?? "";
+    session.walletAddress = process.env.KEYBAN_WALLET_ADDRESS ?? "";
+    logger.info("Agent-wallet credentials configured");
   }
-  session.inviteKey = envInviteKey;
-  session.walletAddress = envWalletAddress;
-  logger.info("Agent-wallet credentials configured");
   const envDkgBlob = process.env.KEYBAN_DKG_BLOB;
   if (envDkgBlob) {
     try {
@@ -124478,10 +124557,10 @@ async function main() {
       version: SERVER_VERSION
     },
     {
-      instructions: "Keyban agent wallet MCP server. Provides tools to manage blockchain wallets: check balances, transfer USDC, sign messages, fetch x402 payment metadata and x402 payment.."
+      instructions: unconfigured ? summarizeConfigurationProblems(configurationProblems) : "Keyban agent wallet MCP server. Provides tools to manage blockchain wallets: check balances, transfer USDC, sign messages, fetch x402 payment metadata and x402 payment.."
     }
   );
-  const tools = [
+  const tools = unconfigured ? [createSetupInstructionsTool(configurationProblems)] : [
     createGetAccountInfoTool(session),
     createApiStatusTool(session),
     createSignMessageTool(session),