LIGHTNING-BKPR-REPORT(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

🌸 LIGHTNING-BKPR-REPORT(7) — the bkpr-report glow-up 🌸

okay bestie, so this is a lightning manual page, and honestly? it's giving accountant-chic. it's the formatting bible for all income impacting events — yes, that's the NAME line and yes we're keeping it 💅

✨ SYNOPSIS ✨

bkpr-report [format] [headers] [escape] [start_time] [end_time]

💖 DESCRIPTION 💖

Bestie. This command was added in v26.04, so if you're on an older node, no crumbs for you 😭

So basically the bkpr-report RPC command creates a list of all income impacting events that the bookkeeper plugin has recorded for this node. All of them. Every single one. It does not skip. It does not ghost you.

And here's the iconic part: it has the useful property that when you use it with $ lightning-cli and escape=csv, it can directly produce valid CSV files. Like, straight into your spreadsheet. spreadsheet-core fr fr 🎀

the params, one by one 🦋

  • format (string, optional) — this format string is used for each income event. Small warning bestie: $ lightning-cli can get confused if the format begins and ends with { and }, so you may need to add a space. iykyk. The following tags in braces get 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). no cap, it just vibes empty ✨

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}: [<value>] 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 {{. that's the whole trick, bestie 🫶

  • 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. so like, the tags get escaped, your own text does not — don't @ me, that's just how it is 😌
  • 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. (yes, max-int. it goes to the moon 🌈)

🔥 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 rusty@rustcorp.com.au is mainly responsible. main character energy, honestly 💜

🌟 SEE ALSO 🌟

lightning-bkpr-listaccountevents(7), lightning-bkpr-listbalances(7), lightningd-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"
}
heads up bestie: if you need your own text escaped, that's on you — only the {} tags get the csv treatment 💖

and that's the whole page! this bad girl ships with Core Lightning v26.06.9, dated with love, and she ate. periodt. 🎀✨💅

📦 where this page comes from