home | help 
LIGHTNING-FUNDCHANNEL(7)				LIGHTNING-FUNDCHANNEL(7)

NAME
     fundchannel -- Command for establishing a lightning channel

SYNOPSIS
     fundchannel id amount [feerate] [announce] [minconf] [push_msat] [close_to]
     [request_amt] [compact_lease] [utxos] [mindepth] [reserve] [channel_type]

DESCRIPTION
     The  fundchannel RPC command opens a payment channel with a peer by commit-
     ting a funding transaction to the blockchain as defined in BOLT #2.

     If not already connected, fundchannel will automatically attempt to connect
     if Core Lightning knows a way to contact the node (either from normal  gos-
     sip, or from a previous connect call).

     This  auto-connection  can fail if Core Lightning does not know how to con-
     tact the target node; see lightning-connect(7).

     Once the transaction is confirmed, normal	channel  operations  may  begin.
     Readiness	is  indicated  by listpeers reporting a state of CHANNELD_NORMAL
     for the channel.

     *	id (pubkey): Id is the peer id obtained from connect.
     *	amount (sat_or_all): The amount in satoshis taken from the internal wal-
	let to fund the channel (but if we have any anchor channels,  this  will
	always leave at least min-emergency- msat as change). The string all can
	be  used  to specify all available funds (may be restricted by the utxos
	parameter, and limited to 16777215 satoshi if large  channels  were  not
	negotiated with the peer). Otherwise, it is in satoshi precision; it can
	be  a  whole number, a whole number ending in sat, a whole number ending
	in 000msat, or a number with 1 to 8 decimal places ending  in  btc.  The
	value cannot be less than the dust limit, currently set to 546, nor more
	than  16777215	satoshi  (unless large channels were negotiated with the
	peer).
     *	feerate (feerate, optional): Used for the opening transaction  and  (un-
	less  option_anchors  is  negotiated), as initial feerate for commitment
	and HTLC transactions (see NOTES in lightning-feerates(7)). The  default
	is normal.
     *	announce  (boolean,  optional): Whether to announce this channel or not.
	An unannounced channel is considered private. The default is True.
     *	minconf (u32, optional): The minimum number of confirmations  that  used
	outputs should have. The default is 1.
     *	push_msat  (msat,  optional): The amount of millisatoshis to push to the
	channel peer at open. Note that this is a gift	to  the  peer  --  these
	satoshis  are  added to the initial balance of the peer at channel start
	and are largely unrecoverable once pushed.
     *	close_to (string, optional): A Bitcoin	address  to  which  the  channel
	funds  should be sent to on close. Only valid if both peers have negoti-
	ated option_upfront_shutdown_script. Returns  close_to	set  to  closing
	script iff is negotiated.
     *	request_amt  (sat, optional): An amount of liquidity you'd like to lease
	from the peer. If peer supports option_will_fund, indicates to	them  to
	include  this  much  liquidity	into the channel. Must also pass in com-
	pact_lease.
     *	compact_lease (string, optional): A compact representation of the peer's
	expected channel lease terms. If the peer's terms don't match this  set,
	we will fail to open the channel.
     *	utxos  (array  of outpoints, optional): The utxos to be used to fund the
	channel, as an array of txid:vout.:
	*  (outpoint, optional)
     *	mindepth (u32, optional): Number of  confirmations  required  before  we
	consider the channel active.
     *	reserve  (sat, optional): The amount we want the peer to maintain on its
	side of the channel. It can be a whole number, a whole number ending  in
	sat,  a  whole number ending in 000msat, or a number with 1 to 8 decimal
	places ending in btc. The default is 1% of the funding amount.
     *	channel_type (array of u32s, optional) (added v24.02):
	*  (u32, optional): Represents the explicit  channel  type  to	request.
	   There  is  currently  no  sanity checking on this value so if you use
	   strange values and your channel breaks, you get to keep both  pieces.
	   BOLT 2 defines the following value types:

     The currently defined basic types are:
     - `option_static_remotekey` (bit 12).
     - `option_anchors` and `option_static_remotekey` (bits 22 and 12).

     Each basic type has the following variations allowed:
     - `option_scid_alias` (bit 46).
     - `option_zeroconf` (bit 50).

RETURN VALUE
     On success, an object is returned, containing:

     *	tx (hex): The raw transaction which funded the channel.
     *	txid (txid): The txid of the transaction which funded the channel.
     *	outnum	(u32):	The 0-based output index showing which output funded the
	channel.
     *	channel_id (hash): The channel_id of the resulting channel.
     *	channel_type (object): Channel_type  as  negotiated  with  peer.  (added
	v24.02):
	*  bits  (array  of  u32s):  Each  bit	set in this channel_type. (added
	   v24.02):
	*  (u32, optional): Bit number.
	*  names (array of strings): Feature name for each bit set in this chan-
	   nel_type. Note that anchors_zero_fee_htlc_tx is a deprecated  synonym
	   for anchors. (added v24.02):
	*  (string,  optional)	(one  of  "static_remotekey/even",  "anchor_out-
	   puts/even",	   "anchors_zero_fee_htlc_tx/even",	 "anchors/even",
	   "scid_alias/even", "zeroconf/even"): Name of feature bit.
     *	close_to  (hex,  optional): The raw scriptPubkey which mutual close will
	go to; only present if close_to parameter was specified  and  peer  sup-
	ports option_upfront_shutdown_script.
     *	mindepth (u32, optional): Number of confirmations before we consider the
	channel active.

ERRORS
     The following error codes may occur:

     *	-1: Catchall nonspecific error.
     *	300: The maximum allowed funding amount is exceeded.
     *	301:  There are not enough funds in the internal wallet (including fees)
	to create the transaction.
     *	302: The output amount is too small, and would be considered dust.
     *	303: Broadcasting of the funding transaction failed, the  internal  call
	to bitcoin-cli returned with an error.
     *	313: The min-emergency-msat reserve not be preserved (and we have or are
	opening anchor channels).

     Failure  may  also occur if lightningd and the peer cannot agree on channel
     parameters (funding limits, channel reserves, fees, etc.).

SEE ALSO
     lightning-connect(7), lightning-listfunds(), lightning-listpeers(7), light-
     ning-feerates(7), lightning-multifundchannel(7)

RESOURCES
     Main web site: https://github.com/ElementsProject/lightning

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli fundchannel -k "id"="nodeid050505050505050505050505050505050505050505050505050505050505" "amount"=1000000 "announce"=True

     {
       "id": "example:fundchannel#1",
       "method": "fundchannel",
       "params": {
	 "id": "nodeid050505050505050505050505050505050505050505050505050505050505",
	 "amount": 1000000,
	 "announce": true
       }
     }

     Response:

     {
       "tx": "020000000000305fundchanneltx350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000350003500035000",
       "txid": "channeltxid350000350000350000350000350000350000350000350000350000",
       "channel_id": "channelid0350000350000350000350000350000350000350000350000350000",
       "channel_type": {
	 "bits": [
	   12,
	   22
	 ],
	 "names": [
	   "static_remotekey/even",
	   "anchors/even"
	 ]
       },
       "outnum": 1
     }

     Example 2: This example shows how to to open new channel with peer  1  from
     one whole utxo (you can use listfunds command to get txid and vout):

     Request:

     $ lightning-cli fundchannel -k "id"="nodeid010101010101010101010101010101010101010101010101010101010101" "amount"="all" "feerate"="normal" "push_msat"=100000 "utxos"='["channeltxid350000350000350000350000350000350000350000350000350000:1"]'

     {
       "id": "example:fundchannel#2",
       "method": "fundchannel",
       "params": {
	 "id": "nodeid010101010101010101010101010101010101010101010101010101010101",
	 "amount": "all",
	 "feerate": "normal",
	 "push_msat": 100000,
	 "utxos": [
	   "channeltxid350000350000350000350000350000350000350000350000350000:1"
	 ]
       }
     }

     Response:

     {
       "tx": "020000000000401fundchanneltx410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000410004100041000",
       "txid": "channeltxid410000410000410000410000410000410000410000410000410000",
       "channel_id": "channelid0410000410000410000410000410000410000410000410000410000",
       "channel_type": {
	 "bits": [
	   12,
	   22
	 ],
	 "names": [
	   "static_remotekey/even",
	   "anchors/even"
	 ]
       },
       "outnum": 1
     }

Core Lightning v26.06.1 				LIGHTNING-FUNDCHANNEL(7)
home | help