Lightning ↔ Arkade

Overview

Lightning and Arkade are both off-chain Bitcoin layers, so swapping between them is fast and cheap. There are no on-chain confirmations to wait for. Satora bridges the two using HTLCs that share a single secret hash, so neither side can cheat:

Lightning → Arkade: you pay a BOLT11 invoice and receive Arkade VTXOs.
Arkade → Lightning: you fund an Arkade VHTLC with VTXOs and Satora pays a BOLT11 invoice you provide.

Both directions settle off-chain in seconds. The same secret hash locks the Lightning side and the Arkade VHTLC, so the atomic swap either completes on both legs or refunds.

Lightning → Arkade

You pay a Lightning invoice, the server funds an Arkade VHTLC, and you claim it to receive VTXOs.

Create the swap

const result = await client.createSwap({
  source: Asset.BTC_LIGHTNING,
  target: Asset.BTC_ARKADE,
  targetAddress: arkadeAddress, // ark1q... where you want the VTXOs
  targetAmount: amountSats, // sats to receive on Arkade
});

const { response } = result;

Pay the invoice

Pay the BOLT11 invoice returned in the response with any Lightning wallet (e.g. Phoenix, Wallet of Satoshi). The SDK generates the secret and shares only its hash, so the server can settle the swap only after you reveal the secret by claiming.

console.log("Pay invoice:", response.bolt11_invoice);
// ... "lnbc1m1p..."
console.log("Swap ID:", response.id);
// ... "550e8400-e29b-41d4-a716-446655440000"

Monitor status & claim

Wait for the status to become serverfunded, then claim the Arkade VHTLC to receive your VTXOs:

WebSocket (recommended)
Polling

const unsubscribe = client.subscribeToSwaps([response.id], (swapId, status) => {
  console.log("Status:", status);
  if (status === "serverfunded") {
    // Ready to claim VTXOs
    unsubscribe();
  }
});

let swap = await client.getSwap(response.id);
while (swap.status !== "serverfunded" && swap.status !== "expired") {
  await new Promise((r) => setTimeout(r, 3000));
  swap = await client.getSwap(response.id);
}

const claimResult = await client.claim(response.id);
if (!claimResult.success) {
  throw new Error(`Claim failed: ${claimResult.message}`);
}
console.log("Claimed! TX:", claimResult.txHash);
// ... "ark:abc123..."

Arkade → Lightning

You provide a Lightning invoice, fund an Arkade VHTLC with your VTXOs, and Satora pays the invoice automatically.

Create the swap

Pass a BOLT11 invoice as the target. You can also pass an LNURL or Lightning address together with an amount, and Satora fetches an invoice for you.

const result = await client.createSwap({
  source: Asset.BTC_ARKADE,
  target: Asset.BTC_LIGHTNING,
  targetAddress: lightningInvoice, // your BOLT11 invoice
});

const { response } = result;

The invoice amount must match what the swap pays out after fees. Use client.getArkadeToLightningQuote(sourceAmountSats) to compute the correct invoice amount up front, or pass an LNURL/Lightning address so the amount is negotiated automatically.

Fund the VHTLC

Send the source amount in VTXOs from your Arkade wallet to the VHTLC address returned in the response:

console.log("Swap ID:", response.id);
// ... "550e8400-e29b-41d4-a716-446655440000"
console.log("Fund VHTLC:", response.arkade_vhtlc_address);
// ... "ark1q..."
console.log("Amount to send:", response.source_amount, "sats");
// ... "101250 sats" (includes fees)

Monitor status

Once your VTXOs land in the VHTLC, Satora settles the Lightning invoice automatically. The swap reaches serverfunded when the invoice is paid, then serverredeemed once Satora claims your VTXOs to complete the swap. There is no claim step on your side.

WebSocket (recommended)
Polling

const unsubscribe = client.subscribeToSwaps([response.id], (swapId, status) => {
  console.log("Status:", status);
  if (status === "serverfunded") {
    console.log("Swap complete! Lightning invoice settled.");
    unsubscribe();
  }
});

let swap = await client.getSwap(response.id);
while (swap.status !== "serverfunded" && swap.status !== "expired") {
  await new Promise((r) => setTimeout(r, 3000));
  swap = await client.getSwap(response.id);
}

If the invoice can’t be paid (status serverwontfund or clientinvalidfunded), your VTXOs stay locked in the VHTLC. Retry with a fresh invoice using client.retryArkadeToLightningSwap(swapId, { lightningAddress }), which collaboratively moves your funds into a new swap with no locktime wait. See Refund an on-chain HTLC for recovery details.

Build with AI

We have generated a llms-full.txt file that converts all our documentation into a single markdown document following the llmstxt.org standard. Feed it to any AI coding agent (Claude, Cursor, Copilot, etc.) and it will have everything it needs to integrate the Satora Swaps SDK into your project.

Full example: Lightning → Arkade

/**
 * Lightning → Arkade: end-to-end example.
 *
 * The user pays a Lightning invoice and receives Arkade VTXOs after claiming.
 */

import {
  Asset,
  Client,
  InMemorySwapStorage,
  InMemoryWalletStorage,
} from "@satora/swap";

const client = await Client.builder()
  .withSignerStorage(new InMemoryWalletStorage())
  .withSwapStorage(new InMemorySwapStorage())
  .withOrgCode(process.env.ORG_CODE || "")
  .build();

const arkadeAddress = "ark1q..."; // Where you want the VTXOs
const amountSats = 100_000; // 100,000 sats (0.001 BTC)

const result = await client.createSwap({
  source: Asset.BTC_LIGHTNING,
  target: Asset.BTC_ARKADE,
  targetAddress: arkadeAddress,
  targetAmount: amountSats,
});

const { response } = result;

if (!("bolt11_invoice" in response)) {
  throw new Error("Expected Lightning-to-Arkade swap response");
}

console.log("Pay invoice:", response.bolt11_invoice);
// ... "lnbc1m1p..."
console.log("Swap ID:", response.id);
// ... "550e8400-e29b-41d4-a716-446655440000"

let swap = await client.getSwap(response.id);
while (swap.status !== "serverfunded" && swap.status !== "expired") {
  await new Promise((r) => setTimeout(r, 3000));
  swap = await client.getSwap(response.id);
  console.log("Status:", swap.status);
  // ... "pending" → "clientfunded" → "serverfunded"
}

if (swap.status === "expired") {
  throw new Error("Swap expired - invoice was not paid in time.");
}

const claimResult = await client.claim(response.id);
if (!claimResult.success) {
  throw new Error(`Claim failed: ${claimResult.message}`);
}
console.log("Claimed! TX:", claimResult.txHash);
// ... "ark:abc123..."

const finalSwap = await client.getSwap(response.id);
console.log("Final status:", finalSwap.status);
// ... "clientredeemed"
console.log("Target:", finalSwap.target_amount, "sats (Arkade)");
// ... "Target: 100000 sats (Arkade)"

Full example: Arkade → Lightning

/**
 * Arkade → Lightning: end-to-end example.
 *
 * The user funds an Arkade VHTLC with VTXOs and Satora pays the Lightning invoice.
 */

import {
  Asset,
  Client,
  InMemorySwapStorage,
  InMemoryWalletStorage,
} from "@satora/swap";

const client = await Client.builder()
  .withSignerStorage(new InMemoryWalletStorage())
  .withSwapStorage(new InMemorySwapStorage())
  .withOrgCode(process.env.ORG_CODE || "")
  .build();

const lightningInvoice = "lnbc1m1p..."; // Your BOLT11 invoice

const result = await client.createSwap({
  source: Asset.BTC_ARKADE,
  target: Asset.BTC_LIGHTNING,
  targetAddress: lightningInvoice,
});

const { response } = result;

if (!("arkade_vhtlc_address" in response)) {
  throw new Error("Expected Arkade-to-Lightning swap response");
}

console.log("Swap ID:", response.id);
// ... "550e8400-e29b-41d4-a716-446655440000"
console.log("Fund VHTLC:", response.arkade_vhtlc_address);
// ... "ark1q..."
console.log("Amount to send:", response.source_amount, "sats");
// ... "101250 sats" (includes fees)

// Send `response.source_amount` sats in VTXOs from your Arkade wallet to
// `response.arkade_vhtlc_address`, then wait for the invoice to settle.

let swap = await client.getSwap(response.id);
while (swap.status !== "serverfunded" && swap.status !== "expired") {
  await new Promise((r) => setTimeout(r, 3000));
  swap = await client.getSwap(response.id);
  console.log("Status:", swap.status);
  // ... "pending" → "clientfunded" → "serverfunded"
}

if (swap.status === "expired") {
  throw new Error("Swap expired - VHTLC was not funded in time.");
}

const finalSwap = await client.getSwap(response.id);
console.log("Final status:", finalSwap.status);
// ... "serverredeemed"
console.log("Source:", finalSwap.source_amount, "sats (Arkade)");
console.log("Target:", finalSwap.target_amount, "sats (Lightning)");
// ... "Target: 100000 sats (Lightning)"

Introduction

Integration

Advanced

Overview

Lightning → Arkade

Create the swap

Pay the invoice

Monitor status & claim

Arkade → Lightning

Create the swap

Fund the VHTLC

Monitor status

Build with AI

​Overview

​Lightning → Arkade

​Create the swap

​Pay the invoice

​Monitor status & claim

​Arkade → Lightning

​Create the swap

​Fund the VHTLC

​Monitor status

​Build with AI

Overview

Lightning → Arkade

Create the swap

Pay the invoice

Monitor status & claim

Arkade → Lightning

Create the swap

Fund the VHTLC

Monitor status

Build with AI