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

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "additionalProperties": false,
  "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"
    ],
    "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"
    ],
    "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": "bcrt1qcqqvkswps3e6ck3jmqf86f9tcaeke5z04d3tv4",
          "satoshi": 555555
        }
      },
      "response": {
        "tx": "0200000001187e8867dc9462f0acbf9b7ecad69c786bdb04bdc89eb0bea45db35f8cf7dd860000000000fdffffff02237a080000000000160014c000cb41c18473ac5a32d8127d24abc7736cd04f0636e30b0000000022512052021c61da23b2eda3d5000c6d812d0c9b088c237ed2a510abd94d8c3f7c421d20000000",
        "txid": "faf2ac1e15fe8df73c411d404224cb481f01cabdde58df83c56d5d6050ec53a9",
        "psbt": "cHNidP8BAgQCAAAAAQMEIAAAAAEEAQEBBQECAQYBAwH7BAIAAAAAAQBxAgAAAAGdA6aKwu4U7Zes8OwDJHp4bI3maidtrjOK6N85klZucAEAAAAA/f///wIAwusLAAAAABYAFCchPiIXtPVr0Ztsg5Pcn2G+aRIzQD/9EAEAAAAWABRz0UYcTRX0fJpAf766DfDa2wbGUGcAAAABAR8AwusLAAAAABYAFCchPiIXtPVr0Ztsg5Pcn2G+aRIzIgICB+wrNVNHEthq4DDdm/rsCOLd6h7Bzs/7lyXtessSq2ZHMEQCIEW+oeZvFbmuQidamye9/iuDhJ41SARdgZV8yWWjfq8vAiAS3no++NDmJjip3G/y4VTfQ/jiJv2jv9lQKqBUK9hQ0wEiBgIH7Cs1U0cS2GrgMN2b+uwI4t3qHsHOz/uXJe16yxKrZggnIT4iAAAAAAEOIBh+iGfclGLwrL+bfsrWnHhr2wS9yJ6wvqRds1+M992GAQ8EAAAAAAEQBP3///8AIgICLKJZZMteDpQ8BfcEOrSAECukrPM9dXeamXREWCtGR1AIwADLQQwAAAABAwgjeggAAAAAAAEEFgAUwADLQcGEc6xaMtgSfSSrx3Ns0E8M/AlsaWdodG5pbmcEAgABAAEDCAY24wsAAAAAAQQiUSBSAhxh2iOy7aPVAAxtgS0MmwiMI37SpRCr2U2MP3xCHSEHxKQ1JAGJOzVxgiryRaI4NGaYWWe35WSg4OUGHU+NcXEJAIvHqlwOAAAAAA=="
      }
    },
    {
      "request": {
        "id": "example:withdraw#2",
        "method": "withdraw",
        "params": {
          "destination": "bcrt1phtprcvhz842sxe8qw0yryvc0g6n6dw2puweklcpnfye273kjpfhs0d6d2e",
          "satoshi": "all",
          "feerate": "20000perkb",
          "minconf": 0,
          "utxos": [
            "f2f4e67dbf2791a3b57dd986418156b116b452c5fc27b077da7c529db82f06f5:0"
          ]
        }
      },
      "response": {
        "tx": "0200000001f5062fb89d527cda77b027fcc552b416b156814186d97db5a39127bf7de6f4f20000000000fdffffff0119f70e0000000000225120bac23c32e23d550364e073c832330f46a7a6b941e3b36fe0334932af46d20a6f87000000",
        "txid": "41dd478136c95acc82b7669fa4c70843da2ecd04baa7c53cbe8c73d0dd98e5c1",
        "psbt": "cHNidP8BAgQCAAAAAQMEhwAAAAEEAQEBBQEBAQYBAwH7BAIAAAAAAQCJAgAAAAGxWGMGDX3aCdIKW4Vrs4nxXQD8LjoWZ2z3R6yqUp0MxAEAAAAA/f///wKSAA8AAAAAACJRIP2rfAH65wwI4LH5rKzKEQpTEh513FSiXnVCQW80Kur3QEIPAAAAAAAiACCWVeKnMwzYbcafjtGEWvVYDdBrFaeUA0yVceU9Vjmzl3oAAAABASuSAA8AAAAAACJRIP2rfAH65wwI4LH5rKzKEQpTEh513FSiXnVCQW80Kur3AQ4g9QYvuJ1SfNp3sCf8xVK0FrFWgUGG2X21o5Env33m9PIBDwQAAAAAARAE/f///wETQFj1/T/JtePk1+LfX9fAK4QBBwl1Xt1YmoE2cQOo/0hAvCLgwb5zSZCrDGAhxdSujHXyVo3a19wl+ayqa0/nckAhFr2SP8yeYDMCCkVocL4aDjUqc7hPoTIp/uS7zAf7okk6CQDK3xgoAAAAAAABAwgZ9w4AAAAAAAEEIlEgusI8MuI9VQNk4HPIMjMPRqemuUHjs2/gM0kyr0bSCm8hB6Jvzf+c2c5Qrvvj78smeIzuWAjjEtHW01YDo2je0daMCQBxtd2rDQAAAAz8CWxpZ2h0bmluZwQCAAEA"
      }
    }
  ]
}