NAME

lightning-listnodes -- Command to get the list of nodes in the known network.

SYNOPSIS

listnodes [id]

DESCRIPTION

The listnodes command returns nodes the node has learned about via gossip messages, or a single one if the node id was specified.

•: id (pubkey, optional): The public key of the node to list.

RETURN VALUE

On success, an object containing nodes is returned. It is an array of objects, where each object contains:

nodeid (pubkey): The public key of the node.
last_timestamp (u32, optional): A node_announcement has been received for this node (UNIX timestamp).

If last_timestamp is present: - alias (string) (up to 32 characters): The fun alias this node advertized. - color (hex) (always 6 characters): The favorite RGB color this node advertized. - features (hex): BOLT #9 features bitmap this node advertized. - addresses (array of objects): The addresses this node advertized.: - type (string) (one of "dns", "ipv4", "ipv6", "torv2", "torv3"): Type of connection (until 23.08, websocket was also allowed). - 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): - 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). - 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.

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.

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": "88a0882a8a59a1",


      "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": "88a0882a8a59a1",


      "addresses": []


    },


    {


      "nodeid": "nodeid010101010101010101010101010101010101010101010101010101010101",


      "alias": "JUNIORBEAM",


      "color": "0266e4",


      "last_timestamp": 1738010000,


      "features": "88a0882a8a59a1",


      "addresses": []


    },


    {


      "nodeid": "nodeid030303030303030303030303030303030303030303030303030303030303",


      "alias": "HOPPINGFIRE",


      "color": "035d2b",


      "last_timestamp": 1738020000,


      "features": "88a0882a8a59a1",


      "addresses": []


    },


    {


      "nodeid": "nodeid040404040404040404040404040404040404040404040404040404040404",


      "alias": "JUNIORFELONY",


      "color": "0382ce",


      "last_timestamp": 1738030000,


      "features": "88a0882a8a59a1",


      "addresses": []


    }


  ]
}