lightning-wallet-mcp 1.11.1 → 1.11.2

package/README.md

@@ -16,9 +16,9 @@ Your agent can pay for L402 and X402 APIs, pay any Lightning invoice or Lightnin
 claude mcp add lightning-wallet -- npx -y lightning-wallet-mcp
 ```
 
-Then in Claude: *"Register a Lightning wallet for me with the email you@example.com"*.
+Then in Claude: *"Register a Lightning wallet for me"*.
 
-That is it. `register_operator` saves your credentials to `~/.lightning-wallet/credentials.json` (mode 0600) and every later session reuses them automatically. Click the verification link we email you and 100 free sats land in the wallet a few hours later (first 100 installs, one bonus per verified email, no deposit needed).
+That is it. `register_operator` saves your credentials to `~/.lightning-wallet/credentials.json` (mode 0600) and every later session reuses them automatically. Registering is free. Your first paid call needs a small deposit: ask for a deposit invoice with `get_deposit_invoice` (or `lw deposit <sats>` on the CLI) and pay it from any Lightning wallet. An email address is optional and only used for notifications; click the verification link if you add one.
 
 **Cursor / Windsurf / any MCP host** (`.cursor/mcp.json`, `.mcp.json`, or the host's MCP settings):
 
@@ -64,7 +64,8 @@ claude mcp add --transport http lightning-wallet https://lightningfaucet.com/mcp
 
 ```bash
 npm install -g lightning-wallet-mcp
-lw register --name "My Bot" --email you@example.com   # saves credentials locally, no export needed
+lw register                      # free; saves credentials locally, no export needed (--email you@example.com is optional, for notifications)
+lw deposit 500                   # prints a Lightning invoice; pay it to fund the wallet
 lw balance
 lw pay-api https://lightningfaucet.com/api/l402/fortune
 lw pay <bolt11>
@@ -123,7 +124,7 @@ All 46 tools work with the operator key unless noted. Switch to an agent key wit
 |------|-------------|
 | `register_operator` | Create an account; credentials are saved locally |
 | `update_operator` | Set email (sends a verification link) or display name |
-| `claim_promo` | Claim the install promo manually (it is also granted automatically after verification) |
+| `claim_promo` | Reports install promo status. The 100-sat launch promo has ended; the tool is kept for backward compatibility |
 | `withdraw` | Withdraw to an external invoice (minimum 10 sats) |
 | `create_withdraw_link` | LNURL-withdraw link to sweep into any wallet by QR |
 | `recover_account` | Recover with the recovery code (rotates the key) |
@@ -180,7 +181,7 @@ There is intentionally no faucet or free-spin claim tool: those are one per pers
 ## CLI reference
 
 ```
-lw register [--name "..."] [--email you@example.com]
+lw register [--name "..."] [--email you@example.com] [--force]
 lw use-key <api_key> [--agent]      lw credentials      lw forget      lw recover <code>
 lw whoami | balance | info
 lw pay <bolt11> [--max-fee 10]      lw pay-address user@domain 100 [--comment "..."]
@@ -286,7 +287,7 @@ Accept real BOLT11 invoices in the tool schemas; tolerate omitted MCP args; vali
 Pre-payment policy hook.
 
 ### v1.4.x (2026-06)
-`update_operator`, `claim_promo`, keyless `get_info`, the install promo.
+`update_operator`, `claim_promo`, keyless `get_info`, the launch install promo (now ended).
 
 ### v1.3.0
 L402 protocol v0 headers, `.well-known/l402.json` discovery.

package/dist/cli.js

@@ -100,10 +100,35 @@ function parseArgs(argv) {
     return { command, positional, flags };
 }
 // --- Commands ---
+const RATE_LIMIT_RE = /rate limit/i;
 async function cmdRegister(positional, flags) {
     const name = flags.name || positional[0] || undefined;
     const email = flags.email || undefined;
-    const result = await (0, lightning_faucet_js_1.registerOperator)(name, email);
+    const force = flags.force !== undefined && flags.force !== 'false';
+    const saved = (0, credentials_js_1.activeStoredKey)((0, credentials_js_1.loadCredentials)());
+    if (saved && !force) {
+        // Never call the API when a wallet is already saved: registration is rate limited
+        // per IP and a second account would orphan the funded one.
+        return {
+            already_registered: true,
+            using: `saved ${saved.type} credentials`,
+            credentials_file: (0, credentials_js_1.credentialsPath)(),
+            message: `Already registered. Using the saved ${saved.type} credentials in ${(0, credentials_js_1.credentialsPath)()}. Nothing was changed.`,
+            next_step: 'Run: lw whoami   (or lw balance). To fund the wallet run: lw deposit <sats>',
+            force_hint: 'To create a brand new wallet anyway (this replaces the saved credentials), run: lw register --force',
+        };
+    }
+    let result;
+    try {
+        result = await (0, lightning_faucet_js_1.registerOperator)(name, email);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (RATE_LIMIT_RE.test(message)) {
+            throw new Error(`${message} You may already have a wallet: reuse your saved credentials (${(0, credentials_js_1.credentialsPath)()}) instead of registering again. Run: lw credentials   or   lw whoami`);
+        }
+        throw err;
+    }
     const savedTo = (0, credentials_js_1.saveOperatorKey)(result.apiKey, { id: result.operatorId, name, recovery_code: result.recoveryCode });
     return {
         operator_id: result.operatorId,
@@ -113,9 +138,8 @@ async function cmdRegister(positional, flags) {
         hint: savedTo
             ? `Credentials saved to ${savedTo}. lw commands will use them automatically; no export needed.`
             : `export LIGHTNING_WALLET_API_KEY=${result.apiKey}`,
-        next_step: email
-            ? 'Click the verification link we emailed you. Verified operators get 100 free sats credited automatically a few hours later.'
-            : 'Run: lw set-email you@example.com   to get 100 free sats after verification.',
+        next_step: 'Registering is free. Your first paid call needs a small deposit: run   lw deposit <sats>   and pay the invoice from any Lightning wallet.' +
+            (email ? ' Click the verification link we emailed you.' : ' An email is optional; add one for notifications with: lw set-email you@example.com'),
         webhook_tip: 'Set up a webhook to get real-time notifications for payments and balance changes. Run: lw help webhooks',
     };
 }
@@ -386,8 +410,9 @@ USAGE
   lw <command> [options]
 
 SETUP
-  register [--name "name"] [--email "you@example.com"]
-                                 Create operator account. Credentials are saved to
+  register [--name "name"] [--email "you@example.com"] [--force]
+                                 Create operator account (free; email is optional, for notifications).
+                                 If credentials are already saved, nothing is changed; --force makes a new one. Credentials are saved to
                                  ~/.lightning-wallet/credentials.json and reused automatically.
   use-key <api_key> [--agent]     Save an existing key instead (env LIGHTNING_WALLET_API_KEY wins if set)
   credentials                     Show which saved credentials are active (never prints keys)
@@ -417,8 +442,7 @@ COMMANDS
 
   transactions                    Recent transactions [--limit 10] [--offset 0]
   set-email <email>               Set operator email (verification link emailed)
-  claim-promo                     Claim the 100-sat install promo
-                                    (requires verified email + 3h account age)
+  claim-promo                     Show install promo status (the launch promo has ended)
   help                            Show this help
 
 WEBHOOKS
@@ -445,8 +469,11 @@ OUTPUT
   --human                         Human-readable output
 
 EXAMPLES
-  # Register once; the key is saved locally and reused
-  lw register --name "My Bot" --email you@example.com
+  # Register once (free); the key is saved locally and reused. --email is optional.
+  lw register --name "My Bot"
+
+  # Fund the wallet before the first paid call
+  lw deposit 500
 
   # Check balance
   lw balance | jq '.balance_sats'

package/dist/lightning-faucet.d.ts

@@ -596,7 +596,7 @@ export declare class LightningFaucetClient {
     predictionPositions(): Promise<Record<string, unknown>>;
     /**
      * Update operator profile (email and/or name). Setting an email sends a
-     * verification link - a verified email is required for the free-sats promo.
+     * verification link - an email is optional and used for notifications.
      */
     updateOperator(opts: {
         email?: string;
@@ -607,8 +607,7 @@ export declare class LightningFaucetClient {
         email_verification?: string;
     }>;
     /**
-     * Claim a promo bonus (default: the first_100_installs free-sats promo).
-     * Requires a verified email and an operator account at least 3 hours old.
+     * Report promo status (the first_100_installs launch promo has ended; kept for backward compatibility).
      */
     claimPromo(promoCode?: string): Promise<ApiResponse & {
         promo?: string;

package/dist/lightning-faucet.js

@@ -1008,7 +1008,7 @@ class LightningFaucetClient {
     }
     /**
      * Update operator profile (email and/or name). Setting an email sends a
-     * verification link - a verified email is required for the free-sats promo.
+     * verification link - an email is optional and used for notifications.
      */
     async updateOperator(opts) {
         const params = {};
@@ -1019,8 +1019,7 @@ class LightningFaucetClient {
         return this.request('update_operator', params);
     }
     /**
-     * Claim a promo bonus (default: the first_100_installs free-sats promo).
-     * Requires a verified email and an operator account at least 3 hours old.
+     * Report promo status (the first_100_installs launch promo has ended; kept for backward compatibility).
      */
     async claimPromo(promoCode) {
         const params = {};

package/dist/tools.js

@@ -71,7 +71,7 @@ const GetTransactionsSchema = zod_1.z.object({
 // Operator management schemas
 const RegisterOperatorSchema = zod_1.z.object({
     name: zod_1.z.string().optional().describe('Name for the operator account'),
-    email: zod_1.z.string().email().optional().describe('Your email — register WITH it to claim the 100 free-sats install promo. A verification link is sent; once verified, claim_promo funds your wallet. Strongly recommended.'),
+    email: zod_1.z.string().email().optional().describe('Optional email address, used for notifications and account notices. A verification link is sent.'),
 });
 const GetDepositInvoiceSchema = zod_1.z.object({
     amount_sats: zod_1.z.number().int().min(100).max(10_000_000).describe('Amount in satoshis to deposit'),
@@ -391,19 +391,19 @@ exports.TOOL_DEFINITIONS = [
     // Operator management tools
     {
         name: 'register_operator',
-        description: 'Register a new operator account. Returns API key and recovery code. SAVE THESE - they cannot be retrieved later! Tip: pass an email to claim the 100 free-sats install promo.',
+        description: 'Register a new operator account. Returns API key and recovery code. SAVE THESE - they cannot be retrieved later! Registering is free; your first paid call needs a small deposit (use get_deposit_invoice).',
         inputSchema: {
             type: 'object',
             properties: {
                 name: { type: 'string', description: 'Name for the operator account (optional)' },
-                email: { type: 'string', description: 'Email address — pass it here to claim the 100 free-sats install promo (a verification link is sent; once verified, and once the operator account is at least 3 hours old, call claim_promo to get funded). Also used for onboarding tips and important account notices.' },
+                email: { type: 'string', description: 'Optional email address, used for notifications and important account notices. A verification link is sent.' },
             },
             required: [],
         },
     },
     {
         name: 'update_operator',
-        description: 'Update operator profile: set your email (sends a verification link - required for the free-sats promo) and/or display name. REQUIRES OPERATOR KEY.',
+        description: 'Update operator profile: set your email (sends a verification link) and/or display name. REQUIRES OPERATOR KEY.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -415,7 +415,7 @@ exports.TOOL_DEFINITIONS = [
     },
     {
         name: 'claim_promo',
-        description: 'Claim the free-sats install promo (100 sats, first 100 installs). Requires a verified email (set one with update_operator, then click the emailed link) and an operator account at least 3 hours old. REQUIRES OPERATOR KEY.',
+        description: 'The 100-sat launch install promo has ended. This tool is kept for backward compatibility and reports the promo status; it no longer funds new wallets. REQUIRES OPERATOR KEY.',
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightning-wallet-mcp",
-  "version": "1.11.1",
+  "version": "1.11.2",
   "mcpName": "io.github.lightningfaucet/lightning-wallet-mcp",
   "description": "Lightning wallet for AI agents. MCP server + CLI. Works with Claude Code, OpenClaw, Cursor, and any agent framework.",
   "main": "dist/index.js",