lightning-wallet-mcp 1.7.0 → 1.9.0

package/README.md

@@ -130,7 +130,7 @@ 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
 
@@ -138,6 +138,12 @@ Agents-only tournaments on lightningfaucet.com: humans build and fund an agent,
 
 `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
 
 ```
@@ -157,10 +163,10 @@ Every command prints JSON to stdout (add `--human` for a readable view). Errors
 
 ## Pricing
 
-- Platform fee: **1% of the amount, rounded down**. Payments under 100 sats pay no fee.
+- Platform fee: **1% of the amount, rounded down, no minimum** (payments under 100 sats pay no fee) on payments (`pay_invoice`, `pay_lightning_address`, `keysend`, `nostr_zap`) and on paid-API pay-through (`pay_l402_api`). Never more than 1%. `get_info` returns the live schedule as `platform_fees`.
 - Routing fees: charged at cost. An estimate is reserved up front (1% of the amount, at least 3 sats, at most 100) and the unused part is refunded after settlement. Pass `max_fee_sats` to override.
-- Deposits, receiving, same-operator agent transfers and webhooks: free.
-- Withdrawals: 1% platform fee plus routing, minimum 10 sats.
+- Deposits, receiving, operator-to-agent and same-operator agent transfers, and webhooks: free. A payment to another operator's agent pays the 1% payment fee.
+- Withdrawals to your own wallet (`withdraw`, `create_withdraw_link`): **no platform fee**, routing at cost, minimum 10 sats.
 - X402 payments: 1% platform fee plus a 1% exchange spread on the USDC conversion.
 
 Every payment response includes `platform_fee_sats`, `routing_fee_sats` and `total_cost`.
@@ -205,6 +211,10 @@ 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.

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({});
@@ -303,6 +303,64 @@ const ArenaLeaderboardSchema = zod_1.z.object({
 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: [
@@ -317,7 +375,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'pay_l402_api',
-            description: 'Make a request to a paid API. Supports L402 (Lightning) and X402 (USDC on Base) protocols. If payment is required (HTTP 402), automatically detects the protocol and pays. L402 is preferred when both are available. Works with an operator key (pays from the operator wallet; a default agent is provisioned automatically) or an agent key.',
+            description: 'Make a request to a paid API. Supports L402 (Lightning) and X402 (USDC on Base) protocols. Platform fee on the API price: 1%, rounded down, no minimum, reported as fee in the response. If payment is required (HTTP 402), automatically detects the protocol and pays. L402 is preferred when both are available. Works with an operator key (pays from the operator wallet; a default agent is provisioned automatically) or an agent key.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -342,7 +400,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'pay_invoice',
-            description: 'Pay a BOLT11 Lightning invoice. Returns the preimage as proof of payment. Works with an operator key (pays from the operator wallet; a default agent is provisioned automatically) or an agent key. If the response says pending:true the payment is still in flight: do NOT retry, check get_transactions instead.',
+            description: 'Pay a BOLT11 Lightning invoice. Platform fee: 1% of the amount, rounded down, no minimum (nothing under 100 sats), reported as platform_fee_sats; get_info returns the current schedule. Returns the preimage as proof of payment. Works with an operator key (pays from the operator wallet; a default agent is provisioned automatically) or an agent key. If the response says pending:true the payment is still in flight: do NOT retry, check get_transactions instead.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -453,7 +511,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'fund_agent',
-            description: 'Transfer sats from operator balance to an agent.',
+            description: 'Transfer sats from operator balance to an agent. No platform fee.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -524,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',
                     },
@@ -568,7 +626,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // ==========================================
         {
             name: 'get_budget_status',
-            description: 'Get budget status for an agent - shows limit, spent, and remaining. Works with operator or agent keys.',
+            description: 'Get budget status for an agent - shows limit, spent, remaining and the platform_fees schedule that counts against it. Works with operator or agent keys.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -644,7 +702,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // ==========================================
         {
             name: 'get_info',
-            description: 'Get service information including version, status, limits, and supported features. No API key required — works before registering.',
+            description: 'Get service information including version, status, limits, supported features and the current platform_fees schedule (percent and minimum per action). No API key required — works before registering.',
             inputSchema: {
                 type: 'object',
                 properties: {},
@@ -676,7 +734,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // ==========================================
         {
             name: 'withdraw',
-            description: 'Withdraw funds from the operator account to an external Lightning invoice (minimum 10 sats; 1% platform fee, none under 100 sats; unused routing reserve refunded). REQUIRES OPERATOR KEY. Subject to a security cooldown after key rotation.',
+            description: 'Withdraw funds from the operator account to an external Lightning invoice (minimum 10 sats; no platform fee, only the Lightning routing fee at cost; unused routing reserve refunded). REQUIRES OPERATOR KEY. Subject to a security cooldown after key rotation.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -687,7 +745,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'create_withdraw_link',
-            description: 'Create an LNURL-withdraw link for the operator to receive funds. Opens in browser for QR code scanning with any Lightning wallet. Omit amount_sats to sweep full balance (minimum 10 sats after fees). REQUIRES OPERATOR KEY.',
+            description: 'Create an LNURL-withdraw link for the operator to receive funds. Opens in browser for QR code scanning with any Lightning wallet. Omit amount_sats to sweep full balance (minimum 10 sats after the routing reserve). No platform fee. REQUIRES OPERATOR KEY.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -715,7 +773,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'pay_lightning_address',
-            description: 'Pay to a Lightning address (user@domain.com format). Works with an operator key (pays from the operator wallet) or an agent key.',
+            description: 'Pay to a Lightning address (user@domain.com format). Platform fee: 1% of the amount, rounded down, no minimum, reported as platform_fee_sats. Works with an operator key (pays from the operator wallet) or an agent key.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -750,7 +808,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'nostr_zap',
-            description: 'Send a Nostr zap (NIP-57 Lightning payment with optional Nostr event). If the recipient supports NIP-57, a proper zap receipt is created. Otherwise falls back to a regular Lightning address payment. REQUIRES AGENT KEY with Nostr identity set.',
+            description: 'Send a Nostr zap (NIP-57 Lightning payment with optional Nostr event). If the recipient supports NIP-57, a proper zap receipt is created. Otherwise falls back to a regular Lightning address payment. REQUIRES AGENT KEY with Nostr identity set. Paid as a Lightning-address payment: platform fee 1% of the amount, rounded down, no minimum, reported as platform_fee_sats.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -769,7 +827,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // ==========================================
         {
             name: 'transfer_to_agent',
-            description: 'Transfer sats between agents or from operator to agent. REQUIRES OPERATOR KEY.',
+            description: 'Transfer sats between agents or from operator to agent. No platform fee. REQUIRES OPERATOR KEY.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -819,7 +877,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'keysend',
-            description: 'Send a payment directly to a node without an invoice (keysend/spontaneous payment). REQUIRES AGENT KEY.',
+            description: 'Send a payment directly to a node without an invoice (keysend/spontaneous payment). Platform fee: 1% of the amount, rounded down, no minimum, reported as platform_fee_sats. REQUIRES AGENT KEY.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -956,6 +1014,66 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
             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
@@ -1290,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: [
                         {
@@ -1418,6 +1546,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                                 total_spent_sats: result.totalSpentSats,
                                 remaining_sats: result.remainingSats,
                                 has_budget: result.hasBudget,
+                                platform_fees: result.rawResponse?.platform_fees,
                             }, null, 2),
                         },
                     ],
@@ -1556,6 +1685,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                                 max_payment_sats: result.maxPaymentSats,
                                 min_payment_sats: result.minPaymentSats,
                                 supported_features: result.supportedFeatures,
+                                platform_fees: result.rawResponse?.platform_fees,
                             }, null, 2),
                         },
                     ],
@@ -1685,6 +1815,8 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                                 message: `Paid ${parsed.amount_sats} sats to ${parsed.address}`,
                                 amount_sats: result.amountSats,
                                 fee_sats: result.feeSats,
+                                routing_fee_sats: result.routingFeeSats,
+                                platform_fee_sats: result.platformFeeSats,
                                 payment_hash: result.paymentHash,
                                 new_balance: result.newBalance,
                             }, null, 2),
@@ -1741,6 +1873,8 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                                     (result.zapType === 'nip57' ? ' (NIP-57 zap receipt created)' : ' (regular payment, recipient does not support NIP-57)'),
                                 amount_sats: result.amountSats,
                                 fee_sats: result.feeSats,
+                                routing_fee_sats: result.routingFeeSats,
+                                platform_fee_sats: result.platformFeeSats,
                                 payment_hash: result.paymentHash,
                                 new_balance: result.newBalance,
                                 zap_type: result.zapType,
@@ -1954,6 +2088,63 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 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

@@ -522,6 +522,8 @@ export declare class LightningFaucetClient {
     nostrZap(address: string, amountSats: number, recipientPubkey?: string, content?: string, eventId?: string, relays?: string[]): Promise<{
         amountSats: number;
         feeSats: number;
+        routingFeeSats: number;
+        platformFeeSats: number;
         paymentHash: string;
         newBalance: number;
         zapType: 'nip57' | 'fallback';
@@ -554,6 +556,39 @@ export declare class LightningFaucetClient {
     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.
@@ -600,7 +635,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

@@ -11,6 +11,7 @@ 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");
@@ -863,9 +864,16 @@ class LightningFaucetClient {
         if (relays)
             data.relays = relays;
         const result = await this.request('nostr_zap', data);
+        // The backend settles a zap through the Lightning-address path, which reports
+        // routing_fee_sats and platform_fee_sats separately; keep the split so the tool
+        // can show the platform fee it advertised, plus the combined feeSats.
+        const routingFeeSats = result.routing_fee_sats || 0;
+        const platformFeeSats = result.platform_fee_sats || 0;
         return {
             amountSats: result.amount_sats || amountSats,
-            feeSats: result.fee_sats ?? ((result.routing_fee_sats || 0) + (result.platform_fee_sats || 0)),
+            feeSats: result.fee_sats ?? (routingFeeSats + platformFeeSats),
+            routingFeeSats,
+            platformFeeSats,
             paymentHash: result.payment_hash || '',
             newBalance: result.new_balance || 0,
             zapType: result.zap_type || 'fallback',
@@ -947,6 +955,50 @@ class LightningFaucetClient {
     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.
@@ -1054,8 +1106,10 @@ 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 = {}) {
+    return getPublicAction(action, data);
+}
+async function getPublicAction(action, data = {}) {
     const response = await fetchWithTimeout(API_BASE_URL, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },

package/package.json

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