Try the Developer Preview

The developer preview supports three end-to-end flows: receiving a Lightning payment and paying a Lightning invoice on mainnet, and exchanging BTC for USDT on mutinynet. Lightning uses one pinned solver, reached with an addressed RFQ over Nostr. Asset exchange selects a market from the mutinynet solver registry. The solver card publishes the current limits and fee for each swap.

Every funded Lightning swap moves real bitcoin. Use small amounts. The setup below keeps the wallet and its swaps in SQLite files, so a restarted process resumes its claims and refunds.

Setup

You need Node.js 22.13 to 26, with "type": "module" in package.json. Install the SDK, the swap client, an EventSource for Node, and the Nostr transport peer dependency:

pnpm add @arkade-os/sdk @arkade-os/swap eventsource nostr-tools

Save the Lightning solver card as beta-solver.card.json beside your code. The snippets load the wallet’s mnemonic from the ARKADE_MNEMONIC environment variable. Add the two Lightning snippets below after this one, in the same file:

import { configureEventSource, MnemonicIdentity, Wallet } from '@arkade-os/sdk'
import { SQLiteContractRepository, SQLiteWalletRepository } from '@arkade-os/sdk/repositories/sqlite'
import { createSwapClient } from '@arkade-os/swap'
import { createNodeSqlExecutor, swapDatabasePath } from '@arkade-os/swap/node'
import { SQLiteAssetSwapRepository } from '@arkade-os/swap/repositories/sqlite'
import { EventSource } from 'eventsource'
import lightningCard from './beta-solver.card.json' with { type: 'json' }

configureEventSource((url) => new EventSource(url))

// One executor per database file, open for the life of the process
const walletDb = createNodeSqlExecutor('wallet.sqlite')
const swapDb = createNodeSqlExecutor(swapDatabasePath('bitcoin'))

const wallet = await Wallet.create({
  identity: MnemonicIdentity.fromMnemonic(process.env.ARKADE_MNEMONIC!),
  storage: {
    walletRepository: new SQLiteWalletRepository(walletDb),
    contractRepository: new SQLiteContractRepository(walletDb),
  },
})

const client = createSwapClient({
  wallet,
  repository: new SQLiteAssetSwapRepository(swapDb),
  discovery: { localCards: [{ card: lightningCard, network: 'bitcoin' }] },
})
await client.ready

Fund enough BTC to cover more than one test. An unresolved swap holds its funds in the contract until its cancellation or refund path becomes available, so a wallet funded for exactly one swap may be unable to start another. Receiving over Lightning, below, is the quickest way to fund the wallet.

Lightning Receive

This flow creates a Lightning invoice that pays into your Arkade wallet. amount is how many sats you receive in your Arkade wallet. The invoice asks the payer for a little more. The difference is the solver’s fee. Keep the client running while the payer pays. The client claims the payment, and the claim reveals the secret that lets the solver collect on Lightning.

const request = await client.receive({ via: 'lightning', amount: 10_000n })
console.log(request.artifact.bolt11) // pay this invoice from any Lightning wallet

client.onUpdate(({ swap, outcome }) => {
  if (swap.id === request.id) console.log(outcome)
})

The snippet prints each outcome as it changes: accepted, then open while the invoice waits for payment, then funded once the solver locks the sats for you, then claimed. claimed means the sats are in your Arkade wallet. If nobody pays before the claim window closes, the outcome is lapsed. Nothing left your wallet, so nothing comes back. If the application closes before the claim, create the client again on the next start and await client.ready. That resumes pending claims. To receive while the application is offline, see Lightning Services. To receive at a Lightning address, see LNURL and Lightning Addresses.

Pay a Lightning Invoice

Lightning send is exact-out: the invoice amount is the quote’s take, and your lockup carries the quote’s give. The client refunds automatically. If the solver does not pay the invoice, the client refunds the lockup after the quote’s refundLocktime, and the outcome is refunded. If the client is not running then, it refunds on its next start.

import { btcOn } from '@arkade-os/swap'

const invoice = 'lnbc…' // a BOLT11 invoice with an amount, inside the card's bounds

const result = await client.pay(invoice, {
  maxFee: { amount: 500n, asset: btcOn('arkade', 'bitcoin') },
})
if (result.kind !== 'swap') throw new Error('expected a swap')

client.onUpdate(({ swap, outcome }) => {
  if (swap.id === result.swap.id) console.log(outcome)
})

paid means the solver paid the invoice and claimed your lockup. The solver completes the payment without your application staying online. The card currently accepts Lightning payments from 335 to 200,000 sats and sets fee_bps: 30. A 10,000-sat invoice locks 10,031 sats; the difference between give and take is the fee.

Exchange BTC for an Asset

Asset exchange runs on mutinynet, a Bitcoin test network: the mainnet registry lists no asset market, and the mutinynet registry lists BTC/USDT. It needs a second wallet and client on mutinynet. Fund that wallet with mutinynet bitcoin: send coins from the mutinynet faucet to its boarding address, then board them (Boarding & Offboarding). The client calculates the quote from the solver card’s feed and fee, and funds the swap. This flow uses its own wallet, so put it in its own file.

Keep what you receive within the card’s bounds. With amountOn: 'give', the client does not check them. A swap outside them is funded, the solver does not fill it, and you must cancel it to get the deposit back.
The fee is charged in USDT, so maxFee names USDT in its smallest unit (2 decimals).
The client fetches the price feed itself, so it must be able to reach it. If the feed is unreachable, quoting fails before anything is funded.

import { asset, configureEventSource, MnemonicIdentity, RestArkProvider, Wallet } from '@arkade-os/sdk'
import { SQLiteContractRepository, SQLiteWalletRepository } from '@arkade-os/sdk/repositories/sqlite'
import { arkadeAsset, btcOn, createSwapClient } from '@arkade-os/swap'
import { createNodeSqlExecutor, swapDatabasePath } from '@arkade-os/swap/node'
import { SQLiteAssetSwapRepository } from '@arkade-os/swap/repositories/sqlite'
import { EventSource } from 'eventsource'

configureEventSource((url) => new EventSource(url))

const USDT_ID = 'f121ac9b7656797cc68d1e8fecacfbaa2069ec1461edf0bf2f3c37404cb9791a0000' // USDT's asset id on mutinynet

const testWalletDb = createNodeSqlExecutor('wallet-mutinynet.sqlite')
const testSwapDb = createNodeSqlExecutor(swapDatabasePath('mutinynet'))

const testWallet = await Wallet.create({
  identity: MnemonicIdentity.fromMnemonic(process.env.ARKADE_MNEMONIC!, { isMainnet: false }),
  arkProvider: new RestArkProvider('https://mutinynet.arkade.sh'),
  storage: {
    walletRepository: new SQLiteWalletRepository(testWalletDb),
    contractRepository: new SQLiteContractRepository(testWalletDb),
  },
})
console.log(await testWallet.getBoardingAddress()) // fund this from the faucet, then board

const testClient = createSwapClient({ wallet: testWallet, repository: new SQLiteAssetSwapRepository(testSwapDb) })
await testClient.ready

const USDT = arkadeAsset('mutinynet', asset.AssetId.fromString(USDT_ID))

const swap = await testClient.exchange({
  give: btcOn('arkade', 'mutinynet'),
  take: USDT,
  amount: 100_000n, // sats you give
  amountOn: 'give',
  maxFee: { amount: 50n, asset: USDT }, // 0.50 USDT
})

testClient.onUpdate((update) => {
  if (update.swap.id === swap.id) console.log(update.outcome)
})

The snippet prints each outcome as it changes. open means the swap is funded and waits for the solver. filled means the USDT is in your Arkade wallet. An unfilled swap has no fill deadline, but the virtual output that holds your deposit still expires with its batch. If the deposit stays unfilled past that, the operator sweeps it, and the swap reports needs_recovery. Recover a Swept Swap brings it back. cancel submits the cancellation without a solver signature. Keep that action available until your application sees a fill or a cancellation, because the deposit stays locked until then:

const { outcome } = await testClient.cancel(swap.id)

A cancel can race a fill. If the fill wins, cancel reports filled and does not throw.

Preview Availability

Flow	Solver selection	Current availability
Lightning receive	One pinned solver, addressed directly	Available for testing, within the card’s bounds
Lightning send	One pinned solver, addressed directly	Available for testing, within the card’s bounds
Asset exchange	Market selected from the mutinynet solver registry	Testing on mutinynet (BTC/USDT); no mainnet market is listed
Onchain payments	Market selected from the mutinynet solver registry	Testing on mutinynet only

Lightning Solver Card

The Lightning preview solver is not listed in the registry. Its signed card publishes the connection details and current terms. Save it as beta-solver.card.json and pin it with discovery.localCards.

beta-solver.card.json

{
  "version": 0,
  "name": "beta-solver",
  "discovery_pubkey": "66422c952f8dcb96e4d0c3f049cd1e265b8461b916d9913c65c2494b64b4e3ce",
  "transports": {
    "nostr": {
      "relays": ["wss://nostr.arkade.sh"]
    }
  },
  "markets": [
    {
      "base_asset": { "id": "arkade:bitcoin/slip44:0", "name": "Bitcoin", "ticker": "BTC", "decimals": 8 },
      "quote_asset": { "id": "bolt11:bitcoin/slip44:0", "name": "Bitcoin", "ticker": "BTC", "decimals": 8 },
      "fee_bps": 30,
      "min_base_amount": "335",
      "max_base_amount": "200000",
      "min_quote_amount": "335",
      "max_quote_amount": "200000"
    }
  ],
  "sig": "a3267a3bc5082d69bdbe47c6844aaa76f28e01d713217c46a61fdc265fb478aed9e971dbcab5103c1d3951ff6a2191929fcdb1334995733884bc6dfbdff22045"
}

The min_* and max_* fields are the card’s bounds, in sats: the quote fields for an invoice you pay, and the base fields for what you receive in Arkade. This card opens both directions.The card is signed, and sig covers the connection data it advertises. Pinning the card makes this solver and its advertised connection data part of the application’s trust boundary. Load the latest signed card before deployment because its limits, fee, relay, and key may change.

Lightning Payments

Request, fund, claim, and recover Lightning swaps.

Exchange Assets

Integrate asset discovery, exchange, and cancellation.

Implementation Status

Check solver, client, and route readiness.

Trust and Limitations

Review settlement guarantees, external dependencies, and recovery conditions.

Understand Intents

Build with Intents

Earn Fees

Reference

Setup

Lightning Receive

Pay a Lightning Invoice

Exchange BTC for an Asset

Preview Availability

Lightning Solver Card

Lightning Payments

Exchange Assets

Implementation Status

Trust and Limitations

​Setup

​Lightning Receive

​Pay a Lightning Invoice

​Exchange BTC for an Asset

​Preview Availability

​Lightning Solver Card

Lightning Payments

Exchange Assets

Implementation Status

Trust and Limitations

Setup

Lightning Receive

Pay a Lightning Invoice

Exchange BTC for an Asset

Preview Availability

Lightning Solver Card