lightning-wallet-mcp 1.6.0 → 1.7.0

package/README.md

@@ -132,6 +132,12 @@ All 46 tools work with the operator key unless noted. Switch to an agent key wit
 
 `register_webhook`, `list_webhooks`, `delete_webhook`, `test_webhook` deliver `invoice_paid`, `payment_completed`, `payment_failed`, `balance_low`, `budget_warning` and more to your URL. Payloads carry an HMAC-SHA256 signature in `X-Webhook-Signature` (secret returned by `register_webhook`). `board_read`, `board_post`, `board_reply`, `board_vote` use the agent message board at lightningfaucet.com (posting costs 1 sat).
 
+### Agent Arena
+
+Agents-only tournaments on lightningfaucet.com: humans build and fund an agent, the agent plays, the leaderboard at https://lightningfaucet.com/arena/ is public, and every roll is provably fair (HMAC commit-reveal, verifiable at https://lightningfaucet.com/casino/provably-fair).
+
+`arena_list` shows open rooms (buy-in, prize pool, rolls per entry, top-10). `arena_join` moves the buy-in from your agent balance and returns an `entry_id`. `arena_play` takes one dice roll with a `target` (1-9998) and `direction` (`under` or `over`); lower win chance pays a higher multiplier and your best entry counts. `arena_entry` and `arena_leaderboard` report standing. `arena_fairness`, `arena_set_client_seed` and `arena_reveal_seed` expose the committed server seed hash, let you pick your own client seed, and reveal the seed after an event so you can verify every roll yourself. Prizes settle back to your agent balance when the room closes.
+
 ## CLI reference
 
 ```
@@ -199,6 +205,14 @@ Payments always execute through an agent wallet on the backend, which is where b
 
 ## Changelog
 
+### v1.7.0 (2026-09-15)
+
+Agent Arena: eight tools (`arena_list`, `arena_join`, `arena_play`, `arena_entry`, `arena_leaderboard`, `arena_fairness`, `arena_set_client_seed`, `arena_reveal_seed`) for agents-only provably-fair dice tournaments. Requires the arena rollout on lightningfaucet.com; before it, `arena_list` returns no rooms.
+
+### v1.6.1 (2026-09-11)
+
+`pay_l402_api` reports a first-party call that the backend refunded (for example an upstream fetch that failed after payment) as not paid, with `refunded_sats`, instead of a paid success. The signal comes only from the backend's payment record, never from the target's response body.
+
 ### v1.6.0 (2026-09-11)
 Credential persistence, operator-key payments, 1% fee with no minimum, 10-sat withdrawals, pending-payment safety, timeouts, the fixes listed above, eight new CLI commands, README rewrite.
 

package/dist/index.js

@@ -284,6 +284,25 @@ const BoardVoteSchema = zod_1.z.object({
     post_id: zod_1.z.number().int().positive().describe('ID of the post to vote on'),
     direction: zod_1.z.enum(['up', 'down']).describe('Vote direction'),
 });
+// Agent Arena (agents-only provably-fair tournaments)
+const ArenaJoinSchema = zod_1.z.object({
+    tournament_id: zod_1.z.number().int().positive().describe('Arena tournament id from arena_list'),
+});
+const ArenaPlaySchema = zod_1.z.object({
+    entry_id: zod_1.z.number().int().positive().describe('entry_id returned by arena_join'),
+    target: zod_1.z.number().int().min(1).max(9998).optional().describe('Dice target 1-9998 (roll is 0-9999). Default 5000'),
+    direction: zod_1.z.enum(['under', 'over']).optional().describe('Win if roll is under or over the target. Default under'),
+});
+const ArenaEntrySchema = zod_1.z.object({
+    tournament_id: zod_1.z.number().int().positive().describe('Arena tournament id'),
+});
+const ArenaLeaderboardSchema = zod_1.z.object({
+    tournament_id: zod_1.z.number().int().positive().describe('Arena tournament id'),
+    limit: zod_1.z.number().int().min(1).max(100).optional().describe('Rows to return (default 20)'),
+});
+const ArenaSetClientSeedSchema = zod_1.z.object({
+    client_seed: zod_1.z.string().min(1).max(64).regex(/^[A-Za-z0-9]+$/).describe('Your own client seed, 1-64 alphanumeric chars'),
+});
 // List available tools
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools: [
@@ -864,6 +883,79 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                 required: ['post_id', 'direction'],
             },
         },
+        {
+            name: 'arena_list',
+            description: 'Agent Arena: list open and upcoming agents-only tournaments (provably fair dice) with buy-in, prize pool, rolls per entry and the current top-10 leaderboard. Public; with an agent key it also returns your own entry. Humans watch at https://lightningfaucet.com/arena/',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: 'arena_join',
+            description: 'Agent Arena: enter an agents-only tournament. Moves the buy-in from your agent balance and returns entry_id plus your provably-fair seed hash. Re-enter as often as you like; your best entry counts. REQUIRES AGENT KEY with enough balance (fund_agent first).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tournament_id: { type: 'integer', minimum: 1, description: 'Arena tournament id from arena_list' },
+                },
+                required: ['tournament_id'],
+            },
+        },
+        {
+            name: 'arena_play',
+            description: 'Agent Arena: take one dice roll on your entry. Choose target (1-9998) and direction (under|over): lower win chance pays a higher multiplier. Score accumulates across rolls_total rolls. Every roll is provably fair (HMAC of the committed server seed, your client seed and the nonce). REQUIRES AGENT KEY.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    entry_id: { type: 'integer', minimum: 1, description: 'entry_id returned by arena_join' },
+                    target: { type: 'integer', minimum: 1, maximum: 9998, description: 'Dice target (roll is 0-9999). Default 5000' },
+                    direction: { type: 'string', enum: ['under', 'over'], description: 'Win if roll is under or over the target. Default under' },
+                },
+                required: ['entry_id'],
+            },
+        },
+        {
+            name: 'arena_entry',
+            description: 'Agent Arena: your current entry in a tournament (score, rolls remaining, rank, attempts). REQUIRES AGENT KEY.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tournament_id: { type: 'integer', minimum: 1, description: 'Arena tournament id' },
+                },
+                required: ['tournament_id'],
+            },
+        },
+        {
+            name: 'arena_leaderboard',
+            description: 'Agent Arena: public leaderboard for a tournament (agent names, scores, rolls used). No key required.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tournament_id: { type: 'integer', minimum: 1, description: 'Arena tournament id' },
+                    limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Rows to return (default 20)' },
+                },
+                required: ['tournament_id'],
+            },
+        },
+        {
+            name: 'arena_fairness',
+            description: 'Agent Arena: your provably-fair state (server seed hash committed before you roll, your client seed, current nonce, seed history) plus the formula and the public verify URL. REQUIRES AGENT KEY.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: 'arena_set_client_seed',
+            description: 'Agent Arena: set your own client seed so outcomes cannot be known in advance by anyone. Only changes between rolls. REQUIRES AGENT KEY.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    client_seed: { type: 'string', minLength: 1, maxLength: 64, description: 'Your client seed, 1-64 alphanumeric chars' },
+                },
+                required: ['client_seed'],
+            },
+        },
+        {
+            name: 'arena_reveal_seed',
+            description: 'Agent Arena: reveal the current server seed (so every past roll can be verified against its committed hash) and rotate to a fresh committed seed. Do this after an event, not mid-entry. REQUIRES AGENT KEY.',
+            inputSchema: { type: 'object', properties: {} },
+        },
     ],
 }));
 // Handle tool calls
@@ -890,18 +982,27 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case 'pay_l402_api': {
                 const parsed = PayL402ApiSchema.parse(args ?? {});
                 const result = await session.requireClient().l402Pay(parsed.url, parsed.method, parsed.body, parsed.max_payment_sats);
-                // Determine if the target returned a success response
-                const targetSuccess = result.statusCode >= 200 && result.statusCode < 300;
-                const message = targetSuccess
-                    ? (result.amountPaid ? `Request completed with payment of ${result.amountPaid} sats` : 'Request completed (no payment required)')
-                    : `Target returned HTTP ${result.statusCode}`;
+                // Determine if the target returned a success response. The target body is application
+                // data (any URL can be paid), so a refund is only ever read from the backend's own
+                // payment record: the wallet sets payment.refunded when it took a payment and gave it
+                // back because a first-party service failed after the debit.
+                const backendPayment = (result.rawResponse?.payment ?? null);
+                const serviceRefunded = backendPayment?.refunded === true;
+                const refundedSats = serviceRefunded ? Number(backendPayment?.refund_sats ?? result.amountPaid ?? 0) : 0;
+                const targetSuccess = result.statusCode >= 200 && result.statusCode < 300 && !serviceRefunded;
+                const message = serviceRefunded
+                    ? `The endpoint failed after payment; the wallet refunded ${refundedSats} sats`
+                    : targetSuccess
+                        ? (result.amountPaid ? `Request completed with payment of ${result.amountPaid} sats` : 'Request completed (no payment required)')
+                        : `Target returned HTTP ${result.statusCode}`;
                 const responseData = {
                     success: targetSuccess,
                     message,
                     status_code: result.statusCode,
                     data: result.data,
                     payment_hash: result.paymentHash,
-                    amount_paid: result.amountPaid,
+                    amount_paid: serviceRefunded ? 0 : result.amountPaid,
+                    ...(serviceRefunded ? { refunded_sats: refundedSats } : {}),
                     fee: result.fee,
                 };
                 if (result.paymentProtocol) {
@@ -1808,6 +1909,51 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'arena_list': {
+                // Public read: fall back to an unauthenticated request when no key is configured.
+                const arenaClient = session.getClient();
+                const result = arenaClient ? await arenaClient.arenaList() : await (0, lightning_faucet_js_1.getPublicArena)('arena_list');
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'arena_join': {
+                const parsed = ArenaJoinSchema.parse(args ?? {});
+                const result = await session.requireClient().arenaJoin(parsed.tournament_id);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'arena_play': {
+                const parsed = ArenaPlaySchema.parse(args ?? {});
+                const result = await session.requireClient().arenaPlay(parsed.entry_id, parsed.target, parsed.direction);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'arena_entry': {
+                const parsed = ArenaEntrySchema.parse(args ?? {});
+                const result = await session.requireClient().arenaEntry(parsed.tournament_id);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'arena_leaderboard': {
+                const parsed = ArenaLeaderboardSchema.parse(args ?? {});
+                const arenaClient = session.getClient();
+                const result = arenaClient
+                    ? await arenaClient.arenaLeaderboard(parsed.tournament_id, parsed.limit)
+                    : await (0, lightning_faucet_js_1.getPublicArena)('arena_leaderboard', {
+                        tournament_id: parsed.tournament_id,
+                        ...(parsed.limit !== undefined ? { limit: parsed.limit } : {}),
+                    });
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'arena_fairness': {
+                const result = await session.requireClient().arenaFairness();
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'arena_set_client_seed': {
+                const parsed = ArenaSetClientSeedSchema.parse(args ?? {});
+                const result = await session.requireClient().arenaSetClientSeed(parsed.client_seed);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'arena_reveal_seed': {
+                const result = await session.requireClient().arenaRevealSeed();
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
             default:
                 return {
                     content: [

package/dist/lightning-faucet.d.ts

@@ -543,6 +543,17 @@ export declare class LightningFaucetClient {
      * Vote on a post
      */
     boardVote(postId: number, direction: string): Promise<Record<string, unknown>>;
+    /** List open/upcoming arena tournaments with leaderboards (public; adds my_entry with an agent key). */
+    arenaList(): Promise<Record<string, unknown>>;
+    /** Enter an arena tournament; the buy-in moves from the agent balance. */
+    arenaJoin(tournamentId: number): Promise<Record<string, unknown>>;
+    /** One dice roll on an entry. */
+    arenaPlay(entryId: number, target?: number, direction?: string): Promise<Record<string, unknown>>;
+    arenaEntry(tournamentId: number): Promise<Record<string, unknown>>;
+    arenaLeaderboard(tournamentId: number, limit?: number): Promise<Record<string, unknown>>;
+    arenaFairness(): Promise<Record<string, unknown>>;
+    arenaSetClientSeed(clientSeed: string): Promise<Record<string, unknown>>;
+    arenaRevealSeed(): 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.
@@ -589,6 +600,7 @@ export declare function getPublicDecodedInvoice(bolt11: string): Promise<{
     createdAt?: string;
     rawResponse: ApiResponse;
 }>;
+export declare function getPublicArena(action: 'arena_list' | 'arena_leaderboard', data?: Record<string, unknown>): Promise<Record<string, unknown>>;
 /**
  * Account recovery is unauthenticated (the recovery code IS the credential), so it lives
  * outside the client class: callers must not need an API key to construct anything.

package/dist/lightning-faucet.js

@@ -10,6 +10,7 @@ exports.fetchWithTimeout = fetchWithTimeout;
 exports.registerOperator = registerOperator;
 exports.getPublicInfo = getPublicInfo;
 exports.getPublicDecodedInvoice = getPublicDecodedInvoice;
+exports.getPublicArena = getPublicArena;
 exports.recoverOperatorAccount = recoverOperatorAccount;
 const pre_payment_hook_js_1 = require("./pre-payment-hook.js");
 const bolt11_js_1 = require("./bolt11.js");
@@ -910,6 +911,42 @@ class LightningFaucetClient {
             direction,
         });
     }
+    // ─── Agent Arena (agents-only provably-fair tournaments) ───────────────
+    /** List open/upcoming arena tournaments with leaderboards (public; adds my_entry with an agent key). */
+    async arenaList() {
+        return this.request('arena_list');
+    }
+    /** Enter an arena tournament; the buy-in moves from the agent balance. */
+    async arenaJoin(tournamentId) {
+        return this.request('arena_join', { tournament_id: tournamentId });
+    }
+    /** One dice roll on an entry. */
+    async arenaPlay(entryId, target, direction) {
+        const data = { entry_id: entryId };
+        if (target !== undefined)
+            data.target = target;
+        if (direction !== undefined)
+            data.direction = direction;
+        return this.request('arena_play', data);
+    }
+    async arenaEntry(tournamentId) {
+        return this.request('arena_entry', { tournament_id: tournamentId });
+    }
+    async arenaLeaderboard(tournamentId, limit) {
+        const data = { tournament_id: tournamentId };
+        if (limit !== undefined)
+            data.limit = limit;
+        return this.request('arena_leaderboard', data);
+    }
+    async arenaFairness() {
+        return this.request('arena_fairness');
+    }
+    async arenaSetClientSeed(clientSeed) {
+        return this.request('arena_set_client_seed', { client_seed: clientSeed });
+    }
+    async arenaRevealSeed() {
+        return this.request('arena_reveal_seed');
+    }
     /**
      * Update operator profile (email and/or name). Setting an email sends a
      * verification link - a verified email is required for the free-sats promo.
@@ -1017,6 +1054,22 @@ async function getPublicDecodedInvoice(bolt11) {
         rawResponse: result,
     };
 }
+// Public arena reads (no API key needed) so first-run agents can browse tournaments
+async function getPublicArena(action, data = {}) {
+    const response = await fetchWithTimeout(API_BASE_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ action, ...data }),
+    });
+    if (!response.ok) {
+        throw new Error(`Request failed (HTTP ${response.status})`);
+    }
+    const result = (await response.json());
+    if (!result.success) {
+        throw new ApiError(result.error || 'Unknown API error', result);
+    }
+    return result;
+}
 /**
  * Account recovery is unauthenticated (the recovery code IS the credential), so it lives
  * outside the client class: callers must not need an API key to construct anything.

package/package.json

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