LIGHTNING-LISTNODES(7)

💖 lightning-listnodes(7) — the glow-up edition ✨

okay bestie, so this is the manual page for lightning-listnodes, a Core Lightning command, and honestly? it's a little baddie. it just… tells you who's out there. no cap. 🦋

---

✨ NAME ✨

listnodes — the command that gets you the list of nodes in the known network. that's it. that's the vibe. 💅

---

🌸 SYNOPSIS 🌸

listnodes [id]

---

🎀 DESCRIPTION 🎀

so listnodes returns the nodes your node has learned about via gossip messages. like, the whole group chat of the network, basically. 🫶

and if you hand it a node id? it'll pull up just that one. main character energy only. 👑

• id (pubkey, optional) — the public key of the node to list. optional, so you can ghost it and get everybody.

---

🔥 RETURN VALUE 🔥

on success you get back an object containing nodes. it's an array of objects, and every single object has:

• nodeid (pubkey) — the public key of the node. their whole identity, fr fr.
• last_timestamp (u32, optional) — a node_announcement has been received for this node (UNIX timestamp).

now, if last_timestamp is present, you also get all this goodness:

• alias (string) (up to 32 characters) — the fun alias this node advertized. literally their display name. 💖
• color (hex) (always 6 characters) — the favorite RGB color this node advertized. aesthetic choice, respected.
• features (hex) — BOLT #9 features bitmap this node advertized.
• addresses (array of objects) — the addresses this node advertized, which breaks down into:
  • type (string) (one of "dns", "ipv4", "ipv6", "torv2", "torv3") — type of connection (until 23.08, websocket was also allowed). ⚠️ note that little parenthetical, bestie, it's a whole era marker.
  • port (u16) — port number.

if type is "dns", "ipv4", "ipv6", "torv2" or "torv3":

• address (string) — address in expected format for type. ✨

if option_will_fund is present:

• option_will_fund (object) — the whole funding-leasing situation:
  • lease_fee_base_msat (msat) — the fixed fee for a lease (whole number of satoshis).
  • lease_fee_basis (u32) — the proportional fee in basis points (parts per 10,000) for a lease.
  • funding_weight (u32) — the onchain weight you'll have to pay for a lease.
  • channel_fee_max_base_msat (msat) — the maximum base routing fee this node will charge during the lease.
  • channel_fee_max_proportional_thousandths (u32) — the maximum proportional routing fee this node will charge during the lease (in thousandths, not millionths like channel_update). 😭 yes, thousandths. read it twice. i did.
  • compact_lease (hex) — the lease as represented in the node_announcement.

---

💀 ERRORS 💀

on failure, one of the following error codes may be returned:

• -32602 — error in given parameters. your params did not pass the vibe check, sorry babe. 🙈

---

🧚 AUTHOR 🧚

Vincenzo Palazzo <vincenzo.palazzo@protonmail.com> wrote the initial version of this man page, but many others did the hard work of actually implementing this rpc command. shoutout to the whole squad, genuinely. 🫶

---

⭐ SEE ALSO ⭐

• lightning-listchannels(7) — go read that one next, iykyk.

---

🌈 RESOURCES 🌈

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

---

🍓 EXAMPLES 🍓

Example 1: 💜

Request:

$ lightning-cli listnodes -k "id"="nodeid030303030303030303030303030303030303030303030303030303030303"

{
  "id": "example:listnodes#1",
  "method": "listnodes",
  "params": {
    "id": "nodeid030303030303030303030303030303030303030303030303030303030303"
  }
}

Response:

{
  "nodes": [
    {
      "nodeid": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "alias": "HOPPINGFIRE",
      "color": "035d2b",
      "last_timestamp": 1738000000,
      "features": "8898882a8a59a1",
      "addresses": []
    }
  ]
}

Example 2: 🔥

Request:

$ lightning-cli listnodes

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

Response:

{
  "nodes": [
    {
      "nodeid": "nodeid020202020202020202020202020202020202020202020202020202020202",
      "alias": "SILENTARTIST",
      "color": "022d22",
      "last_timestamp": 1738000000,
      "features": "8898882a8a59a1",
      "addresses": []
    },
    {
      "nodeid": "nodeid010101010101010101010101010101010101010101010101010101010101",
      "alias": "JUNIORBEAM",
      "color": "0266e4",
      "last_timestamp": 1738010000,
      "features": "8898882a8a59a1",
      "addresses": []
    },
    {
      "nodeid": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "alias": "HOPPINGFIRE",
      "color": "035d2b",
      "last_timestamp": 1738020000,
      "features": "8898882a8a59a1",
      "addresses": []
    },
    {
      "nodeid": "nodeid040404040404040404040404040404040404040404040404040404040404",
      "alias": "JUNIORFELONY",
      "color": "0382ce",
      "last_timestamp": 1738030000,
      "features": "8898882a8a59a1",
      "addresses": []
    }
  ]
}

---

and that's the whole page, bestie!! 🎀 this one shipped with Core Lightning v26.06.9 — iconic version, ate, periodt. go forth and list some nodes. 💖✨