{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "close",
  "title": "Command for closing channels with direct peers",
  "description": [
    "The **close** RPC command attempts to close the channel cooperatively with the peer, or unilaterally after *unilateraltimeout*, and the to-local output will be sent to the address specified in *destination*.",
    "",
    "The peer needs to be live and connected in order to negotiate a mutual close. The default of unilaterally closing after 48 hours is usually a reasonable indication that you can no longer contact the peer."
  ],
  "request": {
    "required": [
      "id"
    ],
    "additionalProperties": true,
    "properties": {
      "id": {
        "type": "string",
        "description": [
          "Peer id, channel id or short_channel_id. 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."
        ]
      },
      "unilateraltimeout": {
        "type": "u32",
        "description": [
          "If it is not zero, the command will unilaterally close the channel when that number of seconds is reached. If *unilateraltimeout* is zero, then the command will wait indefinitely until the peer is online and can negotiate a mutual close."
        ],
        "default": "2 days (172800 seconds)"
      },
      "destination": {
        "type": "string",
        "description": [
          "Any Bitcoin bech32 type. If the peer hasn't offered the option_shutdown_anysegwit feature, then taproot addresses (or other v1+ segwit) are not allowed. Tell your friends to upgrade!"
        ],
        "default": "a Core Lightning wallet address"
      },
      "fee_negotiation_step": {
        "type": "string",
        "description": [
          "It controls how closing fee negotiation is performed assuming the peer proposes a fee that is different than our estimate. (Note that modern peers use the quick-close protocol which does not allow negotiation: see *feerange* instead).",
          "",
          "On every negotiation step we must give up some amount from our proposal towards the peer's proposal. This parameter can be an integer in which case it is interpreted as number of satoshis to step at a time. Or it can be an integer followed by `%` to designate a percentage of the interval to give up. A few examples, assuming the peer proposes a closing fee of 3000 satoshi and our estimate shows it must be 4000:",
          "    * `10`: our next proposal will be 4000-10=3990.",
          "    * `10%`: our next proposal will be 4000-(10% of (4000-3000))=3900.",
          "    * '1': our next proposal will be 3999. This is the most extreme case when we insist on our fee as much as possible.",
          "    * `100%`: our next proposal will be 3000. This is the most relaxed case when we quickly accept the peer's proposal."
        ],
        "default": "`50%`"
      },
      "wrong_funding": {
        "type": "outpoint",
        "description": [
          "It can only be specified if both sides have offered the `shutdown_wrong_funding` feature (enabled by the **experimental-shutdown-wrong-funding** option). It must be a transaction id followed by a colon then the output number. Instead of negotiating a shutdown to spend the expected funding transaction, the shutdown transaction will spend this output instead. This is only allowed if this peer opened the channel and the channel is unused: it can rescue openings which have been manually miscreated."
        ]
      },
      "force_lease_closed": {
        "type": "boolean",
        "description": [
          "If the channel has funds leased to the peer (option_will_fund), we prevent initiation of a mutual close unless this flag is passed in."
        ],
        "default": "False"
      },
      "feerange": {
        "type": "array",
        "items": {
          "type": "feerate"
        },
        "description": [
          "An optional array [ *min*, *max* ], indicating the minimum and maximum feerates to offer: the peer will obey these if it supports the quick-close protocol. *slow* and *unilateral_close* are the defaults. Note that the maximum fee will be capped at the final commitment transaction fee (unless the experimental anchor-outputs option is negotiated)."
        ]
      }
    }
  },
  "response": {
    "required": [
      "type"
    ],
    "additionalProperties": true,
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "mutual",
          "unilateral",
          "unopened"
        ],
        "description": [
          "Whether we successfully negotiated a mutual close, closed without them, or discarded not-yet-opened channel."
        ]
      }
    },
    "allOf": [
      {
        "if": {
          "additionalProperties": true,
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "mutual",
                "unilateral"
              ]
            }
          }
        },
        "then": {
          "additionalProperties": false,
          "required": [
            "txs",
            "txids"
          ],
          "properties": {
            "type": {},
            "txs": {
              "added": "v24.11",
              "type": "array",
              "items": {
                "type": "hex"
              },
              "description": [
                "The raw bitcoin transactions used to close the channel (if it was open)."
              ]
            },
            "txids": {
              "added": "v24.11",
              "type": "array",
              "items": {
                "type": "txid"
              },
              "description": [
                "The transaction ids of the *tx* field(s)."
              ]
            }
          }
        },
        "else": {
          "additionalProperties": false,
          "properties": {
            "type": {}
          }
        }
      }
    ],
    "post_return_value_notes": [
      "A unilateral close may still occur at any time 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."
    ]
  },
  "notes": [
    "Prior to 0.7.2, **close** took two parameters: *force* and *timeout*. *timeout* was the number of seconds before *force* took effect (default, 30), and *force* determined whether the result was a unilateral close or an RPC error (default). Even after the timeout, the channel would be closed if the peer reconnected."
  ],
  "notifications": [
    "Notifications may be returned indicating what is going on, especially if the peer is offline and we are waiting."
  ],
  "author": [
    "ZmnSCPxj [ZmnSCPxj@protonmail.com](mailto:ZmnSCPxj@protonmail.com) is mainly responsible."
  ],
  "see_also": [
    "lightning-disconnect(7)",
    "lightning-fundchannel(7)",
    "lightningd-config(5)"
  ],
  "resources": [
    "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
  ],
  "examples": [
    {
      "request": {
        "id": "example:close#1",
        "method": "close",
        "params": {
          "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
          "unilateraltimeout": 1
        }
      },
      "response": {
        "tx": "02000000000101cls00101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
        "txid": "txid010101010101010101010101010101010101010101010101010101010101",
        "txs": [
          "02000000000101cls00101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101"
        ],
        "txids": [
          "txid010101010101010101010101010101010101010101010101010101010101"
        ],
        "type": "mutual"
      }
    },
    {
      "request": {
        "id": "example:close#2",
        "method": "close",
        "params": {
          "id": "nodeid040404040404040404040404040404040404040404040404040404040404",
          "destination": "bcrt1p0004040404040404040404040404040404040404040404040404040404"
        }
      },
      "response": {
        "tx": "02000000000101cls10202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202",
        "txid": "txid020202020202020202020202020202020202020202020202020202020202",
        "txs": [
          "02000000000101cls10202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202"
        ],
        "txids": [
          "txid020202020202020202020202020202020202020202020202020202020202"
        ],
        "type": "mutual"
      }
    }
  ]
}
