Skip to main content
Medusa Wallet provides a comprehensive set of API functions for building Lightning Network applications. The API is organized into four main modules:

​
API Modules

LNbits API

Authentication, wallet management, payments, and invoices

Medusa Pricing API

Historical Bitcoin price data and fiat conversions

Boltz Swap API

Lightning to on-chain swaps via Boltz

Utility APIs

Lightning address resolution, blockchain data, and release management

​
Getting Started

The Medusa Wallet API is built on top of LNbits and provides additional functionality for pricing and swaps. All API functions are available through the imported modules: 
import lnbits from '@/api/lnbits'
import medusa from '@/api/medusa'

​
Base URL

The default base URL for the LNbits API is: 
https://wallet.medusa.bz
You can configure a custom LNbits URL using the settings store: 
import { useSettingsStore } from '@/store/settings'

const lnbitsUrl = useSettingsStore.getState().lnbitsUrl

​
Authentication

Most API endpoints require authentication using one of three key types:
​
accessToken
string
User session token obtained from register() or login()
​
adminkey
string
Wallet admin key for privileged operations (payments, wallet management)
​
inkey
string
Wallet invoice key for read operations (viewing payments, creating invoices)

​
React Hooks

Medusa Wallet provides React Query hooks for all API functions:

​
Query Hooks

  • useUser(accessToken) - Fetch user data and wallets
  • usePayments(inkeys, enabled) - Fetch payment history
  • usePaginatedPayments(...) - Fetch paginated payments
  • useSwaps(adminkey) - Fetch swap history
  • useAutoSwaps(adminkey) - Fetch auto-swap configurations
  • usePaylinks(inkey) - Fetch LNURL paylinks

​
Mutation Hooks

  • useCreateInvoice(inkey, amount, memo) - Create Lightning invoice
  • usePay(adminkey) - Pay Lightning invoice or LNURL
  • useCreateSwap(adminkey) - Create Boltz swap
  • useCreateAutoSwap(adminkey) - Create auto-swap configuration
  • useDeleteAutoSwap(adminkey) - Delete auto-swap

​
Error Handling

All API functions throw errors with descriptive messages. Use try/catch blocks or React Query’s error handling: 
try {
  const user = await lnbits.getUser(accessToken)
} catch (error) {
  console.error(error.message)
}

​
TypeScript Support

All API functions are fully typed with TypeScript. Import types from the API modules: 
import type { PayData, CreateSwapData, CreateAutoSwapData } from '@/api/lnbits'
import type { FiatSnapshot } from '@/types/fiat'

​
Next Steps

LNbits API

Explore authentication and payment functions

Medusa Pricing API

Learn about historical price lookups

Boltz Swap API

Integrate Lightning swaps

Utility APIs

Lightning address, blockchain data, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us