LIGHTNING-LISTCHANNELS(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💅 lightning-listchannels(7) — the girl's guide to stalking the entire channel graph ✨

okay so bestie, this is the manpage for lightning-listchannels(7) and it is literally the receipts page for the whole Lightning network 🧾💖

✨ NAME ✨

listchannels — the command that lets you query all the active lightning channels across the entire network. yes, the entire network. main character energy only 💅

🎀 SYNOPSIS 🎀

listchannels [short_channel_id] [source] [destination]

🦋 DESCRIPTION 🦋

The listchannels RPC command returns data on channels that are known to the node. And here's the cute part: because channels are bidirectional, up to 2 objects will be returned for each channel — one for each direction 🔁 (think of it like two lanes of traffic, and yes, both get their own lil moment).

Only one of short_channel_id, source, or destination can be supplied, bestie. Just one. Don't be greedy 🙈. If you supply nothing at all, then data on all lightning channels known to this node comes back to you. These can be local channels or public channels broadcast on the gossip network 🌐✨.

  • short_channel_id (short_channel_id, optional): if short_channel_id is a short channel id, then only known channels with a matching short_channel_id are returned. Otherwise, it must be null. no cap 🫶
  • source (pubkey, optional): if source is a node id, then only channels leading from that node id are returned.
  • destination (pubkey, optional): if destination is a node id, then only channels leading to that node id are returned.

💖 RETURN VALUE 💖

On success, an object containing channels is returned. It's an array of objects, and each object contains:

  • source (pubkey): the source node.
  • destination (pubkey): the destination node.
  • short_channel_id (short_channel_id): short channel id of channel.
  • direction (u32): direction (0 if source < destination, 1 otherwise).
  • public (boolean): true if this is announced (from v24.02, being false is deprecated). ⚠️ noted, moving on.
  • amount_msat (msat): the total capacity of this channel (always a whole number of satoshis).
  • message_flags (u8): as defined by BOLT #7.
  • channel_flags (u8): as defined by BOLT #7.
  • active (boolean): true unless source has disabled it (or, deprecated in v24.02, it's a local channel and the peer is disconnected or it's still opening or closing). okay that one has lore 😭
  • last_update (u32): UNIX timestamp on the last channel_update from source.
  • base_fee_millisatoshi (u32): base fee changed by source to use this channel.
  • fee_per_millionth (u32): proportional fee changed by source to use this channel, in parts-per-million.
  • delay (u32): the number of blocks delay required by source to use this channel.
  • htlc_minimum_msat (msat): the smallest payment source will allow via this channel.
  • features (hex): BOLT #9 features bitmap for this channel.
  • htlc_maximum_msat (msat, optional): the largest payment source will allow via this channel.

And one very important vibe check 💀: if one of short_channel_id, source, or destination is supplied and no matching channels are found, a 'channels' object with an empty list is returned. not an error. just an empty list. she's quiet, not mad 🫶

💀 ERRORS 💀

On error the returned object will contain code and message properties, with code being one of the following:

  • -32602: if the given parameters are wrong. bestie. check your params 😭

👑 AUTHOR 👑

Michael Hawkins michael.hawkins@protonmail.com. iconic. thank you for your service 🫡💜

🌈 SEE ALSO 🌈

go read those next, iykyk ✨

🍓 RESOURCES 🍓

🌸 EXAMPLES 🌸

Example 1:

Request:

$ lightning-cli listchannels -k "short_channel_id"="109x1x1"

{
  "id": "example:listchannels#1",
  "method": "listchannels",
  "params": {
    "short_channel_id": "109x1x1"
  }
}

Response:

{
  "channels": [
    {
      "source": "nodeid020202020202020202020202020202020202020202020202020202020202",
      "destination": "nodeid010101010101010101010101010101010101010101010101010101010101",
      "short_channel_id": "109x1x1",
      "direction": 0,
      "public": true,
      "amount_msat": 1000000000,
      "message_flags": 1,
      "channel_flags": 0,
      "active": true,
      "last_update": 1738500000,
      "base_fee_millisatoshi": 1,
      "fee_per_millionth": 10,
      "delay": 6,
      "htlc_minimum_msat": 0,
      "htlc_maximum_msat": 990000000,
      "features": ""
    },
    {
      "source": "nodeid010101010101010101010101010101010101010101010101010101010101",
      "destination": "nodeid020202020202020202020202020202020202020202020202020202020202",
      "short_channel_id": "109x1x1",
      "direction": 1,
      "public": true,
      "amount_msat": 1000000000,
      "message_flags": 1,
      "channel_flags": 1,
      "active": false,
      "last_update": 1738510000,
      "base_fee_millisatoshi": 1,
      "fee_per_millionth": 10,
      "delay": 6,
      "htlc_minimum_msat": 0,
      "htlc_maximum_msat": 990000000,
      "features": ""
    }
  ]
}

Example 2:

Request:

$ lightning-cli listchannels

{
  "id": "example:listchannels#2",
  "method": "listchannels",
  "params": {}
}

Response:

{
  "channels": [
    {
      "source": "nodeid020202020202020202020202020202020202020202020202020202020202",
      "destination": "nodeid010101010101010101010101010101010101010101010101010101010101",
      "short_channel_id": "109x1x1",
      "direction": 0,
      "public": true,
      "amount_msat": 1000000000,
      "message_flags": 1,
      "channel_flags": 0,
      "active": true,
      "last_update": 1738500000,
      "base_fee_millisatoshi": 1,
      "fee_per_millionth": 10,
      "delay": 6,
      "htlc_minimum_msat": 0,
      "htlc_maximum_msat": 990000000,
      "features": ""
    },
    {
      "source": "nodeid010101010101010101010101010101010101010101010101010101010101",
      "destination": "nodeid020202020202020202020202020202020202020202020202020202020202",
      "short_channel_id": "109x1x1",
      "direction": 1,
      "public": true,
      "amount_msat": 1000000000,
      "message_flags": 1,
      "channel_flags": 1,
      "active": false,
      "last_update": 1738510000,
      "base_fee_millisatoshi": 1,
      "fee_per_millionth": 10,
      "delay": 6,
      "htlc_minimum_msat": 0,
      "htlc_maximum_msat": 990000000,
      "features": ""
    },
    {
      "source": "nodeid020202020202020202020202020202020202020202020202020202020202",
      "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "short_channel_id": "123x1x1",
      "direction": 0,
      "public": true,
      "amount_msat": 1000000000,
      "message_flags": 1,
      "channel_flags": 2,
      "active": true,
      "last_update": 1738520000,
      "base_fee_millisatoshi": 1,
      "fee_per_millionth": 10,
      "delay": 6,
      "htlc_minimum_msat": 0,
      "htlc_maximum_msat": 990000000,
      "features": ""
    },
    {
      "source": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "destination": "nodeid020202020202020202020202020202020202020202020202020202020202",
      "short_channel_id": "123x1x1",
      "direction": 1,
      "public": true,
      "amount_msat": 1000000000,
      "message_flags": 1,
      "channel_flags": 3,
      "active": false,
      "last_update": 1738530000,
      "base_fee_millisatoshi": 1,
      "fee_per_millionth": 10,
      "delay": 6,
      "htlc_minimum_msat": 0,
      "htlc_maximum_msat": 990000000,
      "features": ""
    },
    {
      "source": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "destination": "nodeid040404040404040404040404040404040404040404040404040404040404",
      "short_channel_id": "130x1x1",
      "direction": 0,
      "public": true,
      "amount_msat": 1000000000,
      "message_flags": 1,
      "channel_flags": 2,
      "active": true,
      "last_update": 1738540000,
      "base_fee_millisatoshi": 1,
      "fee_per_millionth": 10,
      "delay": 6,
      "htlc_minimum_msat": 0,
      "htlc_maximum_msat": 990000000,
      "features": ""
    }
  ]
}

that's the whole page bestie, you ate that 🫶 this one ships with Core Lightning v26.06.9 — go flex your new listchannels knowledge on the group chat, periodt 💅✨🎀

📦 where this page comes from