LIGHTNING-CONNECT(7)

💅 LIGHTNING-CONNECT 💅

okay bestie, welcome to the lightning-connect page — that's section 7 of the manual, for the record, and it's all about the connect command, aka how you link up with another lightning node 🫶

---

✨ NAME ✨

connect — the command for connecting to another lightning node. that's it, that's the vibe 🦋

---

✨ SYNOPSIS ✨

connect id [host] [port]

---

✨ DESCRIPTION ✨

so the connect RPC command is what establishes a brand-new connection with another node on the Lightning Network. it's giving first contact 👑

but lowkey important: connecting to a node is just the first step in opening a channel with another node. once the peer is connected, you can open a channel with lightning-fundchannel(7). one thing at a time, bestie 💅

and if there are active channels with the peer, connect returns once all the subdaemons are in place to handle the channels, not just once it's connected. like it's not done until the whole squad is assembled, periodt ✨

• id (string) — the target node's public key. as a convenience, id may be of the form id@host or id@host:port — in which case the host and port parameters must be omitted. 🎀 this can fail if your C-lightning node is a fresh install that has not connected to any peers yet (your node has no gossip yet), or if the target id is a fresh install that has no channels yet (nobody will gossip about a node until it has one published channel). no cap, the gossip pipeline needs something to talk about 😭
• host (string, optional) — the peer's hostname or IP address. if host is not specified (or doesn't work), the connection will be attempted to an IP belonging to id obtained through gossip with other already connected peers. and if host begins with a / it is interpreted as a local path and the connection will be made to that local socket (see bind-addr in lightningd-config(5)). slay, sockets 🧚
• port (u16, optional) — the peer's port number. if not specified, the port depends on the current network:
  • bitcoin mainnet: 9735.
  • bitcoin testnet: 19735.
  • bitcoin signet: 39735.
  • bitcoin regtest: 19846.

---

✨ RETURN VALUE ✨

on success, an object is returned, containing all this good stuff:

• id (pubkey) — the peer we connected to. hi bestie 🫶
• features (hex) — BOLT 9 features bitmap offered by peer.
• direction (string) (one of "in", "out") — whether they initiated connection or we did. main character energy either way 💅
• address (object) — address information (mainly useful if direction is out).:
  • type (string) (one of "local socket", "ipv4", "ipv6", "torv2", "torv3") — type of connection (torv2/torv3 only if direction is out).
  • if type is "local socket": socket (string) — socket filename.
  • if type is "ipv4", "ipv6", "torv2" or "torv3": address (string) — address in expected format for type. port (u16) — port number.

---

✨ ERRORS ✨

on failure, one of these will come back at you 😭

• 400: unable to connect, no address known for peer
• 401: if some addresses are known but connecting to all of them failed, the message will contain details about the failures
• 402: if the peer disconnected while we were connecting
• -32602: if the given parameters are wrong

💀 ngl, 402 is the "it's not me, it's you" of error codes. they left mid-conversation.

---

✨ AUTHOR ✨

Rusty Russell rusty@rustcorp.com.au is mainly responsible. Felix fixone@gmail.com is the original author of this manpage. legends, both of them 👑

---

✨ SEE ALSO ✨

lightning-fundchannel(7), lightning-listpeers(7), lightning-listchannels(7), lightning-disconnect(7) — the whole friend group 🌸

---

✨ RESOURCES ✨

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

---

✨ EXAMPLES ✨

Example 1 🦋

Request:

$ lightning-cli connect -k "id"="nodeid020202020202020202020202020202020202020202020202020202020202" "host"="localhost" "port"=19735

{
  "id": "example:connect#1",
  "method": "connect",
  "params": {
    "id": "nodeid020202020202020202020202020202020202020202020202020202020202",
    "host": "localhost",
    "port": 19735
  }
}

Response:

{
  "id": "nodeid020202020202020202020202020202020202020202020202020202020202",
  "features": "0898882a8a59a1",
  "direction": "out",
  "address": {
    "type": "ipv4",
    "address": "127.0.0.1",
    "port": 19735
  }
}

Example 2 🎀

Request:

$ lightning-cli connect -k "id"="nodeid030303030303030303030303030303030303030303030303030303030303" "host"="localhost" "port"=19736

{
  "id": "example:connect#2",
  "method": "connect",
  "params": {
    "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
    "host": "localhost",
    "port": 19736
  }
}

Response:

{
  "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
  "features": "0898882a8a59a1",
  "direction": "out",
  "address": {
    "type": "ipv4",
    "address": "127.0.0.1",
    "port": 19736
  }
}

---

and that's the whole page, bestie 💖 this lil rewrite was brought to you by Core Lightning v26.06.9, living under the LIGHTNING-CONNECT(7) heading — go forth and connect, you've got this 👑✨