Lendasat DocsHandle Refunds & Failures
Refund Onchain HTLC
Refund funds locked in an onchain Bitcoin HTLC when a swap fails or times out.
Locktime Required: Refunds are only possible AFTER the HTLC locktime expires. This is typically 24-48 hours after swap creation.
When to Refund
Refunds are typically needed when:
- The swap status is
Expired(service never funded VHTLC) - The service didn't respond to your BTC payment
- Network congestion prevented timely completion
- You want to recover funds from an incomplete swap
Refund Onchain HTLC
const result = await client.refundSwap(swapId, {
destinationAddress: "bc1q...", // Your BTC address
feeRateSatPerVb: 5,
});
if (result.success) {
console.log("Refund TX:", result.txId);
console.log("Amount:", result.refundAmount, "sats");
} else {
console.error("Refund failed:", result.message);
}Complete Refund Flow
Full example with status checking and error handling:
// Check swap status first
const swap = await client.getSwap(swapId);
console.log("Status:", swap.status);
// Attempt refund (will fail if locktime hasn't expired)
const result = await client.refundSwap(swapId, {
destinationAddress: "bc1q...",
feeRateSatPerVb: 5,
});
if (result.success) {
console.log("Refund broadcast:", result.broadcast);
console.log("TX ID:", result.txId);
console.log("Refund amount:", result.refundAmount, "sats");
console.log("Fee:", result.fee, "sats");
} else {
// May need to wait for locktime
console.log(result.message);
}Check HTLC Status on Blockchain
Verify HTLC funds using blockchain explorers:
# Check HTLC UTXO status
curl https://mempool.space/api/address/YOUR_HTLC_ADDRESS/utxoOr programmatically:
const swap = await client.getSwap(swapId);
console.log("Status:", swap.status);
// The SDK checks locktime and UTXO availability automatically
// when you call refundSwap(). If locktime hasn't expired,
// the error message will tell you when it does.Important Notes
Onchain Fees: Refunding an onchain HTLC requires paying Bitcoin network fees. The SDK handles fee estimation automatically.
- Longer locktimes - Onchain HTLCs have longer locktimes (24-48h) than VHTLCs
- Network fees - You'll pay standard BTC transaction fees for the refund
- Confirmation time - Refund transactions need blockchain confirmations
- One UTXO - Each HTLC holds one UTXO that can only be spent once