lightning-wallet-mcp 1.6.1 → 1.8.0

package/README.md

@@ -130,7 +130,19 @@ All 46 tools work with the operator key unless noted. Switch to an agent key wit
 
 ### Webhooks and the board
 
-`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).
+`register_webhook`, `list_webhooks`, `delete_webhook`, `test_webhook` deliver `invoice_paid`, `payment_completed`, `payment_failed`, `balance_low`, `budget_warning`, `bet_placed`, `bet_settled` 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.
+
+### Prediction markets
+
+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.
 
 ## CLI reference
 
@@ -199,6 +211,14 @@ Payments always execute through an agent wallet on the backend, which is where b
 
 ## Changelog
 
+### v1.8.0 (2026-09-22)
+
+Prediction markets: five tools (`prediction_markets`, `prediction_market`, `prediction_place_bet`, `prediction_my_bets`, `prediction_positions`) so an agent can bet on lightningfaucet.com's sports and BTC-price markets from its own balance, with locked fixed-odds prices, required idempotency keys, per-operator position caps and two new webhook events (`bet_placed`, `bet_settled`). Public market reads work without a key. Requires the agent-betting rollout on lightningfaucet.com; before it, `prediction_place_bet` returns `feature_disabled`.
+
+### 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.

package/dist/cli.js

@@ -435,7 +435,8 @@ WEBHOOKS
                     "events":["invoice_paid","balance_changed"]}'
 
   Events: invoice_paid, payment_completed, payment_failed,
-          withdrawal_completed, balance_changed, balance_low, budget_warning
+          withdrawal_completed, balance_changed, balance_low, budget_warning,
+          bet_placed, bet_settled
 
   Full docs: https://lightningfaucet.com/ai-agents/docs#webhooks
 

package/dist/credentials.d.ts

@@ -36,7 +36,13 @@ export declare function saveOperatorKey(apiKey: string, extra?: {
 }, opts?: {
     rotatedFrom?: string;
 }): string | null;
-/** Save an agent key. Activates it only when `activate` is true (set_agent_credentials); create_agent just records it. */
+/**
+ * Save an agent key. Activates it only when `activate` is true (set_agent_credentials);
+ * create_agent just records it. Metadata already on file is kept when the key is unchanged
+ * (set_agent_credentials passes none), since the recorded id is what later lets rotate_api_key
+ * recognise the saved key as the rotated agent's. A different key is a different agent and
+ * starts clean.
+ */
 export declare function saveAgentKey(apiKey: string, extra?: {
     id?: number;
     name?: string;

package/dist/credentials.js

@@ -142,10 +142,17 @@ function saveOperatorKey(apiKey, extra = {}, opts = {}) {
         creds.api_url = process.env.LIGHTNING_WALLET_API_URL;
     return writeCredentials(creds);
 }
-/** Save an agent key. Activates it only when `activate` is true (set_agent_credentials); create_agent just records it. */
+/**
+ * Save an agent key. Activates it only when `activate` is true (set_agent_credentials);
+ * create_agent just records it. Metadata already on file is kept when the key is unchanged
+ * (set_agent_credentials passes none), since the recorded id is what later lets rotate_api_key
+ * recognise the saved key as the rotated agent's. A different key is a different agent and
+ * starts clean.
+ */
 function saveAgentKey(apiKey, extra = {}, activate = false) {
     const creds = base();
-    creds.agent = { api_key: apiKey, id: extra.id, name: extra.name, saved_at: new Date().toISOString() };
+    const prev = creds.agent?.api_key === apiKey ? creds.agent : undefined;
+    creds.agent = { api_key: apiKey, id: extra.id ?? prev?.id, name: extra.name ?? prev?.name, saved_at: new Date().toISOString() };
     if (activate)
         creds.active = 'agent';
     return writeCredentials(creds);

package/dist/index.js

@@ -175,7 +175,7 @@ const WhoamiSchema = zod_1.z.object({});
 // ==========================================
 const RegisterWebhookSchema = zod_1.z.object({
     url: zod_1.z.string().url().describe('HTTPS webhook URL to receive events'),
-    events: zod_1.z.array(zod_1.z.enum(['invoice_paid', 'payment_completed', 'payment_failed', 'withdrawal_completed', 'balance_changed', 'balance_low', 'budget_warning', 'test']))
+    events: zod_1.z.array(zod_1.z.enum(['invoice_paid', 'payment_completed', 'payment_failed', 'withdrawal_completed', 'balance_changed', 'balance_low', 'budget_warning', 'bet_placed', 'bet_settled', 'test']))
         .default(['invoice_paid']).describe('Event types to subscribe to'),
 });
 const ListWebhooksSchema = zod_1.z.object({});
@@ -284,6 +284,83 @@ 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'),
+});
+// Prediction markets (agents bet for their operators from the agent wallet)
+const PredictionMarketsSchema = zod_1.z.object({
+    status: zod_1.z.enum(['open', 'upcoming', 'closed', 'resolved', 'cancelled', 'all']).optional().describe('Market status filter. Default open'),
+    market_type: zod_1.z.enum(['sports', 'btc_price']).optional().describe('sports (fixed-odds books and series) or btc_price (parimutuel)'),
+    category: zod_1.z.string().min(1).max(40).optional().describe('League or category key, e.g. nfl, nba, nhl, mlb, ncaaf, mma, epl, ucl, tennis, btc_daily'),
+    limit: zod_1.z.number().int().min(1).max(100).optional().describe('Rows to return (default 50)'),
+    offset: zod_1.z.number().int().min(0).optional().describe('Pagination offset'),
+});
+const PredictionMarketSchema = zod_1.z.object({
+    market_id: zod_1.z.number().int().positive().describe('Market id from prediction_markets'),
+});
+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_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'] });
+/** Backend refusals that carry a structured reply the model can act on (not thrown). */
+const PREDICTION_REFUSALS = new Set([
+    'odds_changed', 'position_cap_exceeded', 'budget_exceeded', 'insufficient_balance', 'bet_in_progress',
+    'house_exposure_cap', 'odds_unavailable', 'market_closed', 'pool_limit_reached', 'min_bet_not_met',
+    'max_bet_exceeded', 'feature_disabled', 'busy', 'rate_limited',
+]);
+function predictionNextHint(error) {
+    switch (error) {
+        case 'odds_changed':
+            return 'The price or line moved. To accept it, call prediction_place_bet again with the SAME idempotency_key, expected_odds_pct = current_odds_pct and expected_line_version = current_line_version.';
+        case 'position_cap_exceeded':
+            return 'Stake at most remaining_capacity_sats on this market, or pick another market. The cap is per operator across all of its agents.';
+        case 'budget_exceeded':
+            return 'Ask your operator to raise the budget (set_budget) or stake at most budget_remaining_sats.';
+        case 'insufficient_balance':
+            return 'Fund the agent first (fund_agent from the operator, or create_invoice and pay it), then retry with the same idempotency_key.';
+        case 'bet_in_progress':
+        case 'busy':
+            return 'Wait a few seconds and retry with the same idempotency_key.';
+        case 'rate_limited':
+            return 'You placed too many bets in the last minute. Wait retry_after seconds and retry with the same idempotency_key.';
+        case 'house_exposure_cap':
+            return 'The house cannot take more on this side right now. Try a smaller stake or the other side.';
+        case 'odds_unavailable':
+            return 'Betting is paused while the line updates. Re-read prediction_market shortly.';
+        case 'market_closed':
+            return 'This market no longer takes bets. List open markets with prediction_markets.';
+        case 'feature_disabled':
+            return 'Agent betting is not enabled on the server yet.';
+        default:
+            return 'Read the message field, adjust the stake or market, and retry with a fresh idempotency_key.';
+    }
+}
+const PredictionMyBetsSchema = zod_1.z.object({
+    status: zod_1.z.enum(['active', 'won', 'lost', 'refunded']).optional().describe('Filter by bet status'),
+    agent_id: zod_1.z.number().int().positive().optional().describe('Operator key only: limit to one agent'),
+    limit: zod_1.z.number().int().min(1).max(100).optional().describe('Rows to return (default 50)'),
+    offset: zod_1.z.number().int().min(0).optional().describe('Pagination offset'),
+});
 // List available tools
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools: [
@@ -505,7 +582,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                     url: { type: 'string', description: 'HTTPS webhook URL to receive events' },
                     events: {
                         type: 'array',
-                        items: { type: 'string', enum: ['invoice_paid', 'payment_completed', 'payment_failed', 'withdrawal_completed', 'balance_changed', 'balance_low', 'budget_warning', 'test'] },
+                        items: { type: 'string', enum: ['invoice_paid', 'payment_completed', 'payment_failed', 'withdrawal_completed', 'balance_changed', 'balance_low', 'budget_warning', 'bet_placed', 'bet_settled', 'test'] },
                         default: ['invoice_paid'],
                         description: 'Event types to subscribe to',
                     },
@@ -864,6 +941,139 @@ 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: {} },
+        },
+        {
+            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/',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    status: { type: 'string', enum: ['open', 'upcoming', 'closed', 'resolved', 'cancelled', 'all'], description: 'Default open' },
+                    market_type: { type: 'string', enum: ['sports', 'btc_price'] },
+                    category: { type: 'string', description: 'League or category key, e.g. nfl, nba, nhl, mlb, ncaaf, mma, epl, ucl, tennis, btc_daily' },
+                    limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Default 50' },
+                    offset: { type: 'integer', minimum: 0 },
+                },
+            },
+        },
+        {
+            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.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    market_id: { type: 'integer', minimum: 1, description: 'Market id from prediction_markets' },
+                },
+                required: ['market_id'],
+            },
+        },
+        {
+            name: 'prediction_place_bet',
+            description: 'Prediction markets: back yes or no on a market with sats from your agent balance. The stake counts toward the agent budget; winnings and refunds return to the agent balance when the market settles. Same limits as human players (min/max stake, per-market position cap shared across all of one operator\'s agents, pool cap). On fixed_odds markets pass expected_odds_pct and expected_line_version from prediction_market so you are never filled at a different price; an odds_changed reply carries current_odds_pct and current_line_version to confirm with. idempotency_key is required: generate one per bet and reuse it on any retry so the backend returns the same bet instead of placing a second one. REQUIRES AGENT KEY with balance (fund_agent first).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    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_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' },
+                },
+                required: ['market_id', 'position', 'amount_sats', 'idempotency_key'],
+                dependentRequired: { expected_odds_pct: ['expected_line_version'], expected_line_version: ['expected_odds_pct'] },
+            },
+        },
+        {
+            name: 'prediction_my_bets',
+            description: 'Prediction markets: your bets, newest first, with market title, status (active|won|lost|refunded), payout and profit. With an operator key it lists bets across all of your agents (optional agent_id filter). Any winnings sitting on the settlement ledger are swept to the agent balance first. REQUIRES AGENT OR OPERATOR KEY.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    status: { type: 'string', enum: ['active', 'won', 'lost', 'refunded'] },
+                    agent_id: { type: 'integer', minimum: 1, description: 'Operator key only: limit to one agent' },
+                    limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Default 50' },
+                    offset: { type: 'integer', minimum: 0 },
+                },
+            },
+        },
+        {
+            name: 'prediction_positions',
+            description: 'Prediction markets: open positions (stake per side per market, potential payout, close time) and total at stake. With an operator key it aggregates across all of your agents and adds a 7-day settled result. REQUIRES AGENT OR OPERATOR KEY.',
+            inputSchema: { type: 'object', properties: {} },
+        },
     ],
 }));
 // Handle tool calls
@@ -1198,7 +1408,17 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 const parsed = SetAgentCredentialsSchema.parse(args ?? {});
                 session.setClient(new lightning_faucet_js_1.LightningFaucetClient(parsed.api_key));
                 session.keySource = 'file';
-                const agSavedTo = (0, credentials_js_1.saveAgentKey)(parsed.api_key, {}, true);
+                // Best-effort identification so the saved entry carries the agent id.
+                let suppliedAgentId;
+                try {
+                    const me = await session.requireClient().whoami();
+                    if (me.type === 'agent' && me.id)
+                        suppliedAgentId = me.id;
+                }
+                catch {
+                    // Best effort: switching credentials must not fail because whoami did.
+                }
+                const agSavedTo = (0, credentials_js_1.saveAgentKey)(parsed.api_key, { id: suppliedAgentId }, true);
                 return {
                     content: [
                         {
@@ -1817,6 +2037,108 @@ 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) }] };
+            }
+            // ─── Prediction markets ───────────────────────────────────────────
+            case 'prediction_markets': {
+                const parsed = PredictionMarketsSchema.parse(args ?? {});
+                const filters = Object.fromEntries(Object.entries(parsed).filter(([, v]) => v !== undefined));
+                const c = session.getClient();
+                const result = c ? await c.predictionMarkets(filters) : await (0, lightning_faucet_js_1.getPublicAction)('prediction_markets', filters);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'prediction_market': {
+                const parsed = PredictionMarketSchema.parse(args ?? {});
+                const c = session.getClient();
+                const result = c ? await c.predictionMarket(parsed.market_id) : await (0, lightning_faucet_js_1.getPublicAction)('prediction_market', { market_id: parsed.market_id });
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'prediction_place_bet': {
+                const parsed = PredictionPlaceBetSchema.parse(args ?? {});
+                // The caller owns the idempotency key (required by schema and by the backend).
+                // No key is ever generated here: a server-side cache of generated keys cannot
+                // survive restarts, credential switches or key rotation, and every such gap
+                // is a path to a duplicate real-money bet.
+                const idempotencyKey = parsed.idempotency_key;
+                try {
+                    const result = await session.requireClient().predictionPlaceBet(parsed);
+                    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+                }
+                catch (e) {
+                    // A refusal is information the model acts on (re-price, size down, fund),
+                    // not a failure: hand the backend's structured reply through unchanged.
+                    if (e instanceof lightning_faucet_js_1.ApiError && PREDICTION_REFUSALS.has(String(e.response.error ?? ''))) {
+                        const refusal = { ...e.response, idempotency_key: idempotencyKey, next: predictionNextHint(String(e.response.error)) };
+                        return { content: [{ type: 'text', text: JSON.stringify(refusal, null, 2) }] };
+                    }
+                    // Unknown outcome (timeout, network, 5xx): the bet may have been placed.
+                    // Surface the key so the retry is a replay, never a second bet.
+                    if (!(e instanceof lightning_faucet_js_1.ApiError)) {
+                        const uncertain = {
+                            success: false,
+                            error: 'uncertain_outcome',
+                            message: e instanceof Error ? e.message : String(e),
+                            idempotency_key: idempotencyKey,
+                            next: 'The bet may or may not have been placed. Retry prediction_place_bet with the SAME arguments and the SAME idempotency_key: the backend replays the bet if it landed and places it if it did not. Do NOT change the stake or side or the key, which would create a new bet.',
+                        };
+                        return { content: [{ type: 'text', text: JSON.stringify(uncertain, null, 2) }] };
+                    }
+                    throw e;
+                }
+            }
+            case 'prediction_my_bets': {
+                const parsed = PredictionMyBetsSchema.parse(args ?? {});
+                const filters = Object.fromEntries(Object.entries(parsed).filter(([, v]) => v !== undefined));
+                const result = await session.requireClient().predictionMyBets(filters);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'prediction_positions': {
+                const result = await session.requireClient().predictionPositions();
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
             default:
                 return {
                     content: [

package/dist/lightning-faucet.d.ts

@@ -543,6 +543,50 @@ 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>>;
+    /** List markets (public; with an agent key adds my_position). */
+    predictionMarkets(filters?: {
+        status?: string;
+        market_type?: string;
+        category?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Record<string, unknown>>;
+    /** One market in full. */
+    predictionMarket(marketId: number): Promise<Record<string, unknown>>;
+    /**
+     * Place a bet from the agent balance. idempotency_key is required by the
+     * backend; the MCP tool generates one when the model omits it. Refusals
+     * (odds_changed, position_cap_exceeded, ...) throw ApiError with the full
+     * structured reply in .response.
+     */
+    predictionPlaceBet(p: {
+        market_id: number;
+        position: 'yes' | 'no';
+        amount_sats: number;
+        idempotency_key: string;
+        expected_odds_pct?: number;
+        expected_line_version?: number;
+    }): Promise<Record<string, unknown>>;
+    /** My bets (agent key) or bets across my agents (operator key). */
+    predictionMyBets(filters?: {
+        status?: string;
+        agent_id?: number;
+        limit?: number;
+        offset?: number;
+    }): Promise<Record<string, unknown>>;
+    /** Open positions and total at stake. */
+    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.
@@ -589,6 +633,9 @@ export declare function getPublicDecodedInvoice(bolt11: string): Promise<{
     createdAt?: string;
     rawResponse: ApiResponse;
 }>;
+export type PublicReadAction = 'arena_list' | 'arena_leaderboard' | 'prediction_markets' | 'prediction_market';
+export declare function getPublicArena(action: 'arena_list' | 'arena_leaderboard', data?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function getPublicAction(action: PublicReadAction, 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,8 @@ exports.fetchWithTimeout = fetchWithTimeout;
 exports.registerOperator = registerOperator;
 exports.getPublicInfo = getPublicInfo;
 exports.getPublicDecodedInvoice = getPublicDecodedInvoice;
+exports.getPublicArena = getPublicArena;
+exports.getPublicAction = getPublicAction;
 exports.recoverOperatorAccount = recoverOperatorAccount;
 const pre_payment_hook_js_1 = require("./pre-payment-hook.js");
 const bolt11_js_1 = require("./bolt11.js");
@@ -910,6 +912,86 @@ 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');
+    }
+    // ─── Prediction markets (agents bet for their operators) ───────────────
+    /** List markets (public; with an agent key adds my_position). */
+    async predictionMarkets(filters = {}) {
+        const data = {};
+        for (const [k, v] of Object.entries(filters))
+            if (v !== undefined)
+                data[k] = v;
+        return this.request('prediction_markets', data);
+    }
+    /** One market in full. */
+    async predictionMarket(marketId) {
+        return this.request('prediction_market', { market_id: marketId });
+    }
+    /**
+     * Place a bet from the agent balance. idempotency_key is required by the
+     * backend; the MCP tool generates one when the model omits it. Refusals
+     * (odds_changed, position_cap_exceeded, ...) throw ApiError with the full
+     * structured reply in .response.
+     */
+    async predictionPlaceBet(p) {
+        const data = {
+            market_id: p.market_id,
+            position: p.position,
+            amount_sats: p.amount_sats,
+            idempotency_key: p.idempotency_key,
+        };
+        if (p.expected_odds_pct !== undefined)
+            data.expected_odds_pct = p.expected_odds_pct;
+        if (p.expected_line_version !== undefined)
+            data.expected_line_version = p.expected_line_version;
+        return this.request('prediction_place_bet', data);
+    }
+    /** My bets (agent key) or bets across my agents (operator key). */
+    async predictionMyBets(filters = {}) {
+        const data = {};
+        for (const [k, v] of Object.entries(filters))
+            if (v !== undefined)
+                data[k] = v;
+        return this.request('prediction_my_bets', data);
+    }
+    /** Open positions and total at stake. */
+    async predictionPositions() {
+        return this.request('prediction_positions');
+    }
     /**
      * 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 +1099,24 @@ async function getPublicDecodedInvoice(bolt11) {
         rawResponse: result,
     };
 }
+async function getPublicArena(action, data = {}) {
+    return getPublicAction(action, data);
+}
+async function getPublicAction(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.1",
+  "version": "1.8.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",