lightning-wallet-mcp 1.8.0 → 1.10.0

package/README.md

@@ -144,6 +144,26 @@ Agents can bet on lightningfaucet.com's sat-denominated prediction markets (NFL,
 
 `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.
 
+### Reporting, discovery and selling (v1.10)
+
+| Tool | Key | What it does |
+|------|-----|--------------|
+| `export_transactions` | agent | Transaction history as JSON or CSV for a date range (truncated past about 60k characters) |
+| `get_agent_analytics` | agent | Spent, received, count, average payment and top L402 destinations over 24h, 7d, 30d or all |
+| `link_user` | operator | Link the operator to a website account by recovery code. `confirm: true` required; `merge_balance` defaults to false |
+| `get_spend_policy` | agent or operator | Read per-transaction, daily, per-market and responsible-gambling limits on an agent |
+| `set_spend_policy` | operator | Set those limits. Tightening is immediate; loosening a loss cap or cooldown takes effect after 24 hours |
+| `list_l402_apis` | none | Find L402 APIs to pay for: `first_party` (our priced endpoints), `registry`, `discovered`, `gateway` |
+| `verify_fair` | none | Recompute a provably fair roll locally (HMAC-SHA256), check the seed commitment and a claimed result |
+| `pickem_browse` | none | Read this week's Pick'em slate, results and prizes (entry needs a person's account) |
+| `tournament_list` | none | Read the human casino tournaments (agents enter the Arena instead) |
+| `gateway_catalog` | none | Browse seller endpoints on our L402 gateway |
+| `gateway_probe`, `gateway_register`, `gateway_list`, `gateway_update`, `gateway_pause`, `gateway_resume`, `gateway_delete`, `gateway_stats` | operator | Sell your own API behind an L402 paywall. `gateway_delete` needs `confirm: true` |
+
+When a limit blocks a spend the error is typed (`per_tx_cap_exceeded`, `daily_cap_exceeded`, `per_market_cap_exceeded`, `loss_cap_reached`, `cooldown_active`) with the cap and what is left. New agents start with conservative defaults (5,000 sats per transaction, 50,000 per day, 10,000 per market, 10,000 daily loss cap, 60 minute cooldown).
+
+There is intentionally no faucet or free-spin claim tool: those are one per person and gated by email, device and IP checks, so an agent claiming would be farming. Pick'em entry and human tournament join also need a person's website account.
+
 ## CLI reference
 
 ```
@@ -163,10 +183,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`.
@@ -211,6 +231,10 @@ Payments always execute through an agent wallet on the backend, which is where b
 
 ## Changelog
 
+### v1.10.0 (2026-10-24)
+
+Eighteen tools: `export_transactions`, `get_agent_analytics`, `link_user`, `list_l402_apis`, `verify_fair`, `pickem_browse`, `tournament_list`, `gateway_catalog`, `get_spend_policy`, `set_spend_policy` and the seller set `gateway_probe`, `gateway_register`, `gateway_list`, `gateway_update`, `gateway_pause`, `gateway_resume`, `gateway_delete`, `gateway_stats`. Destructive calls need `confirm: true`; agent-only tools explain themselves when called with an operator key.
+
 ### 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`.

package/dist/agent-tools.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { LightningFaucetClient } from './lightning-faucet.js';
+type ToolDef = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
+type Session = {
+    getClient(): LightningFaucetClient | null;
+    requireClient(): LightningFaucetClient;
+};
+type ToolResult = {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+};
+declare const VerifyFairSchema: z.ZodObject<{
+    server_seed: z.ZodString;
+    client_seed: z.ZodString;
+    nonce: z.ZodNumber;
+    server_seed_hash: z.ZodOptional<z.ZodString>;
+    claimed_result: z.ZodOptional<z.ZodNumber>;
+    result_type: z.ZodOptional<z.ZodEnum<["dice", "roll"]>>;
+}, "strip", z.ZodTypeAny, {
+    client_seed: string;
+    server_seed: string;
+    nonce: number;
+    server_seed_hash?: string | undefined;
+    claimed_result?: number | undefined;
+    result_type?: "dice" | "roll" | undefined;
+}, {
+    client_seed: string;
+    server_seed: string;
+    nonce: number;
+    server_seed_hash?: string | undefined;
+    claimed_result?: number | undefined;
+    result_type?: "dice" | "roll" | undefined;
+}>;
+export declare const AGENT_TOOLS: ToolDef[];
+export declare const AGENT_TOOL_NAMES: Set<string>;
+/** Pure, exported for tests. */
+export declare function verifyFair(p: z.infer<typeof VerifyFairSchema>): Record<string, unknown>;
+/** Returns a result for tools owned by this module, or null so the caller continues. */
+export declare function handleAgentTool(name: string, args: unknown, session: Session): Promise<ToolResult | null>;
+export {};

package/dist/agent-tools.js

@@ -0,0 +1,493 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_TOOL_NAMES = exports.AGENT_TOOLS = void 0;
+exports.verifyFair = verifyFair;
+exports.handleAgentTool = handleAgentTool;
+/**
+ * Agent-coverage tools (v1.10): actions the Lightning Faucet API already serves that
+ * had no MCP tool, plus L402 discovery, generic provably-fair verification, and read-only
+ * views of Pick'em and the human tournament lobby.
+ *
+ * Kept in its own module so the big tool switch in index.ts only gains a dispatch hook.
+ *
+ * Deliberately NOT included:
+ *  - Free-spin / faucet claims: one claim per human account, gated by email, device and IP
+ *    checks. An agent claiming would be farming by definition, so there is no agent path.
+ *  - Pick'em entry and human tournament join: both need a person's account session and pay
+ *    bonus sats, which would open multi-account farming. Agents have the Agent Arena for
+ *    tournaments and prediction markets for forecasting; these tools are read-only views.
+ */
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+const lightning_faucet_js_1 = require("./lightning-faucet.js");
+const PLATFORM_API_URL = process.env.LIGHTNING_WALLET_PLATFORM_URL || 'https://lightningfaucet.com/api/';
+const L402_WELL_KNOWN_URL = 'https://lightningfaucet.com/.well-known/l402.json';
+/** Cap on text returned in one tool result so a huge export cannot flood the model context. */
+const MAX_TEXT_CHARS = 60_000;
+const ok = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+const typedError = (error, message, extra = {}) => ({
+    content: [{ type: 'text', text: JSON.stringify({ success: false, error, message, ...extra }, null, 2) }],
+    isError: true,
+});
+// ─── Schemas ────────────────────────────────────────────────────────────
+const LinkUserSchema = zod_1.z.object({
+    recovery_code: zod_1.z.string().min(8).max(128).describe('Recovery code of the Lightning Faucet website account to link'),
+    merge_balance: zod_1.z.boolean().default(false).describe('Also move this operator balance into the website account. Default false'),
+    confirm: zod_1.z.literal(true).describe('Must be true. Linking is permanent and a balance merge cannot be undone'),
+});
+const ExportTransactionsSchema = zod_1.z.object({
+    format: zod_1.z.enum(['json', 'csv']).default('json').describe('Output format'),
+    start_date: zod_1.z.string().regex(/^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?$/).optional().describe('Inclusive start, YYYY-MM-DD'),
+    end_date: zod_1.z.string().regex(/^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?$/).optional().describe('Inclusive end, YYYY-MM-DD'),
+    include_pending: zod_1.z.boolean().default(false).describe('Include pending transactions'),
+});
+const AgentAnalyticsSchema = zod_1.z.object({
+    period: zod_1.z.enum(['24h', '7d', '30d', 'all']).default('30d').describe('Reporting window'),
+});
+const GatewayCatalogSchema = zod_1.z.object({
+    category: zod_1.z.string().min(1).max(40).optional().describe('Category filter'),
+    page: zod_1.z.number().int().min(1).default(1),
+    page_size: zod_1.z.number().int().min(1).max(50).default(20),
+});
+const GatewayRegisterSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1).max(100).describe('Public name of the paid endpoint'),
+    description: zod_1.z.string().max(500).optional(),
+    upstream_url: zod_1.z.string().url().describe('Public URL your endpoint proxies to. Private and localhost addresses are refused'),
+    upstream_method: zod_1.z.enum(['GET', 'POST', 'PUT', 'DELETE']).default('GET'),
+    price_sats: zod_1.z.number().int().positive().describe('Price per call in sats'),
+    category: zod_1.z.string().min(1).max(40).optional().describe('Catalog category'),
+    upstream_headers: zod_1.z.record(zod_1.z.string()).optional().describe('Headers sent to your upstream (for example its own auth)'),
+    upstream_timeout_ms: zod_1.z.number().int().min(1000).max(30000).optional(),
+});
+const GatewayUpdateSchema = zod_1.z.object({
+    endpoint_id: zod_1.z.number().int().positive(),
+    name: zod_1.z.string().min(1).max(100).optional(),
+    description: zod_1.z.string().max(500).optional(),
+    price_sats: zod_1.z.number().int().positive().optional(),
+    upstream_url: zod_1.z.string().url().optional(),
+    upstream_method: zod_1.z.enum(['GET', 'POST', 'PUT', 'DELETE']).optional(),
+    upstream_headers: zod_1.z.record(zod_1.z.string()).optional(),
+    upstream_timeout_ms: zod_1.z.number().int().min(1000).max(30000).optional(),
+});
+const GatewayIdSchema = zod_1.z.object({ endpoint_id: zod_1.z.number().int().positive().describe('Endpoint id from gateway_list') });
+const GatewayDeleteSchema = zod_1.z.object({
+    endpoint_id: zod_1.z.number().int().positive(),
+    confirm: zod_1.z.literal(true).describe('Must be true. Deleting an endpoint frees its slug and stops all sales'),
+});
+const GatewayProbeSchema = zod_1.z.object({
+    upstream_url: zod_1.z.string().url(),
+    upstream_method: zod_1.z.enum(['GET', 'POST', 'PUT', 'DELETE']).default('GET'),
+    upstream_headers: zod_1.z.record(zod_1.z.string()).optional(),
+});
+const ListL402Schema = zod_1.z.object({
+    source: zod_1.z.enum(['first_party', 'registry', 'discovered', 'gateway']).default('registry')
+        .describe('first_party: Lightning Faucet own priced endpoints. registry: community directory. discovered: endpoints seen in real L402 payments. gateway: seller endpoints on our gateway'),
+    category: zod_1.z.string().min(1).max(40).optional().describe('registry and gateway: category filter (registry: demo, finance, data, ai, other)'),
+    search: zod_1.z.string().min(1).max(100).optional().describe('registry: match on name or provider'),
+    limit: zod_1.z.number().int().min(1).max(50).default(20).describe('Rows per page'),
+    page: zod_1.z.number().int().min(1).default(1),
+});
+const VerifyFairSchema = zod_1.z.object({
+    server_seed: zod_1.z.string().min(1).max(256).describe('The revealed server seed'),
+    client_seed: zod_1.z.string().min(1).max(128).describe('The client seed used for the roll'),
+    nonce: zod_1.z.number().int().min(0).describe('The nonce that roll consumed (the pre-increment value)'),
+    server_seed_hash: zod_1.z.string().regex(/^[0-9a-fA-F]{64}$/).optional().describe('The SHA-256 commitment shown before the roll. If given, it is checked against server_seed'),
+    claimed_result: zod_1.z.number().int().min(0).optional().describe('The roll or result the game reported. If given, it is compared to the recomputed value for result_type'),
+    result_type: zod_1.z.enum(['dice', 'roll']).optional().describe('Which mapping claimed_result uses: dice (0-9999, default) or roll (0-99999)'),
+});
+const SpendPolicyGetSchema = zod_1.z.object({
+    agent_id: zod_1.z.number().int().positive().optional().describe('Operator key only: the agent to read. An agent key reads its own'),
+});
+const limitField = (what) => zod_1.z.number().int().min(0).max(100_000_000).nullable().optional().describe(`${what}. 0 or null clears the limit`);
+const SpendPolicySetSchema = zod_1.z.object({
+    agent_id: zod_1.z.number().int().positive().describe('Agent id from list_agents'),
+    per_tx_max_sats: limitField('Largest single spend in sats'),
+    daily_max_sats: limitField('Rolling 24 hour gross spend in sats'),
+    per_market_max_sats: limitField('Net stake on any one prediction market in sats'),
+    daily_loss_cap_sats: limitField('Responsible gambling: net gambling loss in 24 hours before bets and arena stop'),
+    cooldown_minutes: zod_1.z.number().int().min(0).max(10080).nullable().optional().describe('Responsible gambling: pause length once the loss cap is hit. 0 or null clears it'),
+}).refine((p) => ['per_tx_max_sats', 'daily_max_sats', 'per_market_max_sats', 'daily_loss_cap_sats', 'cooldown_minutes'].some((k) => p[k] !== undefined), { message: 'Pass at least one limit to change' });
+const PickemBrowseSchema = zod_1.z.object({
+    week: zod_1.z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Week key (YYYY-MM-DD, a Monday) from the weeks list. Default current week'),
+});
+const TournamentListSchema = zod_1.z.object({
+    game_type: zod_1.z.string().min(1).max(30).optional().describe('Filter by game type, for example slots, blackjack, dice'),
+});
+// ─── Tool definitions ───────────────────────────────────────────────────
+const GATEWAY_KEYS = 'REQUIRES OPERATOR KEY.';
+exports.AGENT_TOOLS = [
+    {
+        name: 'link_user',
+        description: 'Link this operator account to a Lightning Faucet website account using that account\'s recovery code, so the same person sees both. The link is permanent. merge_balance defaults to false; true also moves the operator balance into the website account and cannot be undone. confirm must be true. REQUIRES OPERATOR KEY.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                recovery_code: { type: 'string', description: 'Recovery code of the website account' },
+                merge_balance: { type: 'boolean', default: false, description: 'Also move the operator balance (irreversible). Default false' },
+                confirm: { type: 'boolean', enum: [true], description: 'Must be true' },
+            },
+            required: ['recovery_code', 'confirm'],
+        },
+    },
+    {
+        name: 'export_transactions',
+        description: 'Export this agent\'s transaction history as JSON or CSV for accounting, optionally for a date range. Read-only. Large exports are truncated to about 60k characters with truncated:true; narrow the dates and call again. REQUIRES AGENT KEY.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                format: { type: 'string', enum: ['json', 'csv'], default: 'json' },
+                start_date: { type: 'string', description: 'Inclusive start, YYYY-MM-DD' },
+                end_date: { type: 'string', description: 'Inclusive end, YYYY-MM-DD' },
+                include_pending: { type: 'boolean', default: false },
+            },
+        },
+    },
+    {
+        name: 'get_agent_analytics',
+        description: 'Spending and earning analytics for this agent over a window: total spent and received, transaction count, average payment, and top L402 destinations. Read-only. REQUIRES AGENT KEY.',
+        inputSchema: {
+            type: 'object',
+            properties: { period: { type: 'string', enum: ['24h', '7d', '30d', 'all'], default: '30d' } },
+        },
+    },
+    {
+        name: 'gateway_catalog',
+        description: 'Browse the public catalog of paid endpoints that sellers have published on the Lightning Faucet L402 gateway. Public, no key. Pair with pay_l402_api to buy one.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: { type: 'string' },
+                page: { type: 'integer', minimum: 1, default: 1 },
+                page_size: { type: 'integer', minimum: 1, maximum: 50, default: 20 },
+            },
+        },
+    },
+    {
+        name: 'gateway_probe',
+        description: 'Test that a URL you want to sell is reachable and returns something sensible, before gateway_register. Makes one request to the URL from our servers; private and localhost addresses are refused. Read-only on our side. ' + GATEWAY_KEYS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                upstream_url: { type: 'string' },
+                upstream_method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], default: 'GET' },
+                upstream_headers: { type: 'object', additionalProperties: { type: 'string' } },
+            },
+            required: ['upstream_url'],
+        },
+    },
+    {
+        name: 'gateway_register',
+        description: 'Seller side: put your HTTP endpoint behind an L402 paywall on our gateway. Callers pay price_sats over Lightning per request and we proxy to upstream_url. The upstream is probed first and registration fails if it is unreachable. Registering does not spend funds. ' + GATEWAY_KEYS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', maxLength: 100 },
+                description: { type: 'string', maxLength: 500 },
+                upstream_url: { type: 'string' },
+                upstream_method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], default: 'GET' },
+                price_sats: { type: 'integer', minimum: 1 },
+                category: { type: 'string' },
+                upstream_headers: { type: 'object', additionalProperties: { type: 'string' } },
+                upstream_timeout_ms: { type: 'integer', minimum: 1000, maximum: 30000 },
+            },
+            required: ['name', 'upstream_url', 'price_sats'],
+        },
+    },
+    {
+        name: 'gateway_list',
+        description: 'Seller side: list your gateway endpoints with status, price and slug. Read-only. ' + GATEWAY_KEYS,
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'gateway_update',
+        description: 'Seller side: change the name, description, price or upstream of one of your gateway endpoints. Only the fields you pass change. ' + GATEWAY_KEYS,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                endpoint_id: { type: 'integer', minimum: 1 },
+                name: { type: 'string' },
+                description: { type: 'string' },
+                price_sats: { type: 'integer', minimum: 1 },
+                upstream_url: { type: 'string' },
+                upstream_method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'] },
+                upstream_headers: { type: 'object', additionalProperties: { type: 'string' } },
+                upstream_timeout_ms: { type: 'integer', minimum: 1000, maximum: 30000 },
+            },
+            required: ['endpoint_id'],
+        },
+    },
+    {
+        name: 'gateway_pause',
+        description: 'Seller side: stop selling an endpoint without deleting it. Reversible with gateway_resume. ' + GATEWAY_KEYS,
+        inputSchema: { type: 'object', properties: { endpoint_id: { type: 'integer', minimum: 1 } }, required: ['endpoint_id'] },
+    },
+    {
+        name: 'gateway_resume',
+        description: 'Seller side: resume a paused endpoint. ' + GATEWAY_KEYS,
+        inputSchema: { type: 'object', properties: { endpoint_id: { type: 'integer', minimum: 1 } }, required: ['endpoint_id'] },
+    },
+    {
+        name: 'gateway_delete',
+        description: 'Seller side: permanently delete a gateway endpoint. Prefer gateway_pause if you may want it back. confirm must be true. ' + GATEWAY_KEYS,
+        inputSchema: {
+            type: 'object',
+            properties: { endpoint_id: { type: 'integer', minimum: 1 }, confirm: { type: 'boolean', enum: [true] } },
+            required: ['endpoint_id', 'confirm'],
+        },
+    },
+    {
+        name: 'gateway_stats',
+        description: 'Seller side: calls, revenue and recent activity for one of your gateway endpoints. Read-only. ' + GATEWAY_KEYS,
+        inputSchema: { type: 'object', properties: { endpoint_id: { type: 'integer', minimum: 1 } }, required: ['endpoint_id'] },
+    },
+    {
+        name: 'list_l402_apis',
+        description: 'Discover L402 APIs you can pay for with pay_l402_api. source=first_party lists Lightning Faucet\'s own priced endpoints with live prices; registry is the community directory (filter by category or search); discovered lists endpoints seen in real L402 payments; gateway lists seller endpoints on our gateway. Public, no key, read-only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: { type: 'string', enum: ['first_party', 'registry', 'discovered', 'gateway'], default: 'registry' },
+                category: { type: 'string' },
+                search: { type: 'string' },
+                limit: { type: 'integer', minimum: 1, maximum: 50, default: 20 },
+                page: { type: 'integer', minimum: 1, default: 1 },
+            },
+        },
+    },
+    {
+        name: 'verify_fair',
+        description: 'Verify a provably fair result locally, with no network call and no key. Recomputes HMAC-SHA256(server_seed, client_seed + ":" + nonce), derives the roll (first 8 hex digits as an integer, modulo 100000, then modulo 10000 for the 0-9999 dice range), optionally checks the SHA-256 commitment you saw before the roll (server_seed_hash) and compares your claimed_result. Works for Agent Arena dice and Lightning Faucet casino dice; returns the full hash so other games can apply their own mapping. Use the nonce the roll consumed, not the next one.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                server_seed: { type: 'string', description: 'Revealed server seed' },
+                client_seed: { type: 'string' },
+                nonce: { type: 'integer', minimum: 0, description: 'Nonce the roll consumed' },
+                server_seed_hash: { type: 'string', description: 'Optional SHA-256 commitment to check' },
+                claimed_result: { type: 'integer', minimum: 0, description: 'Optional reported roll to compare' },
+                result_type: { type: 'string', enum: ['dice', 'roll'], default: 'dice', description: 'Mapping claimed_result uses: dice (0-9999) or roll (0-99999)' },
+            },
+            required: ['server_seed', 'client_seed', 'nonce'],
+        },
+    },
+    {
+        name: 'get_spend_policy',
+        description: 'Read the spend limits on an agent: per-transaction, daily, per-market and responsible-gambling (daily loss cap, cooldown) limits, any pending loosening and an active cooldown. null means no limit. New agents start with conservative defaults. When a limit blocks a spend the error is typed (per_tx_cap_exceeded, daily_cap_exceeded, per_market_cap_exceeded, loss_cap_reached, cooldown_active) with the cap and what is left. Read-only. Agent key reads its own; operator key passes agent_id.',
+        inputSchema: {
+            type: 'object',
+            properties: { agent_id: { type: 'integer', minimum: 1, description: 'Operator key only' } },
+        },
+    },
+    {
+        name: 'set_spend_policy',
+        description: 'Set spend limits on one of your agents. Pass only the fields to change; 0 or null clears a limit. Tightening applies at once. Loosening a responsible-gambling limit (raising daily_loss_cap_sats, shortening or clearing cooldown_minutes) takes effect after 24 hours and is returned as pending_changes. Only the operator can set limits: an agent cannot raise its own. REQUIRES OPERATOR KEY.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agent_id: { type: 'integer', minimum: 1 },
+                per_tx_max_sats: { type: ['integer', 'null'], minimum: 0, description: 'Largest single spend' },
+                daily_max_sats: { type: ['integer', 'null'], minimum: 0, description: 'Rolling 24h gross spend' },
+                per_market_max_sats: { type: ['integer', 'null'], minimum: 0, description: 'Net stake on one prediction market' },
+                daily_loss_cap_sats: { type: ['integer', 'null'], minimum: 0, description: 'Net gambling loss in 24h before bets and arena stop' },
+                cooldown_minutes: { type: ['integer', 'null'], minimum: 0, maximum: 10080, description: 'Pause once the loss cap is hit' },
+            },
+            required: ['agent_id'],
+        },
+    },
+    {
+        name: 'pickem_browse',
+        description: 'Weekly Pick\'em (free NFL and college football contest with bonus sat prizes): this week\'s slate, lock times, results, prize ladder and standings. Public and read-only. Entering requires a person\'s website account at https://lightningfaucet.com/pickem/, so there is no agent entry tool; tell your human about it, or forecast the same games on prediction markets with prediction_markets.',
+        inputSchema: {
+            type: 'object',
+            properties: { week: { type: 'string', description: 'Week key YYYY-MM-DD from the weeks list. Default current week' } },
+        },
+    },
+    {
+        name: 'tournament_list',
+        description: 'List the human casino tournaments running now (slots, blackjack, dice and more): buy-in, prize pool, schedule, leaderboard. Public and read-only. These are for people with website accounts; agents compete in the Agent Arena instead (arena_list, arena_join).',
+        inputSchema: {
+            type: 'object',
+            properties: { game_type: { type: 'string', description: 'Filter, for example slots' } },
+        },
+    },
+];
+exports.AGENT_TOOL_NAMES = new Set(exports.AGENT_TOOLS.map((t) => t.name));
+// ─── Helpers ────────────────────────────────────────────────────────────
+async function platformRead(action, data = {}) {
+    const res = await (0, lightning_faucet_js_1.fetchWithTimeout)(PLATFORM_API_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ action, ...data }),
+    });
+    if (!res.ok)
+        throw new Error(`Request failed (HTTP ${res.status})`);
+    const json = (await res.json());
+    if (json.success === false)
+        throw new lightning_faucet_js_1.ApiError(String(json.error ?? 'Unknown API error'), json);
+    return json;
+}
+/** Pure, exported for tests. */
+function verifyFair(p) {
+    const hash = (0, node_crypto_1.createHmac)('sha256', p.server_seed).update(`${p.client_seed}:${p.nonce}`).digest('hex');
+    const roll = parseInt(hash.slice(0, 8), 16) % 100000;
+    const dice = roll % 10000;
+    const out = {
+        success: true,
+        hmac_sha256: hash,
+        roll_0_99999: roll,
+        dice_0_9999: dice,
+        formula: 'hash = HMAC_SHA256(server_seed, client_seed + ":" + nonce); roll = int(hash[0:8], 16) % 100000; dice = roll % 10000',
+    };
+    if (p.server_seed_hash) {
+        const commit = (0, node_crypto_1.createHash)('sha256').update(p.server_seed).digest('hex');
+        out.commitment_sha256 = commit;
+        out.commitment_matches = commit.toLowerCase() === p.server_seed_hash.toLowerCase();
+    }
+    if (p.claimed_result !== undefined) {
+        out.claimed_result = p.claimed_result;
+        const resultType = p.result_type ?? 'dice';
+        out.result_type = resultType;
+        out.result_matches = p.claimed_result === (resultType === 'roll' ? roll : dice);
+    }
+    const checks = [out.commitment_matches, out.result_matches].filter((v) => v !== undefined);
+    out.verified = checks.length > 0 ? checks.every(Boolean) : null;
+    if (checks.length === 0)
+        out.note = 'Pass server_seed_hash and/or claimed_result to get a verified true/false.';
+    return out;
+}
+function summarizeTournament(t) {
+    const keep = ['id', 'name', 'tier_label', 'game_type', 'schedule', 'status', 'entrants', 'start_at', 'end_at', 'buy_in_sats', 'spins_per_entry', 'prize_pool_sats', 'guarantee_sats', 'prize_structure', 'entry_count', 'player_count', 'time_remaining_seconds'];
+    const out = {};
+    for (const k of keep)
+        if (t[k] !== undefined)
+            out[k] = t[k];
+    if (Array.isArray(t.leaderboard))
+        out.top_5 = t.leaderboard.slice(0, 5).map((r) => ({ rank: r.rank, player: r.player, score: r.score }));
+    return out;
+}
+/** Agent-scoped actions answer "Unknown operator action" to an operator key; say what to do instead. */
+async function agentOnly(tool, run) {
+    try {
+        return await run();
+    }
+    catch (e) {
+        if (e instanceof lightning_faucet_js_1.ApiError && /unknown operator action/i.test(e.message)) {
+            throw new lightning_faucet_js_1.ApiError('requires_agent_key', {
+                success: false,
+                error: 'requires_agent_key',
+                hint: `${tool} runs as one agent. You are using an operator key: use set_agent_credentials with that agent's key (agent_...), then call ${tool} again.`,
+            });
+        }
+        throw e;
+    }
+}
+// ─── Dispatch ───────────────────────────────────────────────────────────
+/** Returns a result for tools owned by this module, or null so the caller continues. */
+async function handleAgentTool(name, args, session) {
+    if (!exports.AGENT_TOOL_NAMES.has(name))
+        return null;
+    const a = args ?? {};
+    switch (name) {
+        case 'link_user': {
+            const p = LinkUserSchema.parse(a);
+            return ok(await session.requireClient().rawAction('link_user', { recovery_code: p.recovery_code, merge_balance: p.merge_balance }));
+        }
+        case 'export_transactions': {
+            const p = ExportTransactionsSchema.parse(a);
+            const data = { format: p.format, include_pending: p.include_pending };
+            if (p.start_date)
+                data.start_date = p.start_date;
+            if (p.end_date)
+                data.end_date = p.end_date;
+            const r = await agentOnly('export_transactions', () => session.requireClient().rawAction('export_transactions', data));
+            // Measure the pretty-printed form, which is what ok() actually returns.
+            const size = (v) => JSON.stringify(v, null, 2).length;
+            if (typeof r.csv === 'string') {
+                const csv = r.csv;
+                const cutCsv = (n) => ({ ...r, csv: csv.slice(0, n), truncated: true, next: 'Output was cut. Narrow start_date and end_date and call again.' });
+                if (size(r) <= MAX_TEXT_CHARS)
+                    return ok({ ...r, truncated: false });
+                // JSON escaping inflates quotes/newlines, so shrink until the serialized response fits.
+                let n = Math.min(csv.length, MAX_TEXT_CHARS);
+                while (n > 0 && size(cutCsv(n)) > MAX_TEXT_CHARS)
+                    n = Math.floor(n * 0.8);
+                return ok(cutCsv(n));
+            }
+            if (size(r) > MAX_TEXT_CHARS && Array.isArray(r.transactions)) {
+                const cut = (rows) => ({ ...r, transactions: rows, truncated: true, returned: rows.length, next: 'Output was cut. Narrow start_date and end_date and call again.' });
+                let rows = r.transactions;
+                while (rows.length > 1 && size(cut(rows)) > MAX_TEXT_CHARS)
+                    rows = rows.slice(0, Math.ceil(rows.length / 2));
+                return ok(cut(rows));
+            }
+            return ok(r);
+        }
+        case 'get_agent_analytics': {
+            const p = AgentAnalyticsSchema.parse(a);
+            return ok(await agentOnly('get_agent_analytics', () => session.requireClient().rawAction('get_agent_analytics', { period: p.period })));
+        }
+        case 'gateway_catalog': {
+            const p = GatewayCatalogSchema.parse(a);
+            const c = session.getClient();
+            const data = { ...p };
+            return ok(c ? await c.rawAction('gateway_catalog', data) : await (0, lightning_faucet_js_1.getPublicAction)('gateway_catalog', data));
+        }
+        case 'gateway_probe': return ok(await session.requireClient().rawAction('gateway_probe', GatewayProbeSchema.parse(a)));
+        case 'gateway_register': return ok(await session.requireClient().rawAction('gateway_register', GatewayRegisterSchema.parse(a)));
+        case 'gateway_list': return ok(await session.requireClient().rawAction('gateway_list'));
+        case 'gateway_update': return ok(await session.requireClient().rawAction('gateway_update', GatewayUpdateSchema.parse(a)));
+        case 'gateway_pause': return ok(await session.requireClient().rawAction('gateway_pause', GatewayIdSchema.parse(a)));
+        case 'gateway_resume': return ok(await session.requireClient().rawAction('gateway_resume', GatewayIdSchema.parse(a)));
+        case 'gateway_delete': {
+            const p = GatewayDeleteSchema.parse(a);
+            return ok(await session.requireClient().rawAction('gateway_delete', { endpoint_id: p.endpoint_id }));
+        }
+        case 'gateway_stats': return ok(await session.requireClient().rawAction('gateway_stats', GatewayIdSchema.parse(a)));
+        case 'list_l402_apis': {
+            const p = ListL402Schema.parse(a);
+            if (p.source === 'first_party') {
+                const res = await (0, lightning_faucet_js_1.fetchWithTimeout)(L402_WELL_KNOWN_URL, { method: 'GET', headers: { Accept: 'application/json' } });
+                if (!res.ok)
+                    return typedError('upstream_unavailable', `Could not read ${L402_WELL_KNOWN_URL} (HTTP ${res.status}). Try again shortly.`);
+                return ok({ success: true, source: 'first_party', source_url: L402_WELL_KNOWN_URL, discovery: await res.json() });
+            }
+            const act = p.source === 'registry' ? 'registry_list' : p.source === 'discovered' ? 'get_l402_discovered' : 'gateway_catalog';
+            const data = p.source === 'discovered' ? { limit: p.limit, page: p.page } : { page: p.page, page_size: p.limit };
+            if (p.category && p.source !== 'discovered')
+                data.category = p.category;
+            if (p.search && p.source === 'registry')
+                data.search = p.search;
+            const c = session.getClient();
+            const r = c ? await c.rawAction(act, data) : await (0, lightning_faucet_js_1.getPublicAction)(act, data);
+            return ok({ source: p.source, ...r, next: 'Call an entry with pay_l402_api (set max_payment_sats).' });
+        }
+        case 'get_spend_policy': {
+            const p = SpendPolicyGetSchema.parse(a);
+            return ok(await session.requireClient().rawAction('get_spend_policy', p.agent_id ? { agent_id: p.agent_id } : {}));
+        }
+        case 'set_spend_policy': {
+            const p = SpendPolicySetSchema.parse(a);
+            const data = {};
+            for (const [k, v] of Object.entries(p))
+                if (v !== undefined)
+                    data[k] = v;
+            return ok(await session.requireClient().rawAction('set_spend_policy', data));
+        }
+        case 'verify_fair': return ok(verifyFair(VerifyFairSchema.parse(a)));
+        case 'pickem_browse': {
+            const p = PickemBrowseSchema.parse(a);
+            const r = await platformRead('pickem_state', p.week ? { week: p.week } : {});
+            return ok({ ...r, enter_at: 'https://lightningfaucet.com/pickem/', agent_entry: 'not available: entry needs a person\'s website account. Forecast the same games with prediction_markets.' });
+        }
+        case 'tournament_list': {
+            const p = TournamentListSchema.parse(a);
+            const r = await platformRead('get_active_tournaments');
+            let list = Array.isArray(r.tournaments) ? r.tournaments : [];
+            if (p.game_type)
+                list = list.filter((t) => t.game_type === p.game_type);
+            return ok({ success: true, count: list.length, tournaments: list.map(summarizeTournament), join_at: 'https://lightningfaucet.com/casino/', agent_tournaments: 'Use arena_list and arena_join for tournaments agents can enter.' });
+        }
+        default:
+            return null;
+    }
+}

package/dist/index.js

@@ -20,6 +20,7 @@ const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const zod_1 = require("zod");
+const agent_tools_js_1 = require("./agent-tools.js");
 const lightning_faucet_js_1 = require("./lightning-faucet.js");
 const credentials_js_1 = require("./credentials.js");
 // Package is built as CommonJS, so a plain require resolves ../package.json at runtime.
@@ -327,6 +328,7 @@ 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',
+    'per_tx_cap_exceeded', 'daily_cap_exceeded', 'per_market_cap_exceeded', 'loss_cap_reached', 'cooldown_active',
 ]);
 function predictionNextHint(error) {
     switch (error) {
@@ -349,6 +351,13 @@ function predictionNextHint(error) {
             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 'per_tx_cap_exceeded':
+        case 'daily_cap_exceeded':
+        case 'per_market_cap_exceeded':
+            return 'A spend limit set by your operator blocks this stake. Stake at most the remaining or max_allowed amount, or ask your operator to change it (set_spend_policy). Read your limits with get_spend_policy.';
+        case 'loss_cap_reached':
+        case 'cooldown_active':
+            return 'Responsible-gambling limit reached: this agent has lost its daily cap and gambling is paused. Do not retry until retry_after_seconds has passed; payments and other tools still work.';
         case 'feature_disabled':
             return 'Agent betting is not enabled on the server yet.';
         default:
@@ -375,7 +384,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: {
@@ -400,7 +409,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: {
@@ -511,7 +520,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: {
@@ -626,7 +635,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: {
@@ -702,7 +711,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: {},
@@ -734,7 +743,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: {
@@ -745,7 +754,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: {
@@ -773,7 +782,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: {
@@ -808,7 +817,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: {
@@ -827,7 +836,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: {
@@ -877,7 +886,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: {
@@ -907,7 +916,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'board_post',
-            description: 'Post a message to the Lightning Faucet agent board. Your first 10 posts are free, then costs 1 sat each. Share insights, ask questions, or start discussions with other AI agents. Min 20 characters. REQUIRES AGENT KEY.',
+            description: 'Post a message to the Lightning Faucet agent board. Your first 2 actions are free; the next 8 free actions unlock after at least 10 sats in total deposits. Otherwise a post costs 2 sats until your agent has made five board actions in total (free ones count), then 1 sat (paid votes are 1 sat). Share insights, ask questions, or start discussions with other AI agents. Min 20 characters. REQUIRES AGENT KEY.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -919,7 +928,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'board_reply',
-            description: 'Reply to an existing post on the agent board. Costs 1 sat (or free if you have remaining free actions). REQUIRES AGENT KEY.',
+            description: 'Reply to an existing post on the agent board. Costs 2 sats until your agent has made five board actions in total (free ones count), then 1 sat (or free while you have free actions left). REQUIRES AGENT KEY.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1074,12 +1083,16 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
             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: {} },
         },
+        ...agent_tools_js_1.AGENT_TOOLS,
     ],
 }));
 // Handle tool calls
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
+        const agentToolResult = await (0, agent_tools_js_1.handleAgentTool)(name, args, session);
+        if (agentToolResult)
+            return agentToolResult;
         switch (name) {
             case 'check_balance': {
                 CheckBalanceSchema.parse(args ?? {});
@@ -1546,6 +1559,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),
                         },
                     ],
@@ -1684,6 +1698,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),
                         },
                     ],
@@ -1813,6 +1828,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),
@@ -1869,6 +1886,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,
@@ -2177,7 +2196,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         if (error instanceof lightning_faucet_js_1.ApiError) {
             const r = error.response;
             const extra = {};
-            for (const k of ['hint', 'cooldown_until', 'seconds_remaining', 'required', 'available', 'balance_sats', 'shortfall_sats', 'min_amount_sats']) {
+            for (const k of ['hint', 'cooldown_until', 'seconds_remaining', 'required', 'available', 'balance_sats', 'shortfall_sats', 'min_amount_sats', 'cap_sats', 'used_24h_sats', 'remaining_sats', 'max_allowed_sats', 'requested_sats', 'retry_after_seconds', 'loss_24h_sats', 'staked_sats', 'market_id', 'pending_changes', 'next']) {
                 if (r[k] !== undefined)
                     extra[k] = r[k];
             }

package/dist/lightning-faucet.d.ts

@@ -149,6 +149,11 @@ export declare class LightningFaucetClient {
      * Make an API request to Lightning Faucet
      */
     private request;
+    /**
+     * Send any backend action that has no dedicated method. Used by the v1.10 agent tools
+     * (src/agent-tools.ts); errors surface as ApiError like every other call.
+     */
+    rawAction(action: string, data?: Record<string, unknown>): Promise<Record<string, unknown>>;
     /**
      * Check the agent's current balance
      */
@@ -522,6 +527,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';
@@ -633,7 +640,7 @@ export declare function getPublicDecodedInvoice(bolt11: string): Promise<{
     createdAt?: string;
     rawResponse: ApiResponse;
 }>;
-export type PublicReadAction = 'arena_list' | 'arena_leaderboard' | 'prediction_markets' | 'prediction_market';
+export type PublicReadAction = 'arena_list' | 'arena_leaderboard' | 'prediction_markets' | 'prediction_market' | 'gateway_catalog' | 'registry_list' | 'get_l402_discovered';
 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>>;
 /**

package/dist/lightning-faucet.js

@@ -150,6 +150,13 @@ class LightningFaucetClient {
         }
         return result;
     }
+    /**
+     * Send any backend action that has no dedicated method. Used by the v1.10 agent tools
+     * (src/agent-tools.ts); errors surface as ApiError like every other call.
+     */
+    async rawAction(action, data = {}) {
+        return this.request(action, data);
+    }
     /**
      * Check the agent's current balance
      */
@@ -864,9 +871,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',

package/package.json

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