bsv-mcp 0.2.15 → 0.3.1

package/index.ts

@@ -1,23 +1,15 @@
 #!/usr/bin/env bun
 
-// Redirect console.log/warn/info/debug to stderr in stdio mode.
-// MCP stdio transport uses stdout exclusively for JSON-RPC messages —
-// any stray stdout output corrupts the protocol. Must run before any import.
-const _isStdio =
-	process.argv.includes("--stdio") ||
-	process.env.TRANSPORT?.toLowerCase() === "stdio";
-if (_isStdio) {
-	const _err = console.error.bind(console);
-	console.log = (...a: unknown[]) => _err("[log]", ...a);
-	console.warn = (...a: unknown[]) => _err("[warn]", ...a);
-	console.info = (...a: unknown[]) => _err("[info]", ...a);
-	console.debug = (...a: unknown[]) => _err("[debug]", ...a);
-}
+// Must stay the first import. The stdio transport owns stdout for JSON-RPC, so
+// the console redirect has to be installed before any other module initializes
+// and gets a chance to log. This was previously a statement block below the
+// imports, which cannot work: ES imports are evaluated before any top-level
+// statement, so every dependency had already initialized by the time it ran.
+import "./utils/stdioGuard";
 
 import { readFile } from "node:fs/promises";
 import os from "node:os";
-import path from "node:path";
-import { dirname, join } from "node:path";
+import path, { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { PrivateKey } from "@bsv/sdk";
 import {
@@ -27,6 +19,7 @@ import {
 } from "@modelcontextprotocol/ext-apps/server";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
 import packageJson from "./package.json";
 import { registerAllPrompts } from "./prompts/index.ts";
@@ -35,8 +28,11 @@ import { getBsvPriceWithCache } from "./tools/bsv/getPrice.ts";
 import { registerAllTools, type ToolsConfig } from "./tools/index.ts";
 import { IntegratedWallet } from "./tools/wallet/integratedWallet.ts";
 import { Wallet } from "./tools/wallet/wallet.ts";
-import { initWallet, destroyWallet } from "./utils/walletInit.ts";
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { DroplitClient, readDroplitSponsorConfig } from "./utils/droplit";
+import {
+	initializeKeysForWalletMode,
+	readExternalWalletConfig,
+} from "./utils/externalWalletConfig";
 import {
 	type BSVJWTPayload,
 	createMCPJWTValidator,
@@ -44,6 +40,12 @@ import {
 } from "./utils/jwtValidator.ts";
 import { SecureKeyManager } from "./utils/keyManager.ts";
 import { setServerInstance } from "./utils/passphrasePrompt.ts";
+import {
+	destroyWallet,
+	initExternalWallet,
+	initWallet,
+	setSpendingApprovalServerInstance,
+} from "./utils/walletInit.ts";
 
 // Initialize server variable (used for stdio mode and passphrase detection)
 let server: McpServer | undefined;
@@ -113,13 +115,13 @@ const CONFIG = {
 	// --stdio CLI flag takes precedence over TRANSPORT env var (matches neighborhood plugin pattern)
 	transportMode: process.argv.includes("--stdio")
 		? "stdio"
-		: (process.env.TRANSPORT?.toLowerCase() || "http"), // 'stdio' or 'http'/default
+		: process.env.TRANSPORT?.toLowerCase() || "http", // 'stdio' or 'http'/default
 	port: Number.parseInt(process.env.PORT || "3000", 10),
 
-	// --- Droplet API Configuration ---
-	useDropletApi: process.env.USE_DROPLET_API === "true",
-	dropletApiUrl: process.env.DROPLET_API_URL || "http://127.0.0.1:4000",
-	dropletFaucetName: process.env.DROPLET_FAUCET_NAME || "",
+	// --- Droplit API Configuration ---
+	useDroplitApi: process.env.USE_DROPLIT_API === "true",
+	droplitApiUrl: process.env.DROPLIT_API_URL || "http://127.0.0.1:4000",
+	droplitFaucetName: process.env.DROPLIT_FAUCET_NAME || "",
 
 	// --- OAuth Configuration ---
 	enableOAuth: process.env.ENABLE_OAUTH !== "false", // Enabled by default
@@ -279,7 +281,11 @@ async function initializeKeys(): Promise<{
 const APP_RESOURCE_URI = "ui://bsv-mcp/app.html";
 const __appDirname = dirname(fileURLToPath(import.meta.url));
 
-function registerMcpAppTools(server: McpServer, wallet?: Wallet, ctx?: import("@1sat/actions").OneSatContext) {
+function registerMcpAppTools(
+	server: McpServer,
+	wallet?: Wallet,
+	ctx?: import("@1sat/actions").OneSatContext,
+) {
 	// Primary dashboard tool — model calls this to open the UI
 	registerAppTool(
 		server,
@@ -333,8 +339,7 @@ function registerMcpAppTools(server: McpServer, wallet?: Wallet, ctx?: import("@
 					const res = await fetch(
 						`https://junglebus.gorillapool.io/v1/transaction/get/${txid}`,
 					);
-					if (!res.ok)
-						throw new Error(`Transaction not found: ${res.status}`);
+					if (!res.ok) throw new Error(`Transaction not found: ${res.status}`);
 					const jbData = (await res.json()) as Record<string, unknown>;
 
 					const { Transaction, Utils } = await import("@bsv/sdk");
@@ -491,7 +496,8 @@ function registerMcpAppTools(server: McpServer, wallet?: Wallet, ctx?: import("@
 						},
 					],
 					structuredContent: {
-						error: "No wallet configured. Set PRIVATE_KEY_WIF or generate keys.",
+						error:
+							"No wallet configured. Set PRIVATE_KEY_WIF or generate keys.",
 					},
 					_meta: { viewUUID: crypto.randomUUID() },
 				};
@@ -660,12 +666,410 @@ function registerMcpAppTools(server: McpServer, wallet?: Wallet, ctx?: import("@
 		},
 	);
 
+	// App-only: scan an address for categorized UTXOs (funding, ordinals, BSV-21 tokens)
+	registerAppTool(
+		server,
+		"app_sweep_scan",
+		{
+			title: "Sweep Scan",
+			description:
+				"App-only: scans a Bitcoin address for categorized UTXOs — funding, ordinals, and BSV-21 tokens.",
+			inputSchema: {
+				address: z.string().describe("Bitcoin address to scan"),
+			},
+			_meta: {
+				ui: { resourceUri: APP_RESOURCE_URI, visibility: ["app"] },
+			},
+		},
+		async (args) => {
+			const { address } = args as { address: string };
+			try {
+				const res = await fetch(
+					`https://ordinals.gorillapool.io/api/txos/address/${address}/unspent?limit=1000`,
+				);
+				if (!res.ok) throw new Error(`GorillaPool API error: ${res.status}`);
+				const utxos = (await res.json()) as Array<Record<string, unknown>>;
+
+				const funding: Array<{
+					outpoint: string;
+					satoshis: number;
+					lockingScript: string;
+				}> = [];
+				const ordinals: Array<{
+					outpoint: string;
+					satoshis: number;
+					lockingScript: string;
+				}> = [];
+				const bsv21Raw: Array<{
+					outpoint: string;
+					satoshis: number;
+					lockingScript: string;
+					tokenId: string;
+					amount: string;
+					sym?: string;
+					dec: number;
+				}> = [];
+
+				for (const utxo of utxos) {
+					const txid = utxo.txid as string;
+					const vout = utxo.vout as number;
+					const outpoint = `${txid}_${vout}`;
+					const satoshis = (utxo.satoshis as number) || 0;
+					const script = (utxo.script as string) || "";
+					const origin = utxo.origin as Record<string, unknown> | undefined;
+					const originData = origin?.data as
+						| Record<string, unknown>
+						| undefined;
+
+					const base = { outpoint, satoshis, lockingScript: script };
+
+					if (originData?.bsv21) {
+						const bsv21 = originData.bsv21 as Record<string, unknown>;
+						bsv21Raw.push({
+							...base,
+							tokenId: (bsv21.id as string) || "",
+							amount: (bsv21.amt as string) || "0",
+							sym: bsv21.sym as string | undefined,
+							dec: (bsv21.dec as number) ?? 0,
+						});
+					} else if (originData?.insc || origin?.outpoint) {
+						ordinals.push(base);
+					} else {
+						funding.push(base);
+					}
+				}
+
+				// Group BSV-21 tokens by tokenId
+				const tokenGroups = new Map<
+					string,
+					{
+						inputs: typeof bsv21Raw;
+						sym?: string;
+						dec: number;
+					}
+				>();
+				for (const item of bsv21Raw) {
+					let group = tokenGroups.get(item.tokenId);
+					if (!group) {
+						group = { inputs: [], sym: item.sym, dec: item.dec };
+						tokenGroups.set(item.tokenId, group);
+					}
+					group.inputs.push(item);
+				}
+
+				const bsv21Tokens: Array<{
+					tokenId: string;
+					symbol?: string;
+					decimals: number;
+					totalAmount: string;
+					inputs: typeof bsv21Raw;
+				}> = [];
+				for (const [tokenId, group] of tokenGroups) {
+					let total = BigInt(0);
+					for (const inp of group.inputs) {
+						total += BigInt(inp.amount);
+					}
+					bsv21Tokens.push({
+						tokenId,
+						symbol: group.sym,
+						decimals: group.dec,
+						totalAmount: total.toString(),
+						inputs: group.inputs,
+					});
+				}
+
+				const totalFundingSats = funding.reduce(
+					(sum, f) => sum + f.satoshis,
+					0,
+				);
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Scanned ${address}: ${funding.length} funding, ${ordinals.length} ordinals, ${bsv21Tokens.length} token types`,
+						},
+					],
+					structuredContent: {
+						address,
+						funding,
+						ordinals,
+						bsv21Tokens,
+						totalFundingSats,
+					},
+					_meta: { viewUUID: crypto.randomUUID() },
+				};
+			} catch (err) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+						},
+					],
+					structuredContent: { error: String(err) },
+					_meta: { viewUUID: crypto.randomUUID() },
+				};
+			}
+		},
+	);
+
+	// App-only: prepare unsigned sweep transaction for client-side signing
+	registerAppTool(
+		server,
+		"app_sweep_prepare",
+		{
+			title: "Sweep Prepare",
+			description:
+				"App-only: builds an unsigned sweep transaction. Returns BEEF hex and reference for client-side signing.",
+			inputSchema: {
+				sweepType: z
+					.enum(["bsv", "ordinals", "bsv21"])
+					.describe("Type of assets to sweep"),
+				inputs: z
+					.array(
+						z.object({
+							outpoint: z.string().describe("Outpoint (txid_vout)"),
+							satoshis: z.number().int().describe("Satoshis in output"),
+							lockingScript: z.string().describe("Locking script hex"),
+						}),
+					)
+					.describe("UTXOs to sweep"),
+			},
+			_meta: {
+				ui: { resourceUri: APP_RESOURCE_URI, visibility: ["app"] },
+			},
+		},
+		async (args) => {
+			const { sweepType, inputs } = args as {
+				sweepType: "bsv" | "ordinals" | "bsv21";
+				inputs: Array<{
+					outpoint: string;
+					satoshis: number;
+					lockingScript: string;
+				}>;
+			};
+
+			if (!ctx) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "BRC-100 wallet context not available",
+						},
+					],
+					structuredContent: { error: "No wallet context" },
+					_meta: { viewUUID: crypto.randomUUID() },
+				};
+			}
+
+			try {
+				if (!ctx.services) throw new Error("Services not available");
+				if (!inputs.length) throw new Error("No inputs provided");
+
+				// Fetch and merge BEEF for all input transactions
+				const txids = [...new Set(inputs.map((i) => i.outpoint.split("_")[0]))];
+				const firstBeef = await ctx.services.getBeefForTxid(txids[0]);
+				for (let i = 1; i < txids.length; i++) {
+					const additionalBeef = await ctx.services.getBeefForTxid(txids[i]);
+					firstBeef.mergeBeef(additionalBeef);
+				}
+
+				// Build input descriptors using SDK format (txid.vout)
+				const inputDescriptors = inputs.map((input) => {
+					const [txid, voutStr] = input.outpoint.split("_");
+					return {
+						outpoint: `${txid}.${Number(voutStr)}`,
+						inputDescription: `Sweep ${sweepType} input`,
+						unlockingScriptLength: 108,
+						sequenceNumber: 0xffffffff,
+					};
+				});
+
+				const inputTotal = inputs.reduce((sum, i) => sum + i.satoshis, 0);
+
+				const createResult = await ctx.wallet.createAction({
+					description: `Sweep ${inputTotal} sats (${sweepType})`,
+					inputBEEF: firstBeef.toBinary(),
+					inputs: inputDescriptors,
+					outputs: [],
+					options: {
+						signAndProcess: false,
+						...(sweepType !== "bsv" && {
+							randomizeOutputs: false,
+						}),
+					},
+				});
+
+				if ("error" in createResult && createResult.error) {
+					throw new Error(String(createResult.error));
+				}
+				if (!createResult.signableTransaction) {
+					throw new Error("No signable transaction returned");
+				}
+
+				// Map our inputs to their indices in the transaction
+				const { Transaction: TxClass, Utils: SdkUtils } = await import(
+					"@bsv/sdk"
+				);
+				const tx = TxClass.fromBEEF(createResult.signableTransaction.tx);
+				const ourOutpoints = new Set(
+					inputs.map((i) => {
+						const [txid, voutStr] = i.outpoint.split("_");
+						return `${txid}.${Number(voutStr)}`;
+					}),
+				);
+
+				const inputsToSign: Array<{
+					index: number;
+					outpoint: string;
+					satoshis: number;
+					lockingScript: string;
+				}> = [];
+				for (let idx = 0; idx < tx.inputs.length; idx++) {
+					const txInput = tx.inputs[idx];
+					const op = `${txInput.sourceTXID}.${txInput.sourceOutputIndex}`;
+					if (ourOutpoints.has(op)) {
+						const match = inputs.find((i) => {
+							const [t, v] = i.outpoint.split("_");
+							return `${t}.${Number(v)}` === op;
+						});
+						if (match) {
+							inputsToSign.push({
+								index: idx,
+								outpoint: match.outpoint,
+								satoshis: match.satoshis,
+								lockingScript: match.lockingScript,
+							});
+						}
+					}
+				}
+
+				const txHex = SdkUtils.toHex(createResult.signableTransaction.tx);
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Prepared ${sweepType} sweep: ${inputsToSign.length} inputs to sign`,
+						},
+					],
+					structuredContent: {
+						txHex,
+						reference: createResult.signableTransaction.reference,
+						inputsToSign,
+					},
+					_meta: { viewUUID: crypto.randomUUID() },
+				};
+			} catch (err) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+						},
+					],
+					structuredContent: { error: String(err) },
+					_meta: { viewUUID: crypto.randomUUID() },
+				};
+			}
+		},
+	);
+
+	// App-only: complete a sweep by broadcasting with client-signed spends
+	registerAppTool(
+		server,
+		"app_sweep_complete",
+		{
+			title: "Sweep Complete",
+			description:
+				"App-only: completes a sweep by broadcasting the transaction with client-signed unlocking scripts.",
+			inputSchema: {
+				reference: z
+					.string()
+					.describe("Opaque reference from app_sweep_prepare"),
+				spends: z
+					.record(
+						z.string(),
+						z.object({
+							unlockingScript: z
+								.string()
+								.describe("Signed unlocking script hex"),
+						}),
+					)
+					.describe("Map of input index to signed unlocking script"),
+			},
+			_meta: {
+				ui: { resourceUri: APP_RESOURCE_URI, visibility: ["app"] },
+			},
+		},
+		async (args) => {
+			const { reference, spends } = args as {
+				reference: string;
+				spends: Record<number, { unlockingScript: string }>;
+			};
+
+			if (!ctx) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "BRC-100 wallet context not available",
+						},
+					],
+					structuredContent: { error: "No wallet context" },
+					_meta: { viewUUID: crypto.randomUUID() },
+				};
+			}
+
+			try {
+				const signResult = await ctx.wallet.signAction({
+					reference,
+					spends,
+					options: { acceptDelayedBroadcast: false },
+				});
+
+				if ("error" in signResult) {
+					throw new Error(String(signResult.error));
+				}
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Sweep broadcast: ${signResult.txid}`,
+						},
+					],
+					structuredContent: {
+						txid: signResult.txid,
+						success: true,
+					},
+					_meta: { viewUUID: crypto.randomUUID() },
+				};
+			} catch (err) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+						},
+					],
+					structuredContent: { error: String(err) },
+					_meta: { viewUUID: crypto.randomUUID() },
+				};
+			}
+		},
+	);
+
 	// Register the HTML resource
 	registerAppResource(
 		server,
 		"BSV Dashboard",
 		APP_RESOURCE_URI,
-		{ description: "Interactive BSV dashboard with Explorer, Wallet, and Ordinals tabs" },
+		{
+			description:
+				"Interactive BSV dashboard with Explorer, Wallet, and Ordinals tabs",
+		},
 		async () => {
 			// When running from bundle (dist/index.js), app.html is a sibling.
 			// When running from source (index.ts), it's in dist/.
@@ -676,7 +1080,8 @@ function registerMcpAppTools(server: McpServer, wallet?: Wallet, ctx?: import("@
 			try {
 				html = await readFile(distPath, "utf-8");
 			} catch {
-				html = "<html><body><p>Dashboard not built. Run <code>bun run build:view</code> to enable it.</p></body></html>";
+				html =
+					"<html><body><p>Dashboard not built. Run <code>bun run build:view</code> to enable it.</p></body></html>";
 			}
 			return {
 				contents: [
@@ -708,6 +1113,8 @@ Options:
 Environment Variables:
   TRANSPORT           Transport mode: 'stdio' or 'http' (default: http)
   PORT               HTTP server port (default: 3000)
+  BRC100_WALLET_URL  Existing SDK HTTPWalletJSON signer RPC URL
+  BRC100_WALLET_ORIGINATOR  Signer permission origin (default: bsv-mcp.local)
   PRIVATE_KEY_WIF    Payment private key in WIF format
   DISABLE_TOOLS      Disable all tools (default: false)
   DISABLE_WALLET_TOOLS   Disable wallet tools (default: false)
@@ -718,7 +1125,7 @@ Environment Variables:
   DISABLE_BSOCIAL_TOOLS  Disable BSocial tools (default: false)
   ENABLE_A2B_TOOLS       Enable A2B tools (default: false)
   DISABLE_BROADCASTING   Disable transaction broadcasting (default: false)
-  USE_DROPLET_API        Use Droplet API for transactions (default: false)
+  USE_DROPLIT_API        Use Droplit API for transactions (default: false)
 
 Tool Categories:
   BSV Tools:      Price lookup, transaction decoding, validation
@@ -731,7 +1138,7 @@ Tool Categories:
 
 Authentication:
   - Most tools work without authentication
-  - Wallet operations require PRIVATE_KEY_WIF or generated keys
+  - Wallet operations use BRC100_WALLET_URL, PRIVATE_KEY_WIF or generated keys
   - BAP/A2B tools require identity keys (generated via bap_generate tool)
 		`);
 		process.exit(0);
@@ -743,7 +1150,25 @@ Authentication:
 	}
 
 	// --- Initialize Keys ---
-	const { payPk, identityPk, xprv, source: keySource } = await initializeKeys();
+	const externalWallet = readExternalWalletConfig();
+	const sponsorConfig = CONFIG.useDroplitApi
+		? undefined
+		: readDroplitSponsorConfig();
+	const keys = await initializeKeysForWalletMode(
+		externalWallet,
+		initializeKeys,
+	);
+	const {
+		payPk,
+		identityPk,
+		xprv,
+		source: keySource,
+	} = keys ?? {
+		payPk: undefined,
+		identityPk: undefined,
+		xprv: undefined,
+		source: "external",
+	};
 
 	// Define persistence based on source
 	const hasPersistentPayKey =
@@ -755,6 +1180,15 @@ Authentication:
 		(keySource === "file" || keySource === "env" || keySource === "encrypted");
 
 	const effectiveConfig = { ...CONFIG };
+	if (externalWallet) {
+		effectiveConfig.loadBapTools = false;
+		effectiveConfig.loadBsocialTools = false;
+		effectiveConfig.loadMneeTools = false;
+		effectiveConfig.loadA2bTools = false;
+		logFunc(
+			"External BRC-100 signer selected; local key loading and generation bypassed.",
+		);
+	}
 
 	// --- Configuration Logging ---
 	logFunc("\n--- BSV MCP Server Configuration ---");
@@ -770,10 +1204,10 @@ Authentication:
 		);
 	}
 	logFunc(
-		`  PRIVATE_KEY_WIF:      ${process.env.PRIVATE_KEY_WIF ? "Set (using env key)" : "Not Set (using file/generating)"}`,
+		`  PRIVATE_KEY_WIF:      ${externalWallet ? "Unused (external signer)" : process.env.PRIVATE_KEY_WIF ? "Set (using env key)" : "Not Set (using file/generating)"}`,
 	);
 	logFunc(
-		`  IDENTITY_KEY_WIF:     ${process.env.IDENTITY_KEY_WIF ? "Set (using env key)" : "Not Set (using file/generating)"}`,
+		`  IDENTITY_KEY_WIF:     ${externalWallet ? "Unused (external signer)" : process.env.IDENTITY_KEY_WIF ? "Set (using env key)" : "Not Set (using file/generating)"}`,
 	);
 	if (process.env.BSV_MCP_PASSPHRASE) {
 		logFunc("  BSV_MCP_PASSPHRASE:   \x1b[31mDEPRECATED - Remove this!\x1b[0m");
@@ -812,11 +1246,11 @@ Authentication:
 		`  DISABLE_BROADCASTING: ${process.env.DISABLE_BROADCASTING === "true" ? "Set (true)" : "Not Set/false"}`,
 	);
 	logFunc(
-		`  USE_DROPLET_API:      ${CONFIG.useDropletApi ? "Set (true)" : "Not Set/false"}`,
+		`  USE_DROPLIT_API:      ${CONFIG.useDroplitApi ? "Set (true)" : "Not Set/false"}`,
 	);
-	if (CONFIG.useDropletApi) {
-		logFunc(`  DROPLET_API_URL:      ${CONFIG.dropletApiUrl}`);
-		logFunc(`  DROPLET_FAUCET_NAME:  ${CONFIG.dropletFaucetName || "Not Set"}`);
+	if (CONFIG.useDroplitApi) {
+		logFunc(`  DROPLIT_API_URL:      ${CONFIG.droplitApiUrl}`);
+		logFunc(`  DROPLIT_FAUCET_NAME:  ${CONFIG.droplitFaucetName || "Not Set"}`);
 	}
 
 	logFunc("\nKey Source:");
@@ -870,11 +1304,11 @@ Authentication:
 			: "\x1b[31mDisabled\x1b[0m";
 
 		let payKeyNote = "";
-		if (!hasPersistentPayKey) {
+		if (!externalWallet && !hasPersistentPayKey) {
 			payKeyNote = " \x1b[33m(Using generated payPk)\x1b[0m";
 		}
 		let identityKeyNote = "";
-		if (!hasPersistentIdentityKey) {
+		if (!externalWallet && !hasPersistentIdentityKey) {
 			identityKeyNote = " \x1b[33m(Using generated identityPk)\x1b[0m";
 		}
 
@@ -910,28 +1344,36 @@ Authentication:
 	let remoteServices: import("@1sat/wallet-remote").OneSatServices | undefined;
 
 	if (CONFIG.loadTools) {
-		// Check if we should use Droplet API mode
-		if (CONFIG.useDropletApi && CONFIG.dropletFaucetName) {
-			// Initialize IntegratedWallet in Droplet mode
+		// Check if we should use Droplit API mode
+		if (externalWallet) {
+			const chain = process.env.BSV_CHAIN ?? "main";
+			if (chain !== "main" && chain !== "test")
+				throw new Error("BSV_CHAIN must be main or test");
+			const result = await initExternalWallet(externalWallet, chain);
+			remoteCtx = result.ctx;
+			remoteServices = result.services;
+			logFunc(`External BRC-100 signer ready. Identity: ${result.identityKey}`);
+		} else if (CONFIG.useDroplitApi && CONFIG.droplitFaucetName) {
+			// Initialize IntegratedWallet in Droplit mode
 			if (CONFIG.loadWalletTools) {
 				try {
 					integratedWallet = new IntegratedWallet({
-						useDropletApi: true,
-						dropletConfig: {
-							apiUrl: CONFIG.dropletApiUrl,
-							faucetName: CONFIG.dropletFaucetName,
+						useDroplitApi: true,
+						droplitConfig: {
+							apiUrl: CONFIG.droplitApiUrl,
+							faucetName: CONFIG.droplitFaucetName,
 						},
 						paymentKey: payPk,
 						identityKey: identityPk,
 					});
 					logFunc(
-						`\x1b[32mINFO: Droplet API mode initialized successfully (Faucet: ${CONFIG.dropletFaucetName}).\x1b[0m`,
+						`\x1b[32mINFO: Droplit API mode initialized successfully (Faucet: ${CONFIG.droplitFaucetName}).\x1b[0m`,
 					);
 					logFunc(
-						`\x1b[33mNOTE: Using Droplet API at ${CONFIG.dropletApiUrl}\x1b[0m`,
+						`\x1b[33mNOTE: Using Droplit API at ${CONFIG.droplitApiUrl}\x1b[0m`,
 					);
 					logFunc(
-						"\x1b[33mNOTE: Local keys are ignored in Droplet API mode\x1b[0m",
+						"\x1b[33mNOTE: Local keys are ignored in Droplit API mode\x1b[0m",
 					);
 					wallet = integratedWallet.getLocalWallet();
 
@@ -941,7 +1383,7 @@ Authentication:
 					effectiveConfig.loadBsocialTools = false;
 				} catch (e) {
 					logFunc(
-						`\x1b[31mERROR: Failed to initialize Droplet API mode: ${e instanceof Error ? e.message : String(e)}. Wallet-dependent tools will be unavailable.\x1b[0m`,
+						`\x1b[31mERROR: Failed to initialize Droplit API mode: ${e instanceof Error ? e.message : String(e)}. Wallet-dependent tools will be unavailable.\x1b[0m`,
 					);
 					integratedWallet = undefined;
 					effectiveConfig.loadWalletTools = false;
@@ -1006,6 +1448,16 @@ Authentication:
 		}
 	}
 
+	const droplitClient =
+		sponsorConfig && remoteCtx
+			? new DroplitClient({ ...sponsorConfig, wallet: remoteCtx.wallet })
+			: undefined;
+	if (sponsorConfig && CONFIG.loadTools && !remoteCtx) {
+		throw new Error(
+			"Configured Droplit sponsor requires an initialized BRC-100 wallet context",
+		);
+	}
+
 	// Build the shared tools config (used by server factory for each session)
 	const toolsConfig: ToolsConfig = CONFIG.loadTools
 		? {
@@ -1025,6 +1477,7 @@ Authentication:
 				disableBroadcasting: effectiveConfig.disableBroadcasting,
 				ctx: remoteCtx,
 				services: remoteServices,
+				droplitClient,
 			}
 		: {
 				enableBsvTools: false,
@@ -1058,6 +1511,7 @@ Authentication:
 		// Stdio: single server instance, single transport
 		server = createConfiguredServer(serverFactoryOpts);
 		setServerInstance(server);
+		setSpendingApprovalServerInstance(server);
 		const transport = new StdioServerTransport();
 		await server.connect(transport);
 		logFunc("BSV MCP Server running on stdio");
@@ -1080,7 +1534,9 @@ Authentication:
 			}
 		>();
 
-		logFunc(`Starting BSV MCP Server in Streamable HTTP mode on port ${port}...`);
+		logFunc(
+			`Starting BSV MCP Server in Streamable HTTP mode on port ${port}...`,
+		);
 		if (CONFIG.enableOAuth) {
 			logFunc(`OAuth 2.1 authentication enabled`);
 			logFunc(`  Issuer: ${CONFIG.oauthIssuer}`);
@@ -1096,8 +1552,7 @@ Authentication:
 			"Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
 			"Access-Control-Allow-Headers":
 				"Content-Type, Authorization, mcp-session-id, Last-Event-ID, mcp-protocol-version",
-			"Access-Control-Expose-Headers":
-				"mcp-session-id, mcp-protocol-version",
+			"Access-Control-Expose-Headers": "mcp-session-id, mcp-protocol-version",
 		} as const;
 
 		/**
@@ -1154,10 +1609,7 @@ Authentication:
 								"bsv:tokens",
 							],
 							response_types_supported: ["code"],
-							grant_types_supported: [
-								"authorization_code",
-								"refresh_token",
-							],
+							grant_types_supported: ["authorization_code", "refresh_token"],
 							token_endpoint_auth_methods_supported: ["none"],
 							code_challenge_methods_supported: ["S256"],
 						},
@@ -1203,7 +1655,9 @@ Authentication:
 				// --- MCP Streamable HTTP endpoint ---
 				if (url.pathname === "/mcp") {
 					// Validate OAuth
-					let authInfo: { token: string; clientId: string; scopes: string[] } | undefined;
+					let authInfo:
+						| { token: string; clientId: string; scopes: string[] }
+						| undefined;
 					try {
 						const userCtx = await validateAuth(req);
 						if (userCtx) {
@@ -1247,10 +1701,18 @@ Authentication:
 									error: { code: -32001, message: "Session not found" },
 									id: null,
 								}),
-								{ status: 404, headers: { "Content-Type": "application/json", ...corsHeaders } },
+								{
+									status: 404,
+									headers: {
+										"Content-Type": "application/json",
+										...corsHeaders,
+									},
+								},
 							);
 						}
-						const response = await session.transport.handleRequest(req, { authInfo });
+						const response = await session.transport.handleRequest(req, {
+							authInfo,
+						});
 						// Add CORS headers to transport response
 						for (const [k, v] of Object.entries(corsHeaders)) {
 							if (!response.headers.has(k)) response.headers.set(k, v);
@@ -1290,9 +1752,7 @@ Authentication:
 			},
 		});
 
-		logFunc(
-			`Bun server listening on http://localhost:${port}`,
-		);
+		logFunc(`Bun server listening on http://localhost:${port}`);
 		logFunc("  MCP Endpoint: /mcp (Streamable HTTP)");
 		logFunc("  OAuth Discovery: /.well-known/oauth-protected-resource");
 	}