Lendasat DocsHandle Refunds & Failures
Refund Locktime & Conditions
Understanding when and how refunds become available based on locktime expiration.
Security by Design: Timelocks are essential for atomic swap security. They ensure that either both parties complete the swap, or both can recover their funds.
Timeout Summary
| Type | Duration | Purpose |
|---|---|---|
| Swap Request | 30 min | Time to make initial payment |
| Lightning Invoice | 10 min | Lightning payment window |
| EVM HTLC | 10-30 min | Time for user to claim EVM funds |
| Arkade VHTLC | 2 hours | Time for service to claim |
| Onchain HTLC | 24-48 hours | Time for onchain refund |
Locktime Hierarchy
In an atomic swap, timelocks are staggered to ensure safe completion:
┌─────────────────────────────────────────────────────────────────┐
│ LOCKTIME HIERARCHY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ User's HTLC (BTC side) Service's HTLC (EVM side) │
│ ───────────────────── ─────────────────────── │
│ │
│ Locktime: 24-48 hours Locktime: 10-30 minutes │
│ ▲ ▲ │
│ │ │ │
│ │ └── Shorter: Service │
│ │ claims first or │
│ │ user refunds │
│ │ │
│ └── Longer: User has time │
│ to claim or refund │
│ │
└─────────────────────────────────────────────────────────────────┘Locktime Values by Swap Type
| Swap Type | Your Locktime | Service Locktime | Reason |
|---|---|---|---|
| BTC → EVM (Arkade) | 2 hours | 30 minutes | Service claims first |
| BTC → EVM (Onchain) | 24-48 hours | 2 hours | Onchain needs more time |
| EVM → BTC | 30 minutes | 10 minutes | Fast EVM settlement |
| Lightning | 10 min invoice | N/A | Lightning is instant |
Check Refundable Amount
Use the SDK to check if a swap has funds available for refund:
// Check swap status and refund availability
const swap = await client.getSwap(swapId);
console.log("Status:", swap.status);
// Attempt refund — the SDK checks locktime automatically
const result = await client.refundSwap(swapId, {
destinationAddress: "bc1q...", // or "ark1q..." for Arkade swaps
});
if (!result.success) {
// If locktime hasn't expired, message tells you when it does
console.log(result.message);
}Refund Decision Flowchart
┌──────────────┐
│ Check Swap │
│ Status │
└──────┬───────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Pending │ │ Funded │ │ Terminal │
│ │ │ │ │ │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ No funds │ │ Check │ │ Already │
│ to refund │ │ locktime │ │ resolved │
└───────────┘ └─────┬─────┘ └───────────┘
│
┌──────┴──────┐
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ Expired │ │ Active │
│ → Refund │ │ → Wait │
└──────────┘ └──────────┘Best Practices
Priority: Always try to complete the swap first. Refunds should only be used when completion is impossible.
- Claim before refund - If
ServerFunded, claim instead of waiting for refund - Don't rush - Wait for locktime to expire naturally
- Monitor status - Keep checking until resolved
- Have patience - Onchain refunds may take 24-48 hours to become available
- Check both HTLCs - Some swaps have funds on both sides
Common Scenarios
| Scenario | What Happened | Action |
|---|---|---|
| Service unresponsive | You paid, service didn't fund | Wait for locktime, then refund |
| Forgot to claim | Service funded, you didn't claim | Claim immediately if still ServerFunded |
| Network issues | Transaction stuck | Wait for confirmation or refund |
| Changed mind | Want to cancel swap | Wait for locktime (cannot cancel early) |