LIGHTNING-UTXOPSBT(7)

✨ NAME ✨

okay so this is the manual page for LIGHTNING-UTXOPSBT(7) — bestie, it's the utxopsbt command, and its whole job is populating PSBT inputs from the UTXOs you hand it 💅

🌸 SYNOPSIS 🌸

utxopsbt satoshi feerate startweight utxos [reserve] [reservedok]
[locktime] [min_witness_weight] [excess_as_change]
[opening_anchor_channel]

🦋 DESCRIPTION 🦋

utxopsbt is a low-level RPC command that creates a PSBT using unreserved inputs in the wallet, and it optionally reserves them too. no cap.

it deliberately mirrors the parameters and output of lightning-fundpsbt(7) — except instead of an optional minconf parameter for picking unreserved outputs out of the wallet, it takes a compulsory list of outputs to use. that's the whole vibe difference, iykyk.

• satoshi (sat_or_all) — the minimum satoshi value of the output(s) you need. or literally the string all, meaning "use all unreserved inputs". if it's a value, 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. so many options, all valid 🎀
• feerate (feerate) — used for the transaction as the initial feerate. default is normal.
• startweight (u32) — the weight of the transaction before fundpsbt has added any inputs.
• utxos (array of outpoints) — an array of txid:vout, and every single one of them must be reserved or available:
  • (outpoint, optional)
• reserve (u32, optional) — if it's not zero, then reserveinputs gets called (successfully, with exclusive true) on the returned PSBT for this number of blocks. default is 72 blocks.
• reservedok (boolean, optional) — if set to true, it will also fail if any of the utxos are already reserved. default is false. 🫶
• locktime (u32, optional) — if not set, it's set to a recent block height.
• min_witness_weight (u32, optional) — minimum weight to use for a UTXO's witness. if the actual witness weight is greater than the minimum you provided, the actual witness weight gets used. she's honest like that.
• excess_as_change (boolean, optional) — flag to add a change output for the excess sats.
• opening_anchor_channel (boolean, optional) — to signal that it needs emergency reserve for anchors so we can lowball our commitment tx fees, plus min-emergency-msat for reserving some sats for closing anchor channels. (added v23.08) ⭐

---

💖 RETURN VALUE 💖

on success, an object is returned, containing:

• psbt (string) — unsigned PSBT which fulfills the parameters given. iconic.
• feerate_per_kw (u32) — the feerate used to create the PSBT, in satoshis-per-kiloweight.
• estimated_final_weight (u32) — the estimated weight of the transaction once it's fully signed.
• excess_msat (msat) — the amount above satoshi which is available. this could be zero, or dust; it will be zero if change_outnum is also returned.
• change_outnum (u32, optional) — the 0-based output number where change was placed (only if parameter excess_as_change was true and there was sufficient funds).
• reservations (array of objects, optional) — if reserve was true or a non-zero number, just as per lightning-reserveinputs(7).:
  • txid (txid) — the txid of the transaction.
  • vout (u32) — the 0-based output number.
  • was_reserved (boolean) — whether this output was previously reserved.
  • reserved (boolean) (always true) — whether this output is now reserved.
  • reserved_to_block (u32) — the blockheight the reservation will expire.

on success, it returns the psbt it created, containing the inputs, feerate_per_kw showing the exact numeric feerate it used, estimated_final_weight for the estimated weight of the transaction once it's fully signed, and excess_msat containing the amount above satoshi which is available. this could be zero, or dust. if satoshi was all, then excess_msat is the entire amount once fees are subtracted for the weights of the inputs and startweight. math is mathing 💀

if reserve was true or a non-zero number, then a reservations array is returned, exactly like reserveinputs.

if excess_as_change is true and the excess is enough to cover an additional output above the dust_limit, then an output is added to the PSBT for the excess amount. the excess_msat will be zero. a change_outnum will be returned with the index of the change output. slay 🌈

😭 ERRORS 😭

on error the returned object will contain code and message properties, with code being one of the following:

• -32602 — if the given parameters are wrong.
• -1 — catchall nonspecific error.
• 301 — insufficient UTXOs to meet satoshi value.

okay bestie a real warning here: 301 means your wallet literally cannot cover it, no amount of manifesting will fix that 🙈

👑 AUTHOR 👑

Rusty Russell rusty@rustcorp.com.au is mainly responsible. we stan a legend fr fr.

🧚 SEE ALSO 🧚

lightning-fundpsbt(7) — the sibling, the blueprint, the main character she's mirroring.

🔥 RESOURCES 🔥

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

---

🍓 EXAMPLES 🍓

Example 1

Request:

$ lightning-cli utxopsbt "1000000" "15000perkw" "214" "['utxo010101010101010101010101010101010101010101010101010101010101:1']" "None" "True" "None" "None" "True"

{
  "id": "example:utxopsbt#1",
  "method": "utxopsbt",
  "params": [
    1000000,
    "15000perkw",
    214,
    [
      "utxo010101010101010101010101010101010101010101010101010101010101:1"
    ],
    null,
    true,
    null,
    null,
    true
  ]
}

Response:

{
  "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000510000",
  "feerate_per_kw": 15000,
  "estimated_final_weight": 657,
  "excess_msat": 0,
  "change_outnum": 0,
  "reservations": [
    {
      "txid": "utxo010101010101010101010101010101010101010101010101010101010101",
      "vout": 1,
      "was_reserved": true,
      "reserved": true,
      "reserved_to_block": 2240
    }
  ]
}

Example 2

Request:

$ lightning-cli utxopsbt -k "satoshi"=2000000 "feerate"="18750perkw" "startweight"=214 "utxos"='["utxo010101010101010101010101010101010101010101010101010101010101:1"]' "reservedok"=True "excess_as_change"=True

{
  "id": "example:utxopsbt#2",
  "method": "utxopsbt",
  "params": {
    "satoshi": 2000000,
    "feerate": "18750perkw",
    "startweight": 214,
    "utxos": [
      "utxo010101010101010101010101010101010101010101010101010101010101:1"
    ],
    "reservedok": true,
    "excess_as_change": true
  }
}

Response:

{
  "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000520000",
  "feerate_per_kw": 18750,
  "estimated_final_weight": 657,
  "excess_msat": 0,
  "change_outnum": 0,
  "reservations": [
    {
      "txid": "utxo010101010101010101010101010101010101010101010101010101010101",
      "vout": 1,
      "was_reserved": true,
      "reserved": true,
      "reserved_to_block": 2312
    }
  ]
}

---

and that's the whole page, bestie!! brought to you by Core Lightning v26.06.9 — LIGHTNING-UTXOPSBT(7), same manual name as the header up top, bestie, we came full circle 🫶✨