LNCLI Methods Overview
LNCLI Command Line Interface Reference
Info Methods
getinfo
Syntax: lncli getinfo
Description: Returns basic information related to the active LND daemon, including identity pubkey, alias, chains connected to, and information about open/pending channels.
Key Parameters: No additional parameters required (uses global options like --rpcserver, --macaroonpath, --tlscertpath)
Usage Example:
getnetworkinfo
Syntax: lncli getnetworkinfo
Description: Get statistical information about the current state of the Lightning Network from the node's perspective, including number of nodes, channels, and network capacity.
Key Parameters: No additional parameters required
Usage Example:
channelbalance
Syntax: lncli channelbalance
Description: Returns the sum of the total available channel balance across all open channels, categorized in local/remote, pending local/remote and unsettled local/remote balances.
Key Parameters: No additional parameters required
Usage Example:
walletbalance
Syntax: lncli walletbalance
Description: Compute and display the wallet's current on-chain balance, showing total unspent outputs (confirmed and unconfirmed), all confirmed unspent outputs and all unconfirmed unspent outputs under control of the wallet.
Key Parameters:
- --account - The name of the account to retrieve the balance for (optional)
- --min_confs - The minimum number of confirmations each output should have (optional)
Usage Example:
Invoice Methods
addinvoice
Syntax: lncli addinvoice [command options] [value] [preimage]
Description: Add a new invoice, expressing intent for a future payment. Invoices without an amount can be created by not supplying any parameters or providing an amount of 0, allowing the payer to specify the amount.
Key Parameters:
- --memo - A description of the payment to attach along with the invoice
- --amt - The amount of satoshis in this invoice (default: 0)
- --amt_msat - The amount of millisatoshis in this invoice
- --expiry - Payment request expiry time in seconds (default: 3600)
- --amp - Generates an AMP invoice which can be paid multiple times
- --preimage - The hex-encoded preimage (32 byte) for the invoice
- --description_hash - SHA-256 hash of the description
- --fallback_addr - Fallback on-chain address
Usage Examples:
cancelinvoice
Syntax: lncli cancelinvoice [payment_hash]
Description: Cancel an existing invoice by its payment hash. Note: This command is available in newer versions of LND (0.8.0+) and requires the payment hash in hexadecimal format.
Key Parameters:
- payment_hash - The payment hash of the invoice to cancel (required, hex format)
Usage Example:
lookupinvoice
Syntax: lncli lookupinvoice [payment_hash]
Description: Lookup an existing invoice by its payment hash. The passed payment hash must be exactly 32 bytes in hexadecimal format.
Key Parameters:
- payment_hash - The payment hash of the invoice to lookup (required, hex format)
Usage Example:
subscribeinvoices
Syntax: lncli subscribeinvoices [command options]
Description: Creates a uni-directional stream from the server to the client for notifying the client of any newly created/settled invoices. This is a streaming RPC that will continuously return invoice updates.
Key Parameters:
- --add_index - The add index starting point for streaming (optional)
- --settle_index - The settle index starting point for streaming (optional)
Usage Example:
listinvoices
Syntax: lncli listinvoices [command options]
Description: List all invoices currently stored within the database. Any active debug invoices are ignored. It has full support for paginated responses with various filtering options.
Key Parameters:
- --pending_only - Toggles if all invoices should be returned, or only unsettled ones
- --index_offset - The index of an invoice to use as start/end of query (default: 0)
- --max_invoices - The max number of invoices to return (default: 100)
- --paginate-forwards - If set, invoices succeeding the index_offset will be returned
- --creation_date_start - Filter invoices with creation date >= this timestamp
- --creation_date_end - Filter invoices with creation date <= this timestamp
Usage Examples:
Payment Methods
decodepayreq
Syntax: lncli decodepayreq <payment_request>
Description: DecodePayReq takes an encoded payment request string and attempts to decode it, returning a full description of the conditions encoded within the payment request.
Key Parameters:
- payment_request - The Lightning Network payment request (invoice) string to decode
Usage Example:
deleteallpayments
Syntax: lncli deletepayments --all [--include_non_failed]
Description: DeleteAllPayments deletes all outgoing payments from the database. Note that it will not attempt to delete In-Flight payments, since that would be unsafe. By default, only failed payments are deleted.
Key Parameters:
- --all - Delete all payments
- --include_non_failed - Include successful payments in deletion (optional, false by default)
Usage Examples:
deletepayment
Syntax: lncli deletepayments <payment_hash> [--include_non_failed]
Description: DeletePayment deletes a specific outgoing payment from the database by its payment hash. Note that it will not attempt to delete an In-Flight payment, since that would be unsafe.
Key Parameters:
- payment_hash - The hex-encoded payment hash of the payment to delete
- --include_non_failed - Allow deletion of successful payments (optional, false by default)
Usage Example:
listpayments
Syntax: lncli listpayments [--include_incomplete] [--index_offset=<offset>] [--max_payments=<num>] [--reversed]
Description: ListPayments returns a list of all outgoing payments made by the node.
Key Parameters:
- --include_incomplete - Include incomplete (failed/pending) payments in the list
- --index_offset - The index of a payment used as an offset point
- --max_payments - The maximum number of payments to return
- --reversed - Return payments in reverse chronological order
Usage Examples:
trackpayment
Syntax: lncli trackpayment [--json] <payment_hash>
Description: Track progress of an existing payment. Pick up monitoring the progression of a previously initiated payment specified by the hash argument.
Key Parameters:
- payment_hash - The hex-encoded payment hash to track
- --json - Output payment updates as JSON messages
Usage Example:
sendpayment
Syntax: lncli sendpayment [options] --pay_req=<payment_request> OR lncli sendpayment [options] <dest> <amt> [payment_hash] [final_cltv_delta]
Description: Send a payment over Lightning. Can either use a payment request (invoice) or manually specify payment parameters. Note: This command is deprecated in favor of routerrpc.SendPaymentV2 in newer versions.
Key Parameters:
- --pay_req - Payment request (invoice) to pay
- --dest - Destination public key (hex)
- --amt - Amount in satoshis
- --keysend - Send spontaneous payment without invoice
- --amp - Use Atomic Multi-path Payments
- --fee_limit - Maximum fee in satoshis
- --fee_limit_percent - Maximum fee as percentage of payment amount
- --timeout - Payment timeout in seconds
Usage Examples:
Advanced Methods
Channel Management
channelacceptor
Syntax: lncli channelacceptor
Description: Dispatches a bi-directional streaming RPC that allows node operators to accept or reject inbound channel open requests based on custom criteria. Creates a persistent connection where OpenChannel requests are sent to the client, and the client responds with acceptance/rejection decisions.
Key Features:
- Streaming RPC maintaining persistent connection for real-time channel requests
- Custom control over channel acceptance criteria
- Can modify channel parameters like CSV delay, reserve amounts, etc.
Usage Example:
closechannel
Syntax: lncli closechannel [flags] funding_txid output_index OR lncli closechannel [flags] --chan_point=funding_txid:output_index
Description: Closes an active channel identified by its channel outpoint (funding transaction ID and output index). Supports both cooperative and unilateral (force) closures with extensive fee control options.
Key Parameters:
- --force - Attempt unilateral (force) closure
- --block - Wait for channel close confirmation
- --conf_target=<blocks> - Target confirmation blocks for fee estimation
- --sat_per_vbyte=<amount> - Manual fee rate in sat/vbyte
- --delivery_addr=<address> - Address to send funds on cooperative close
Usage Examples:
closedchannels
Syntax: lncli closedchannels [flags]
Description: Returns a description of all closed channels that the node was a participant in. Only shows channels that are fully resolved on-chain.
Key Parameters:
- --cooperative - Show only cooperatively closed channels
- --local_force - Show only locally force-closed channels
- --remote_force - Show only remotely force-closed channels
- --breach - Show only breach remedy transactions
- --funding_canceled - Show only channels where funding was canceled
- --abandoned - Show only abandoned channels
Usage Example:
getchaninfo
Syntax: lncli getchaninfo [flags] <chan_id> OR lncli getchaninfo --chan_point=<txid:index>
Description: Returns detailed authenticated network announcement information for a specific channel, identified by either its compact channel ID or channel point.
Key Parameters:
- chan_id - 8-byte compact channel ID (uint64)
- --chan_point=<txid:index> - Channel point format (alternative to chan_id)
Usage Example:
listchannels
Syntax: lncli listchannels [flags]
Description: Returns a description of all open channels that the node is a participant in. Provides comprehensive filtering options for channel states.
Key Parameters:
- --active_only - Show only currently active channels
- --inactive_only - Show only currently inactive channels
- --public_only - Show only public channels (announced to network)
- --private_only - Show only private channels (not announced)
- --peer=<pubkey> - Show channels with specific peer
Usage Examples:
openchannel
Syntax: lncli openchannel [flags] <node_key> <local_amt> [push_amt]
Description: Opens a new lightning channel to an existing peer. Supports extensive customization of channel parameters, funding options, and fee policies.
Key Parameters:
- --connect=<host:port> - Connect to peer before opening channel
- --private - Make channel private (not announced to network)
- --conf_target=<blocks> - Target confirmation time
- --sat_per_vbyte=<amount> - Manual fee rate
- --min_htlc_msat=<amount> - Minimum HTLC value (default: 1000)
- --base_fee_msat=<amount> - Base fee for forwarding (default: 1000)
- --fee_rate_ppm=<amount> - Fee rate in parts per million (default: 1)
- --zero_conf - Attempt zero-confirmation channel
- --channel_type=<type> - Channel type ("tweakless", "anchors", "taproot")
Usage Examples:
pendingchannels
Syntax: lncli pendingchannels [flags]
Description: Displays information about channels in various pending states - those waiting for confirmations, in the process of closing, or with time-locked funds.
Key Parameters:
- --include_raw_tx - Include raw transaction hex for waiting close channels
Usage Example:
subscribechannelevents
Syntax: lncli subscribechannelevents
Description: Creates a uni-directional stream from server to client that sends real-time updates about channel state changes. Essential for monitoring channel lifecycle events.
Usage Example:
On-Chain Methods
estimatefee
Syntax: lncli estimatefee [command options] send-json-string [--conf_target=N]
Description: Get fee estimates for sending bitcoin on-chain to multiple addresses. EstimateFee asks the chain backend to estimate the fee rate and total fees for a transaction that pays to multiple specified outputs.
Key Parameters:
- send-json-string - JSON string encoding addresses and amounts: '{"ExampleAddr": NumCoinsInSatoshis}'
- --conf_target - Number of blocks that the transaction should confirm in (optional)
- --coin_selection_strategy - Strategy for selecting coins ('largest', 'random', or 'global-config')
Usage Example:
gettransactions (listchaintxns)
Syntax: lncli listchaintxns [command options]
Description: Returns a list describing all the known transactions relevant to the wallet. Lists transactions from the wallet including on-chain transactions that pay to or are spends from lnd.
Key Parameters:
- --start_height - The block height from which to start listing transactions
- --end_height - The block height up to which to list transactions (use -1 for unconfirmed only)
- --account - An optional filter to only include transactions relevant to an account
Usage Examples:
newaddress
Syntax: lncli newaddress [address_type]
Description: Generates a new address under control of the local wallet. Creates a new address for receiving on-chain bitcoin payments.
Key Parameters (Address Types):
- p2wkh - Pay-to-Witness-PubkeyHash (native segwit, bech32)
- np2wkh - Nested-Pay-to-Witness-PubkeyHash (legacy segwit)
- p2tr - Pay-to-Taproot (taproot addresses, bech32m)
Usage Examples:
listunspent
Syntax: lncli listunspent [command options]
Description: Lists utxos available for spending. Returns a list of all unspent transaction outputs (UTXOs) that are under the control of the wallet.
Key Parameters:
- --min_confs - The minimum number of confirmations required for UTXOs (default: 1)
- --max_confs - The maximum number of confirmations for UTXOs
- --account - An optional filter to only include UTXOs from a specific account
Usage Examples:
listaddresses
Note: This command is not available in current LND versions. Address generation is handled through newaddress and transaction history via listchaintxns.
sendcoins
Syntax: lncli sendcoins [command options] addr amt
Description: SendCoins executes a request to send coins to a particular address. Unlike SendMany, this RPC call only allows creating a single output at a time.
Key Parameters:
- --addr - The bitcoin address to send coins to
- --amt - The number of bitcoin denominated in satoshis to send
- --conf_target - The number of blocks that the transaction should confirm in (optional)
- --sat_per_vbyte - Manual fee rate in sat/vByte (optional)
- --send_all - Send all wallet funds
- --label - A label for the transaction
Usage Examples:
sendmany
Syntax: lncli sendmany [command options] send-json-string
Description: SendMany handles a request for a transaction that creates multiple specified outputs in parallel. Allows creating a transaction with multiple outputs in a single transaction.
Key Parameters:
- send-json-string - JSON string encoding addresses and amounts: '{"ExampleAddr": NumCoinsInSatoshis}'
- --conf_target - Number of blocks for confirmation (optional)
- --sat_per_vbyte - Manual fee rate in sat/vByte (optional)
- --label - A label for the transaction
Usage Examples:
subscribetransactions
Note: This is a streaming RPC with no direct CLI command. Accessible via gRPC/REST API for real-time transaction notifications.
Peer Methods
connect
Syntax: lncli connect [command options] <pubkey>@host
Description: ConnectPeer attempts to establish a connection to a remote peer. This is at the networking level and is used for communication between nodes. This is distinct from establishing a channel with a peer.
Key Parameters:
- <pubkey>@host - Target address in format "pubkey@host:port"
- --perm - If set, the daemon will attempt to persistently connect to the target peer
Usage Examples:
disconnect
Syntax: lncli disconnect [command options] <pubkey>
Description: DisconnectPeer attempts to disconnect one peer from another identified by a given pubKey. In the case that there are pending or active channels with the target peer, this action will not be allowed.
Key Parameters:
- <pubkey> - The hex-encoded compressed public key of the peer to disconnect
Usage Example:
listpeers
Syntax: lncli listpeers
Description: ListPeers returns a verbose listing of all currently active peers. Shows detailed information about currently connected peers including their connection status and features.
Usage Example:
subscribepeerevents
Note: This is a streaming RPC with no direct CLI command. Accessible via gRPC/REST API for real-time peer online/offline events.
Routing Methods
buildroute
Syntax: lncli buildroute [command options] [arguments...]
Description: Builds a fully specified route based on a list of hop public keys. Retrieves relevant channel policies from the graph to calculate correct fees and time locks.
Key Parameters:
- --hops - Comma separated hex pubkeys defining the route path
- --amt - Amount to send in satoshis
- --final_cltv_delta - Blocks for last hop to reveal preimage
- --outgoing_chan_id - Short channel ID for first hop
- --payment_addr - Hex encoded payment address for last hop's MPP record
Usage Examples:
estimateroutefee
Syntax: lncli estimateroutefee [command options] dest amt
Description: Allows callers to obtain a lower bound estimate of how much it may cost to send an HTLC to a target destination.
Key Parameters:
- dest - Destination node public key (bytes)
- amt_sat - Amount in satoshis (int64)
Usage Example:
sendtoroute
Syntax: lncli sendtoroute [command options] [arguments...]
Description: ⚠️ DEPRECATED - Sends a payment over Lightning using a specific pre-defined route. Must specify the route and payment hash.
Key Parameters:
- --payment_hash - Hash to use within payment's HTLC
- --routes - JSON array string in queryroutes/buildroute response format
Usage Example:
queryroutes
Syntax: lncli queryroutes [command options] dest amt
Description: Queries the channel router for potential payment paths to a destination node that have sufficient flow for the specified amount, including fees.
Key Parameters:
- dest - 33-byte hex-encoded public key of payment destination
- amt - Amount to send in satoshis
- --fee_limit - Maximum fee allowed in satoshis
- --fee_limit_percent - Percentage of payment amount used as max fee
- --final_cltv_delta - Number of blocks last hop has to reveal preimage
- --use_mc - Use mission control probabilities for pathfinding
Usage Examples:
describegraph
Syntax: lncli describegraph [command options] [arguments...]
Description: Returns a description of the latest Lightning Network graph state from the node's perspective, including all nodes/vertices and edges (channels) connecting them.
Key Parameters:
- --include_unannounced - Include unannounced channels (both private channels and unannounced public channels)
- --include_auth_proof - Include announcement signatures in ChannelEdge data
Usage Examples:
HODL Invoices
addhodlinvoice
Syntax: lncli addhodlinvoice [options] <hash> [amount]
Description: Add a new hold invoice. Creates a hold invoice that ties the invoice to a hash supplied in the request. Unlike regular invoices, HODL invoices allow the receiver to delay settlement until they manually settle or cancel the invoice.
Key Parameters:
- hash - 32-byte hex-encoded hash for the HODL invoice
- amount - Amount in satoshis (positional argument)
- --memo - Description of the payment (optional)
- --amt - Amount in satoshis (alternative to positional)
- --expiry - Invoice expiry time in seconds (default: 86400 seconds/24 hours)
- --private - Include routing hints for private channels
Usage Examples:
settleinvoice
Syntax: lncli settleinvoice [--preimage=<preimage>] <preimage>
Description: Reveal a preimage and use it to settle the corresponding HODL invoice. This releases the held HTLC and completes the payment.
Key Parameters:
- preimage - The hex-encoded preimage (32 bytes) which will allow settling an incoming HTLC
Usage Examples:
Global Options
All LNCLI commands support these global options:
- --rpcserver - host:port of LN daemon (default: "localhost:10009")
- --lnddir - path to LND's base directory (default: "~/.lnd")
- --tlscertpath - path to TLS certificate
- --macaroonpath - path to macaroon file
- --no-macaroons - disable macaroon authentication
- --network - the network LND is running on (mainnet/testnet/simnet)
Version Compatibility Notes
- Commands documented are compatible with LND versions 0.17.x and 0.18.x
- The cancelinvoice command was introduced in LND v0.8.0
- sendpayment is deprecated in favor of routerrpc.SendPaymentV2
- sendtoroute is deprecated and will be removed in future versions
- Some parameter names and output formats may vary between versions
- Always use lncli <command> --help to see version-specific options