Speed up or cancel a transfer

Transfers the site built signal replace-by-fee (BIP 125). While one is pending, its owner can speed it up (the same transaction at a higher fee rate) or cancel it (send every source UTXO back where it came from). Both are a prepare with kind: "speedup" or kind: "cancel" and the pending txid, then sign and submit as usual.

{
  "kind": "speedup",
  "txid": "6897451c42f02de2594abfdd6a5d4fcf4794a62cbbd9fbec1ec983893ddc5df4",
  "owner": { "payment_address": "…", "payment_public_key": "…", "ordinals_address": "…", "ordinals_public_key": "…" },
  "fee_rate": 12
}

Speed up #

The same inputs and outputs; only the change shrinks. When the change cannot pay the higher fee, the server adds plain bitcoin of your payment address. The new fee must be at least the original's fee plus the node's incremental relay fee for the new size, at a rate at least 1 sat/vB above the original's: the summary's min_fee_rate says the lowest rate that works. Too low → replacement_fee_too_low.

Cancel #

Spends the same source UTXOs, each back 1:1 to the address it came from, plus the original funding. The original tools-fee output is kept (you are not charged twice). A cancel of a transfer that is no longer in the mempool (dropped, unknown) is a void: a signed transaction can resurface until something else spends its inputs, so voiding it is how you make sure it never confirms. A cancel is only prepared where it can save something, judged by what bitcoind's mempool shows at that moment, else 409 nothing_to_cancel. A transfer in the mempool (whatever its recorded status) can be cancelled when it pays someone else itself: a cancel, or a speed-up of one, already sends everything home. One out of the mempool can be cancelled (voided) when anything of its chain of replacements pays someone else, since any of them could resurface. A transfer bitcoind refused (rejected) was never sent: nothing to cancel.

The records' actions.cancel follows one rule: it never hides a cancel the prepare would allow. Without asking the mempool for every record, it is shown for every transfer that could still confirm whose chain pays someone else; the prepare then decides, so a pending cancel shows the button but answers nothing_to_cancel until it leaves the mempool.

When it is refused #

Follow the result with Get a wallet transfer: the original becomes replaced, with replaced_by.