prepare_btc_multisig_send
Build and sign a multi-sig Bitcoin transaction from a registered wallet using a Ledger, returning a partial PSBT for cosigners to finalize.
Instructions
Initiator flow — build a tx FROM a registered multi-sig wallet, sign it with our Ledger key in the same call, return the partial PSBT for cosigners to sign. Pipeline: (1) fetch UTXOs across the wallet's gap-limit window, (2) coin-select with a multi-sig-aware vbyte estimator (P2WSH sortedmulti(M,...,N) inputs are ~2-4× P2WPKH), (3) resolve a fresh chain=1 change address (lowest unused index), (4) build PSBT v0 with witnessUtxo + nonWitnessUtxo (Ledger app 2.x requirement) + witnessScript + bip32_derivation for ALL cosigners, (5) sign with our Ledger via the existing co-signer flow (the device walks every output address + amount on-screen), (6) splice our signature into the PSBT, return the partial PSBT. We do NOT finalize or broadcast — the caller gathers remaining signatures externally, then runs combine_btc_psbts + finalize_btc_psbt. The fee-cap guard scales to multi-sig sizes automatically. Phase 3 supports wsh (P2WSH) wallets only; taproot lands in a follow-up PR.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| walletName | Yes | Name of a registered multi-sig wallet (matches `register_btc_multisig_wallet`). | |
| to | Yes | Recipient address. Any of the four mainnet types is accepted as a destination. | |
| amount | Yes | Decimal BTC string (up to 8 fractional digits, e.g. "0.001") or "max" to sweep every UTXO across the wallet's gap-limit window. "max" picks the fee-aware amount after coin-selection so the user doesn't have to subtract fees by hand. | |
| feeRateSatPerVb | No | Fee rate in sat/vB. Optional — defaults to mempool.space's `halfHourFee` (~3-block target). Multi-sig txs are inherently larger than P2WPKH, so the absolute fee at the same sat/vB will be ~2-4× a single-sig send. | |
| allowHighFee | No | Override the fee-cap guard. The cap is `max(10 × feeRate × vbytes, 2% of recipient value)` and uses the multi-sig vsize estimator. |