core-lightning/doc/schemas/lightning-withdraw.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "withdraw",
  "title": "Command for withdrawing funds from the internal wallet",
  "description": [
    "The **withdraw** RPC command sends funds from Core Lightning's internal wallet to the address specified in *destination*."
  ],
  "request": {
    "required": [
      "destination",
      "satoshi"
    ],
    "additionalProperties": false,
    "properties": {
      "destination": {
        "type": "string",
        "description": [
          "Any Bitcoin accepted type, including bech32."
        ]
      },
      "satoshi": {
        "type": "sat_or_all",
        "description": [
          "The amount to be withdrawn from the internal wallet (expressed, as name suggests, in satoshi). The string *all* can be used to specify withdrawal of all available funds (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). 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*."
        ]
      },
      "feerate": {
        "type": "feerate",
        "description": [
          "Used for the withdrawal as initial feerate."
        ],
        "default": "*normal*"
      },
      "minconf": {
        "type": "u16",
        "description": [
          "Minimum number of confirmations that used outputs should have."
        ],
        "default": 1
      },
      "utxos": {
        "type": "array",
        "description": [
          "Specifies the utxos to be used to be withdrawn from, as an array of `txid:vout`. These must be drawn from the node's available UTXO set."
        ],
        "items": {
          "type": "outpoint"
        }
      }
    }
  },
  "response": {
    "required": [
      "psbt",
      "tx",
      "txid"
    ],
    "additionalProperties": false,
    "properties": {
      "tx": {
        "type": "hex",
        "description": [
          "The fully signed bitcoin transaction."
        ]
      },
      "txid": {
        "type": "txid",
        "description": [
          "The transaction id of *tx*."
        ]
      },
      "psbt": {
        "type": "string",
        "description": [
          "The PSBT representing the unsigned transaction."
        ]
      }
    }
  },
  "errors": [
    "On failure, an error is reported and the withdrawal transaction is not created.",
    "",
    "- -1: Catchall nonspecific error.",
    "- 301: There are not enough funds in the internal wallet (including fees) to create the transaction.",
    "- 302: The dust limit is not met.",
    "- 313: The `min-emergency-msat` reserve not be preserved (and we have anchor channels)."
  ],
  "author": [
    "Felix <<fixone@gmail.com>> is mainly responsible."
  ],
  "see_also": [
    "lightning-listfunds(7)",
    "lightning-fundchannel(7)",
    "lightning-newaddr(7)",
    "lightning-txprepare(7)",
    "lightning-feerates(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:withdraw#1",
        "method": "withdraw",
        "params": {
          "destination": "bcrt1qcqqv0101010101010101010101010101010101",
          "satoshi": 555555
        }
      },
      "response": {
        "tx": "020000000001wthdrw91000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000910009100091000",
        "txid": "txidwithdraw2191000910009100091000910009100091000910009100091000",
        "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000911000"
      }
    },
    {
      "request": {
        "id": "example:withdraw#2",
        "method": "withdraw",
        "params": {
          "destination": "bcrt1phtprcvhz02020202020202020202020202020202020202020202020202",
          "satoshi": "all",
          "feerate": "20000perkb",
          "minconf": 0,
          "utxos": [
            "utxo020202020202020202020202020202020202020202020202020202020202:1"
          ]
        }
      },
      "response": {
        "tx": "020000000002wthdrw92000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000920009200092000",
        "txid": "txidwithdraw2292000920009200092000920009200092000920009200092000",
        "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000922000"
      }
    }
  ]
}