{"skill":{"slug":"bitcoin-arkade","displayName":"Build apps with Bitcoin and Stablecoins on Arkade","summary":"Guide for developing with the Arkade TypeScript SDK (@arkade-os/sdk) — Bitcoin wallets, Lightning, smart contracts, and stablecoin swaps.","description":"---\nname: arkade\ndescription: Guide for developing with the Arkade TypeScript SDK (@arkade-os/sdk) — Bitcoin wallets, Lightning, smart contracts, and stablecoin swaps.\nread_when:\n  - user wants to develop or build with Arkade\n  - user wants to use the @arkade-os/sdk TypeScript SDK\n  - user asks about Arkade wallet SDK or API\n  - user wants to create a Bitcoin wallet application\n  - user mentions VTXOs, virtual UTXOs, or offchain Bitcoin development\n  - user wants to integrate Lightning Network with Arkade\n  - user asks about Arkade smart contracts\n  - user wants to send or receive Bitcoin programmatically with Arkade\n  - user asks about onboarding or offboarding Bitcoin\n  - user mentions arkade.computer or Ark protocol SDK\n  - user mentions Ark protocol\nrequires: []\nmetadata:\n  emoji: \"₿\"\n---\n\n# Arkade SDK Development Guide\n\nArkade 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.\n\n## SDK Installation & Setup\n\n```bash\nnpm install @arkade-os/sdk\n```\n\nRequires Node.js >= 22.\n\n```typescript\nimport { SingleKey, Wallet } from \"@arkade-os/sdk\";\n\n// Create an identity (private key)\nconst identity = SingleKey.fromHex(\"your-private-key-hex\");\n// Or generate a new one:\n// const identity = SingleKey.fromRandomBytes();\n\nconst wallet = await Wallet.create({\n  identity,\n  arkServerUrl: \"https://arkade.computer\",\n});\n\nconst address = await wallet.getAddress();\nconsole.log(\"Ark Address:\", address);\n```\n\nFor production, always use a secure key management solution rather than hardcoded keys.\n\n## Core Wallet Operations\n\n### Addresses\n\n```typescript\n// Offchain Ark address (ark1.../tark1...) — for instant payments\nconst arkAddress = await wallet.getAddress();\n\n// Boarding address — for receiving onchain BTC to be onboarded later\nconst boardingAddress = await wallet.getBoardingAddress();\n```\n\n### Balances\n\n```typescript\nconst balance = await wallet.getBalance();\n\nconsole.log(\"Available:\", balance.available, \"sats\"); // spendable now\nconsole.log(\"Total:\", balance.total, \"sats\"); // includes recoverable\nconsole.log(\"Settled:\", balance.settled, \"sats\"); // Bitcoin-anchored\nconsole.log(\"Preconfirmed:\", balance.preconfirmed, \"sats\"); // cosigned\n\n// Pending onchain deposits\nconsole.log(\"Boarding:\", balance.boarding.total, \"sats\");\n```\n\n### Sending Payments\n\n```typescript\n// Send to an Ark address — instant, near-zero fees\nconst txid = await wallet.sendBitcoin({\n  address: \"ark1...\",\n  amount: 50000, // satoshis\n});\n```\n\nFor onchain destinations (`bc1...`/`tb1...`), use the Ramps offboard flow below. For Lightning invoices, use `@arkade-os/boltz-swap`.\n\n### Receiving Payments\n\n```typescript\nconst address = await wallet.getAddress();\n// Share this address with the sender\n\n// Monitor for incoming funds\nconst stop = wallet.notifyIncomingFunds(async (notification) => {\n  if (notification.type === \"vtxo\") {\n    for (const vtxo of notification.vtxos) {\n      console.log(`Received ${vtxo.amount} sats`);\n    }\n  }\n});\n\n// Call stop() when done listening\n```\n\n### VTXOs\n\n```typescript\nconst vtxos = await wallet.getVtxos();\nfor (const vtxo of vtxos) {\n  console.log(vtxo.txid, vtxo.amount, vtxo.status);\n}\n```\n\n## Onchain Ramps (Onboard / Offboard)\n\nConvert between onchain Bitcoin UTXOs and offchain Arkade VTXOs. Best for large transfers; for everyday amounts, Lightning swaps have lower overhead.\n\n```typescript\nimport { Ramps } from \"@arkade-os/sdk\";\n\nconst ramps = new Ramps(wallet);\n\n// Get fee info from the Ark server\nconst info = await wallet.arkProvider.getInfo();\n\n// Onboard: convert boarding UTXOs to VTXOs\nconst commitmentTxid = await ramps.onboard(info.fees);\n\n// Offboard: convert VTXOs to onchain BTC\nconst exitTxid = await ramps.offboard(\n  \"bc1q...\", // destination onchain address\n  info.fees,\n  // amount, // optional — defaults to all available\n);\n```\n\n## Lightning Network\n\n```bash\nnpm install @arkade-os/boltz-swap\n```\n\nLightning integration uses Boltz submarine swaps to bridge between Arkade and the Lightning Network.\n\n```typescript\nimport { ArkadeLightning, BoltzSwapProvider } from \"@arkade-os/boltz-swap\";\n\nconst swapProvider = new BoltzSwapProvider({\n  apiUrl: \"https://api.ark.boltz.exchange\",\n  network: \"bitcoin\",\n});\n\nconst lightning = new ArkadeLightning({\n  wallet,\n  swapProvider,\n});\n\n// Receive via Lightning (reverse swap)\nconst { invoice, paymentHash } = await lightning.createLightningInvoice({\n  amount: 25000,\n});\nconsole.log(\"Pay this:\", invoice);\n\n// Send via Lightning (submarine swap)\nconst result = await lightning.sendLightningPayment({\n  invoice: \"lnbc...\",\n});\nconsole.log(\"Preimage:\", result.preimage);\n```\n\n### Boltz API Endpoints\n\n| Network | URL |\n|---------|-----|\n| Bitcoin mainnet | `https://api.ark.boltz.exchange` |\n| Mutinynet | `https://api.boltz.mutinynet.arkade.sh` |\n| Regtest (local) | `http://localhost:9069` |\n\n## Skill Classes (this package)\n\nThis package (`@arkade-os/skill`) provides higher-level wrapper classes over the SDK:\n\n```bash\nnpm install @arkade-os/skill\n```\n\n```typescript\nimport { Wallet, SingleKey } from \"@arkade-os/sdk\";\nimport {\n  ArkadeBitcoinSkill,\n  ArkaLightningSkill,\n  LendaSwapSkill,\n} from \"@arkade-os/skill\";\n\nconst wallet = await Wallet.create({\n  identity: SingleKey.fromHex(privateKeyHex),\n  arkServerUrl: \"https://arkade.computer\",\n});\n\n// Bitcoin: addresses, balances, send/receive, onboard/offboard\nconst bitcoin = new ArkadeBitcoinSkill(wallet);\nconst balance = await bitcoin.getBalance();\nawait bitcoin.send({ address: \"ark1...\", amount: 50000 });\n\n// Lightning: invoices, payments via Boltz\nconst lightning = new ArkaLightningSkill({ wallet, network: \"bitcoin\" });\nconst inv = await lightning.createInvoice({ amount: 25000 });\n\n// Stablecoin swaps: BTC <-> USDC/USDT\nconst lendaswap = new LendaSwapSkill({ wallet });\nconst quote = await lendaswap.getQuoteBtcToStablecoin(100000, \"usdc_pol\");\n```\n\n### ArkadeBitcoinSkill\n\n- `getArkAddress()` / `getBoardingAddress()` — get addresses\n- `getBalance()` — balance breakdown (offchain + onchain)\n- `send({ address, amount })` — send sats offchain\n- `getTransactionHistory()` — transaction list\n- `onboard(params)` / `offboard(params)` — onchain ramps\n- `waitForIncomingFunds(timeout?)` — wait for incoming payment\n\n### ArkaLightningSkill\n\n- `createInvoice({ amount, description? })` — Lightning invoice (reverse swap)\n- `payInvoice({ bolt11 })` — pay Lightning invoice (submarine swap)\n- `getFees()` / `getLimits()` — swap fees and limits\n- `getPendingSwaps()` / `getSwapHistory()` — swap tracking\n\n### LendaSwapSkill\n\n- `getQuoteBtcToStablecoin(amount, token)` / `getQuoteStablecoinToBtc(amount, token)`\n- `swapBtcToStablecoin(params)` / `swapStablecoinToBtc(params)`\n- `getSwapStatus(swapId)` / `getPendingSwaps()` / `getSwapHistory()`\n- `claimSwap(swapId)` / `refundSwap(swapId)`\n- `getAvailablePairs()`\n\n## Stablecoin Swaps (LendaSwap)\n\nNon-custodial BTC/stablecoin atomic swaps via HTLCs.\n\n**Supported tokens:** `usdc_pol`, `usdc_eth`, `usdc_arb`, `usdt0_pol`, `usdt_eth`, `usdt_arb`\n\n**Supported chains:** `polygon`, `ethereum`, `arbitrum`\n\n```typescript\nconst lendaswap = new LendaSwapSkill({ wallet });\n\n// Get quote\nconst quote = await lendaswap.getQuoteBtcToStablecoin(100000, \"usdc_pol\");\nconsole.log(\"You'll receive:\", quote.targetAmount, \"USDC\");\n\n// Execute swap (BTC -> USDC)\nconst swap = await lendaswap.swapBtcToStablecoin({\n  targetAddress: \"0x...\", // EVM address\n  targetToken: \"usdc_pol\",\n  targetChain: \"polygon\",\n  sourceAmount: 100000,\n});\nconsole.log(\"Swap ID:\", swap.swapId);\n\n// Check status\nconst status = await lendaswap.getSwapStatus(swap.swapId);\n\n// Claim completed swap\nconst claim = await lendaswap.claimSwap(swap.swapId);\n```\n\n## Smart Contracts\n\nArkade supports any valid Tapscript as VTXO locking conditions, enabling programmable offchain Bitcoin.\n\n```bash\nnpm install @arkade-os/sdk @scure/base\n```\n\n```typescript\nimport {\n  RestArkProvider,\n  RestIndexerProvider,\n  SingleKey,\n  VtxoScript,\n  MultisigTapscript,\n  CSVMultisigTapscript,\n} from \"@arkade-os/sdk\";\nimport { hex } from \"@scure/base\";\n\nconst arkProvider = new RestArkProvider(\"https://mutinynet.arkade.sh\");\nconst indexerProvider = new RestIndexerProvider(\"https://mutinynet.arkade.sh\");\nconst info = await arkProvider.getInfo();\nconst serverPubkey = hex.decode(info.signerPubkey).slice(1);\n```\n\n**Available contract primitives:**\n- **MultisigTapscript** — N-of-N multisig\n- **CLTVMultisigTapscript** — Multisig with absolute timelocks\n- **CSVMultisigTapscript** — Multisig with relative timelocks\n- **VtxoScript** — Combine spending paths into Taproot trees\n\n**Contract patterns in docs:** HTLC/Hashlock, Escrow (3-path), Spilman channels, Dryja-Poon channels, Lightning channels, chain swaps, Oracle DLC.\n\nUse `@scure/base` for encoding, NOT `bitcoinjs-lib`.\n\nSee: https://docs.arkadeos.com/contracts/overview\n\n## Networks & Resources\n\n| Network | Server URL | Explorer |\n|---------|-----------|----------|\n| Bitcoin mainnet | `https://arkade.computer` | https://arkade.space |\n| Mutinynet (testnet) | `https://mutinynet.arkade.sh` | https://explorer.mutinynet.arkade.sh |\n| Signet | `https://signet.arkade.sh` | https://explorer.signet.arkade.sh |\n| Regtest (local) | `http://localhost:7070` | — |\n\n**Local development:**\n\n```bash\nnigiri start --ark\n```\n\nThis starts a Bitcoin regtest node with an Arkade operator at `http://localhost:7070`.\n\n## Key Concepts\n\n- **VTXOs**: Virtual Transaction Outputs — self-custodial offchain Bitcoin coins. States: preconfirmed, settled, recoverable, spent.\n- **Batch Swaps**: How VTXOs achieve Bitcoin finality — multiple transactions batched into a single onchain settlement.\n- **Preconfirmation**: Instant confirmation cosigned by the operator, before onchain settlement.\n- **Virtual Mempool**: DAG-based offchain execution engine that processes Arkade transactions.\n- **Unilateral Exit**: Users can always withdraw their funds onchain without operator cooperation.\n- **Ark Addresses**: `ark1...` (mainnet) / `tark1...` (testnet) — bech32m-encoded addresses containing server + user keys.\n\n## Documentation\n\n- Full docs: https://docs.arkadeos.com\n- Technical primer: https://docs.arkadeos.com/primer\n- Wallet SDK v0.3: https://docs.arkadeos.com/wallets/v0.3/setup\n- Smart contracts: https://docs.arkadeos.com/contracts/overview\n- Lightning swaps: https://docs.arkadeos.com/contracts/lightning-swaps\n- LLM-friendly index: https://docs.arkadeos.com/llms.txt\n- GitHub: https://github.com/arkade-os/skill\n","tags":{"latest":"0.2.1"},"stats":{"comments":0,"downloads":625,"installsAllTime":0,"installsCurrent":0,"stars":1,"versions":1},"createdAt":1772044872094,"updatedAt":1778491640561},"latestVersion":{"version":"0.2.1","createdAt":1772044872094,"changelog":"- New SKILL.md provides a detailed guide for developing with the Arkade TypeScript SDK (@arkade-os/sdk), including Bitcoin wallet creation, Lightning integration, and stablecoin swaps.\n- Covers core concepts such as VTXOs (Virtual TXOs), offchain transactions, onboarding/offboarding, and maintaining self-custody.\n- Step-by-step instructions for installing and initializing the SDK, handling wallet operations, sending/receiving payments, and monitoring balances.\n- Documents onchain ramps, Lightning Network integration via Boltz swaps, and atomic swaps with stablecoins through LendaSwap.\n- Introduces higher-level skill classes: ArkadeBitcoinSkill, ArkaLightningSkill, and LendaSwapSkill with method overviews.\n- Serves as a comprehensive development reference for building with Arkade on Bitcoin and Lightning.","license":null},"metadata":null,"owner":{"handle":"tiero","userId":"s17dg1d4xh06w3rqgqpn2yg2398850kz","displayName":"tiero","image":"https://avatars.githubusercontent.com/u/3596602?v=4"},"moderation":null}