Create Swaps

Onchain → Arkade

Create a swap from on-chain Bitcoin to Arkade VTXOs for instant, low-fee transactions.

Overview

On-chain to Arkade swaps allow you to move Bitcoin from the main chain to Arkade. The process:

Create swap - Get a P2WSH HTLC address to send BTC
Send BTC - Send on-chain Bitcoin to the HTLC address
Claim VTXOs - Receive Arkade VTXOs once the BTC confirms

On-chain swaps require waiting for Bitcoin confirmations (typically 1-6 blocks). For instant swaps, consider using Lightning to Arkade instead.

Create Swap

const result = await client.createBitcoinToArkadeSwap({
  satsReceive: 100000, // 100k sats to receive on Arkade
  targetAddress: "ark1q...", // Your Arkade address
});

console.log("Send BTC to:", result.response.btc_htlc_address);
console.log("Amount:", result.response.source_amount, "sats");
console.log("Swap ID:", result.response.id);

Complete Flow

Full example from swap creation to claiming VTXOs:

// 1. Create swap
const result = await client.createBitcoinToArkadeSwap({
  satsReceive: 100000,
  targetAddress: "ark1q...",
});

console.log("Send", result.response.source_amount, "sats to:", result.response.btc_htlc_address);

// 2. Poll for status
let swap = await client.getSwap(result.response.id);
while (swap.status !== "serverfunded" && swap.status !== "clientredeemed") {
  await new Promise((r) => setTimeout(r, 10000)); // 10s for onchain
  swap = await client.getSwap(result.response.id);
  console.log("Status:", swap.status);
}

// 3. Claim VTXOs
if (swap.status === "serverfunded") {
  const claim = await client.claimArkade(result.response.id, {
    destinationAddress: "ark1q...",
  });
  console.log("Claimed:", claim.success);
}

Monitor Swap Status

const swap = await client.getSwap(swapId);
console.log("Status:", swap.status);
console.log("Source amount:", swap.source_amount, "sats");
console.log("Target amount:", swap.target_amount, "sats");

Swap Request Parameters

Parameter	Type	Required	Description
`sourceAmount`	bigint	Yes	Amount of sats to send
`targetChain`	string	Yes	Target chain (e.g., `arkade`)
`referralCode`	string	No	Optional referral code

Swap Response

Field	Type	Description
`id`	string	Unique swap ID
`htlcAddress`	string	P2WSH address to send BTC
`sourceAmount`	number	BTC amount to send (including fee)
`targetAmount`	number	Arkade VTXOs to receive
`hashLock`	string	HTLC hash lock
`timelock`	number	HTLC expiration (block height)
`status`	string	Current swap status
`createdAt`	string	Creation timestamp

Important Notes

Wait for Confirmations: The service waits for Bitcoin confirmations before funding the Arkade VHTLC. This typically takes 10-60 minutes depending on network conditions.

Exact amount - Send exactly the sourceAmount to the HTLC address
Timelock - Send BTC before the timelock expires (usually 24-48 hours)
One transaction - Send the full amount in a single transaction
Fees included - The sourceAmount includes the swap fee

Next Steps

After creating a swap:

Send BTC - Use any Bitcoin wallet to send to the P2WSH address
Wait for confirmations - Service waits for block confirmations
Claim VTXOs - Call claimArkade() when status is ServerFunded
If failed - Use refundSwap() after timelock expires

EVM → BTC

Create a swap from stablecoins on Polygon or Ethereum to Bitcoin (via Arkade or Lightning).

Get Swap by ID

Fetch the current status and details of a specific swap using its unique identifier.

Onchain → Arkade

On this page