Boltz Swap API

The Boltz Swap API enables seamless swaps between Lightning Network and on-chain Bitcoin. You can create submarine swaps (Lightning → on-chain), reverse swaps (on-chain → Lightning), and configure automatic reverse swaps.

Import

import lnbits from '@/api/lnbits'

All swap functions are part of the LNbits API module and require Boltz extension to be enabled on the LNbits server.

Configuration

getBoltzConfig

Retrieve Boltz service configuration including fees and limits.

const config = await lnbits.getBoltzConfig()

config

object

Boltz configuration with service limits and fees

Show properties

minimal

number

Minimum swap amount in satoshis

maximal

number

Maximum swap amount in satoshis

fees

object

Fee structure for swaps

Usage

const config = await lnbits.getBoltzConfig()

console.log(`Swap limits:`)
console.log(`  Min: ${config.minimal} sats`)
console.log(`  Max: ${config.maximal} sats`)

Submarine Swaps (Lightning → On-chain)

Submarine swaps allow you to send Lightning funds and receive on-chain Bitcoin.

createSwap

Create a submarine swap or reverse swap.

const swap = await lnbits.createSwap(data, adminkey)

data

CreateSwapData

required

Swap configuration

Show properties

walletId

string

required

ID of the wallet to use for the swap

address

string

required

Bitcoin address for receiving (reverse) or refund (submarine)

amount

number

required

Amount in satoshis

direction

'in' | 'out'

required

Swap direction: ‘in’ for submarine (Lightning → on-chain), ‘out’ for reverse (on-chain → Lightning)

amountOption

'send' | 'receive'

required

Whether amount represents what you send or receive

adminkey

string

required

Admin key of the wallet

swap

object

Created swap object with status and details

Show properties

string

Unique swap identifier

status

string

Current swap status

bip21

string

BIP21 payment URI (for submarine swaps)

address

string

Bitcoin address for payment

amount

number

Swap amount in satoshis

time

string

Creation timestamp

Submarine Swap
Reverse Swap
React Hook

// Lightning → On-chain
const swap = await lnbits.createSwap(
  {
    walletId: 'wallet_abc123',
    address: 'bc1q...',  // Your Bitcoin address
    amount: 100000,       // 100k sats
    direction: 'in',
    amountOption: 'send'
  },
  adminkey
)

console.log('Pay this invoice to complete swap:')
console.log(swap.bip21)

// On-chain → Lightning
const swap = await lnbits.createSwap(
  {
    walletId: 'wallet_abc123',
    address: 'bc1q...',  // Refund address
    amount: 100000,       // 100k sats
    direction: 'out',
    amountOption: 'receive'
  },
  adminkey
)

console.log('Send Bitcoin to:')
console.log(swap.address)

import useCreateSwap from '@/hooks/mutation/useCreateSwap'

function SwapComponent({ adminkey }) {
  const createSwap = useCreateSwap(adminkey)

  const handleCreateSwap = () => {
    createSwap.mutate({
      walletId: 'wallet_abc123',
      address: 'bc1q...',
      amount: 100000,
      direction: 'in',
      amountOption: 'send'
    })
  }

  return (
    <button 
      onClick={handleCreateSwap}
      disabled={createSwap.isPending}
    >
      Create Swap
    </button>
  )
}

Swap Management

listSwaps

Retrieve all submarine swaps (Lightning → on-chain) for the user.

const swaps = await lnbits.listSwaps(adminkey)

adminkey

string

required

Admin key with permission to view swaps across all wallets

swaps

array

Array of submarine swap objects

listReverseSwaps

Retrieve all reverse swaps (on-chain → Lightning) for the user.

const swaps = await lnbits.listReverseSwaps(adminkey)

adminkey

string

required

Admin key with permission to view swaps across all wallets

swaps

array

Array of reverse swap objects

Usage
React Hook

const [submarine, reverse] = await Promise.all([
  lnbits.listSwaps(adminkey),
  lnbits.listReverseSwaps(adminkey)
])

console.log(`Submarine swaps: ${submarine.length}`)
console.log(`Reverse swaps: ${reverse.length}`)

import useSwaps from '@/hooks/query/useSwaps'

function SwapsComponent({ adminkey }) {
  const { data: swaps, isLoading } = useSwaps(adminkey)

  if (isLoading) return <Loading />

  return (
    <ul>
      {swaps?.map(swap => (
        <li key={swap.id}>
          {swap.amount} sats - {swap.status}
        </li>
      ))}
    </ul>
  )
}

Auto Swaps

Automatic reverse swaps allow you to automatically convert incoming Lightning payments to on-chain Bitcoin when your wallet balance exceeds a threshold.

createAutoSwap

Configure automatic reverse swaps for a wallet.

const autoSwap = await lnbits.createAutoSwap(data, adminkey)

data

CreateAutoSwapData

required

Auto-swap configuration

Show properties

walletId

string

required

ID of the wallet to configure

amount

number

required

Balance threshold in satoshis that triggers the auto-swap

address

string

required

Bitcoin address to receive swapped funds

adminkey

string

required

Admin key of the wallet

autoSwap

object

Created auto-swap configuration

Show properties

string

Unique auto-swap configuration ID

balance

number

Balance threshold in satoshis

onchain_address

string

Destination Bitcoin address

Usage
React Hook

// Auto-swap when balance exceeds 500k sats
const autoSwap = await lnbits.createAutoSwap(
  {
    walletId: 'wallet_abc123',
    amount: 500000,
    address: 'bc1q...'
  },
  adminkey
)

console.log('Auto-swap configured')
console.log(`Trigger: ${autoSwap.balance} sats`)
console.log(`Destination: ${autoSwap.onchain_address}`)

import useCreateAutoSwap from '@/hooks/mutation/useCreateAutoSwap'

function AutoSwapComponent({ adminkey }) {
  const createAutoSwap = useCreateAutoSwap(adminkey)

  const handleCreate = () => {
    createAutoSwap.mutate({
      walletId: 'wallet_abc123',
      amount: 500000,
      address: 'bc1q...'
    })
  }

  return <button onClick={handleCreate}>Enable Auto-Swap</button>
}

listAutoReverseSwaps

Retrieve all configured auto-swap settings.

const autoSwaps = await lnbits.listAutoReverseSwaps(adminkey)

adminkey

string

required

Admin key with permission to view auto-swaps across all wallets

autoSwaps

array

Array of auto-swap configuration objects

Usage
React Hook

const autoSwaps = await lnbits.listAutoReverseSwaps(adminkey)

autoSwaps.forEach(config => {
  console.log(`Wallet: ${config.wallet}`)
  console.log(`Threshold: ${config.balance} sats`)
  console.log(`Address: ${config.onchain_address}`)
})

import useAutoSwaps from '@/hooks/query/useAutoSwaps'

function AutoSwapsComponent({ adminkey }) {
  const { data: autoSwaps } = useAutoSwaps(adminkey)

  return (
    <ul>
      {autoSwaps?.map(config => (
        <li key={config.id}>
          Threshold: {config.balance} sats
        </li>
      ))}
    </ul>
  )
}

deleteAutoSwap

Remove an auto-swap configuration.

await lnbits.deleteAutoSwap(id, adminkey)

string

required

Auto-swap configuration ID to delete

adminkey

string

required

Admin key of the wallet

Usage
React Hook

await lnbits.deleteAutoSwap('config_id_123', adminkey)
console.log('Auto-swap disabled')

import useDeleteAutoSwap from '@/hooks/mutation/useDeleteAutoSwap'

function DeleteAutoSwapButton({ id, adminkey }) {
  const deleteAutoSwap = useDeleteAutoSwap(adminkey)

  return (
    <button onClick={() => deleteAutoSwap.mutate(id)}>
      Disable Auto-Swap
    </button>
  )
}

Swap Types Explained

Submarine Swaps (Lightning → On-chain)

Create a submarine swap with direction: 'in'
Pay the Lightning invoice provided in the response
Receive on-chain Bitcoin at your specified address
Use for: Cashing out to on-chain, cold storage, exchanges

Reverse Swaps (On-chain → Lightning)

Create a reverse swap with direction: 'out'
Send on-chain Bitcoin to the provided address
Receive Lightning funds in your wallet
Use for: Topping up Lightning wallet, instant liquidity

Auto Swaps

Configure auto-swap with a balance threshold
Automatically triggered when wallet balance exceeds threshold
Converts excess Lightning balance to on-chain Bitcoin
Use for: Automatic treasury management, risk reduction

Best Practices

Fee Awareness

const config = await lnbits.getBoltzConfig()

// Check fees before creating swap
const swapAmount = 100000
if (swapAmount < config.minimal || swapAmount > config.maximal) {
  throw new Error('Amount outside allowed range')
}

Error Handling

try {
  const swap = await lnbits.createSwap(data, adminkey)
  console.log('Swap created:', swap.id)
} catch (error) {
  console.error('Swap failed:', error.message)
  // Handle insufficient balance, invalid address, etc.
}

Monitoring Swaps

// Poll swap status
const checkSwapStatus = async () => {
  const swaps = await lnbits.listSwaps(adminkey)
  const pendingSwaps = swaps.filter(s => s.status === 'pending')
  
  console.log(`${pendingSwaps.length} swaps pending`)
}

// Check every 30 seconds
setInterval(checkSwapStatus, 30000)

See /api/lnbits for payment and wallet management functions
Swap fees are paid from the swap amount automatically
All swaps use instant settlement for reverse swaps when enabled

Developer Guide

API Reference

Components

Import

Configuration

getBoltzConfig

Submarine Swaps (Lightning → On-chain)

createSwap

Swap Management

listSwaps

listReverseSwaps

Auto Swaps

createAutoSwap

listAutoReverseSwaps

deleteAutoSwap

Swap Types Explained

Submarine Swaps (Lightning → On-chain)

Reverse Swaps (On-chain → Lightning)

Auto Swaps

Best Practices

Fee Awareness

Error Handling

Monitoring Swaps

Build docs developers (and LLMs) love

Developer Guide

API Reference

Components

​Import

​Configuration

​getBoltzConfig

​Submarine Swaps (Lightning → On-chain)

​createSwap

​Swap Management

​listSwaps

​listReverseSwaps

​Auto Swaps

​createAutoSwap

​listAutoReverseSwaps

​deleteAutoSwap

​Swap Types Explained

​Submarine Swaps (Lightning → On-chain)

​Reverse Swaps (On-chain → Lightning)

​Auto Swaps

​Best Practices

​Fee Awareness

​Error Handling

​Monitoring Swaps

​Related

Build docs developers (and LLMs) love

Import

Configuration

getBoltzConfig

Submarine Swaps (Lightning → On-chain)

createSwap

Swap Management

listSwaps

listReverseSwaps

Auto Swaps

createAutoSwap

listAutoReverseSwaps

deleteAutoSwap

Swap Types Explained

Submarine Swaps (Lightning → On-chain)

Reverse Swaps (On-chain → Lightning)

Auto Swaps

Best Practices

Fee Awareness

Error Handling

Monitoring Swaps

Related