Skip to main content

Overview

Medusa Wallet includes several utility API modules that provide additional functionality beyond core payment operations. These include Lightning address resolution, blockchain data from Mempool.space, and GitHub release checking.

Lightning Address API

The Lightning Address API resolves Lightning addresses (e.g., [email protected]) to LNURL endpoints.

wellKnown()

Fetches the LNURL endpoint and payment information for a Lightning address.
lnaddress
string
required
The Lightning address to resolve (e.g., “[email protected]”)
needsParse
boolean
default:true
Whether the address needs to be parsed (set to false if already formatted as URL)
Returns: WellKnown | false
import lnaddress from '@/api/lnaddress'

// Resolve a Lightning address
const wellKnown = await lnaddress.wellKnown('[email protected]')

if (wellKnown) {
  console.log('Callback URL:', wellKnown.callback)
  console.log('Min sendable:', wellKnown.minSendable / 1000, 'sats')
  console.log('Max sendable:', wellKnown.maxSendable / 1000, 'sats')
  console.log('Comments allowed:', wellKnown.commentAllowed, 'chars')
} else {
  console.log('Invalid or unreachable Lightning address')
}
This API follows the LNURL-pay specification (LUD-06) for Lightning address resolution.

Mempool API

Integration with Mempool.space API for Bitcoin blockchain data.

getCurrentBlockHeight()

Fetches the current Bitcoin blockchain tip height. Returns: Promise<number> - The current block height
import mempool from '@/api/mempool'

// Get current block height
const height = await mempool.getCurrentBlockHeight()
console.log('Current block height:', height)
The Mempool.space API is used for on-chain Bitcoin data. Block height is useful for swap operations and blockchain confirmations.

GitHub API

Integration with GitHub API for release management and version checking.

getMedusaLatestRelease()

Fetches the latest release version tag from the Medusa Wallet GitHub repository. Returns: Promise<string> - The latest release tag (e.g., “v0.3.0”)
import github from '@/api/github'

// Check for latest version
try {
  const latestVersion = await github.getMedusaLatestRelease()
  console.log('Latest version:', latestVersion)
  
  // Compare with current version
  const currentVersion = 'v0.3.0' // From app version
  if (latestVersion !== currentVersion) {
    console.log('New version available!')
  }
} catch (error) {
  console.error('Failed to fetch latest release')
}
The GitHub API has rate limits for unauthenticated requests (60 requests per hour). Consider caching the result and implementing appropriate retry logic.

Maxfy API

Integration with Maxfy for Bitcoin purchase functionality.

getVouchers()

Fetches available active Bitcoin purchase vouchers. Returns: Promise<Voucher[]> - Array of active vouchers
Voucher
object

createTransaction()

Creates a Bitcoin purchase transaction.
lnaddress
string
required
Lightning address to receive the Bitcoin
email
string
required
Email address for purchase receipt
voucherId
number
required
ID of the selected voucher
Returns: Promise<CheckoutData>
CheckoutData
object
import maxfy from '@/api/maxfy'

// Fetch available vouchers
const vouchers = await maxfy.getVouchers()
console.log('Available vouchers:', vouchers)

// Create purchase transaction
const transaction = await maxfy.createTransaction(
  '[email protected]',
  '[email protected]',
  vouchers[0].id
)

// Open checkout URL
window.open(transaction.checkout_url)
The Maxfy API is authenticated using basic auth credentials. The credentials are embedded in the source code for the Medusa-specific integration.

Buy Bitcoin Feature

Learn how to buy Bitcoin in the app

Lightning Address

Understanding Lightning addresses

LNbits API

Core Lightning wallet operations

Swap API

Bitcoin swap operations

Build docs developers (and LLMs) love