arkade

name	arkade
description	Guide for developing with the Arkade TypeScript SDK (@arkade-os/sdk) — Bitcoin wallets, Lightning, smart contracts, and stablecoin swaps.
read_when	["user wants to develop or build with Arkade","user wants to use the @arkade-os/sdk TypeScript SDK","user asks about Arkade wallet SDK or API","user wants to create a Bitcoin wallet application","user mentions VTXOs, virtual UTXOs, or offchain Bitcoin development","user wants to integrate Lightning Network with Arkade","user asks about Arkade smart contracts","user wants to send or receive Bitcoin programmatically with Arkade","user asks about onboarding or offboarding Bitcoin","user mentions arkade.computer or Arkade SDK","user mentions Arkade protocol"]
requires	[]
metadata	{"emoji":"₿"}

Arkade SDK Development Guide

Arkade is a programmable Bitcoin execution layer. It uses VTXOs (Virtual Transaction Outputs) to enable instant offchain Bitcoin transactions with near-zero fees, while users retain full self-custody and unilateral exit rights. No changes to Bitcoin are required.

Terminology Notice

Use current Arkade terminology in all docs, comments, and user-facing text:

• Use Arkade operator or the operator, not deprecated terms such as "Ark service provider", "ASP", or "Ark server".
• Use batch swap, not "round".
• Use commitment transaction or batch swap commitment transaction, not "round transaction".
• Use Arkade address, not "Ark address".
• Use Arkade transaction, not "Ark transaction", "out of round transaction", or "arkoor".
• Use delegate for the entity that renews VTXOs; use "delegating" only when describing the user action.

SDK Installation & Setup

pnpm add @arkade-os/sdk

Requires Node.js >= 22.

import { generateMnemonic } from "@scure/bip39";
import { wordlist } from "@scure/bip39/wordlists/english";
import { MnemonicIdentity, Wallet } from "@arkade-os/sdk";

const mnemonic = generateMnemonic(wordlist);
const identity = MnemonicIdentity.fromMnemonic(mnemonic);

const wallet = await Wallet.create({
  identity,
  arkServerUrl: "https://arkade.computer",
});

const address = await wallet.getAddress();
console.log("Arkade address:", address);

For production, always use a secure key management solution rather than hardcoded keys.

Core Wallet Operations

Addresses

// Offchain Arkade address (ark1.../tark1...) — for instant payments
const arkAddress = await wallet.getAddress();

// Boarding address — for receiving onchain BTC to be onboarded later
const boardingAddress = await wallet.getBoardingAddress();

Balances

const balance = await wallet.getBalance();

console.log("Available:", balance.available, "sats"); // spendable now
console.log("Total:", balance.total, "sats"); // includes recoverable
console.log("Settled:", balance.settled, "sats"); // Bitcoin-anchored
console.log("Preconfirmed:", balance.preconfirmed, "sats"); // cosigned

// Pending onchain deposits
console.log("Boarding:", balance.boarding.total, "sats");

Sending Payments

// Send to an Arkade address — instant, near-zero fees
const txid = await wallet.sendBitcoin({
  address: "ark1...",
  amount: 50000, // satoshis
});

For onchain destinations (bc1.../tb1...), use the Ramps offboard flow below. For Lightning invoices, use @arkade-os/boltz-swap.

Receiving Payments

const address = await wallet.getAddress();
// Share this address with the sender

// Monitor for incoming funds
const stop = wallet.notifyIncomingFunds(async (notification) => {
  if (notification.type === "vtxo") {
    for (const vtxo of notification.vtxos) {
      console.log(`Received ${vtxo.amount} sats`);
    }
  }
});

// Call stop() when done listening

VTXOs

const vtxos = await wallet.getVtxos();
for (const vtxo of vtxos) {
  console.log(vtxo.txid, vtxo.amount, vtxo.status);
}

Onchain Ramps (Onboard / Offboard)

Convert between onchain Bitcoin UTXOs and offchain Arkade VTXOs. Best for large transfers; for everyday amounts, Lightning swaps have lower overhead.

import { Ramps } from "@arkade-os/sdk";

const ramps = new Ramps(wallet);

// Get fee info from the Arkade operator
const info = await wallet.arkProvider.getInfo();

// Onboard: convert boarding UTXOs to VTXOs
const commitmentTxid = await ramps.onboard(info.fees);

// Offboard: convert VTXOs to onchain BTC
const exitTxid = await ramps.offboard(
  "bc1q...", // destination onchain address
  info.fees,
  // amount, // optional — defaults to all available
);

Lightning Network

pnpm add @arkade-os/boltz-swap

Lightning integration uses Boltz submarine swaps to bridge between Arkade and the Lightning Network.

import { ArkadeSwaps, BoltzSwapProvider } from "@arkade-os/boltz-swap";

const swapProvider = new BoltzSwapProvider({
  apiUrl: "https://api.ark.boltz.exchange",
  network: "bitcoin",
});

const lightning = new ArkadeSwaps({
  wallet,
  swapProvider,
});

// Receive via Lightning (reverse swap)
const { invoice, paymentHash } = await lightning.createLightningInvoice({
  amount: 25000,
});
console.log("Pay this:", invoice);

// Send via Lightning (submarine swap)
const result = await lightning.sendLightningPayment({
  invoice: "lnbc...",
});
console.log("Preimage:", result.preimage);

Boltz API Endpoints

Network	URL
Bitcoin mainnet	https://api.ark.boltz.exchange
Mutinynet	https://api.boltz.mutinynet.arkade.sh
Signet	https://api.boltz.signet.arkade.sh
Regtest (local)	http://localhost:9069

Skill Classes (this package)

This package (@arkade-os/skill) provides higher-level wrapper classes over the SDK:

pnpm add @arkade-os/skill

import { generateMnemonic } from "@scure/bip39";
import { wordlist } from "@scure/bip39/wordlists/english";
import { MnemonicIdentity, Wallet } from "@arkade-os/sdk";
import {
  ArkadeBitcoinSkill,
  ArkadeLightningSkill,
  LendaSwapSkill,
} from "@arkade-os/skill";

const mnemonic = generateMnemonic(wordlist);
const identity = MnemonicIdentity.fromMnemonic(mnemonic);

const wallet = await Wallet.create({
  identity,
  arkServerUrl: "https://arkade.computer",
});

// Bitcoin: addresses, balances, send/receive, onboard/offboard
const bitcoin = new ArkadeBitcoinSkill(wallet);
const balance = await bitcoin.getBalance();
await bitcoin.send({ address: "ark1...", amount: 50000 });

// Lightning: invoices, payments via Boltz
const lightning = new ArkadeLightningSkill({ wallet });
const inv = await lightning.createInvoice({ amount: 25000 });

// Stablecoin swaps: BTC <-> USDC/USDT
const lendaswap = new LendaSwapSkill({ wallet });
const quote = await lendaswap.getQuoteBtcToStablecoin(100000, "usdc_pol");

ArkadeBitcoinSkill

• getArkadeAddress() / getBoardingAddress() — get addresses
• getBalance() — balance breakdown (offchain + onchain)
• send({ address, amount }) — send sats offchain
• getTransactionHistory() — transaction list
• onboard(params) / offboard(params) — onchain ramps
• waitForIncomingFunds(timeout?) — wait for incoming payment

ArkadeLightningSkill

• createInvoice({ amount, description? }) — Lightning invoice (reverse swap)
• payInvoice({ bolt11 }) — pay Lightning invoice (submarine swap)
• getFees() / getLimits() — swap fees and limits
• getPendingSwaps() / getSwapHistory() — swap tracking

LendaSwapSkill

• getQuoteBtcToStablecoin(amount, token) / getQuoteStablecoinToBtc(amount, token)
• swapBtcToStablecoin(params) / swapStablecoinToBtc(params)
• getSwapStatus(swapId) / getPendingSwaps() / getSwapHistory()
• claimSwap(swapId) / refundSwap(swapId)
• getAvailablePairs()

Stablecoin Swaps (LendaSwap)

Non-custodial BTC/stablecoin atomic swaps via HTLCs.

Supported tokens: usdc_pol, usdc_eth, usdc_arb, usdt0_pol, usdt_eth, usdt_arb

Supported chains: polygon, ethereum, arbitrum

const lendaswap = new LendaSwapSkill({ wallet });

// Get quote
const quote = await lendaswap.getQuoteBtcToStablecoin(100000, "usdc_pol");
console.log("You'll receive:", quote.targetAmount, "USDC");

// Execute swap (BTC -> USDC)
const swap = await lendaswap.swapBtcToStablecoin({
  targetAddress: "0x...", // EVM address
  targetToken: "usdc_pol",
  targetChain: "polygon",
  sourceAmount: 100000,
});
console.log("Swap ID:", swap.swapId);

// Check status
const status = await lendaswap.getSwapStatus(swap.swapId);

// Claim completed swap
const claim = await lendaswap.claimSwap(swap.swapId);

Smart Contracts

Arkade supports any valid Tapscript as VTXO locking conditions, enabling programmable offchain Bitcoin.

pnpm add @arkade-os/sdk @scure/base

import {
  RestArkProvider,
  RestIndexerProvider,
  VtxoScript,
  MultisigTapscript,
  CLTVMultisigTapscript,
  CSVMultisigTapscript,
} from "@arkade-os/sdk";
import { hex } from "@scure/base";

const arkProvider = new RestArkProvider("https://mutinynet.arkade.sh");
const indexerProvider = new RestIndexerProvider("https://mutinynet.arkade.sh");
const info = await arkProvider.getInfo();
const operatorPubkey = hex.decode(info.signerPubkey).slice(1);

Available contract primitives:

• MultisigTapscript — N-of-N multisig
• CLTVMultisigTapscript — Multisig with absolute timelocks (collaborative paths)
• CSVMultisigTapscript — Multisig with relative timelocks (unilateral paths)
• ConditionMultisigTapscript — Condition + multisig (e.g., hashlock + collaborative)
• ConditionCSVMultisigTapscript — Condition + CSV multisig (e.g., hashlock + unilateral)
• VtxoScript — Combine spending paths into Taproot trees

Contract patterns in docs: HTLC/Hashlock, Escrow (3-path), Spilman channels, Dryja-Poon channels, Lightning channels, chain swaps, Oracle DLC.

Use @scure/base for encoding, NOT bitcoinjs-lib.

See: https://docs.arkadeos.com/contracts/overview

Networks & Resources

Network	Operator URL	Explorer
Bitcoin mainnet	https://arkade.computer	https://arkade.space
Mutinynet (testnet)	https://mutinynet.arkade.sh	https://explorer.mutinynet.arkade.sh
Signet	https://signet.arkade.sh	https://explorer.signet.arkade.sh
Regtest (local)	http://localhost:7070	—

Local development:

nigiri start --ark

This starts a Bitcoin regtest node with an Arkade operator at http://localhost:7070.

Key Concepts

• VTXOs: Virtual Transaction Outputs — self-custodial offchain Bitcoin coins. States: preconfirmed, settled, recoverable, spent.
• Batch Swaps: How VTXOs achieve Bitcoin finality — multiple transactions batched into a single onchain settlement.
• Preconfirmation: Instant confirmation cosigned by the operator, before onchain settlement.
• Virtual Mempool: DAG-based offchain execution engine that processes Arkade transactions.
• Unilateral Exit: Users can always withdraw their funds onchain without operator cooperation.
• Arkade Addresses: ark1... (mainnet) / tark1... (testnet) — bech32m-encoded addresses containing operator + user keys.

Documentation

• Full docs: https://docs.arkadeos.com
• Technical primer: https://docs.arkadeos.com/primer
• Wallet SDK: https://docs.arkadeos.com/wallets/getting-started/introduction
• Smart contracts: https://docs.arkadeos.com/contracts/overview
• Lightning swaps: https://docs.arkadeos.com/contracts/lightning-swaps
• LLM-friendly index: https://docs.arkadeos.com/llms.txt
• GitHub: https://github.com/arkade-os/skill