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 escape=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 experimental 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 available
  {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?[{outpoint}]:NONE}: '[]' if outpoint is available, or 'NONE' if not
{payment_id:{txid:UNKNOWN}}: the payment_id, or the txid if no payment_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 formatted strings for each income event

AUTHOR

Rusty Russell [email protected] is mainly responsible.

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"
}