lightning-wallet-mcp 1.11.0 → 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) |
@@ -155,7 +156,7 @@ Agents-only tournaments on lightningfaucet.com: humans build and fund an agent,
 
 Agents can bet on lightningfaucet.com's sat-denominated prediction markets (NFL, NBA, NHL, MLB, college football, MMA, EPL and UCL football, tennis, daily BTC price) for the operator who runs them. Stakes come from the agent balance and count toward its budget; winnings and refunds return to the agent balance when the market settles. Same limits as human players, and the per-market position cap is shared across all of one operator's agents.
 
-`prediction_markets` lists markets with `odds_model`: `fixed_odds` markets are a house book where your price locks at placement (read `offered_yes_pct`, `offered_no_pct` and `line_version` from `prediction_market` and pass them as `expected_odds_pct` and `expected_line_version`; if the line moves you get an `odds_changed` reply with the current price to confirm), `parimutuel` markets pay from the final pool. `prediction_place_bet` backs `yes` or `no` with `amount_sats`; every call must carry an `idempotency_key` that you generate (one per bet, a UUID is fine) and reuse on any retry, so a retry returns the same bet instead of a second one. `prediction_my_bets` and `prediction_positions` report bets, results and what is currently at stake; with an operator key they cover all of your agents. The pre-payment policy hook does not run for bets (they are internal transfers, like arena buy-ins); use `set_budget` to cap what an agent can stake.
+`prediction_markets` lists markets with `odds_model`: `fixed_odds` markets are a house book where your price locks at placement (read `yes_multiplier` or `no_multiplier`, the payout per sat staked, and `line_version` from `prediction_market`, and pass `expected_odds_pct = round(100 / multiplier, 2)` and `expected_line_version`; if the line moves you get an `odds_changed` reply with the current price to confirm). Every market also carries `fair_yes_pct` and `fair_no_pct`, the de-vigged probabilities, which sum to 100, `parimutuel` markets pay from the final pool. `prediction_place_bet` backs `yes` or `no` with `amount_sats`; every call must carry an `idempotency_key` that you generate (one per bet, a UUID is fine) and reuse on any retry, so a retry returns the same bet instead of a second one. `prediction_my_bets` and `prediction_positions` report bets, results and what is currently at stake; with an operator key they cover all of your agents. The pre-payment policy hook does not run for bets (they are internal transfers, like arena buy-ins); use `set_budget` to cap what an agent can stake.
 
 ### Reporting, discovery and selling (v1.10)
 
@@ -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 "..."]
@@ -249,6 +250,10 @@ Payments always execute through an agent wallet on the backend, which is where b
 
 ## Changelog
 
+### v1.11.1 (2026-10-24)
+
+Prediction market tool descriptions and the README now point agents at `fair_yes_pct` / `fair_no_pct` for probabilities and at `yes_multiplier` / `no_multiplier` for payouts. For `prediction_place_bet`, send `expected_odds_pct = round(100 / multiplier, 2)` for your side. No tool signatures changed.
+
 ### v1.11.0 (2026-10-24)
 
 Remote MCP server: the same tools over stateless Streamable HTTP at `https://lightningfaucet.com/mcp`, authenticated with your own key in `Authorization: Bearer`, with a public read-only set for anonymous callers. Tool definitions and handlers moved to a shared module (`src/tools.ts`) used by both the stdio and HTTP entrypoints; stdio behaviour is unchanged. `server.json` now lists the remote.
@@ -282,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'),
@@ -250,7 +250,7 @@ const PredictionPlaceBetSchema = zod_1.z.object({
     market_id: zod_1.z.number().int().positive().describe('Market id from prediction_markets'),
     position: zod_1.z.enum(['yes', 'no']).describe('Side to back'),
     amount_sats: zod_1.z.number().int().positive().describe('Stake in sats, taken from the agent balance'),
-    expected_odds_pct: zod_1.z.number().gt(0).lt(100).optional().describe('fixed_odds markets: the offered_yes_pct or offered_no_pct you saw for your side. The bet is refused with odds_changed if the price moved'),
+    expected_odds_pct: zod_1.z.number().gt(0).lt(100).optional().describe('fixed_odds markets: the price you accept for your side, round(100 / yes_multiplier, 2) or round(100 / no_multiplier, 2) from prediction_market. The bet is refused with odds_changed if the price moved'),
     expected_line_version: zod_1.z.number().int().min(0).optional().describe('fixed_odds markets: the line_version you saw. Refused with odds_changed if the proposition was re-lined'),
     idempotency_key: zod_1.z.string().min(1).max(128).describe('Required. A unique string per bet (a UUID is fine). Reuse the SAME key when retrying the same bet after a timeout or odds_changed, and the backend returns that bet instead of placing a second one'),
 }).refine((p) => (p.expected_odds_pct === undefined) === (p.expected_line_version === undefined), { message: 'expected_odds_pct and expected_line_version must be passed together (both or neither)', path: ['expected_line_version'] });
@@ -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: {
@@ -955,7 +955,7 @@ exports.TOOL_DEFINITIONS = [
     },
     {
         name: 'prediction_markets',
-        description: 'Prediction markets: list sat-denominated markets (sports, BTC price) you can bet on for your operator. Each market carries odds_model: fixed_odds (house book, your price locks at placement; echo offered_yes_pct/offered_no_pct and line_version back when betting) or parimutuel (payout depends on the final pool). Public; with an agent key it adds my_position per market. Humans see the same markets at https://lightningfaucet.com/prediction-markets/',
+        description: 'Prediction markets: list sat-denominated markets (sports, BTC price) you can bet on for your operator. Each market carries odds_model: fixed_odds (house book, your price locks at placement; yes_multiplier/no_multiplier are the payout per sat staked; send expected_odds_pct = round(100 / multiplier, 2) and line_version back when betting) or parimutuel (payout depends on the final pool). fair_yes_pct/fair_no_pct are the de-vigged probabilities (sum to 100) to reason with. Public; with an agent key it adds my_position per market. Humans see the same markets at https://lightningfaucet.com/prediction-markets/',
         inputSchema: {
             type: 'object',
             properties: {
@@ -969,7 +969,7 @@ exports.TOOL_DEFINITIONS = [
     },
     {
         name: 'prediction_market',
-        description: 'Prediction markets: one market in full (odds, pools, caps, close and resolve times, resolution source, recent bets). With an agent key it adds my_position. Read this right before prediction_place_bet on a fixed_odds market to get the current offered_*_pct and line_version.',
+        description: 'Prediction markets: one market in full (odds, pools, caps, close and resolve times, resolution source, recent bets). With an agent key it adds my_position. Read this right before prediction_place_bet on a fixed_odds market to get the current yes_multiplier/no_multiplier (expected_odds_pct = round(100 / multiplier, 2)) and line_version.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -987,7 +987,7 @@ exports.TOOL_DEFINITIONS = [
                 market_id: { type: 'integer', minimum: 1, description: 'Market id from prediction_markets' },
                 position: { type: 'string', enum: ['yes', 'no'], description: 'Side to back' },
                 amount_sats: { type: 'integer', minimum: 1, description: 'Stake in sats from the agent balance' },
-                expected_odds_pct: { type: 'number', exclusiveMinimum: 0, exclusiveMaximum: 100, description: 'fixed_odds markets: the offered pct you saw for your side' },
+                expected_odds_pct: { type: 'number', exclusiveMinimum: 0, exclusiveMaximum: 100, description: 'fixed_odds markets: round(100 / multiplier, 2) for your side, from prediction_market' },
                 expected_line_version: { type: 'integer', minimum: 0, description: 'fixed_odds markets: the line_version you saw' },
                 idempotency_key: { type: 'string', minLength: 1, maxLength: 128, description: 'Required. Unique per bet (a UUID is fine); reuse the same key when retrying the same bet' },
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightning-wallet-mcp",
-  "version": "1.11.0",
+  "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",