LIGHTNING-LISTCHAINMOVES(7)
💅 LIGHTNING-LISTCHAINMOVES(7) 💅
okay so bestie, welcome to lightning-listchainmoves — that's the manual page name, iconic, we love a lowercase-with-dashes moment. this one's about pulling up the audit list of all onchain coin movements. like a receipts folder but for your sats. 🧾✨
🌸 NAME 🌸
listchainmoves — the command that gets you the audit list of all onchain coin movements. every coin that moved onchain? it's in here. no cap. 💖
🦋 SYNOPSIS 🦋
listchainmoves [index [start] [limit]]look at her. three optional little args, all chillin in brackets, none of them mandatory. she's low maintenance fr fr.
✨ DESCRIPTION ✨
so this command was added in v25.09 — new girl on the block, and she's already main character energy. 💅
listchainmoves returns the confirmed balance changes onchain over time. that's the vibe: not pending stuff, not maybes — confirmed. 📌
here's the parameters situation, one by one:
index(string, optional) (always"created") — this tells the command how to interpretstartandlimit. and yes, the only value it takes is literally"created", that's the whole personality. 🎀start(u64, optional) — ifindexis specified, you can also specifystartto start from that value. and where do you usually get that value? fromlightning-wait(7), bestie. iykyk. ⭐limit(u32, optional) — ifindexis specified,limitlets you set the maximum number of entries to return. so you don't get absolutely flooded. 💀
ngl the pattern here is:startandlimitonly do their thing ifindexis specified. don't come for me, that's just what the manpage says. 🫶
👑 RETURN VALUE 👑
on success, you get an object containing chainmoves. it's an array of objects, and every single object inside contains this whole list:
created_index(u64) — a 1-based index showing the order this move was created in. 1-based, so the first one is 1, not 0. she's not like other indexes. 💅account_id(string) — this is either thechannel_idcorresponding to the channel involved, or a string such aswalletfor the internal wallet, orexternalfor some other external source. so basically: who's account is this. 🏦credit_msat(msat) — amount credited. and note: one of this ordebit_msatis zero. you don't get both, that's the rule. 💖debit_msat(msat) — amount debited. and again, one of this orcredit_msatis zero. balance, bestie. ⚖️timestamp(u64) — time of this event in seconds since January 1 1970 UTC. yes, unix epoch, the classic. 🕰️primary_tag(string) (one of"deposit","withdrawal","penalty","channel_open","channel_close","delayed_to_us","htlc_tx","htlc_timeout","htlc_fulfill","to_wallet","anchor","to_them","penalized","stolen","ignored","to_miner") — a set of one or more tags defining the nature of the change. like a vibe check for your transaction. 🔥extra_tags(array of strings) — a set of extra tags expanding on the details:- (string, optional) (one of
"opener","leased","stealable","splice","foreign") — the extra sprinkle on top. 🧚
- (string, optional) (one of
utxo(outpoint) — the txid and outpoint number spent for this balance change. the receipts of the receipts. 🧾output_msat(msat) — the output amount (always a whole number of sats). ⚠️ note that in some cases (e.g. channel opens), not all these belong to us. read that again bestie, don't get too excited. 😭blockheight(u32) — the block number wheretxidappeared (alternately, whereutxowas spent). 📦peer_id(pubkey, optional) — the lightning peer associated with this onchain event. your lil friend. 🫶originating_account(string, optional) — this is either achannel_idcorresponding to the source channel involved, or a string such aswalletfor the internal wallet. where it came from. 🐣spending_txid(txid, optional) — the transaction ID which did the spending. the culprit. 🕵️payment_hash(hash, optional) — the payment hash associated with this balance change. 🔗output_count(u32, optional) — the number of outputs in thetxid(so you can tell once you've seen events for all of them). handy little counter, honestly obsessed. 🎀
💀 ERRORS 💀
on failure, one of the following error codes may be returned:
-32602— error in given parameters. aka you gave her something she can't work with. tragic, but fixable. 🙈
🌈 RESOURCES 🌈
main web site: https://github.com/ElementsProject/lightning — go say hi, the source is right there. ⭐
🍓 EXAMPLES 🍓
Example 1:
Request:
$ lightning-cli listchainmoves{
"id": "example:listchainmoves#1",
"method": "listchainmoves",
"params": {}
}Response:
...and here's what comes back, bestie — a whole chainmoves array, one object per move, and it is so much information 💅 read it slow, okay?
{
"chainmoves": [
{
"created_index": 1,
"account_id": "wallet",
"credit_msat": 200000000000,
"debit_msat": 0,
"timestamp": 1758192762,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "994185cba7723715c0aa1d1859ce2781116776cea917035c90f8f04c9f4e095e:1",
"output_msat": 200000000000,
"blockheight": 104
},
{
"created_index": 2,
"account_id": "252d1b0a1e57895e84137f28cf19ab2c35847e284c112fefdecc7afeaa5c1de7",
"credit_msat": 0,
"debit_msat": 0,
"timestamp": 1758192777,
"primary_tag": "channel_open",
"extra_tags": [],
"utxo": "542906c8a9d90596592459a9484f4286a3200f6540599c83b43af2ac4166c6ca:1",
"peer_id": "nodeid010101010101010101010101010101010101010101010101010101010101",
"output_msat": 1000000000,
"blockheight": 109
},
{
"created_index": 3,
"account_id": "wallet",
"credit_msat": 2000000000,
"debit_msat": 0,
"timestamp": 1758192780,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "19e9e42f2f2097ea1dc18d7eb670bc53c90cbe31bb1daba8e94abf3c6b60d2dc:1",
"output_msat": 2000000000,
"blockheight": 110
},
{
"created_index": 4,
"account_id": "wallet",
"credit_msat": 0,
"debit_msat": 200000000000,
"timestamp": 1738530000,
"primary_tag": "withdrawal",
"extra_tags": [],
"utxo": "994185cba7723715c0aa1d1859ce2781116776cea917035c90f8f04c9f4e095e:1",
"spending_txid": "94418b652c9a0d79129552d317dcc37cb55afda1387257a22c7f16aa3981b7bc",
"output_msat": 200000000000,
"blockheight": 111
},
{
"created_index": 5,
"account_id": "wallet",
"credit_msat": 198995073000,
"debit_msat": 0,
"timestamp": 1738530000,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "94418b652c9a0d79129552d317dcc37cb55afda1387257a22c7f16aa3981b7bc:1",
"output_msat": 198995073000,
"blockheight": 111
},
{
"created_index": 6,
"account_id": "a397dd9b3e44afcb67f3f3ce1d649b74a8ade63e35505985e4cc1828634f69a2",
"credit_msat": 1000000000,
"debit_msat": 0,
"timestamp": 1738530000,
"primary_tag": "channel_open",
"extra_tags": [
"opener"
],
"utxo": "94418b652c9a0d79129552d317dcc37cb55afda1387257a22c7f16aa3981b7bc:0",
"peer_id": "nodeid030303030303030303030303030303030303030303030303030303030303",
"output_msat": 1000000000,
"blockheight": 111
},
{
"created_index": 7,
"account_id": "wallet",
"credit_msat": 2000000000,
"debit_msat": 0,
"timestamp": 1758192792,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "b6d0090efbeb347fa59f90b321d6906cdf86779c15477582979fa427249f71f5:1",
"output_msat": 2000000000,
"blockheight": 114
},
{
"created_index": 8,
"account_id": "wallet",
"credit_msat": 0,
"debit_msat": 198995073000,
"timestamp": 1758192795,
"primary_tag": "withdrawal",
"extra_tags": [],
"utxo": "94418b652c9a0d79129552d317dcc37cb55afda1387257a22c7f16aa3981b7bc:1",
"spending_txid": "32de3d1592062670eb8630875a28705cc1988b7f83f8c712bf9d39be2152efec",
"output_msat": 198995073000,
"blockheight": 115
},
{
"created_index": 9,
"account_id": "wallet",
"credit_msat": 197990453000,
"debit_msat": 0,
"timestamp": 1758192795,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "32de3d1592062670eb8630875a28705cc1988b7f83f8c712bf9d39be2152efec:0",
"output_msat": 197990453000,
"blockheight": 115
},
{
"created_index": 10,
"account_id": "f8fc83a432cbfb2fffe222cc06727fdd977b5dd10ebd6707158e799e6f522d9f",
"credit_msat": 1000000000,
"debit_msat": 0,
"timestamp": 1758192795,
"primary_tag": "channel_open",
"extra_tags": [
"opener"
],
"utxo": "32de3d1592062670eb8630875a28705cc1988b7f83f8c712bf9d39be2152efec:1",
"peer_id": "nodeid050505050505050505050505050505050505050505050505050505050505",
"output_msat": 1000000000,
"blockheight": 115
},
{
"created_index": 11,
"account_id": "wallet",
"credit_msat": 486914000,
"debit_msat": 0,
"timestamp": 1738520000,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "874b26d4c523a902fdc44b88ec000eb5c3fe8754c9d44190a140561e24e77781:0",
"output_msat": 486914000,
"blockheight": 121
},
{
"created_index": 12,
"account_id": "a397dd9b3e44afcb67f3f3ce1d649b74a8ade63e35505985e4cc1828634f69a2",
"credit_msat": 0,
"debit_msat": 489809898,
"timestamp": 1738520000,
"primary_tag": "channel_close",
"extra_tags": [],
"utxo": "94418b652c9a0d79129552d317dcc37cb55afda1387257a22c7f16aa3981b7bc:0",
"spending_txid": "txid010101010101010101010101010101010101010101010101010101010101",
"output_msat": 1000000000,
"output_count": 2,
"blockheight": 121
},
{
"created_index": 13,
"account_id": "external",
"credit_msat": 510190000,
"debit_msat": 0,
"timestamp": 1738520000,
"primary_tag": "to_them",
"extra_tags": [],
"utxo": "874b26d4c523a902fdc44b88ec000eb5c3fe8754c9d44190a140561e24e77781:1",
"originating_account": "channelid0230000230000230000230000230000230000230000230000230000",
"output_msat": 510190000,
"blockheight": 121
},
{
"created_index": 14,
"account_id": "wallet",
"credit_msat": 2000000000,
"debit_msat": 0,
"timestamp": 1758192808,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "c9c9bec064382b6a6fb2a30d8923949b3c9f732465542b96e9ad1b5eebda4c7d:0",
"output_msat": 2000000000,
"blockheight": 122
},
{
"created_index": 15,
"account_id": "wallet",
"credit_msat": 0,
"debit_msat": 197990453000,
"timestamp": 1738500000,
"primary_tag": "withdrawal",
"extra_tags": [],
"utxo": "32de3d1592062670eb8630875a28705cc1988b7f83f8c712bf9d39be2152efec:0",
"spending_txid": "0137213d852e76d48f0270a78218d2f562ac0a8974f814cab66376537cfd1682",
"output_msat": 197990453000,
"blockheight": 123
},
{
"created_index": 16,
"account_id": "wallet",
"credit_msat": 196985833000,
"debit_msat": 0,
"timestamp": 1738500000,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "0137213d852e76d48f0270a78218d2f562ac0a8974f814cab66376537cfd1682:1",
"output_msat": 196985833000,
"blockheight": 123
},
{
"created_index": 17,
"account_id": "channelid0230200230200230200230200230200230200230200230200230200",
"credit_msat": 1000000000,
"debit_msat": 0,
"timestamp": 1738500000,
"primary_tag": "channel_open",
"extra_tags": [
"opener"
],
"utxo": "0137213d852e76d48f0270a78218d2f562ac0a8974f814cab66376537cfd1682:0",
"peer_id": "nodeid030303030303030303030303030303030303030303030303030303030303",
"output_msat": 1000000000,
"blockheight": 123
}
]
}okay lowkey stare at it for a sec because the shape of it is so satisfying ✨ every move gets a created_index counting up from 1, and then only the fields that actually apply — like, entry 2 has no spending_txid at all, but entry 4 does, and entry 12 rocks an output_count of 2 because it's a channel_close. entries with extra_tags get themselves an array (["opener"]) and the rest just get a tidy []. no cap, it's giving very consistent 💅
also notice account_id isn't always "wallet" — sometimes it's a big hex id, sometimes the literal string "channelid0230...", sometimes "external" 🦋 and there's originating_account on entry 13 for when you need to know where a thing came from. iykyk.
🌸 Example 2 🌸
bestie said "wait, can i start further down the list" and the answer is yes, literally just pass start. here's the request:
$ lightning-cli listchainmoves -k "index"="created" "start"=10{
"id": "example:listchainmoves#2",
"method": "listchainmoves",
"params": {
"index": "created",
"start": 10
}
}and the response:
Response:
{
"chainmoves": [
{
"created_index": 10,
"account_id": "f8fc83a432cbfb2fffe222cc06727fdd977b5dd10ebd6707158e799e6f522d9f",
"credit_msat": 1000000000,
"debit_msat": 0,
"timestamp": 1758192795,
"primary_tag": "channel_open",
"extra_tags": [
"opener"
],
"utxo": "32de3d1592062670eb8630875a28705cc1988b7f83f8c712bf9d39be2152efec:1",
"peer_id": "nodeid050505050505050505050505050505050505050505050505050505050505",
"output_msat": 1000000000,
"blockheight": 115
},
{
"created_index": 11,
"account_id": "wallet",
"credit_msat": 486914000,
"debit_msat": 0,
"timestamp": 1738520000,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "874b26d4c523a902fdc44b88ec000eb5c3fe8754c9d44190a140561e24e77781:0",
"output_msat": 486914000,
"blockheight": 121
},
{
"created_index": 12,
"account_id": "a397dd9b3e44afcb67f3f3ce1d649b74a8ade63e35505985e4cc1828634f69a2",
"credit_msat": 0,
"debit_msat": 489809898,
"timestamp": 1738520000,
"primary_tag": "channel_close",
"extra_tags": [],
"utxo": "94418b652c9a0d79129552d317dcc37cb55afda1387257a22c7f16aa3981b7bc:0",
"spending_txid": "txid010101010101010101010101010101010101010101010101010101010101",
"output_msat": 1000000000,
"output_count": 2,
"blockheight": 121
},
{
"created_index": 13,
"account_id": "external",
"credit_msat": 510190000,
"debit_msat": 0,
"timestamp": 1738520000,
"primary_tag": "to_them",
"extra_tags": [],
"utxo": "874b26d4c523a902fdc44b88ec000eb5c3fe8754c9d44190a140561e24e77781:1",
"originating_account": "channelid0230000230000230000230000230000230000230000230000230000",
"output_msat": 510190000,
"blockheight": 121
},
{
"created_index": 14,
"account_id": "wallet",
"credit_msat": 2000000000,
"debit_msat": 0,
"timestamp": 1758192808,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "c9c9bec064382b6a6fb2a30d8923949b3c9f732465542b96e9ad1b5eebda4c7d:0",
"output_msat": 2000000000,
"blockheight": 122
},
{
"created_index": 15,
"account_id": "wallet",
"credit_msat": 0,
"debit_msat": 197990453000,
"timestamp": 1738500000,
"primary_tag": "withdrawal",
"extra_tags": [],
"utxo": "32de3d1592062670eb8630875a28705cc1988b7f83f8c712bf9d39be2152efec:0",
"spending_txid": "0137213d852e76d48f0270a78218d2f562ac0a8974f814cab66376537cfd1682",
"output_msat": 197990453000,
"blockheight": 123
},
{
"created_index": 16,
"account_id": "wallet",
"credit_msat": 196985833000,
"debit_msat": 0,
"timestamp": 1738500000,
"primary_tag": "deposit",
"extra_tags": [],
"utxo": "0137213d852e76d48f0270a78218d2f562ac0a8974f814cab66376537cfd1682:1",
"output_msat": 196985833000,
"blockheight": 123
},
{
"created_index": 17,
"account_id": "channelid0230200230200230200230200230200230200230200230200230200",
"credit_msat": 1000000000,
"debit_msat": 0,
"timestamp": 1738500000,
"primary_tag": "channel_open",
"extra_tags": [
"opener"
],
"utxo": "0137213d852e76d48f0270a78218d2f562ac0a8974f814cab66376537cfd1682:0",
"peer_id": "nodeid030303030303030303030303030303030303030303030303030303030303",
"output_msat": 1000000000,
"blockheight": 123
}
]
}okay bestie that's the whole thing 🌸 every created_index from 10 all the way to 17, every utxo, every spending_txid, every originating_account, every output_count, every blockheight — all present and accounted for, no crumbs left on the plate 💅
go forth and audit your little heart out, icon ✨
reminder reminder reminder: everything you just read came straight out of Core Lightning v26.06.9, page LIGHTNING-LISTCHAINMOVES(7) 🎀 read the date on the tin before you trust the deets, bestie, docs get retouched all the time 🦋
mwah, go touch some sats 💖🧚♀️
📦 where this page comes from
- nixpkgs unstable: clightning 26.06.9
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms