LIGHTNING-BKPR-LISTINCOME(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💖 LIGHTNING-BKPR-LISTINCOME(7) 💖

ok so this is the lightning-bkpr-listincome page from section 7 of the manual, and bestie, it's literally the receipts page for your node. it's giving "show me the money" energy. let's get into it 🎀

✨ NAME ✨

bkpr-listincome — the command that lists, like, every income-impacting event. that's it, that's the vibe 💅

🦋 SYNOPSIS 🦋

bkpr-listincome [consolidate_fees] [start_time] [end_time]

three optional lil args, all cozy in a row. slay.

🌸 DESCRIPTION 🌸

bkpr-listincome is the RPC command that hands you a full list of every income-impacting event the bookkeeper plugin has recorded for this node. every single one. no cap. it's your node's whole money diary and it's honestly iconic 👑

here's the params, and yes they're all optional:

  • consolidate_fees (boolean, optional) — if true, we emit a single, consolidated event for any onchain-fees for a txid and account. otherwise, events for every update to the onchain fee calculation for this account and txid will be printed. ⚠️ heads up though: this means the events emitted are non-stable, i.e. calling listincome twice may result in different onchain fee events being emitted, depending on how much information we've logged for that transaction. so like, don't be weirded out if it changes on you. the default is True.
  • start_time (u32, optional) — a UNIX timestamp (in seconds) that filters events after the provided timestamp. the default is zero.
  • end_time (u32, optional) — a UNIX timestamp (in seconds) that filters events up to and at the provided timestamp. the default is max-int. yes, that's the big one 🫶
ngl the fee-consolidation instability is the one thing to remember here — stable output is not guaranteed when consolidate_fees is on, fr fr.

⭐ RETURN VALUE ⭐

on success, you get back an object containing income_events. it's an array of objects, and each object inside contains:

  • account (string) — the account name. if the account is a channel, it's the channel_id.
  • tag (string) — type of income event.
  • credit_msat (msat) — amount earned (income). 🤑
  • debit_msat (msat) — amount spent (expenses). 😭
  • currency (string) — human-readable bech32 part for this coin type.
  • timestamp (u32) — timestamp this event was recorded by the node. for consolidated events such as onchain_fees, it's the most recent timestamp.
  • description (string, optional) — more information about this event. if it's an invoice type, typically the bolt11/bolt12 description.
  • outpoint (string, optional) — the txid:outnum for this event, if applicable.
  • txid (txid, optional) — the txid of the transaction that created this event, if applicable.
  • payment_id (hex, optional) — Lightning payment identifier. for an htlc, this will be the preimage.

🧚 AUTHOR 🧚

Lisa Neigut niftynei@gmail.com is mainly responsible. thank you lisa, we appreciate you 💜

🌈 SEE ALSO 🌈

lightning-bkpr-listaccountevents(7), lightning-listfunds(7), lightning-bkpr-listbalances(7)

go read those next, iykyk 🦋

🔥 RESOURCES 🔥

Main web site: https://github.com/ElementsProject/lightning

🍓 EXAMPLES 🍓

Example 1

Request:

$ lightning-cli bkpr-listincome -k "consolidate_fees"=False

{
  "id": "example:bkpr-listincome#1",
  "method": "bkpr-listincome",
  "params": {
    "consolidate_fees": false
  }
}

Response:

{
  "income_events": [
    {
      "account": "wallet",
      "tag": "deposit",
      "credit_msat": 200000000000,
      "debit_msat": 0,
      "currency": "bcrt",
      "timestamp": 1738500000,
      "description": "edited utxo description",
      "outpoint": "txidbk0000000000000000000000000000000000000000000000000000000000:1"
    },
    {
      "account": "wallet",
      "tag": "deposit",
      "credit_msat": 2000000000,
      "debit_msat": 0,
      "currency": "bcrt",
      "timestamp": 1738510000,
      "outpoint": "txidbk0101010101010101010101010101010101010101010101010101010101:1"
    },
    {
      "account": "wallet",
      "tag": "onchain_fee",
      "credit_msat": 0,
      "debit_msat": 1004927000,
      "currency": "bcrt",
      "timestamp": 1738520000,
      "txid": "channeltxid340000340000340000340000340000340000340000340000340000"
    },
    {
      "account": "wallet",
      "tag": "onchain_fee",
      "credit_msat": 1004927000,
      "debit_msat": 0,
      "currency": "bcrt",
      "timestamp": 1738530000,
      "txid": "channeltxid340000340000340000340000340000340000340000340000340000"
    }
  ]
}

Example 2

Request:

$ lightning-cli bkpr-listincome

{
  "id": "example:bkpr-listincome#2",
  "method": "bkpr-listincome",
  "params": {}
}

Response:

{
  "income_events": [
    {
      "account": "wallet",
      "tag": "deposit",
      "credit_msat": 200000000000,
      "debit_msat": 0,
      "currency": "bcrt",
      "timestamp": 1738510000,
      "description": "edited utxo description",
      "outpoint": "txidbk0101010101010101010101010101010101010101010101010101010101:1"
    },
    {
      "account": "channelid0230000230000230000230000230000230000230000230000230000",
      "tag": "invoice",
      "credit_msat": 500000000,
      "debit_msat": 0,
      "currency": "bcrt",
      "timestamp": 1738520000,
      "description": "edited invoice description from description send some sats l2 to l3",
      "payment_id": "paymentid0000202020202020202020202020202020202020202020202020202"
    },
    {
      "account": "channelid0340200340200340200340200340200340200340200340200340200",
      "tag": "onchain_fee",
      "credit_msat": 0,
      "debit_msat": 6960000,
      "currency": "bcrt",
      "timestamp": 1738530000,
      "txid": "channeltxid340200340200340200340200340200340200340200340200340200"
    }
  ]
}

ok that's the whole page, you ate that 🫶 this one's from Core Lightning v26.06.9, dated LIGHTNING-BKPR-LISTINCOME(7) — go check your income events bestie, your node is literally main character energy 💖✨

📦 where this page comes from