LIGHTNING-CLOSE(7)
==================
:doctype: manpage

NAME
----
lightning-close - Command for closing channels with direct peers

SYNOPSIS
--------
*close* 'id' ['force'] ['timeout']

DESCRIPTION
-----------

The *close* RPC command attempts to close the channel cooperatively
with the peer.
If the given 'id' is a peer ID (66 hex digits as a string), then
it applies to the active channel of the direct peer corresponding to
the given peer ID.
If the given 'id' is a channel ID (64 hex digits as a string, or
the short channel ID 'blockheight:txindex:outindex' form), then it
applies to that channel.

The *close* command will time out and return with an error when the
number of seconds specified in 'timeout' is reached.
If unspecified, it times out in 30 seconds.

The 'force' argument, if the JSON value 'true', will cause the
channel to be unilaterally closed when the timeout is reached.
If so, timeout will not cause an error, but instead cause the
channel to be failed and put onchain unilaterally.
Unilateral closes will lead to your funds getting locked according
to the 'to_self_delay' parameter of the peer.

Normally the peer needs to be live and connected in order to negotiate
a mutual close.
Forcing a unilateral close can be used if you suspect you can no longer
contact the peer.

RETURN VALUE
------------

On success, an object with fields 'tx' and 'txid' containing the
closing transaction are returned.
It will also have a field 'type' which is either the JSON string
'mutual' or the JSON string 'unilateral'.
A 'mutual' close means that we could negotiate a close with the
peer, while a 'unilateral' close means that the 'force' flag was
set and we had to close the channel without waiting for the
counterparty.

A unilateral close may still occur with 'force' set to 'false' if
the peer did not behave correctly during the close negotiation.

Unilateral closes will return your funds after a delay.
The delay will vary based on the peer 'to_self_delay' setting, not
your own setting.

On failure, if *close* failed due to timing out with 'force'
argument 'false', the channel will still eventually close once
we have contacted the peer.

AUTHOR
------
ZmnSCPxj <ZmnSCPxj@protonmail.com> is mainly responsible.

SEE ALSO
--------


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