LIGHTNING-BKPR-REPORT(7) LIGHTNING-BKPR-REPORT(7) NAME bkpr-report -- Formatting for all income impacting events SYNOPSIS bkpr-report [format] [headers] [escape] [start_time] [end_time] DESCRIPTION Command added in v26.04. The bkpr-report RPC command creates a list of all income impacting events that the bookkeeper plugin has recorded for this node. It has the useful property that when used with $ lightning-cli and the es- cape=csv it can directly produce valid CSV files. * format (string, optional): This format string is used for each income event (note that $ lightning-cli can get confused if the format begins and ends with { and }, so you may need to add a space). The following tags in braces are replaced: * {account}: account name (channel id, or 'wallet') * {tag}: event tag. This will be one of: * deposit: an onchain send to the wallet by outpoint. * htlc_fulfill: an onchain HTLC fulfill (due to unilaterally closed channel) at outpoint. * invoice: either incoming (positive credit) or outgoing (positive debit) payment. * invoice_fee: the routing fee paid to pay an outgoing invoice * journal_entry: an accounting fixup, caused by loss of data (or, a node which predates bookkeeper) * lease_fee: a fee paid or received to lease a channel via the experi- mental liquidity advertisement option * onchain_fee,: a miner fee paid to open/close a channel, or make a bitcoin payment. The txid will correspond to a withdrawal outpoint for withdrawl * pushed: an amount pushed to or from us on channel open. * rebalance_fee: routing fee paid for sending a payment to ourselves. * routed: credit gained from routing a payment * withdrawal: debit from an onchain spend. * {description}: description as provided in the invoice, if present * {credit}: credit amount in BTC * {debit}: debit amount in BTC * {fees}: fee amount in BTC * {localtime}: event timestamp in local time as YYYY-MM-DD HH:MM:SS * {utctime}: event timestamp in UTC as YYYY-MM-DD HH:MM:SS * {outpoint}: outpoint, if present * {txid}: txid, if present * {payment_id}: payment hash, if present * {bkpr-currency}: value of bkpr-currency, if any * {currencyrate}: exchange rate for 1 BTC at that event time, if avail- able * {creditdebit}: +credit or -debit (or 0) in BTC * {currencycredit}: credit amount converted into bkpr-currency * {currencydebit}: debit amount converted into bkpr-currency * {currencycreditdebit}: +credit or -debit (or 0) in bkpr-currency If a field is unavailable, it expands to an empty string (or 0 for credit, debit, fees and creditdebit). Tags support C-style conditional syntax: {tag[?if-set][:if-not-set]} * if-set: text to use when the tag is present (and non-zero for credit, debit, fees and creditdebit). Default is the tag value itself. * if- not-set: text to use when the tag is absent (or zero for amount fields). Default is empty string (or 0 for amount fields). Either or both parts may be omitted, and each part can itself contain tags. For example: * {outpoint:NONE}: the outpoint value, or 'NONE' if not available * {credit:0.00}: the credit value, or '0.00' if zero * {outpoint?[{out- point}]:NONE}: [<value>] if outpoint is available, or 'NONE' if not * {payment_id:{txid:UNKNOWN}}: the payment_id, or the txid if no pay- ment_id, or 'UNKNOWN' if neither To include a literal {, write {{. * headers (array of strings, optional): strings to place at the top of the output (useful when creating CSV files directly).: * (string, optional) * escape (string, optional): How to handle the formatted output fields: if set to csv it will handle fields with commas or double-quotes correctly for that format. Note that text is never escaped (you need to do that), only {} tags. The default is none. * start_time (u32, optional): UNIX timestamp (in seconds) that filters events after the provided timestamp. The default is zero. * end_time (u32, optional): UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. The default is max-int. RETURN VALUE On success, an object is returned, containing: * report (array of strings): * (string, optional): The headers one per entry, followed by the for- matted strings for each income event AUTHOR Rusty Russell rusty@rustcorp.com.au is mainly responsible. SEE ALSO lightning-bkpr-listaccountevents(7), lightning-bkpr-listbalances(7), light- ningd-config(5) RESOURCES Main web site: https://github.com/ElementsProject/lightning EXAMPLES Example 1: Request: $ lightning-cli bkpr-report -k "headers"='["Date,Tag,Account,Description,Credit,Debit,BTC/USD,Credit (USD),Debit(USD)"]' "format"="{localtime},{tag},{account},{description?Invoice description {description}:{outpoint?Onchain output {outpoint}:{txid?Onchain transaction {txid}}}},{credit?+{credit}:0},{debit?-{debit}:0},{currencyrate},${currencycredit},${currencydebit}" "escape"="csv" { "id": "example:bkpr-report#1", "method": "bkpr-report", "params": { "headers": [ "Date,Tag,Account,Description,Credit,Debit,BTC/USD,Credit (USD),Debit(USD)" ], "format": "{localtime},{tag},{account},{description?Invoice description {description}:{outpoint?Onchain output {outpoint}:{txid?Onchain transaction {txid}}}},{credit?+{credit}:0},{debit?-{debit}:0},{currencyrate},${currencycredit},${currencydebit}", "escape": "csv" } } Response: { "report": [ "Date,Tag,Account,Description,Credit,Debit,BTC/USD,Credit (USD),Debit(USD)", "2026-04-02 12:42:03,deposit,wallet,Onchain output 37562cf0b3a5d6783ae02925bcc486bb89afe156abf15e692736e5da9a060018:1,+0.02000000000,0,67140.89,$1342.81,$0.00", "2026-04-02 12:42:04,invoice,9b3114c8003dc8dedbcf3b7bc9fb04e1575a1112aea33be8369ae9670aff64f4,Invoice description test_bkpr_report_invoice,0,-0.00000123456,67140.89,$0.00,$0.08", "2026-04-02 12:42:04,onchain_fee,9b3114c8003dc8dedbcf3b7bc9fb04e1575a1112aea33be8369ae9670aff64f4,Onchain transaction f464ff0a67e99a36e83ba3ae12115a57e104fbc97b3bcfdbdec83d00c814319b,0,-0.00004927000,67140.89,$0.00,$3.30" ], "format-hint": "simple" } Core Lightning v26.06.1 LIGHTNING-BKPR-REPORT(7)
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | AUTHOR | SEE ALSO | RESOURCES | EXAMPLES
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=lightning-bkpr-report&sektion=7&manpath=FreeBSD+Ports+15.1.quarterly>