@xlmtools/cli 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# @xlmtools/cli
+
+XLMTools CLI — the MCP server that runs locally on the user's machine. Handles tool registration, payment signing, budget tracking, and response caching.
+
+## How it works
+
+This package is an MCP stdio server. It's started automatically by Claude, Cursor, or any MCP-compatible host when a user calls a XLMTools tool.
+
+```
+MCP Host (Claude, Cursor, Windsurf)
+    |  stdio
+    v
+@xlmtools/cli (this package)
+    |  - 21 tools registered via @modelcontextprotocol/sdk
+    |  - mppx polyfills fetch to auto-handle 402 payments
+    |  - budget enforcement (withBudget)
+    |  - response caching (withCache, 5-min TTL)
+    |
+    |  HTTPS
+    v
+@xlmtools/api (hosted API server)
+```
+
+## Install (for users)
+
+```bash
+claude mcp add xlmtools npx @xlmtools/cli
+```
+
+On first run, the CLI:
+1. Generates a Stellar keypair at `~/.xlmtools/config.json`
+2. Funds the wallet with testnet XLM via friendbot (testnet only)
+3. Adds a USDC trustline so the wallet can receive payments
+
+## Development
+
+```bash
+# From the monorepo root
+pnpm dev:cli
+
+# Or directly
+cd packages/cli
+pnpm dev
+```
+
+The dev script uses `tsx watch` for hot-reload during development.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Compiles TypeScript to `dist/`. The compiled entry point is `dist/index.js`.
+
+## Architecture
+
+### Tools (21 total)
+
+**Paid** (7) — wrapped with `withCache` + `withBudget`:
+search, research, youtube, screenshot, scrape, image, stocks
+
+**Free** (14):
+crypto, weather, domain, wallet, tools, budget, dex-orderbook, dex-candles, dex-trades, swap-quote, stellar-asset, stellar-account, stellar-pools, oracle-price
+
+### Key modules
+
+| File | Purpose |
+| --- | --- |
+| `src/index.ts` | Entry point, registers all 21 tools |
+| `src/lib/wallet.ts` | Wallet creation, auto-funding on testnet |
+| `src/lib/budget.ts` | Session budget state, `withBudget()` wrapper |
+| `src/lib/cache.ts` | Response cache, `withCache()` wrapper |
+| `src/lib/format.ts` | `ok()`, `okPaid()`, `err()` response formatters |
+| `src/lib/config.ts` | Tool prices and free tool list |
+| `src/lib/logger.ts` | pino logger (stderr) |
+| `src/tools/*.ts` | One file per tool |
+
+### Payment flow
+
+1. Tool handler calls `fetch(apiUrl/toolname)` with params
+2. API returns `402 Payment Required`
+3. mppx (global fetch polyfill) intercepts the 402
+4. Builds a Soroban SAC USDC transfer using the local Stellar keypair
+5. Signs and retries the request with payment proof
+6. API verifies, executes the tool, returns result with receipt
+7. `okPaid()` strips the receipt and appends a human-readable payment footer
+
+### Budget flow
+
+```
+withCache(tool, params, () =>
+  withBudget(tool, async () => {
+    // API call
+  })
+)
+```
+
+Cache is checked first (hit = free). Budget is checked second (over limit = blocked). API call happens last. Only successful calls are charged and cached.

package/dist/cli.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+import { Mppx } from "mppx/client";
+import { stellar } from "@stellar/mpp/charge/client";
+import { Horizon } from "@stellar/stellar-sdk";
+import { loadOrCreateWallet, getKeypair } from "./lib/wallet.js";
+import { TOOL_PRICES } from "./lib/config.js";
+import { logger } from "./lib/logger.js";
+// ── Arg parsing ──────────────────────────────────────────
+function parseArgs(argv) {
+    const [tool, ...rest] = argv;
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i].startsWith("--") && i + 1 < rest.length) {
+            const key = rest[i].slice(2).replace(/-/g, "_");
+            flags[key] = rest[i + 1];
+            i++;
+        }
+        else {
+            positional.push(rest[i]);
+        }
+    }
+    return { tool: tool ?? "", positional, flags };
+}
+// ── URL builder ──────────────────────────────────────────
+function buildRequest(base, tool, pos, flags) {
+    const p = new URLSearchParams();
+    // Map each tool to its API endpoint + params
+    const toolMap = {
+        search: () => { p.set("q", pos[0] ?? ""); if (flags.count)
+            p.set("count", flags.count); return { path: "/search" }; },
+        research: () => { p.set("q", pos[0] ?? ""); if (flags.num_results)
+            p.set("num_results", flags.num_results); return { path: "/research" }; },
+        youtube: () => { if (flags.id)
+            p.set("id", flags.id);
+        else
+            p.set("q", pos[0] ?? flags.query ?? ""); return { path: "/youtube" }; },
+        screenshot: () => { p.set("url", pos[0] ?? ""); if (flags.format)
+            p.set("format", flags.format); return { path: "/screenshot" }; },
+        scrape: () => { p.set("url", pos[0] ?? ""); return { path: "/scrape" }; },
+        image: () => ({ path: "/image", method: "POST", body: JSON.stringify({ prompt: pos[0] ?? "", size: flags.size ?? "1024x1024" }) }),
+        stocks: () => { p.set("symbol", pos[0] ?? ""); return { path: "/stocks" }; },
+        crypto: () => { p.set("ids", pos[0] ?? ""); if (flags.vs_currency)
+            p.set("vs_currency", flags.vs_currency); return { path: "/crypto" }; },
+        weather: () => { p.set("location", pos[0] ?? ""); return { path: "/weather" }; },
+        domain: () => { p.set("name", pos[0] ?? ""); return { path: "/domain" }; },
+        "dex-orderbook": () => { p.set("pair", pos[0] ?? ""); if (flags.limit)
+            p.set("limit", flags.limit); return { path: "/dex-orderbook" }; },
+        "dex-candles": () => { p.set("pair", pos[0] ?? ""); if (flags.resolution)
+            p.set("resolution", flags.resolution); if (flags.limit)
+            p.set("limit", flags.limit); return { path: "/dex-candles" }; },
+        "dex-trades": () => { p.set("pair", pos[0] ?? ""); if (flags.limit)
+            p.set("limit", flags.limit); if (flags.trade_type)
+            p.set("trade_type", flags.trade_type); return { path: "/dex-trades" }; },
+        "swap-quote": () => { p.set("from", pos[0] ?? flags.from ?? ""); p.set("to", pos[1] ?? flags.to ?? ""); p.set("amount", pos[2] ?? flags.amount ?? ""); if (flags.mode)
+            p.set("mode", flags.mode); return { path: "/swap-quote" }; },
+        "stellar-asset": () => { p.set("asset", pos[0] ?? ""); return { path: "/stellar-asset" }; },
+        "stellar-account": () => { p.set("address", pos[0] ?? ""); return { path: "/stellar-account" }; },
+        "stellar-pools": () => { if (pos[0] || flags.asset)
+            p.set("asset", pos[0] ?? flags.asset ?? ""); if (flags.limit)
+            p.set("limit", flags.limit); return { path: "/stellar-pools" }; },
+        "oracle-price": () => { p.set("asset", pos[0] ?? ""); if (flags.feed)
+            p.set("feed", flags.feed); return { path: "/oracle-price" }; },
+    };
+    const builder = toolMap[tool];
+    if (!builder) {
+        process.stderr.write(`Unknown tool: ${tool}\nRun xlm --help for available tools.\n`);
+        process.exit(1);
+    }
+    const { path, method, body } = builder();
+    const qs = p.toString();
+    const url = qs ? `${base}${path}?${qs}` : `${base}${path}`;
+    const init = { method: method ?? "GET" };
+    if (body) {
+        init.headers = { "Content-Type": "application/json" };
+        init.body = body;
+    }
+    return { url, init };
+}
+// ── Local tool handlers ──────────────────────────────────
+async function handleWallet(publicKey) {
+    const server = new Horizon.Server("https://horizon-testnet.stellar.org");
+    try {
+        const account = await server.loadAccount(publicKey);
+        const xlm = account.balances.find((b) => b.asset_type === "native");
+        const usdc = account.balances.find((b) => "asset_code" in b && b.asset_code === "USDC");
+        return {
+            address: publicKey,
+            network: "stellar:testnet",
+            xlm_balance: xlm?.balance ?? "0",
+            usdc_balance: usdc && "balance" in usdc ? usdc.balance : "0",
+        };
+    }
+    catch {
+        return {
+            address: publicKey,
+            network: "stellar:testnet",
+            xlm_balance: "0",
+            usdc_balance: "0",
+            note: "Account not funded yet",
+        };
+    }
+}
+function handleTools() {
+    const paid = Object.entries(TOOL_PRICES).map(([name, price]) => ({
+        name,
+        price: `$${price}`,
+    }));
+    const free = [
+        "crypto", "weather", "domain", "wallet", "tools", "budget",
+        "dex-orderbook", "dex-candles", "dex-trades", "swap-quote",
+        "stellar-asset", "stellar-account", "stellar-pools", "oracle-price",
+    ];
+    return { paid, free, network: "stellar:testnet", payment: "MPP / USDC" };
+}
+// ── Help text ────────────────────────────────────────────
+const HELP = `XLMTools CLI — Stellar-native tools with pay-per-call
+
+Usage: xlm <tool> [args] [--flag value]
+
+Paid tools ($0.001-$0.04 USDC via Stellar MPP):
+  search <query> [--count N]            Web search
+  research <query> [--num-results N]    Deep research
+  youtube <query> | --id <id>           YouTube search/lookup
+  screenshot <url> [--format png]       Capture URL screenshot
+  scrape <url>                          Extract text from URL
+  image <prompt> [--size 1024x1024]     AI image generation
+  stocks <symbol>                       Stock quotes
+
+Free tools:
+  crypto <ids> [--vs-currency usd]      Crypto prices
+  weather <location>                    Current weather
+  domain <name>                         Domain availability
+  dex-orderbook <pair> [--limit N]      Stellar DEX orderbook
+  dex-candles <pair>                    OHLCV candlesticks
+  dex-trades <pair>                     Recent DEX trades
+  swap-quote <from> <to> <amount>       DEX swap pathfinding
+  stellar-asset <asset>                 Asset info
+  stellar-account <address>             Account lookup
+  stellar-pools [--asset X]             Liquidity pools
+  oracle-price <asset> [--feed crypto]  Oracle prices
+  wallet                                Your Stellar wallet
+  tools                                 List all tools
+
+Examples:
+  xlm search "Stellar MPP micropayments"
+  xlm crypto bitcoin,ethereum,stellar
+  xlm weather Lagos
+  xlm stocks AAPL
+  xlm dex-orderbook XLM/USDC --limit 5
+  xlm wallet
+`;
+// ── Main ─────────────────────────────────────────────────
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        process.stdout.write(HELP);
+        return;
+    }
+    const { tool, positional, flags } = parseArgs(args);
+    // Init wallet + mppx (payment handling)
+    const config = loadOrCreateWallet();
+    const keypair = getKeypair(config);
+    Mppx.create({
+        methods: [
+            stellar.charge({
+                keypair,
+                mode: "pull",
+                onProgress(event) {
+                    logger.debug({ eventType: event.type }, "MPP payment event");
+                },
+            }),
+        ],
+    });
+    // ── Local tools (no API call needed) ──
+    if (tool === "wallet") {
+        const data = await handleWallet(config.stellarPublicKey);
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    if (tool === "tools") {
+        console.log(JSON.stringify(handleTools(), null, 2));
+        return;
+    }
+    // ── API tools ──
+    const isPaid = tool in TOOL_PRICES;
+    const { url, init } = buildRequest(config.apiUrl, tool, positional, flags);
+    if (isPaid) {
+        process.stderr.write(`  Tool: ${tool} · Cost: $${TOOL_PRICES[tool]} USDC\n`);
+    }
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        const text = await res.text();
+        process.stderr.write(`Error ${res.status}: ${text}\n`);
+        process.exit(1);
+    }
+    const data = (await res.json());
+    // Print receipt footer for paid tools
+    if (isPaid && data.receipt) {
+        const { receipt, ...rest } = data;
+        const r = receipt;
+        console.log(JSON.stringify(rest, null, 2));
+        const hash = r.tx_hash.length > 16 ? r.tx_hash.slice(0, 16) + "..." : r.tx_hash;
+        const network = r.network === "stellar:testnet" ? "stellar testnet" : r.network;
+        process.stderr.write(`\n  Payment: $${r.amount} ${r.currency} · tx/${hash} · ${network}\n`);
+    }
+    else {
+        console.log(JSON.stringify(data, null, 2));
+    }
+}
+main().catch((e) => {
+    logger.error({ err: e }, "CLI fatal error");
+    process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Mppx } from "mppx/client";
+import { stellar } from "@stellar/mpp/charge/client";
+import { loadOrCreateWallet, getKeypair } from "./lib/wallet.js";
+import { logger } from "./lib/logger.js";
+import { registerCryptoTool } from "./tools/crypto.js";
+import { registerWeatherTool } from "./tools/weather.js";
+import { registerDomainTool } from "./tools/domain.js";
+import { registerToolsListTool } from "./tools/tools-list.js";
+import { registerWalletTool } from "./tools/wallet-tool.js";
+import { registerSearchTool } from "./tools/search.js";
+import { registerResearchTool } from "./tools/research.js";
+import { registerYoutubeTool } from "./tools/youtube.js";
+import { registerScreenshotTool } from "./tools/screenshot.js";
+import { registerScrapeTool } from "./tools/scrape.js";
+import { registerImageTool } from "./tools/image.js";
+import { registerStocksTool } from "./tools/stocks.js";
+import { registerDexOrderbookTool } from "./tools/dex-orderbook.js";
+import { registerDexCandlesTool } from "./tools/dex-candles.js";
+import { registerDexTradesTool } from "./tools/dex-trades.js";
+import { registerSwapQuoteTool } from "./tools/swap-quote.js";
+import { registerStellarAssetTool } from "./tools/stellar-asset.js";
+import { registerStellarAccountTool } from "./tools/stellar-account.js";
+import { registerStellarPoolsTool } from "./tools/stellar-pools.js";
+import { registerOraclePriceTool } from "./tools/oracle-price.js";
+import { registerBudgetTool } from "./tools/budget.js";
+const config = loadOrCreateWallet();
+const keypair = getKeypair(config);
+// Mppx polyfills global fetch to auto-handle 402 payments
+Mppx.create({
+    methods: [
+        stellar.charge({
+            keypair,
+            mode: "pull",
+            onProgress(event) {
+                logger.debug({ eventType: event.type }, "MPP payment event");
+            },
+        }),
+    ],
+});
+// { logging: {} } enables ctx.mcpReq.log() in tool handlers
+const server = new McpServer({ name: "xlmtools", version: "0.1.0" }, { capabilities: { tools: {}, logging: {} } });
+// Free tools
+registerCryptoTool(server);
+registerWeatherTool(server);
+registerDomainTool(server);
+registerToolsListTool(server);
+registerWalletTool(server);
+registerBudgetTool(server);
+// Paid tools
+registerSearchTool(server);
+registerResearchTool(server);
+registerYoutubeTool(server);
+registerScreenshotTool(server);
+registerScrapeTool(server);
+registerImageTool(server);
+registerStocksTool(server);
+// Stellar-native tools (free)
+registerDexOrderbookTool(server);
+registerDexCandlesTool(server);
+registerDexTradesTool(server);
+registerSwapQuoteTool(server);
+registerStellarAssetTool(server);
+registerStellarAccountTool(server);
+registerStellarPoolsTool(server);
+registerOraclePriceTool(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("XLMTools MCP server running");
+}
+main().catch((error) => {
+    logger.error({ err: error }, "Fatal error");
+    process.exit(1);
+});

package/dist/lib/budget.js

@@ -0,0 +1,54 @@
+import { err } from "./format.js";
+import { TOOL_PRICES } from "./config.js";
+import { logger } from "./logger.js";
+// Session-scoped budget state (resets on MCP server restart)
+let maxBudget = null;
+let totalSpent = 0;
+export function setBudget(max) {
+    maxBudget = max;
+    logger.info({ max }, "session budget set");
+}
+export function clearBudget() {
+    maxBudget = null;
+    totalSpent = 0;
+    logger.info("session budget cleared");
+}
+export function getStatus() {
+    return {
+        max: maxBudget,
+        spent: Math.round(totalSpent * 1000) / 1000,
+        remaining: maxBudget !== null
+            ? Math.round((maxBudget - totalSpent) * 1000) / 1000
+            : null,
+    };
+}
+function canSpend(amount) {
+    if (maxBudget === null)
+        return true;
+    // Round to 3 decimal places to avoid floating-point drift
+    const spent = Math.round(totalSpent * 1000) / 1000;
+    return spent + amount <= maxBudget;
+}
+function recordSpend(amount) {
+    totalSpent += amount;
+    logger.debug({ amount, totalSpent }, "spend recorded");
+}
+/**
+ * Wrap a paid tool call with budget checking.
+ * If budget would be exceeded, returns an error without calling the API.
+ * On success, records the spend.
+ */
+export async function withBudget(toolName, fn) {
+    const price = parseFloat(TOOL_PRICES[toolName] ?? "0");
+    if (!canSpend(price)) {
+        const status = getStatus();
+        return err(`Budget limit reached. This call costs $${TOOL_PRICES[toolName]} ` +
+            `but only $${status.remaining?.toFixed(3)} remains. ` +
+            `Use the budget tool to check or adjust your limit.`);
+    }
+    const result = await fn();
+    if (!result.isError) {
+        recordSpend(price);
+    }
+    return result;
+}

package/dist/lib/cache.js

@@ -0,0 +1,41 @@
+import { logger } from "./logger.js";
+const TTL_MS = 5 * 60 * 1000; // 5 minutes
+const store = new Map();
+/**
+ * Wrap a tool call with response caching.
+ * Identical tool+params within the TTL return the cached result
+ * with no API call and no payment.
+ */
+export async function withCache(toolName, params, fn) {
+    const key = `${toolName}:${JSON.stringify(params)}`;
+    const cached = store.get(key);
+    if (cached && Date.now() < cached.expires) {
+        logger.debug({ toolName }, "cache hit");
+        const original = cached.result;
+        if (original.content[0]?.type === "text") {
+            return {
+                ...original,
+                content: [
+                    {
+                        type: "text",
+                        text: `[cached — no charge]\n\n${original.content[0].text}`,
+                    },
+                ],
+            };
+        }
+        return original;
+    }
+    const result = await fn();
+    if (!result.isError) {
+        store.set(key, { result, expires: Date.now() + TTL_MS });
+    }
+    // Evict expired entries periodically
+    if (store.size > 50) {
+        const now = Date.now();
+        for (const [k, v] of store) {
+            if (now >= v.expires)
+                store.delete(k);
+        }
+    }
+    return result;
+}

package/dist/lib/config.js

@@ -0,0 +1,16 @@
+export const TOOL_PRICES = {
+    search: "0.003",
+    research: "0.010",
+    youtube: "0.002",
+    screenshot: "0.010",
+    scrape: "0.002",
+    image: "0.040",
+    stocks: "0.001",
+};
+export const FREE_TOOLS = new Set([
+    "crypto", "weather", "domain", "wallet", "tools",
+    // Stellar-native tools (free — Horizon + StellarExpert + Reflector are public APIs)
+    "dex-orderbook", "dex-candles", "dex-trades",
+    "swap-quote", "stellar-asset", "stellar-account",
+    "stellar-pools", "oracle-price",
+]);

package/dist/lib/format.js

@@ -0,0 +1,37 @@
+function formatReceipt(receipt) {
+    const hashShort = receipt.tx_hash.length > 12
+        ? receipt.tx_hash.slice(0, 12) + "..."
+        : receipt.tx_hash;
+    const network = receipt.network === "stellar:testnet" ? "stellar testnet" : receipt.network;
+    return `\n---\nPayment: $${receipt.amount} ${receipt.currency} \u00b7 tx/${hashShort} \u00b7 ${network}`;
+}
+export function ok(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        isError: false,
+    };
+}
+/**
+ * Format a paid tool response, appending a receipt line if present.
+ * Strips the receipt from the data to avoid cluttering the JSON output,
+ * then appends a human-readable payment line.
+ */
+export function okPaid(data) {
+    const receipt = data.receipt;
+    if (!receipt) {
+        return ok(data);
+    }
+    // Strip receipt from the JSON data — show it as a footer instead
+    const { receipt: _, ...rest } = data;
+    const text = JSON.stringify(rest, null, 2) + formatReceipt(receipt);
+    return {
+        content: [{ type: "text", text }],
+        isError: false,
+    };
+}
+export function err(message) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}

package/dist/lib/logger.js

@@ -0,0 +1,2 @@
+import pino from "pino";
+export const logger = pino({ name: "xlmtools", level: process.env.LOG_LEVEL ?? "info" }, pino.destination(2));

package/dist/lib/wallet.js

@@ -0,0 +1,106 @@
+import { Keypair, Horizon, TransactionBuilder, Networks, Operation, Asset, } from "@stellar/stellar-sdk";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { logger } from "./logger.js";
+const CONFIG_DIR = join(homedir(), ".xlmtools");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+// Circle USDC issuer on Stellar testnet
+const USDC_ISSUER = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5";
+const HORIZON_TESTNET = "https://horizon-testnet.stellar.org";
+/**
+ * Auto-fund a new wallet on Stellar TESTNET only.
+ * This uses the public friendbot (free testnet XLM) and adds a USDC
+ * trustline so the account can receive payments. This function must
+ * never be called on mainnet — friendbot does not exist there.
+ */
+async function fundTestnetWallet(keypair) {
+    // Safety: only run on testnet
+    const network = process.env.STELLAR_NETWORK ?? "testnet";
+    if (network !== "testnet") {
+        logger.info({ network }, "Skipping auto-fund — not on testnet");
+        return false;
+    }
+    const publicKey = keypair.publicKey();
+    // Step 1: Fund with friendbot
+    process.stderr.write("  Funding wallet with testnet XLM...");
+    try {
+        const res = await fetch(`https://friendbot.stellar.org?addr=${publicKey}`);
+        if (!res.ok) {
+            process.stderr.write(" failed\n");
+            logger.warn({ status: res.status }, "Friendbot funding failed");
+            return false;
+        }
+        process.stderr.write(" done\n");
+    }
+    catch (e) {
+        process.stderr.write(" failed (network error)\n");
+        logger.warn({ err: e }, "Friendbot request failed");
+        return false;
+    }
+    // Step 2: Add USDC trustline
+    process.stderr.write("  Adding USDC trustline...");
+    try {
+        const server = new Horizon.Server(HORIZON_TESTNET);
+        const account = await server.loadAccount(publicKey);
+        const usdcAsset = new Asset("USDC", USDC_ISSUER);
+        const tx = new TransactionBuilder(account, {
+            fee: "100",
+            networkPassphrase: Networks.TESTNET,
+        })
+            .addOperation(Operation.changeTrust({ asset: usdcAsset }))
+            .setTimeout(30)
+            .build();
+        tx.sign(keypair);
+        await server.submitTransaction(tx);
+        process.stderr.write(" done\n");
+    }
+    catch (e) {
+        process.stderr.write(" failed\n");
+        logger.warn({ err: e }, "USDC trustline failed");
+        return false;
+    }
+    return true;
+}
+export function loadOrCreateWallet() {
+    if (existsSync(CONFIG_PATH)) {
+        return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    }
+    const keypair = Keypair.random();
+    const config = {
+        stellarPrivateKey: keypair.secret(),
+        stellarPublicKey: keypair.publicKey(),
+        apiUrl: process.env.XLMTools_API_URL ?? "http://localhost:3000",
+    };
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+    process.stderr.write("\n" +
+        "XLMTools — First Run Setup (Stellar Testnet)\n" +
+        "─".repeat(44) + "\n\n" +
+        `  Wallet:  ${config.stellarPublicKey}\n` +
+        `  Network: Stellar Testnet\n\n`);
+    // Auto-fund on testnet (non-blocking — don't break startup if it fails)
+    fundTestnetWallet(keypair)
+        .then((funded) => {
+        if (funded) {
+            process.stderr.write("\n  Wallet funded and ready.\n" +
+                "  Get testnet USDC: https://faucet.circle.com\n" +
+                "  (paste your wallet address above)\n\n" +
+                "─".repeat(40) + "\n\n");
+        }
+        else {
+            process.stderr.write("\n  Auto-funding failed. Fund manually:\n" +
+                "  1. https://lab.stellar.org/account/fund  (testnet XLM)\n" +
+                "  2. https://faucet.circle.com             (testnet USDC)\n\n" +
+                "─".repeat(40) + "\n\n");
+        }
+    })
+        .catch(() => {
+        // Silently handle — wallet is still created, just unfunded
+    });
+    logger.info({ publicKey: config.stellarPublicKey }, "New Stellar wallet generated");
+    return config;
+}
+export function getKeypair(config) {
+    return Keypair.fromSecret(config.stellarPrivateKey);
+}