beignet 0.2.0 → 0.4.0

package/dist/cli/openapi.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getOpenApiSpec = void 0;
+const auth_1 = require("./auth");
 function getOpenApiSpec() {
-    return {
+    const spec = {
         openapi: '3.0.3',
         info: {
             title: 'Beignet Lightning API',
@@ -12,6 +13,7 @@ function getOpenApiSpec() {
                 'When provided, the response is cached for 24 hours — repeated requests with the same key and body return the cached response. ' +
                 'If the same key is reused with a different request body, a `409 IDEMPOTENCY_CONFLICT` error is returned.\n\n' +
                 '**TLS:** The daemon supports HTTPS when started with `--tls-cert` and `--tls-key` flags (or `BEIGNET_TLS_CERT`/`BEIGNET_TLS_KEY` env vars).\n\n' +
+                '**Scoped API keys:** Besides the legacy single `apiToken` (implicit admin scope), the `apiKeys` config defines named keys with `readonly`, `invoice`, and/or `admin` scopes. Each operation lists the scopes it accepts in `x-accepted-scopes`; unclassified routes are admin-only. Requests fail with 401 (bad/absent key) or 403 (valid key, insufficient scope).\n\n' +
                 '**Spending Limits:** Configure `dailySpendLimitSats` (or `BEIGNET_DAILY_SPEND_LIMIT_SATS` env var) to enforce a daily budget. Query `GET /spend-limit` for current usage.\n\n' +
                 '**Drain Mode:** `POST /stop` accepts `{ "drain": true }` to stop accepting new payments and wait for in-flight ones to settle before shutdown.'
         },
@@ -160,6 +162,101 @@ function getOpenApiSpec() {
                     }
                 }
             },
+            '/forwards': {
+                get: {
+                    summary: 'List settled forwards (fees earned), newest first',
+                    tags: ['Payments'],
+                    parameters: [
+                        {
+                            name: 'since',
+                            in: 'query',
+                            schema: { type: 'integer' },
+                            description: 'Only events settled at/after this ms timestamp'
+                        },
+                        {
+                            name: 'until',
+                            in: 'query',
+                            schema: { type: 'integer' },
+                            description: 'Only events settled at/before this ms timestamp'
+                        },
+                        { name: 'limit', in: 'query', schema: { type: 'integer' } },
+                        { name: 'offset', in: 'query', schema: { type: 'integer' } },
+                        {
+                            name: 'channelId',
+                            in: 'query',
+                            schema: { type: 'string' },
+                            description: 'Match the inbound OR outbound leg'
+                        }
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Forwarding events (msat values as strings)',
+                            content: jsonContent({
+                                type: 'array',
+                                items: { $ref: '#/components/schemas/ForwardingEvent' }
+                            })
+                        }
+                    }
+                }
+            },
+            '/forwards/summary': {
+                get: {
+                    summary: 'Forwarding totals: count, volume out, fees earned',
+                    tags: ['Payments'],
+                    parameters: [
+                        {
+                            name: 'since',
+                            in: 'query',
+                            schema: { type: 'integer' },
+                            description: 'Only events settled at/after this ms timestamp'
+                        }
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Forwarding summary (msat values as strings)',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/ForwardingSummary'
+                            })
+                        }
+                    }
+                }
+            },
+            '/watchtowers': {
+                get: {
+                    summary: 'List configured watchtowers with per-tower session + backlog health',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Watchtower health',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    towers: {
+                                        type: 'array',
+                                        items: { $ref: '#/components/schemas/WatchtowerInfo' }
+                                    }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/watchtower/add': {
+                post: {
+                    summary: 'Add a watchtower (pubkey@host:port, LND altruist tower)',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ uri: 'string' }),
+                    responses: { '200': { description: 'Tower added' } }
+                }
+            },
+            '/watchtower/remove': {
+                delete: {
+                    summary: 'Remove a watchtower and drop its sessions + backlog',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ uri: 'string' }),
+                    responses: { '200': { description: 'Tower removed' } }
+                }
+            },
             '/invoices': {
                 get: {
                     summary: 'List created invoices',
@@ -193,6 +290,75 @@ function getOpenApiSpec() {
                     }
                 }
             },
+            '/invoice/create-hold': {
+                post: {
+                    summary: 'Create a hold invoice for a caller-supplied payment hash (preimage stays with the caller; the incoming HTLC parks until settle/cancel)',
+                    tags: ['Invoices'],
+                    requestBody: bodyContent({
+                        paymentHash: 'string',
+                        amountMsat: 'string?',
+                        amountSats: 'number?',
+                        description: 'string?',
+                        expiry: 'number?'
+                    }),
+                    responses: {
+                        '200': {
+                            description: 'Created hold invoice',
+                            content: jsonContent({ $ref: '#/components/schemas/InvoiceInfo' })
+                        }
+                    }
+                }
+            },
+            '/invoice/settle-hold': {
+                post: {
+                    summary: 'Settle a hold invoice with its preimage: validates sha256(preimage) and fulfills every parked HTLC (all MPP parts)',
+                    tags: ['Invoices'],
+                    requestBody: bodyContent({ preimage: 'string' }),
+                    responses: {
+                        '200': {
+                            description: 'Settled',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: { paymentHash: { type: 'string' } }
+                            })
+                        }
+                    }
+                }
+            },
+            '/invoice/cancel-hold': {
+                post: {
+                    summary: 'Cancel a hold invoice: fails parked HTLCs back with incorrect_or_unknown_payment_details and rejects future ones',
+                    tags: ['Invoices'],
+                    requestBody: bodyContent({ paymentHash: 'string' }),
+                    responses: {
+                        '200': {
+                            description: 'Cancelled',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    paymentHash: { type: 'string' },
+                                    htlcsFailed: { type: 'integer' }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/invoices/held': {
+                get: {
+                    summary: 'List hold invoices with lifecycle state and parked totals',
+                    tags: ['Invoices'],
+                    responses: {
+                        '200': {
+                            description: 'Hold invoices',
+                            content: jsonContent({
+                                type: 'array',
+                                items: { $ref: '#/components/schemas/HoldInvoiceInfo' }
+                            })
+                        }
+                    }
+                }
+            },
             '/invoice': {
                 get: {
                     summary: 'Get a specific invoice by payment hash',
@@ -370,15 +536,81 @@ function getOpenApiSpec() {
                     }
                 }
             },
+            '/channel/update-commitment-feerate': {
+                post: {
+                    summary: 'Update the channel commitment transaction feerate (BOLT 2 update_fee). Not the routing fee policy.',
+                    tags: ['Channels'],
+                    requestBody: bodyContent({
+                        channelId: 'string',
+                        feeratePerKw: 'number'
+                    }),
+                    responses: { '200': { description: 'Commitment feerate updated' } }
+                }
+            },
             '/channel/update-fee': {
                 post: {
-                    summary: 'Update channel fee rate',
+                    summary: 'Deprecated alias for /channel/update-commitment-feerate. Sets the commitment feerate, not the routing fee policy.',
+                    deprecated: true,
                     tags: ['Channels'],
                     requestBody: bodyContent({
                         channelId: 'string',
                         feeratePerKw: 'number'
                     }),
-                    responses: { '200': { description: 'Fee updated' } }
+                    responses: { '200': { description: 'Commitment feerate updated' } }
+                }
+            },
+            '/channel/update-policy': {
+                post: {
+                    summary: 'Set the ROUTING fee policy for one channel (channelId) or all channels (all: true); regenerates and re-broadcasts the channel_update. Msat fields accept number or decimal string.',
+                    tags: ['Channels'],
+                    requestBody: bodyContent({
+                        channelId: 'string?',
+                        all: 'boolean?',
+                        feeBaseMsat: 'number?',
+                        feeProportionalMillionths: 'number?',
+                        cltvExpiryDelta: 'number?',
+                        htlcMinimumMsat: 'string?',
+                        htlcMaximumMsat: 'string?'
+                    }),
+                    responses: {
+                        '200': {
+                            description: 'Updated count + effective policies',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    updated: { type: 'integer' },
+                                    policies: {
+                                        type: 'array',
+                                        items: { $ref: '#/components/schemas/ChannelPolicy' }
+                                    }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/channel/policy': {
+                get: {
+                    summary: 'Get the effective routing fee policy for a channel (override or node defaults)',
+                    tags: ['Channels'],
+                    parameters: [
+                        {
+                            name: 'channelId',
+                            in: 'query',
+                            required: true,
+                            schema: { type: 'string' }
+                        }
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Effective channel policy',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/ChannelPolicy'
+                            })
+                        },
+                        '400': { description: 'Missing channelId' },
+                        '404': { description: 'Channel not found' }
+                    }
                 }
             },
             '/channels/ensure-minimum': {
@@ -466,12 +698,12 @@ function getOpenApiSpec() {
             },
             '/peer/connect': {
                 post: {
-                    summary: 'Connect to a peer',
+                    summary: 'Connect to a peer (omit host+port to resolve the address from the gossip graph / DNS bootstrap)',
                     tags: ['Peers'],
                     requestBody: bodyContent({
                         pubkey: 'string',
-                        host: 'string',
-                        port: 'number'
+                        host: 'string?',
+                        port: 'number?'
                     }),
                     responses: {
                         '200': {
@@ -725,96 +957,614 @@ function getOpenApiSpec() {
                     responses: { '200': { description: 'Probe result' } }
                 }
             },
-            '/backup': {
-                post: {
-                    summary: 'Create database backup',
-                    tags: ['Node'],
-                    requestBody: bodyContent({ destPath: 'string' }),
-                    responses: { '200': { description: 'Backup result' } }
-                }
-            },
-            '/send': {
-                post: {
-                    summary: 'Send on-chain Bitcoin',
-                    tags: ['Node'],
-                    requestBody: bodyContent({
-                        address: 'string',
-                        amountSats: 'number',
-                        satsPerVbyte: 'number?'
-                    }),
-                    responses: { '200': { description: 'Transaction info' } }
-                }
-            },
-            '/readiness': {
+            '/graph/info': {
                 get: {
-                    summary: 'Get mainnet readiness report with weighted checks',
-                    tags: ['Node'],
+                    summary: 'Network graph summary (node/channel counts, last sync)',
+                    tags: ['Graph'],
                     responses: {
                         '200': {
-                            description: 'Readiness report',
-                            content: jsonContent({
-                                $ref: '#/components/schemas/ReadinessReport'
-                            })
+                            description: 'Graph summary',
+                            content: jsonContent({ $ref: '#/components/schemas/GraphInfo' })
                         }
                     }
                 }
             },
-            '/stats': {
+            '/graph/node': {
                 get: {
-                    summary: 'Get node statistics',
-                    tags: ['Node'],
+                    summary: 'Node announcement info (alias, addresses, features) + its known channels',
+                    tags: ['Graph'],
                     parameters: [
                         {
-                            name: 'window',
+                            name: 'pubkey',
                             in: 'query',
-                            schema: { type: 'integer' },
-                            description: 'Time window in milliseconds. Only payments created within this window are included.'
+                            required: true,
+                            schema: { type: 'string' },
+                            description: '33-byte node public key (hex)'
                         }
                     ],
                     responses: {
                         '200': {
-                            description: 'Node stats',
-                            content: jsonContent({ $ref: '#/components/schemas/NodeStats' })
-                        }
+                            description: 'Graph node info',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/GraphNodeInfo'
+                            })
+                        },
+                        '404': { description: 'Node not found in graph' }
                     }
                 }
             },
-            '/liquidity': {
+            '/graph/channel': {
                 get: {
-                    summary: 'Get liquidity snapshot with recommendations',
-                    tags: ['Node'],
+                    summary: 'Channel info from gossip: endpoints, capacity and both directions of routing policy',
+                    tags: ['Graph'],
+                    parameters: [
+                        {
+                            name: 'scid',
+                            in: 'query',
+                            required: true,
+                            schema: { type: 'string' },
+                            description: 'Short channel id as <block>x<txIndex>x<output> or 16-char hex'
+                        }
+                    ],
                     responses: {
                         '200': {
-                            description: 'Liquidity snapshot',
+                            description: 'Graph channel info',
                             content: jsonContent({
-                                $ref: '#/components/schemas/LiquiditySnapshot'
+                                $ref: '#/components/schemas/GraphChannelInfo'
                             })
-                        }
+                        },
+                        '404': { description: 'Channel not found in graph' }
                     }
                 }
             },
-            '/fees': {
+            '/graph/describe': {
                 get: {
-                    summary: 'Get on-chain fee rate snapshot with trend analysis and channel-open recommendation',
-                    tags: ['Node'],
+                    summary: 'Paged dump of known graph channels (limit defaults to 500 and is capped at 500)',
+                    tags: ['Graph'],
+                    parameters: [
+                        { name: 'limit', in: 'query', schema: { type: 'integer' } },
+                        { name: 'offset', in: 'query', schema: { type: 'integer' } }
+                    ],
                     responses: {
                         '200': {
-                            description: 'Fee snapshot',
-                            content: jsonContent({ $ref: '#/components/schemas/FeeSnapshot' })
-                        },
-                        '400': { description: 'No fee samples recorded yet' }
+                            description: 'Paged channel dump with totalChannels/limit/offset',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    totalChannels: { type: 'integer' },
+                                    limit: { type: 'integer' },
+                                    offset: { type: 'integer' },
+                                    channels: {
+                                        type: 'array',
+                                        items: { $ref: '#/components/schemas/GraphChannelInfo' }
+                                    }
+                                }
+                            })
+                        }
                     }
                 }
             },
-            '/fees/estimates': {
-                get: {
-                    summary: 'Get current on-chain fee rate estimates in sats/vbyte',
-                    tags: ['Node'],
+            '/route/query': {
+                post: {
+                    summary: 'Compute a route to a destination WITHOUT sending; hops feed /payment/send-to-route',
+                    tags: ['Routing'],
+                    requestBody: bodyContent({
+                        destination: 'string',
+                        amountSats: 'number',
+                        maxFeeSats: 'number?'
+                    }),
                     responses: {
                         '200': {
-                            description: 'Fee estimates',
-                            content: jsonContent({ $ref: '#/components/schemas/OnchainFees' })
-                        }
+                            description: 'Route with per-hop fees and totals',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/RouteQueryResult'
+                            })
+                        },
+                        '400': { description: 'No route or fee exceeds maximum' }
+                    }
+                }
+            },
+            '/payment/send-to-route': {
+                post: {
+                    summary: 'Send a payment along an explicit route (hops from POST /route/query)',
+                    tags: ['Payments'],
+                    requestBody: {
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        paymentHash: { type: 'string' },
+                                        route: {
+                                            type: 'object',
+                                            properties: {
+                                                hops: {
+                                                    type: 'array',
+                                                    items: { $ref: '#/components/schemas/RouteHop' }
+                                                }
+                                            },
+                                            required: ['hops']
+                                        },
+                                        paymentSecret: {
+                                            type: 'string',
+                                            description: 'Invoice payment_secret (required by most modern invoices)'
+                                        }
+                                    },
+                                    required: ['paymentHash', 'route']
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Payment info',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/PaymentInfo'
+                            })
+                        }
+                    }
+                }
+            },
+            '/message/sign': {
+                post: {
+                    summary: "Sign a message with the node identity key (LND-compatible: double-SHA256 of 'Lightning Signed Message:' + message, compact recoverable ECDSA, zbase32)",
+                    tags: ['Node'],
+                    requestBody: bodyContent({ message: 'string' }),
+                    responses: {
+                        '200': {
+                            description: 'Signature (zbase32) and our node pubkey',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    signature: { type: 'string' },
+                                    pubkey: { type: 'string' }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/message/verify': {
+                post: {
+                    summary: 'Verify an LND-style message signature: recovers the signer pubkey and reports whether it is a known graph node. Compare pubkey against the expected signer.',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ message: 'string', signature: 'string' }),
+                    responses: {
+                        '200': {
+                            description: 'Verification result',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    valid: { type: 'boolean' },
+                                    pubkey: { type: 'string', nullable: true },
+                                    knownNode: { type: 'boolean' }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/gossip/sync': {
+                post: {
+                    summary: 'Request a gossip graph sync from one peer (pubkey) or all connected peers',
+                    tags: ['Graph'],
+                    requestBody: bodyContent({ pubkey: 'string?' }),
+                    responses: {
+                        '200': {
+                            description: 'Pubkeys a sync was initiated with',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    syncedFrom: {
+                                        type: 'array',
+                                        items: { type: 'string' }
+                                    }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/gossip/sync-rapid': {
+                post: {
+                    summary: 'Download and apply a Rapid Gossip Sync snapshot (mainnet only)',
+                    tags: ['Graph'],
+                    responses: {
+                        '200': {
+                            description: 'Ingestion counts',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    channelsAdded: { type: 'integer' },
+                                    updatesApplied: { type: 'integer' }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/channel/diagnostics': {
+                get: {
+                    summary: 'Routing-readiness diagnostics for a channel (SCID/announcement/peer-connection issues)',
+                    tags: ['Channels'],
+                    parameters: [
+                        {
+                            name: 'channelId',
+                            in: 'query',
+                            required: true,
+                            schema: { type: 'string' }
+                        }
+                    ],
+                    responses: {
+                        '200': { description: 'Diagnostics with an issues list' },
+                        '404': { description: 'Channel not found' }
+                    }
+                }
+            },
+            '/address/validate': {
+                post: {
+                    summary: 'Validate a Bitcoin address for the active network',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ address: 'string' }),
+                    responses: {
+                        '200': {
+                            description: 'Validity',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    address: { type: 'string' },
+                                    valid: { type: 'boolean' }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/recover-fallback-funds': {
+                post: {
+                    summary: 'Sweep UTXOs at the funding-key fallback address into the wallet',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ feeRatePerVbyte: 'number?' }),
+                    responses: {
+                        '200': {
+                            description: 'Broadcast txid and recovered amount, or { recovered: false } when nothing to recover',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    txid: { type: 'string' },
+                                    amountSat: { type: 'integer' },
+                                    inputCount: { type: 'integer' },
+                                    recovered: { type: 'boolean' }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/backup/trigger': {
+                post: {
+                    summary: 'Trigger an on-demand backup to the configured backupPath (no-op when unset)',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Trigger acknowledged',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: { triggered: { type: 'boolean' } }
+                            })
+                        }
+                    }
+                }
+            },
+            '/backup': {
+                post: {
+                    summary: 'Create database backup',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ destPath: 'string' }),
+                    responses: { '200': { description: 'Backup result' } }
+                }
+            },
+            '/backup/scb': {
+                get: {
+                    summary: 'Export the encrypted static channel backup (seed-encrypted blob)',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Encoded SCB blob, channel count, and on-disk path'
+                        }
+                    }
+                }
+            },
+            '/backup/peer-retrieved': {
+                get: {
+                    summary: 'Get the newest valid SCB a peer returned via BOLT 1 peer storage (recovery flow: reinstall with the mnemonic, connect to peers, fetch this, then POST /restore/scb with its encoded blob)',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Encoded SCB blob, its creation timestamp, and the peer that returned it'
+                        },
+                        '404': {
+                            description: 'No peer has returned a valid backup this session'
+                        }
+                    }
+                }
+            },
+            '/restore/scb': {
+                post: {
+                    summary: 'Restore channels from a static channel backup (on-chain recovery only: the peer force-closes and our balance is swept from its commitment)',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ encoded: 'string?', path: 'string?' }),
+                    responses: {
+                        '200': {
+                            description: 'Channel ids now recovering, entries skipped with reasons, and total channel count in the backup'
+                        },
+                        '400': {
+                            description: 'Invalid params (need exactly one of encoded/path), wrong seed, or wrong network'
+                        }
+                    }
+                }
+            },
+            '/send': {
+                post: {
+                    summary: 'Send on-chain Bitcoin',
+                    tags: ['Node'],
+                    requestBody: bodyContent({
+                        address: 'string',
+                        amountSats: 'number',
+                        satsPerVbyte: 'number?'
+                    }),
+                    responses: { '200': { description: 'Transaction info' } }
+                }
+            },
+            '/send-max': {
+                post: {
+                    summary: 'Sweep the entire spendable on-chain balance to one address (amount = balance minus fee)',
+                    tags: ['Node'],
+                    requestBody: bodyContent({
+                        address: 'string',
+                        satsPerVbyte: 'number?'
+                    }),
+                    responses: {
+                        '200': {
+                            description: 'Transaction info',
+                            content: jsonContent({ $ref: '#/components/schemas/TxInfo' })
+                        },
+                        '400': { description: 'Invalid address/fee rate or no UTXOs' }
+                    }
+                }
+            },
+            '/tx/bump-fee': {
+                post: {
+                    summary: 'Replace an unconfirmed RBF-signalling wallet transaction with a higher-fee version (BIP 125)',
+                    tags: ['Node'],
+                    requestBody: bodyContent({
+                        txid: 'string',
+                        satsPerVbyte: 'number'
+                    }),
+                    responses: {
+                        '200': {
+                            description: 'Boost result',
+                            content: jsonContent({ $ref: '#/components/schemas/BoostResult' })
+                        },
+                        '400': {
+                            description: 'NOT_BOOSTABLE (unknown/confirmed/non-RBF tx; try /tx/boost for CPFP) or invalid params'
+                        }
+                    }
+                }
+            },
+            '/tx/boost': {
+                post: {
+                    summary: 'Fee-bump an unconfirmed wallet transaction: RBF when possible, otherwise CPFP',
+                    tags: ['Node'],
+                    requestBody: bodyContent({
+                        txid: 'string',
+                        satsPerVbyte: 'number?'
+                    }),
+                    responses: {
+                        '200': {
+                            description: 'Boost result',
+                            content: jsonContent({ $ref: '#/components/schemas/BoostResult' })
+                        },
+                        '400': {
+                            description: 'NOT_BOOSTABLE or invalid params'
+                        }
+                    }
+                }
+            },
+            '/transactions/boostable': {
+                get: {
+                    summary: 'List unconfirmed wallet transactions eligible for RBF and/or CPFP fee bumping',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Boostable transactions by method',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/BoostableTransactions'
+                            })
+                        }
+                    }
+                }
+            },
+            '/consolidate': {
+                post: {
+                    summary: 'Merge all spendable UTXOs into a single output at a fresh wallet address (send-max-to-self)',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ satsPerVbyte: 'number?' }),
+                    responses: {
+                        '200': {
+                            description: 'Consolidation result',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/ConsolidateResult'
+                            })
+                        },
+                        '400': {
+                            description: 'NOTHING_TO_CONSOLIDATE (fewer than 2 UTXOs) or invalid params'
+                        }
+                    }
+                }
+            },
+            '/psbt/build': {
+                post: {
+                    summary: 'Build an UNSIGNED PSBT for an external signer (hardware wallet); includes bip32 derivation metadata, nothing is signed or broadcast',
+                    tags: ['Node'],
+                    requestBody: bodyContent({
+                        outputs: 'array',
+                        satsPerVbyte: 'number?'
+                    }),
+                    responses: {
+                        '200': {
+                            description: 'Unsigned PSBT (base64) with fee, vsize estimate and input/output summary'
+                        },
+                        '400': { description: 'Invalid outputs/fee rate or no UTXOs' }
+                    }
+                }
+            },
+            '/psbt/import-signed': {
+                post: {
+                    summary: 'Validate and finalize an externally signed PSBT; returns { txid, txHex } WITHOUT broadcasting',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ psbtBase64: 'string' }),
+                    responses: {
+                        '200': { description: 'Finalized transaction (not broadcast)' },
+                        '400': {
+                            description: 'PSBT_IMPORT_FAILED (missing/invalid signatures)'
+                        }
+                    }
+                }
+            },
+            '/psbt/combine': {
+                post: {
+                    summary: 'Combine partially signed copies of the same PSBT (multi-party signing)',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ psbts: 'array' }),
+                    responses: {
+                        '200': { description: 'Combined PSBT (base64)' },
+                        '400': { description: 'Fewer than two PSBTs or malformed input' }
+                    }
+                }
+            },
+            '/readiness': {
+                get: {
+                    summary: 'Get mainnet readiness report with weighted checks',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Readiness report',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/ReadinessReport'
+                            })
+                        }
+                    }
+                }
+            },
+            '/stats': {
+                get: {
+                    summary: 'Get node statistics',
+                    tags: ['Node'],
+                    parameters: [
+                        {
+                            name: 'window',
+                            in: 'query',
+                            schema: { type: 'integer' },
+                            description: 'Time window in milliseconds. Only payments created within this window are included.'
+                        }
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Node stats',
+                            content: jsonContent({ $ref: '#/components/schemas/NodeStats' })
+                        }
+                    }
+                }
+            },
+            '/liquidity': {
+                get: {
+                    summary: 'Get liquidity snapshot with recommendations',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Liquidity snapshot',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/LiquiditySnapshot'
+                            })
+                        }
+                    }
+                }
+            },
+            '/advisor/recommendations': {
+                get: {
+                    summary: 'Liquidity analysis (advisor analyze) plus the concrete circular-rebalance plan',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Advisor recommendations',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/AdvisorRecommendations'
+                            })
+                        }
+                    }
+                }
+            },
+            '/advisor/execute-rebalances': {
+                post: {
+                    summary: 'Execute the advisor rebalance plan under a strict per-UTC-day routing-fee budget (persisted across restarts)',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ budgetSatsPerDay: 'number?' }),
+                    responses: {
+                        '200': {
+                            description: 'Execution summary (msat values as strings)',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/RebalanceExecutionSummary'
+                            })
+                        }
+                    }
+                }
+            },
+            '/rebalance': {
+                post: {
+                    summary: 'Circular rebalance: self-payment out over fromChannelId and back in over toChannelId; aborts without paying if the route fee exceeds maxFeeSats',
+                    tags: ['Channels'],
+                    requestBody: bodyContent({
+                        fromChannelId: 'string',
+                        toChannelId: 'string',
+                        amountSats: 'number',
+                        maxFeeSats: 'number'
+                    }),
+                    responses: {
+                        '200': {
+                            description: 'Rebalance result',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/RebalanceResult'
+                            })
+                        },
+                        '400': {
+                            description: 'No route, fee exceeds maxFeeSats, or invalid params'
+                        }
+                    }
+                }
+            },
+            '/fees': {
+                get: {
+                    summary: 'Get on-chain fee rate snapshot with trend analysis and channel-open recommendation',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Fee snapshot',
+                            content: jsonContent({ $ref: '#/components/schemas/FeeSnapshot' })
+                        },
+                        '400': { description: 'No fee samples recorded yet' }
+                    }
+                }
+            },
+            '/fees/estimates': {
+                get: {
+                    summary: 'Get current on-chain fee rate estimates in sats/vbyte',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Fee estimates',
+                            content: jsonContent({ $ref: '#/components/schemas/OnchainFees' })
+                        }
                     }
                 }
             },
@@ -931,55 +1681,139 @@ function getOpenApiSpec() {
                     }
                 }
             },
-            '/events': {
-                get: {
-                    summary: 'Server-Sent Events stream (payment:received, payment:sent, payment:failed, channel:ready, channel:closed, peer:connect, peer:disconnect, node:ready)',
+            '/events': {
+                get: {
+                    summary: 'Server-Sent Events stream (payment:received, payment:sent, payment:failed, invoice:settled, channel:opening, channel:ready, channel:pending-close, channel:force-closing, channel:closed, peer:connect, peer:disconnect, node:ready; plus htlc:forwarded, htlc:fulfilled, htlc:failed when the daemon is started with htlcEvents)',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'SSE stream',
+                            content: { 'text/event-stream': {} }
+                        }
+                    }
+                }
+            },
+            '/stop': {
+                post: {
+                    summary: 'Gracefully stop the daemon (supports drain mode)',
+                    tags: ['Node'],
+                    requestBody: bodyContent({
+                        'drain?': 'boolean',
+                        'drainTimeoutMs?': 'number'
+                    }),
+                    responses: {
+                        '200': {
+                            description: 'Stopped',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    stopped: { type: 'boolean' },
+                                    drained: { type: 'boolean' }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/spend-limit': {
+                get: {
+                    summary: 'Get combined daily spending limit info (Lightning + external on-chain sends share one budget)',
+                    description: 'The daily limit covers Lightning payments AND external on-chain sends (amount + fee). Consolidation, channel funding and fee bumps are excluded. spentSats mirrors totalSats for back-compat.',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Spending limit info with LN/onchain breakdown',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    limitSats: { type: 'integer', nullable: true },
+                                    spentSats: { type: 'integer' },
+                                    remainingSats: { type: 'number' },
+                                    resetsAt: { type: 'integer' },
+                                    totalSats: { type: 'integer' },
+                                    lightningSats: { type: 'integer' },
+                                    onchainSats: { type: 'integer' }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/utxo/freeze': {
+                post: {
+                    summary: 'Freeze a UTXO so coin selection cannot spend it until unfrozen',
+                    tags: ['Node'],
+                    requestBody: bodyContent({ txid: 'string', index: 'integer' }),
+                    responses: {
+                        '200': {
+                            description: 'Frozen outpoint',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: { frozen: { type: 'string' } }
+                            })
+                        }
+                    }
+                }
+            },
+            '/utxo/unfreeze': {
+                post: {
+                    summary: 'Unfreeze a previously frozen UTXO',
                     tags: ['Node'],
+                    requestBody: bodyContent({ txid: 'string', index: 'integer' }),
                     responses: {
                         '200': {
-                            description: 'SSE stream',
-                            content: { 'text/event-stream': {} }
+                            description: 'Unfrozen outpoint',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: { unfrozen: { type: 'string' } }
+                            })
                         }
                     }
                 }
             },
-            '/stop': {
+            '/address/label': {
                 post: {
-                    summary: 'Gracefully stop the daemon (supports drain mode)',
+                    summary: 'Set a user label for an address (empty label clears it)',
                     tags: ['Node'],
-                    requestBody: bodyContent({
-                        'drain?': 'boolean',
-                        'drainTimeoutMs?': 'number'
-                    }),
+                    requestBody: bodyContent({ address: 'string', label: 'string' }),
                     responses: {
                         '200': {
-                            description: 'Stopped',
+                            description: 'Stored label',
                             content: jsonContent({
                                 type: 'object',
                                 properties: {
-                                    stopped: { type: 'boolean' },
-                                    drained: { type: 'boolean' }
+                                    address: { type: 'string' },
+                                    label: { type: 'string' }
                                 }
                             })
                         }
                     }
                 }
             },
-            '/spend-limit': {
+            '/address/labels': {
                 get: {
-                    summary: 'Get daily spending limit info',
+                    summary: 'List all user address labels keyed by address',
                     tags: ['Node'],
                     responses: {
                         '200': {
-                            description: 'Spending limit info',
+                            description: 'Labels map',
                             content: jsonContent({
                                 type: 'object',
-                                properties: {
-                                    limitSats: { type: 'integer', nullable: true },
-                                    spentSats: { type: 'integer' },
-                                    remainingSats: { type: 'number' },
-                                    resetsAt: { type: 'integer' }
-                                }
+                                additionalProperties: { type: 'string' }
+                            })
+                        }
+                    }
+                }
+            },
+            '/wallet/descriptors': {
+                get: {
+                    summary: 'Export BIP 380 output descriptors for the on-chain wallet (public keys only)',
+                    tags: ['Node'],
+                    responses: {
+                        '200': {
+                            description: 'Descriptors',
+                            content: jsonContent({
+                                $ref: '#/components/schemas/DescriptorsInfo'
                             })
                         }
                     }
@@ -988,13 +1822,23 @@ function getOpenApiSpec() {
             '/address/new': {
                 post: {
                     summary: 'Generate a new on-chain receiving address',
+                    description: 'Pass bip21:true (with optional amountSats/label/message) to also receive the address encoded as a BIP21 payment URI.',
                     tags: ['Node'],
+                    requestBody: bodyContent({
+                        bip21: 'boolean?',
+                        amountSats: 'integer?',
+                        label: 'string?',
+                        message: 'string?'
+                    }),
                     responses: {
                         '200': {
                             description: 'New address',
                             content: jsonContent({
                                 type: 'object',
-                                properties: { address: { type: 'string' } }
+                                properties: {
+                                    address: { type: 'string' },
+                                    bip21: { type: 'string' }
+                                }
                             })
                         }
                     }
@@ -1018,6 +1862,7 @@ function getOpenApiSpec() {
             '/mnemonic': {
                 get: {
                     summary: 'Get wallet mnemonic (requires API token)',
+                    description: 'Seed generation is CLI-only: `beignet init` creates the mnemonic; the daemon never generates or replaces a seed. This endpoint only reveals the configured mnemonic, and only when apiToken is set (returns MNEMONIC_REQUIRES_AUTH otherwise).',
                     tags: ['Node'],
                     responses: {
                         '200': {
@@ -1368,13 +2213,59 @@ function getOpenApiSpec() {
                         }
                     }
                 }
+            },
+            '/auth/keys': {
+                get: {
+                    summary: 'List named API keys (admin scope; never returns secrets)',
+                    tags: ['Auth'],
+                    responses: {
+                        '200': {
+                            description: 'Key names with their scopes and revoked flag',
+                            content: jsonContent({
+                                type: 'object',
+                                properties: {
+                                    keys: {
+                                        type: 'array',
+                                        items: {
+                                            type: 'object',
+                                            properties: {
+                                                name: { type: 'string' },
+                                                scopes: {
+                                                    type: 'array',
+                                                    items: {
+                                                        type: 'string',
+                                                        enum: ['readonly', 'invoice', 'admin']
+                                                    }
+                                                },
+                                                revoked: { type: 'boolean' }
+                                            }
+                                        }
+                                    }
+                                }
+                            })
+                        }
+                    }
+                }
+            },
+            '/auth/keys/revoke': {
+                post: {
+                    summary: 'Revoke a named API key for the lifetime of this daemon process (admin scope)',
+                    description: 'Runtime revocation only: the durable mechanism is removing the key from the config file and restarting. The legacy apiToken has no name and cannot be revoked here.',
+                    tags: ['Auth'],
+                    requestBody: bodyContent({ name: 'string' }),
+                    responses: {
+                        '200': { description: 'Key revoked' },
+                        '404': { description: 'No key with that name' }
+                    }
+                }
             }
         },
         components: {
             securitySchemes: {
                 bearerAuth: {
                     type: 'http',
-                    scheme: 'bearer'
+                    scheme: 'bearer',
+                    description: 'Legacy apiToken (implicit admin scope) or the secret of a named scoped API key from the apiKeys config. Routes advertise the scopes they accept via x-accepted-scopes; 401 = bad/absent key, 403 = valid key without a required scope.'
                 }
             },
             schemas: {
@@ -1451,7 +2342,33 @@ function getOpenApiSpec() {
                         vout: { type: 'integer' },
                         address: { type: 'string' },
                         valueSats: { type: 'integer' },
-                        height: { type: 'integer' }
+                        height: { type: 'integer' },
+                        frozen: {
+                            type: 'boolean',
+                            description: 'Frozen UTXOs are excluded from coin selection until unfrozen'
+                        }
+                    }
+                },
+                DescriptorsInfo: {
+                    type: 'object',
+                    description: 'BIP 380 output descriptors (with checksums). Public keys only; private keys are never exported.',
+                    properties: {
+                        fingerprint: { type: 'string' },
+                        network: { type: 'string' },
+                        account: { type: 'integer' },
+                        birthdayHeight: { type: 'integer' },
+                        watchOnly: { type: 'boolean' },
+                        descriptors: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    addressType: { type: 'string' },
+                                    external: { type: 'string' },
+                                    internal: { type: 'string' }
+                                }
+                            }
+                        }
                     }
                 },
                 OnchainFees: {
@@ -1465,6 +2382,40 @@ function getOpenApiSpec() {
                         timestamp: { type: 'integer' }
                     }
                 },
+                ForwardingEvent: {
+                    type: 'object',
+                    description: 'One settled forward. Msat values are decimal strings (JSON-safe bigint).',
+                    properties: {
+                        id: { type: 'integer' },
+                        settledAt: { type: 'integer' },
+                        inChannelId: { type: 'string' },
+                        outChannelId: { type: 'string' },
+                        inScid: { type: 'string' },
+                        outScid: { type: 'string' },
+                        amountInMsat: { type: 'string' },
+                        amountOutMsat: { type: 'string' },
+                        feeMsat: { type: 'string' }
+                    }
+                },
+                ForwardingSummary: {
+                    type: 'object',
+                    properties: {
+                        count: { type: 'integer' },
+                        volumeOutMsat: { type: 'string' },
+                        feesEarnedMsat: { type: 'string' }
+                    }
+                },
+                WatchtowerInfo: {
+                    type: 'object',
+                    properties: {
+                        uri: { type: 'string' },
+                        pubkey: { type: 'string' },
+                        connected: { type: 'boolean' },
+                        sessions: { type: 'integer' },
+                        pendingBacklog: { type: 'integer' },
+                        lastAck: { type: 'integer', nullable: true }
+                    }
+                },
                 HealthInfo: {
                     type: 'object',
                     properties: {
@@ -1519,7 +2470,36 @@ function getOpenApiSpec() {
                         fundingTxid: { type: 'string' },
                         shortChannelId: { type: 'string' },
                         feeratePerKw: { type: 'integer' },
-                        htlcCount: { type: 'integer' }
+                        htlcCount: { type: 'integer' },
+                        feeBaseMsat: { type: 'integer' },
+                        feeProportionalMillionths: { type: 'integer' },
+                        cltvExpiryDelta: { type: 'integer' },
+                        htlcMinimumMsat: {
+                            type: 'string',
+                            description: 'Msat as decimal string'
+                        },
+                        htlcMaximumMsat: {
+                            type: 'string',
+                            description: 'Msat as decimal string'
+                        }
+                    }
+                },
+                ChannelPolicy: {
+                    type: 'object',
+                    properties: {
+                        channelId: { type: 'string' },
+                        feeBaseMsat: { type: 'integer' },
+                        feeProportionalMillionths: { type: 'integer' },
+                        cltvExpiryDelta: { type: 'integer' },
+                        htlcMinimumMsat: {
+                            type: 'string',
+                            description: 'Msat as decimal string'
+                        },
+                        htlcMaximumMsat: {
+                            type: 'string',
+                            description: 'Msat as decimal string'
+                        },
+                        source: { type: 'string', enum: ['override', 'default'] }
                     }
                 },
                 PaymentInfo: {
@@ -1576,6 +2556,26 @@ function getOpenApiSpec() {
                         status: { type: 'string', enum: ['PENDING', 'PAID', 'EXPIRED'] }
                     }
                 },
+                HoldInvoiceInfo: {
+                    type: 'object',
+                    properties: {
+                        paymentHash: { type: 'string' },
+                        bolt11: { type: 'string' },
+                        state: {
+                            type: 'string',
+                            enum: ['OPEN', 'ACCEPTED', 'SETTLED', 'CANCELLED']
+                        },
+                        heldAmountMsat: {
+                            type: 'string',
+                            description: 'Total msat currently parked'
+                        },
+                        htlcCount: { type: 'integer' },
+                        amountSats: { type: 'integer' },
+                        description: { type: 'string' },
+                        expiry: { type: 'integer' },
+                        createdAt: { type: 'integer' }
+                    }
+                },
                 OfferInfo: {
                     type: 'object',
                     properties: {
@@ -1650,6 +2650,130 @@ function getOpenApiSpec() {
                         cltvDelta: { type: 'integer' }
                     }
                 },
+                GraphInfo: {
+                    type: 'object',
+                    properties: {
+                        nodeCount: { type: 'integer' },
+                        channelCount: { type: 'integer' },
+                        lastSyncAt: {
+                            type: 'integer',
+                            description: 'Epoch ms of the last gossip/RGS sync this session, if any'
+                        }
+                    }
+                },
+                GraphChannelPolicy: {
+                    type: 'object',
+                    description: "One direction's routing policy from a channel_update",
+                    properties: {
+                        feeBaseMsat: { type: 'integer' },
+                        feeProportionalMillionths: { type: 'integer' },
+                        cltvExpiryDelta: { type: 'integer' },
+                        htlcMinimumMsat: {
+                            type: 'string',
+                            description: 'Msat as decimal string'
+                        },
+                        htlcMaximumMsat: {
+                            type: 'string',
+                            description: 'Msat as decimal string'
+                        },
+                        disabled: { type: 'boolean' },
+                        lastUpdate: {
+                            type: 'integer',
+                            description: 'channel_update timestamp (seconds)'
+                        }
+                    }
+                },
+                GraphChannelInfo: {
+                    type: 'object',
+                    properties: {
+                        shortChannelId: {
+                            type: 'string',
+                            description: '<block>x<txIndex>x<outputIndex>'
+                        },
+                        node1Pubkey: { type: 'string' },
+                        node2Pubkey: { type: 'string' },
+                        capacitySats: {
+                            type: 'integer',
+                            description: 'Best-known lower bound from htlc_maximum_msat (capacity is not gossiped)'
+                        },
+                        node1Policy: {
+                            $ref: '#/components/schemas/GraphChannelPolicy'
+                        },
+                        node2Policy: {
+                            $ref: '#/components/schemas/GraphChannelPolicy'
+                        }
+                    }
+                },
+                GraphNodeInfo: {
+                    type: 'object',
+                    properties: {
+                        pubkey: { type: 'string' },
+                        alias: { type: 'string' },
+                        color: { type: 'string' },
+                        addresses: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    type: { type: 'integer' },
+                                    host: { type: 'string' },
+                                    port: { type: 'integer' }
+                                }
+                            }
+                        },
+                        featuresHex: { type: 'string' },
+                        lastUpdate: {
+                            type: 'integer',
+                            description: 'node_announcement timestamp (seconds)'
+                        },
+                        channelCount: { type: 'integer' },
+                        channels: { type: 'array', items: { type: 'string' } }
+                    }
+                },
+                RouteHop: {
+                    type: 'object',
+                    properties: {
+                        pubkey: { type: 'string' },
+                        shortChannelId: {
+                            type: 'string',
+                            description: '<block>x<txIndex>x<outputIndex> (16-char hex also accepted on input)'
+                        },
+                        amountToForwardMsat: {
+                            type: 'string',
+                            description: 'Msat as decimal string'
+                        },
+                        outgoingCltvValue: {
+                            type: 'integer',
+                            description: 'RELATIVE CLTV delta from pathfinding (absolute height added at send)'
+                        },
+                        feeMsat: {
+                            type: 'string',
+                            description: 'Fee this hop charges, msat as decimal string'
+                        },
+                        cltvExpiryDelta: { type: 'integer' }
+                    },
+                    required: [
+                        'pubkey',
+                        'shortChannelId',
+                        'amountToForwardMsat',
+                        'outgoingCltvValue'
+                    ]
+                },
+                RouteQueryResult: {
+                    type: 'object',
+                    properties: {
+                        destination: { type: 'string' },
+                        amountSats: { type: 'integer' },
+                        hops: {
+                            type: 'array',
+                            items: { $ref: '#/components/schemas/RouteHop' }
+                        },
+                        totalAmountMsat: { type: 'string' },
+                        totalFeeMsat: { type: 'string' },
+                        totalCltvDelta: { type: 'integer' },
+                        finalCltvExpiry: { type: 'integer' }
+                    }
+                },
                 TxInfo: {
                     type: 'object',
                     properties: {
@@ -1657,6 +2781,45 @@ function getOpenApiSpec() {
                         hex: { type: 'string' }
                     }
                 },
+                BoostResult: {
+                    type: 'object',
+                    properties: {
+                        txid: {
+                            type: 'string',
+                            description: 'Replacement (RBF) or child (CPFP) txid'
+                        },
+                        hex: { type: 'string' },
+                        boostType: { type: 'string', enum: ['rbf', 'cpfp'] },
+                        feeSats: { type: 'integer' },
+                        originalTxid: { type: 'string' }
+                    }
+                },
+                BoostableTransactions: {
+                    type: 'object',
+                    properties: {
+                        rbf: {
+                            type: 'array',
+                            items: { $ref: '#/components/schemas/OnchainTxInfo' }
+                        },
+                        cpfp: {
+                            type: 'array',
+                            items: { $ref: '#/components/schemas/OnchainTxInfo' }
+                        }
+                    }
+                },
+                ConsolidateResult: {
+                    type: 'object',
+                    properties: {
+                        txid: { type: 'string' },
+                        hex: { type: 'string' },
+                        utxosConsolidated: { type: 'integer' },
+                        address: {
+                            type: 'string',
+                            description: 'Fresh wallet address holding the merged output'
+                        },
+                        feeSats: { type: 'integer' }
+                    }
+                },
                 SpliceResult: {
                     type: 'object',
                     properties: {
@@ -1717,6 +2880,84 @@ function getOpenApiSpec() {
                         }
                     }
                 },
+                RebalancePlan: {
+                    type: 'object',
+                    properties: {
+                        fromChannelId: {
+                            type: 'string',
+                            description: 'Channel to push liquidity out of'
+                        },
+                        toChannelId: {
+                            type: 'string',
+                            description: 'Channel to pull liquidity in on'
+                        },
+                        amountSats: { type: 'integer' },
+                        reason: { type: 'string' }
+                    },
+                    required: ['fromChannelId', 'toChannelId', 'amountSats', 'reason']
+                },
+                AdvisorRecommendations: {
+                    allOf: [
+                        { $ref: '#/components/schemas/LiquiditySnapshot' },
+                        {
+                            type: 'object',
+                            properties: {
+                                rebalancePlan: {
+                                    type: 'array',
+                                    items: { $ref: '#/components/schemas/RebalancePlan' },
+                                    description: 'Circular rebalances the executor would run (nothing is executed by this endpoint)'
+                                }
+                            }
+                        }
+                    ]
+                },
+                RebalanceResult: {
+                    type: 'object',
+                    properties: {
+                        paymentHash: { type: 'string' },
+                        amountSats: { type: 'integer' },
+                        feeMsat: {
+                            type: 'string',
+                            description: 'Routing fee paid, msat as decimal string'
+                        },
+                        feeSats: { type: 'integer' },
+                        hops: { type: 'integer' }
+                    },
+                    required: ['paymentHash', 'amountSats', 'feeMsat', 'feeSats', 'hops']
+                },
+                RebalanceExecutionSummary: {
+                    type: 'object',
+                    properties: {
+                        attempts: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    fromChannelId: { type: 'string' },
+                                    toChannelId: { type: 'string' },
+                                    amountSats: { type: 'integer' },
+                                    status: {
+                                        type: 'string',
+                                        enum: ['SUCCEEDED', 'FAILED', 'SKIPPED_BUDGET']
+                                    },
+                                    feeMsat: { type: 'string' },
+                                    error: { type: 'string' }
+                                }
+                            }
+                        },
+                        succeeded: { type: 'integer' },
+                        failed: { type: 'integer' },
+                        skippedBudget: { type: 'integer' },
+                        feeSpentMsat: {
+                            type: 'string',
+                            description: 'Fees spent by this run, msat as decimal string'
+                        },
+                        budgetRemainingMsat: {
+                            type: 'string',
+                            description: 'Remaining budget for the current UTC day'
+                        }
+                    }
+                },
                 LiquidityRecommendation: {
                     type: 'object',
                     properties: {
@@ -2050,6 +3291,19 @@ function getOpenApiSpec() {
         },
         security: [{ bearerAuth: [] }]
     };
+    const paths = spec.paths;
+    for (const [routePath, operations] of Object.entries(paths)) {
+        for (const [method, operation] of Object.entries(operations)) {
+            const routeKey = `${method.toUpperCase()} ${routePath}`;
+            if (!(routeKey in auth_1.ROUTE_SCOPES))
+                continue;
+            operation['x-accepted-scopes'] = [
+                ...auth_1.ROUTE_SCOPES[routeKey],
+                'admin'
+            ];
+        }
+    }
+    return spec;
 }
 exports.getOpenApiSpec = getOpenApiSpec;
 function jsonContent(schema) {