lightning-wallet-mcp 1.4.1 → 1.5.1

package/README.md

@@ -505,6 +505,74 @@ def verify_webhook(payload, signature, secret):
 
 Check the `X-Webhook-Signature` header against the payload.
 
+## Pre-Payment Policy Hook
+
+An optional, vendor-neutral hook lets an external policy endpoint **allow or deny a payment before it executes**. It is off by default — when `PRE_PAYMENT_HOOK_URL` is unset, behaviour is exactly as before. When set, every outgoing payment (`pay_l402_api`, `pay_invoice`, `keysend`, `pay_lightning_address`) is checked against your endpoint first; a denial aborts the payment before any funds move.
+
+This is useful for spending policies, approval workflows, compliance checks, or any external authorization layer. The hook protocol is generic, so any service implementing the request/response contract below can be wired in by configuration alone.
+
+### Configuration
+
+| Env var | Default | Description |
+|---|---|---|
+| `PRE_PAYMENT_HOOK_URL` | _(unset)_ | Policy endpoint to POST each payment proposal to. Unset disables the hook entirely. |
+| `PRE_PAYMENT_HOOK_TIMEOUT_MS` | `3000` | Per-request timeout in milliseconds. |
+| `PRE_PAYMENT_HOOK_FAIL_MODE` | `closed` | `closed` denies a payment if the hook errors or times out; `open` lets it proceed. Default is fail-closed. |
+
+```jsonc
+{
+  "mcpServers": {
+    "lightning-wallet": {
+      "command": "npx",
+      "args": ["lightning-wallet-mcp"],
+      "env": {
+        "LIGHTNING_WALLET_API_KEY": "your-api-key",
+        "PRE_PAYMENT_HOOK_URL": "https://your-policy-endpoint.example/hook"
+      }
+    }
+  }
+}
+```
+
+### Hook request (POST from the client)
+
+The proposal describes only the proposed payment — **it never includes your wallet API key**.
+
+```json
+{
+  "proposal_id": "f7e1…",
+  "agent_id": 42,
+  "protocol": "l402",
+  "destination_or_url": "https://api.example/paid-endpoint",
+  "amount_sats": null,
+  "max_payment_sats": 1000,
+  "method": "GET",
+  "ts": "2026-06-06T18:00:00.000Z"
+}
+```
+
+`protocol` is one of `l402`, `x402`, `bolt11`, `keysend`, `lnaddress`. `amount_sats` is the exact amount when it is known at hook time: for `keysend` and `lnaddress` it is the requested amount, and for `bolt11` it is decoded locally from the invoice (no extra API call). For `l402`/`x402` it is `null` because the amount is set by the payment challenge at execution time — there the hook enforces `max_payment_sats` (the agent-authorised ceiling) up front, and the exact settled amount is available afterward via [webhooks](#webhooks). `max_payment_sats` is the agent-authorised ceiling when applicable.
+
+**Exactly what leaves the wallet.** Only the eight fields above are sent to your hook endpoint: `proposal_id`, `agent_id`, `protocol`, `destination_or_url`, `amount_sats`, `max_payment_sats`, `method`, `ts`. The wallet API key and any other credentials are **never** included.
+
+**Coverage.** The hook gates every agent-initiated spend: `pay_l402_api`, `pay_invoice`, `keysend`, `pay_lightning_address`, and Nostr zaps. Operator-scoped fund management (withdrawals, agent funding, agent-to-agent transfers) is intentionally **not** gated — those are operator actions, not agent spends.
+
+### Hook response (your endpoint returns)
+
+```json
+{ "decision": "allow" }
+```
+
+```json
+{ "decision": "deny", "reason": { "code": "over_limit", "message": "Exceeds per-transaction limit" } }
+```
+
+- `allow` → the payment proceeds.
+- `deny` → the payment is aborted and the tool returns a `PolicyDenied` error surfacing `reason.message`.
+- An optional `attestation` field (any JSON) is treated as opaque by the client — it is logged to stderr and otherwise ignored, so a policy service can return a signed decision for downstream auditing.
+
+On a hook error, timeout, or unrecognized response, the `PRE_PAYMENT_HOOK_FAIL_MODE` applies (deny by default).
+
 ## Pricing
 
 Lightning Faucet charges a 2% platform fee (min 1 sat) on outgoing payments:

package/dist/bolt11.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimal, dependency-free BOLT11 amount decoder.
+ *
+ * Reads only the amount from the invoice's human-readable prefix (HRP). It does
+ * NOT bech32-decode the data part and makes no network call. Returns the amount
+ * in sats, or null when the invoice is amountless or cannot be confidently
+ * parsed — callers treat null as "amount unknown" and degrade gracefully.
+ */
+export declare function bolt11AmountSats(invoice: string): number | null;

package/dist/bolt11.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Minimal, dependency-free BOLT11 amount decoder.
+ *
+ * Reads only the amount from the invoice's human-readable prefix (HRP). It does
+ * NOT bech32-decode the data part and makes no network call. Returns the amount
+ * in sats, or null when the invoice is amountless or cannot be confidently
+ * parsed — callers treat null as "amount unknown" and degrade gracefully.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bolt11AmountSats = bolt11AmountSats;
+// msats per 1 unit of each multiplier (1 BTC = 1e11 msat).
+const MSAT_PER_UNIT = {
+    m: 1e8, // milli  (1e-3 BTC)
+    u: 1e5, // micro  (1e-6 BTC)
+    n: 1e2, // nano   (1e-9 BTC)
+    p: 1e-1, // pico  (1e-12 BTC)
+};
+function bolt11AmountSats(invoice) {
+    try {
+        const lower = invoice.trim().toLowerCase();
+        if (!lower.startsWith('ln'))
+            return null;
+        // The bech32 data part never contains '1', so the LAST '1' is the separator
+        // between the human-readable prefix and the data.
+        const sep = lower.lastIndexOf('1');
+        if (sep < 1)
+            return null;
+        const hrp = lower.slice(0, sep);
+        // hrp = 'ln' + currency-prefix + <digits><multiplier?>. Amountless invoices
+        // (no digits) and unknown currency prefixes do not match → null.
+        const match = hrp.match(/^ln(?:bcrt|bc|tb|sb)(\d+)([munp])?$/);
+        if (!match)
+            return null;
+        const digits = match[1];
+        const multiplier = match[2];
+        let msat;
+        if (multiplier) {
+            const factor = MSAT_PER_UNIT[multiplier];
+            if (factor === undefined)
+                return null;
+            msat = Number(digits) * factor;
+        }
+        else {
+            msat = Number(digits) * 1e11; // whole BTC
+        }
+        if (!Number.isFinite(msat) || msat < 0)
+            return null;
+        return Math.round(msat / 1000);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.js

@@ -85,7 +85,7 @@ const PayL402ApiSchema = zod_1.z.object({
         .describe('Maximum amount in satoshis to pay for this request'),
 });
 const PayInvoiceSchema = zod_1.z.object({
-    bolt11: zod_1.z.string().regex(/^ln(bc|tb|bcrt)1[a-z0-9]+$/i, 'Invalid BOLT11 invoice format')
+    bolt11: zod_1.z.string().regex(/^ln(bc|tb|bcrt)([0-9]+[munp]?)?1[a-z0-9]+$/i, 'Invalid BOLT11 invoice format')
         .describe('BOLT11 invoice string to pay (starts with lnbc...)'),
     max_fee_sats: zod_1.z.number().min(0).optional()
         .describe('Maximum routing fee in satoshis (default: 10% of invoice amount)'),
@@ -98,7 +98,7 @@ const GetInvoiceStatusSchema = zod_1.z.object({
     payment_hash: zod_1.z.string().describe('Payment hash of the invoice to check'),
 });
 const GetTransactionsSchema = zod_1.z.object({
-    limit: zod_1.z.number().min(1).max(200).default(50).describe('Max transactions to return'),
+    limit: zod_1.z.number().min(1).max(100).default(50).describe('Max transactions to return'),
     offset: zod_1.z.number().min(0).default(0).describe('Number to skip for pagination'),
 });
 // Operator management schemas
@@ -173,13 +173,13 @@ const RotateApiKeySchema = zod_1.z.object({
 // Tier 2 schemas
 const GetInfoSchema = zod_1.z.object({});
 const DecodeInvoiceSchema = zod_1.z.object({
-    bolt11: zod_1.z.string().regex(/^ln(bc|tb|bcrt)1[a-z0-9]+$/i, 'Invalid BOLT11 invoice format')
+    bolt11: zod_1.z.string().regex(/^ln(bc|tb|bcrt)([0-9]+[munp]?)?1[a-z0-9]+$/i, 'Invalid BOLT11 invoice format')
         .describe('BOLT11 invoice string to decode'),
 });
 const GetRateLimitsSchema = zod_1.z.object({});
 // Tier 3 schemas
 const WithdrawSchema = zod_1.z.object({
-    invoice: zod_1.z.string().regex(/^ln(bc|tb|bcrt)1[a-z0-9]+$/i, 'Invalid BOLT11 invoice format')
+    invoice: zod_1.z.string().regex(/^ln(bc|tb|bcrt)([0-9]+[munp]?)?1[a-z0-9]+$/i, 'Invalid BOLT11 invoice format')
         .describe('BOLT11 invoice to pay out to'),
 });
 const SweepAgentSchema = zod_1.z.object({
@@ -822,7 +822,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
     try {
         switch (name) {
             case 'check_balance': {
-                CheckBalanceSchema.parse(args);
+                CheckBalanceSchema.parse(args ?? {});
                 const result = await session.requireClient().checkBalance();
                 return {
                     content: [
@@ -838,7 +838,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'pay_l402_api': {
-                const parsed = PayL402ApiSchema.parse(args);
+                const parsed = PayL402ApiSchema.parse(args ?? {});
                 const result = await session.requireClient().l402Pay(parsed.url, parsed.method, parsed.body, parsed.max_payment_sats);
                 // Determine if the target returned a success response
                 const targetSuccess = result.statusCode >= 200 && result.statusCode < 300;
@@ -870,7 +870,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'pay_invoice': {
-                const parsed = PayInvoiceSchema.parse(args);
+                const parsed = PayInvoiceSchema.parse(args ?? {});
                 const result = await session.requireClient().payInvoice(parsed.bolt11, parsed.max_fee_sats);
                 return {
                     content: [
@@ -892,7 +892,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'create_invoice': {
-                const parsed = CreateInvoiceSchema.parse(args);
+                const parsed = CreateInvoiceSchema.parse(args ?? {});
                 const result = await session.requireClient().createInvoice(parsed.amount_sats, parsed.memo);
                 const invoiceResponse = {
                     success: true,
@@ -914,7 +914,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'get_invoice_status': {
-                const parsed = GetInvoiceStatusSchema.parse(args);
+                const parsed = GetInvoiceStatusSchema.parse(args ?? {});
                 const result = await session.requireClient().getInvoiceStatus(parsed.payment_hash);
                 return {
                     content: [
@@ -934,7 +934,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'get_transactions': {
-                const parsed = GetTransactionsSchema.parse(args);
+                const parsed = GetTransactionsSchema.parse(args ?? {});
                 const result = await session.requireClient().getTransactions(parsed.limit, parsed.offset);
                 return {
                     content: [
@@ -952,7 +952,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             }
             // Operator management tool handlers
             case 'register_operator': {
-                const parsed = RegisterOperatorSchema.parse(args);
+                const parsed = RegisterOperatorSchema.parse(args ?? {});
                 const result = await (0, lightning_faucet_js_1.registerOperator)(parsed.name, parsed.email);
                 // Auto-set credentials so subsequent requests use the new operator key
                 session.setClient(new lightning_faucet_js_1.LightningFaucetClient(result.apiKey));
@@ -974,7 +974,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'update_operator': {
-                const parsed = UpdateOperatorSchema.parse(args);
+                const parsed = UpdateOperatorSchema.parse(args ?? {});
                 if (parsed.email === undefined && parsed.name === undefined) {
                     throw new Error('Provide email and/or name to update.');
                 }
@@ -994,7 +994,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'claim_promo': {
-                const parsed = ClaimPromoSchema.parse(args);
+                const parsed = ClaimPromoSchema.parse(args ?? {});
                 const result = await session.requireClient().claimPromo(parsed.promo_code);
                 return {
                     content: [
@@ -1006,7 +1006,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'get_deposit_invoice': {
-                const parsed = GetDepositInvoiceSchema.parse(args);
+                const parsed = GetDepositInvoiceSchema.parse(args ?? {});
                 const result = await session.requireClient().getDepositInvoice(parsed.amount_sats);
                 return {
                     content: [
@@ -1026,7 +1026,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'create_agent': {
-                const parsed = CreateAgentSchema.parse(args);
+                const parsed = CreateAgentSchema.parse(args ?? {});
                 const result = await session.requireClient().createAgent(parsed.name, parsed.description, parsed.budget_limit_sats);
                 return {
                     content: [
@@ -1044,7 +1044,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'fund_agent': {
-                const parsed = FundAgentSchema.parse(args);
+                const parsed = FundAgentSchema.parse(args ?? {});
                 const result = await session.requireClient().fundAgent(parsed.agent_id, parsed.amount_sats);
                 return {
                     content: [
@@ -1062,7 +1062,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'list_agents': {
-                ListAgentsSchema.parse(args);
+                ListAgentsSchema.parse(args ?? {});
                 const result = await session.requireClient().listAgents();
                 return {
                     content: [
@@ -1078,7 +1078,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'set_operator_key': {
-                const parsed = SetOperatorKeySchema.parse(args);
+                const parsed = SetOperatorKeySchema.parse(args ?? {});
                 session.setClient(new lightning_faucet_js_1.LightningFaucetClient(parsed.api_key));
                 return {
                     content: [
@@ -1093,7 +1093,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'set_agent_credentials': {
-                const parsed = SetAgentCredentialsSchema.parse(args);
+                const parsed = SetAgentCredentialsSchema.parse(args ?? {});
                 session.setClient(new lightning_faucet_js_1.LightningFaucetClient(parsed.api_key));
                 return {
                     content: [
@@ -1108,7 +1108,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'whoami': {
-                WhoamiSchema.parse(args);
+                WhoamiSchema.parse(args ?? {});
                 const result = await session.requireClient().whoami();
                 const response = {
                     success: true,
@@ -1137,7 +1137,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // TIER 1: Webhook Management
             // ==========================================
             case 'register_webhook': {
-                const parsed = RegisterWebhookSchema.parse(args);
+                const parsed = RegisterWebhookSchema.parse(args ?? {});
                 const result = await session.requireClient().registerWebhook(parsed.url, parsed.events);
                 return {
                     content: [
@@ -1156,7 +1156,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'list_webhooks': {
-                ListWebhooksSchema.parse(args);
+                ListWebhooksSchema.parse(args ?? {});
                 const result = await session.requireClient().listWebhooks();
                 return {
                     content: [
@@ -1172,7 +1172,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'delete_webhook': {
-                const parsed = DeleteWebhookSchema.parse(args);
+                const parsed = DeleteWebhookSchema.parse(args ?? {});
                 const result = await session.requireClient().deleteWebhook(parsed.webhook_id);
                 return {
                     content: [
@@ -1187,7 +1187,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'test_webhook': {
-                const parsed = TestWebhookSchema.parse(args);
+                const parsed = TestWebhookSchema.parse(args ?? {});
                 const result = await session.requireClient().testWebhook(parsed.webhook_id);
                 return {
                     content: [
@@ -1206,7 +1206,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // TIER 1: Budget Management
             // ==========================================
             case 'get_budget_status': {
-                const parsed = GetBudgetStatusSchema.parse(args);
+                const parsed = GetBudgetStatusSchema.parse(args ?? {});
                 const result = await session.requireClient().getBudgetStatus(parsed.agent_id);
                 return {
                     content: [
@@ -1225,7 +1225,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'set_budget': {
-                const parsed = SetBudgetSchema.parse(args);
+                const parsed = SetBudgetSchema.parse(args ?? {});
                 const result = await session.requireClient().setBudget(parsed.agent_id, parsed.budget_limit_sats);
                 return {
                     content: [
@@ -1245,7 +1245,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // TIER 1: Agent Lifecycle
             // ==========================================
             case 'deactivate_agent': {
-                const parsed = DeactivateAgentSchema.parse(args);
+                const parsed = DeactivateAgentSchema.parse(args ?? {});
                 const result = await session.requireClient().deactivateAgent(parsed.agent_id);
                 return {
                     content: [
@@ -1261,7 +1261,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'reactivate_agent': {
-                const parsed = ReactivateAgentSchema.parse(args);
+                const parsed = ReactivateAgentSchema.parse(args ?? {});
                 const result = await session.requireClient().reactivateAgent(parsed.agent_id);
                 return {
                     content: [
@@ -1280,7 +1280,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // TIER 1: Recovery & Key Rotation
             // ==========================================
             case 'recover_account': {
-                const parsed = RecoverAccountSchema.parse(args);
+                const parsed = RecoverAccountSchema.parse(args ?? {});
                 // Recovery doesn't need an existing API key — recoverAccount() uses its own fetch
                 const tempClient = session.getClient() || new lightning_faucet_js_1.LightningFaucetClient('recovery-placeholder');
                 const result = await tempClient.recoverAccount(parsed.recovery_code);
@@ -1302,7 +1302,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'rotate_api_key': {
-                const parsed = RotateApiKeySchema.parse(args);
+                const parsed = RotateApiKeySchema.parse(args ?? {});
                 const result = await session.requireClient().rotateApiKey(parsed.agent_id);
                 // Auto-switch to the new key
                 session.setClient(new lightning_faucet_js_1.LightningFaucetClient(result.apiKey));
@@ -1324,7 +1324,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // TIER 2: Service Info & Invoice Decoding
             // ==========================================
             case 'get_info': {
-                GetInfoSchema.parse(args);
+                GetInfoSchema.parse(args ?? {});
                 // Service info is public - fall back to an unauthenticated request so
                 // first-run users can check the service before registering.
                 let result;
@@ -1352,7 +1352,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'decode_invoice': {
-                const parsed = DecodeInvoiceSchema.parse(args);
+                const parsed = DecodeInvoiceSchema.parse(args ?? {});
                 const result = await session.requireClient().decodeInvoice(parsed.bolt11);
                 return {
                     content: [
@@ -1373,7 +1373,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'get_rate_limits': {
-                GetRateLimitsSchema.parse(args);
+                GetRateLimitsSchema.parse(args ?? {});
                 const result = await session.requireClient().getRateLimits();
                 return {
                     content: [
@@ -1393,7 +1393,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // TIER 3: Withdrawals & Advanced Payments
             // ==========================================
             case 'withdraw': {
-                const parsed = WithdrawSchema.parse(args);
+                const parsed = WithdrawSchema.parse(args ?? {});
                 const result = await session.requireClient().withdraw(parsed.invoice);
                 return {
                     content: [
@@ -1414,9 +1414,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'create_withdraw_link': {
-                const amountSats = args && typeof args === 'object' && 'amount_sats' in args
-                    ? args.amount_sats
-                    : undefined;
+                const { amount_sats: amountSats } = zod_1.z.object({
+                    amount_sats: zod_1.z.coerce.number().int().min(100).optional(),
+                }).parse(args ?? {});
                 const result = await session.requireClient().createWithdrawLink(amountSats);
                 return {
                     content: [
@@ -1439,7 +1439,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'sweep_agent': {
-                const parsed = SweepAgentSchema.parse(args);
+                const parsed = SweepAgentSchema.parse(args ?? {});
                 const amount = typeof parsed.amount_sats === 'string' ? 999999999 : parsed.amount_sats;
                 const result = await session.requireClient().sweepAgent(parsed.agent_id, amount);
                 return {
@@ -1458,7 +1458,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'pay_lightning_address': {
-                const parsed = PayLightningAddressSchema.parse(args);
+                const parsed = PayLightningAddressSchema.parse(args ?? {});
                 const result = await session.requireClient().payLightningAddress(parsed.address, parsed.amount_sats, parsed.comment);
                 return {
                     content: [
@@ -1480,7 +1480,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // NOSTR IDENTITY & ZAPS
             // ==========================================
             case 'set_nostr_identity': {
-                const parsed = SetNostrIdentitySchema.parse(args);
+                const parsed = SetNostrIdentitySchema.parse(args ?? {});
                 const result = await session.requireClient().setNostrIdentity(parsed.private_key);
                 return {
                     content: [
@@ -1513,7 +1513,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'nostr_zap': {
-                const parsed = NostrZapSchema.parse(args);
+                const parsed = NostrZapSchema.parse(args ?? {});
                 const result = await session.requireClient().nostrZap(parsed.address, parsed.amount_sats, parsed.recipient_pubkey, parsed.content, parsed.event_id, parsed.relays);
                 return {
                     content: [
@@ -1537,7 +1537,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // TIER 4: Advanced Agent Management
             // ==========================================
             case 'transfer_to_agent': {
-                const parsed = TransferToAgentSchema.parse(args);
+                const parsed = TransferToAgentSchema.parse(args ?? {});
                 const result = await session.requireClient().transferToAgent(parsed.to_agent_id, parsed.amount_sats, parsed.from_agent_id);
                 return {
                     content: [
@@ -1555,7 +1555,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'delete_agent': {
-                const parsed = DeleteAgentSchema.parse(args);
+                const parsed = DeleteAgentSchema.parse(args ?? {});
                 if (!parsed.confirm) {
                     return {
                         content: [
@@ -1588,7 +1588,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // TIER 5: Protocol Extensions
             // ==========================================
             case 'lnurl_auth': {
-                const parsed = LnurlAuthSchema.parse(args);
+                const parsed = LnurlAuthSchema.parse(args ?? {});
                 const result = await session.requireClient().lnurlAuth(parsed.lnurl);
                 return {
                     content: [
@@ -1604,7 +1604,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'claim_lnurl_withdraw': {
-                const parsed = ClaimLnurlWithdrawSchema.parse(args);
+                const parsed = ClaimLnurlWithdrawSchema.parse(args ?? {});
                 const result = await session.requireClient().claimLnurlWithdraw(parsed.lnurl);
                 return {
                     content: [
@@ -1622,7 +1622,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'keysend': {
-                const parsed = KeysendSchema.parse(args);
+                const parsed = KeysendSchema.parse(args ?? {});
                 const result = await session.requireClient().keysend(parsed.destination, parsed.amount_sats, parsed.message);
                 return {
                     content: [
@@ -1646,7 +1646,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // MESSAGE BOARD TOOL HANDLERS
             // ==========================================
             case 'board_read': {
-                const parsed = BoardReadSchema.parse(args);
+                const parsed = BoardReadSchema.parse(args ?? {});
                 const result = await session.requireClient().boardRead(parsed.sort, parsed.topic, parsed.limit, parsed.offset);
                 return {
                     content: [
@@ -1658,7 +1658,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'board_post': {
-                const parsed = BoardPostSchema.parse(args);
+                const parsed = BoardPostSchema.parse(args ?? {});
                 const result = await session.requireClient().boardPost(parsed.content, parsed.topic);
                 return {
                     content: [
@@ -1670,7 +1670,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'board_reply': {
-                const parsed = BoardReplySchema.parse(args);
+                const parsed = BoardReplySchema.parse(args ?? {});
                 const result = await session.requireClient().boardReply(parsed.post_id, parsed.content);
                 return {
                     content: [
@@ -1682,7 +1682,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 };
             }
             case 'board_vote': {
-                const parsed = BoardVoteSchema.parse(args);
+                const parsed = BoardVoteSchema.parse(args ?? {});
                 const result = await session.requireClient().boardVote(parsed.post_id, parsed.direction);
                 return {
                     content: [

package/dist/lightning-faucet.d.ts

@@ -118,7 +118,24 @@ interface WhoamiResponse extends ApiResponse {
 }
 export declare class LightningFaucetClient {
     private apiKey;
+    private agentIdCache;
     constructor(apiKey: string);
+    /**
+     * Resolve the current agent id for hook proposals (best-effort, cached).
+     * Returns null if it cannot be determined; a payment is never blocked solely
+     * because identity resolution failed — that decision is left to the policy hook.
+     */
+    private resolveAgentId;
+    /**
+     * Run the optional pre-payment policy hook before executing a payment.
+     *
+     * No-op when `PRE_PAYMENT_HOOK_URL` is unset (behaviour is unchanged). When a
+     * hook is configured this POSTs a vendor-neutral proposal and throws
+     * `PolicyDenied` if the hook — or fail-closed handling of a hook error —
+     * denies the payment. Only the four explicit payment methods call this; it is
+     * invoked before any funds-moving request is sent.
+     */
+    private enforcePrePaymentPolicy;
     /**
      * Make an API request to Lightning Faucet
      */

package/dist/lightning-faucet.js

@@ -8,15 +8,75 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LightningFaucetClient = void 0;
 exports.registerOperator = registerOperator;
 exports.getPublicInfo = getPublicInfo;
+const pre_payment_hook_js_1 = require("./pre-payment-hook.js");
+const bolt11_js_1 = require("./bolt11.js");
 const API_BASE_URL = process.env.LIGHTNING_WALLET_API_URL || 'https://lightningfaucet.com/ai-agents/api';
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
 class LightningFaucetClient {
     apiKey;
+    agentIdCache;
     constructor(apiKey) {
         if (!apiKey) {
             throw new Error('API key is required');
         }
         this.apiKey = apiKey;
     }
+    /**
+     * Resolve the current agent id for hook proposals (best-effort, cached).
+     * Returns null if it cannot be determined; a payment is never blocked solely
+     * because identity resolution failed — that decision is left to the policy hook.
+     */
+    async resolveAgentId() {
+        if (this.agentIdCache !== undefined) {
+            return this.agentIdCache;
+        }
+        try {
+            const who = await this.whoami();
+            this.agentIdCache = who.id || null;
+        }
+        catch {
+            this.agentIdCache = null;
+        }
+        return this.agentIdCache;
+    }
+    /**
+     * Run the optional pre-payment policy hook before executing a payment.
+     *
+     * No-op when `PRE_PAYMENT_HOOK_URL` is unset (behaviour is unchanged). When a
+     * hook is configured this POSTs a vendor-neutral proposal and throws
+     * `PolicyDenied` if the hook — or fail-closed handling of a hook error —
+     * denies the payment. Only the four explicit payment methods call this; it is
+     * invoked before any funds-moving request is sent.
+     */
+    async enforcePrePaymentPolicy(params) {
+        const config = (0, pre_payment_hook_js_1.getPrePaymentHookConfig)();
+        if (!config) {
+            return;
+        }
+        const agentId = await this.resolveAgentId();
+        const proposal = {
+            proposal_id: globalThis.crypto.randomUUID(),
+            agent_id: agentId,
+            protocol: params.protocol,
+            destination_or_url: params.destinationOrUrl,
+            amount_sats: params.amountSats,
+            max_payment_sats: params.maxPaymentSats,
+            method: params.method ?? null,
+            ts: new Date().toISOString(),
+        };
+        const { attestation } = await (0, pre_payment_hook_js_1.runPrePaymentHook)(proposal, config);
+        if (attestation !== undefined) {
+            // Opaque to this client — logged on stderr to avoid corrupting MCP stdio.
+            console.error(`[pre-payment-hook] payment allowed with attestation: ${safeStringify(attestation)}`);
+        }
+    }
     /**
      * Make an API request to Lightning Faucet
      */
@@ -57,6 +117,15 @@ class LightningFaucetClient {
      * Pay an L402-protected API endpoint
      */
     async l402Pay(url, method = 'GET', body, maxPaymentSats = 1000) {
+        // L402 vs X402 is auto-detected server-side; the actual amount is set by the
+        // challenge, so only the agent-authorised ceiling is known at hook time.
+        await this.enforcePrePaymentPolicy({
+            protocol: 'l402',
+            destinationOrUrl: url,
+            amountSats: null,
+            maxPaymentSats,
+            method: method.toUpperCase(),
+        });
         const requestData = {
             url,
             method: method.toUpperCase(),
@@ -93,6 +162,15 @@ class LightningFaucetClient {
      * Pay a BOLT11 Lightning invoice
      */
     async payInvoice(bolt11, maxFeeSats) {
+        // Decode the amount from the invoice locally (no extra API call) so the hook
+        // receives the exact amount; null only if the invoice is amountless/unparseable.
+        await this.enforcePrePaymentPolicy({
+            protocol: 'bolt11',
+            destinationOrUrl: bolt11,
+            amountSats: (0, bolt11_js_1.bolt11AmountSats)(bolt11),
+            maxPaymentSats: null,
+            method: null,
+        });
         const data = {
             invoice: bolt11,
         };
@@ -573,6 +651,13 @@ class LightningFaucetClient {
      * Pay to a Lightning address
      */
     async payLightningAddress(address, amountSats, comment) {
+        await this.enforcePrePaymentPolicy({
+            protocol: 'lnaddress',
+            destinationOrUrl: address,
+            amountSats,
+            maxPaymentSats: amountSats,
+            method: null,
+        });
         const data = {
             address,
             amount_sats: amountSats,
@@ -663,6 +748,13 @@ class LightningFaucetClient {
      * Send keysend payment
      */
     async keysend(destination, amountSats, message) {
+        await this.enforcePrePaymentPolicy({
+            protocol: 'keysend',
+            destinationOrUrl: destination,
+            amountSats,
+            maxPaymentSats: amountSats,
+            method: null,
+        });
         const data = {
             destination,
             amount_sats: amountSats,
@@ -714,6 +806,15 @@ class LightningFaucetClient {
      * Falls back to regular Lightning address payment if recipient doesn't support NIP-57
      */
     async nostrZap(address, amountSats, recipientPubkey, content, eventId, relays) {
+        // A Nostr zap settles as a Lightning-address payment, so it is an agent spend
+        // and must pass the policy hook like any other.
+        await this.enforcePrePaymentPolicy({
+            protocol: 'lnaddress',
+            destinationOrUrl: address,
+            amountSats,
+            maxPaymentSats: amountSats,
+            method: null,
+        });
         const data = {
             address,
             amount_sats: amountSats,

package/dist/pre-payment-hook.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pre-Payment Policy Hook
+ *
+ * An optional, vendor-neutral hook that lets an external policy endpoint allow
+ * or deny a payment *before* it executes. When `PRE_PAYMENT_HOOK_URL` is unset
+ * the hook is inert and payment behaviour is identical to having no hook at all.
+ *
+ * This module contains no vendor-specific logic. It POSTs a generic payment
+ * proposal and interprets a generic decision, so any policy service that speaks
+ * the documented request/response contract can be wired in by configuration
+ * alone. The proposal deliberately carries NO wallet credentials.
+ */
+export type PaymentProtocol = 'l402' | 'x402' | 'bolt11' | 'keysend' | 'lnaddress';
+export type HookFailMode = 'closed' | 'open';
+export interface PrePaymentProposal {
+    /** Unique id for this proposal (one per payment attempt). */
+    proposal_id: string;
+    /** The paying agent's id, when resolvable; null otherwise. */
+    agent_id: number | null;
+    /** Payment protocol being attempted. */
+    protocol: PaymentProtocol;
+    /** Destination address, node pubkey, lightning address, invoice, or target URL. */
+    destination_or_url: string;
+    /** Exact amount when known at hook time; null when the protocol determines it later. */
+    amount_sats: number | null;
+    /** Upper bound the agent authorised, when applicable; null otherwise. */
+    max_payment_sats: number | null;
+    /** HTTP method for L402/X402 URL payments; null for direct Lightning payments. */
+    method: string | null;
+    /** ISO-8601 timestamp of the proposal. */
+    ts: string;
+}
+export interface HookDecisionReason {
+    code?: string;
+    message?: string;
+}
+export interface HookDecision {
+    decision: 'allow' | 'deny';
+    reason?: HookDecisionReason;
+    /** Opaque to this client; forwarded/logged only. */
+    attestation?: unknown;
+}
+export interface PrePaymentHookConfig {
+    url: string;
+    timeoutMs: number;
+    failMode: HookFailMode;
+}
+/**
+ * Read hook configuration from the environment. Returns null when no hook URL is
+ * configured, in which case callers MUST behave exactly as before.
+ *
+ * - `PRE_PAYMENT_HOOK_URL` — when set, enables the hook.
+ * - `PRE_PAYMENT_HOOK_TIMEOUT_MS` — request timeout; defaults to 3000.
+ * - `PRE_PAYMENT_HOOK_FAIL_MODE` — `closed` (default) denies on hook error/timeout;
+ *   `open` proceeds on hook error/timeout.
+ */
+export declare function getPrePaymentHookConfig(env?: Record<string, string | undefined>): PrePaymentHookConfig | null;
+/**
+ * Error thrown when a payment is denied — either explicitly by the hook
+ * (`decision: "deny"`) or implicitly by a hook error under fail-closed mode.
+ */
+export declare class PolicyDenied extends Error {
+    readonly code: string;
+    readonly reason?: HookDecisionReason;
+    constructor(message: string, code?: string, reason?: HookDecisionReason);
+}
+export interface RunHookDeps {
+    /** Injectable fetch, primarily for tests. Defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Run the pre-payment hook for a proposal.
+ *
+ * - decision `allow`: resolves with the (opaque) attestation, if any.
+ * - decision `deny`: throws {@link PolicyDenied} carrying the structured reason.
+ * - transport error / timeout / non-2xx / malformed response: applies failMode —
+ *   `closed` throws {@link PolicyDenied}; `open` resolves (payment proceeds) after
+ *   logging the failure to stderr.
+ */
+export declare function runPrePaymentHook(proposal: PrePaymentProposal, config: PrePaymentHookConfig, deps?: RunHookDeps): Promise<{
+    attestation?: unknown;
+}>;

package/dist/pre-payment-hook.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Pre-Payment Policy Hook
+ *
+ * An optional, vendor-neutral hook that lets an external policy endpoint allow
+ * or deny a payment *before* it executes. When `PRE_PAYMENT_HOOK_URL` is unset
+ * the hook is inert and payment behaviour is identical to having no hook at all.
+ *
+ * This module contains no vendor-specific logic. It POSTs a generic payment
+ * proposal and interprets a generic decision, so any policy service that speaks
+ * the documented request/response contract can be wired in by configuration
+ * alone. The proposal deliberately carries NO wallet credentials.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyDenied = void 0;
+exports.getPrePaymentHookConfig = getPrePaymentHookConfig;
+exports.runPrePaymentHook = runPrePaymentHook;
+const DEFAULT_TIMEOUT_MS = 3000;
+/**
+ * Read hook configuration from the environment. Returns null when no hook URL is
+ * configured, in which case callers MUST behave exactly as before.
+ *
+ * - `PRE_PAYMENT_HOOK_URL` — when set, enables the hook.
+ * - `PRE_PAYMENT_HOOK_TIMEOUT_MS` — request timeout; defaults to 3000.
+ * - `PRE_PAYMENT_HOOK_FAIL_MODE` — `closed` (default) denies on hook error/timeout;
+ *   `open` proceeds on hook error/timeout.
+ */
+function getPrePaymentHookConfig(env = process.env) {
+    const url = env.PRE_PAYMENT_HOOK_URL?.trim();
+    if (!url) {
+        return null;
+    }
+    const timeoutRaw = env.PRE_PAYMENT_HOOK_TIMEOUT_MS?.trim();
+    const parsedTimeout = timeoutRaw ? Number.parseInt(timeoutRaw, 10) : NaN;
+    const timeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout > 0 ? parsedTimeout : DEFAULT_TIMEOUT_MS;
+    // Default fail-closed: when a hook is configured, a hook error denies the payment.
+    const failMode = env.PRE_PAYMENT_HOOK_FAIL_MODE?.trim().toLowerCase() === 'open' ? 'open' : 'closed';
+    return { url, timeoutMs, failMode };
+}
+/**
+ * Error thrown when a payment is denied — either explicitly by the hook
+ * (`decision: "deny"`) or implicitly by a hook error under fail-closed mode.
+ */
+class PolicyDenied extends Error {
+    code;
+    reason;
+    constructor(message, code = 'policy_denied', reason) {
+        super(message);
+        this.name = 'PolicyDenied';
+        this.code = code;
+        this.reason = reason;
+    }
+}
+exports.PolicyDenied = PolicyDenied;
+/**
+ * Run the pre-payment hook for a proposal.
+ *
+ * - decision `allow`: resolves with the (opaque) attestation, if any.
+ * - decision `deny`: throws {@link PolicyDenied} carrying the structured reason.
+ * - transport error / timeout / non-2xx / malformed response: applies failMode —
+ *   `closed` throws {@link PolicyDenied}; `open` resolves (payment proceeds) after
+ *   logging the failure to stderr.
+ */
+async function runPrePaymentHook(proposal, config, deps = {}) {
+    const doFetch = deps.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+    // The timer lives in a try/finally with NO catch: a fail-closed PolicyDenied
+    // (from applyFailMode or the deny branch) propagates straight out, clearing
+    // the timer, and is never caught and re-wrapped. Only the fetch and the body
+    // read are wrapped in their own try/catch, so their failures map to fail-mode
+    // exactly once with the right detail.
+    try {
+        let response;
+        try {
+            response = await doFetch(config.url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(proposal),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            return applyFailMode(config, transportDetail(err, config));
+        }
+        // Non-2xx is handled OUTSIDE the fetch try/catch so the status detail is
+        // preserved and fail-mode runs once.
+        if (!response.ok) {
+            return applyFailMode(config, `policy hook returned HTTP ${response.status}`);
+        }
+        let decision;
+        try {
+            decision = (await response.json());
+        }
+        catch (err) {
+            return applyFailMode(config, transportDetail(err, config, 'policy hook returned an unparseable body'));
+        }
+        if (decision?.decision === 'allow') {
+            return { attestation: decision.attestation };
+        }
+        if (decision?.decision === 'deny') {
+            const reason = decision.reason;
+            const detail = reason?.message || 'payment denied by policy';
+            throw new PolicyDenied(`Payment blocked by pre-payment policy hook: ${detail}`, reason?.code || 'policy_denied', reason);
+        }
+        // Malformed/unknown decision — treat as a hook error and apply the fail mode.
+        return applyFailMode(config, 'policy hook returned an unrecognized decision');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function transportDetail(err, config, fallback = 'policy hook request failed') {
+    return err instanceof Error && err.name === 'AbortError'
+        ? `policy hook timed out after ${config.timeoutMs}ms`
+        : fallback;
+}
+function applyFailMode(config, detail) {
+    if (config.failMode === 'open') {
+        // Fail-open: allow the payment, but record the hook failure on stderr.
+        console.error(`[pre-payment-hook] fail-open: proceeding despite ${detail}`);
+        return {};
+    }
+    throw new PolicyDenied(`Payment blocked by pre-payment policy hook (fail-closed): ${detail}`, 'policy_hook_unavailable');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightning-wallet-mcp",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "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",
@@ -13,6 +13,7 @@
     "build": "tsc",
     "watch": "tsc --watch",
     "start": "node dist/index.js",
+    "test": "npm run build && node --test test/*.test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [