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.
Whether the address needs to be parsed (set to false if already formatted as URL)
Returns : WellKnown | false
LNURL callback URL for requesting invoices
Minimum sendable amount in millisatoshis
Maximum sendable amount in millisatoshis
Maximum length of comment allowed (0 if comments not supported)
JSON-encoded metadata about the recipient
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' )
}
// From api/lnaddress.ts
async function wellKnown ( lnaddress : string , needsParse : boolean = true ) {
let url : string = lnaddress
if ( needsParse ) {
const parsedLNAddress = parse . lnaddress ( lnaddress )
if ( ! parsedLNAddress ) return false
url = `https:// ${ parsedLNAddress . domain } /.well-known/lnurlp/ ${ parsedLNAddress . username } `
}
try {
const response = await fetch ( url , {
headers: { 'Content-Type' : 'application/json' },
method: 'GET'
})
const json = await response . json ()
const { data , error } = WellKnownSchema . safeParse ( json )
if ( error || ! data . callback || ! data . minSendable || ! data . maxSendable ) {
throw new Error ()
}
return {
callback: data . callback ,
minSendable: data . minSendable ,
maxSendable: data . maxSendable ,
commentAllowed: data . commentAllowed ,
metadata: data . metadata
}
} catch {
return false
}
}
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
Usage
Hook Usage
Implementation
import mempool from '@/api/mempool'
// Get current block height
const height = await mempool . getCurrentBlockHeight ()
console . log ( 'Current block height:' , height )
import { useQuery } from '@tanstack/react-query'
import mempool from '@/api/mempool'
function BlockHeightDisplay () {
const { data : blockHeight , isLoading } = useQuery ({
queryKey: [ 'blockHeight' ],
queryFn : () => mempool . getCurrentBlockHeight (),
refetchInterval: 600000 // Refetch every 10 minutes
})
return (
< div >
Current Block : { isLoading ? '...' : blockHeight }
</ div >
)
}
// From api/mempool.ts
const MEMPOOL_URL = 'https://mempool.space'
const API_URL = ` ${ MEMPOOL_URL } /api`
async function getCurrentBlockHeight () {
const response = await fetch ( ` ${ API_URL } /blocks/tip/height` )
const json = await response . json ()
const height = z . number (). parse ( json )
return 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”)
Usage
Hook Usage
Implementation
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' )
}
import { useQuery } from '@tanstack/react-query'
import github from '@/api/github'
function useLatestVersion () {
return useQuery ({
queryKey: [ 'latestVersion' ],
queryFn : () => github . getMedusaLatestRelease (),
staleTime: 3600000 , // Consider stale after 1 hour
retry: 1
})
}
function VersionChecker () {
const { data : latestVersion } = useLatestVersion ()
const currentVersion = Constants . expoConfig ?. version
const hasUpdate = latestVersion &&
latestVersion !== `v ${ currentVersion } `
return hasUpdate ? (
< UpdateNotification version = { latestVersion } />
) : null
}
// From api/github.ts
async function getMedusaLatestRelease () {
const response = await fetch (
'https://api.github.com/repos/Psycarlo/medusa-wallet/releases/latest' ,
{
headers: {
Accept: 'application/vnd.github+json'
}
}
)
const json = await response . json ()
if ( response . ok ) {
if ( ! json . tag_name ) {
throw new Error ( 'Latest release not found' )
}
return json . tag_name as string
} else {
throw new Error ( 'Latest release not found' )
}
}
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
Unique voucher identifier
Processing fee for this voucher
Whether this voucher is currently available
createTransaction()
Creates a Bitcoin purchase transaction.
Lightning address to receive the Bitcoin
Email address for purchase receipt
ID of the selected voucher
Returns : Promise<CheckoutData>
Stripe checkout URL for completing payment
Price ID for Stripe payment
Email address used for the transaction
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 )
// From api/maxfy.ts
const BASE_URL = 'https://api.maxfy.app'
const API_URL = ` ${ BASE_URL } /v1`
async function getVouchers () {
const response = await fetch ( ` ${ API_URL } /vouchersGet` , {
headers ,
method: 'GET'
})
const json = await response . json ()
const data = VouchersSchema . parse ( json )
return data . vouchers . filter (( voucher ) => voucher . active )
}
async function createTransaction (
lnaddress : string ,
email : string ,
voucherId : number
) {
const response = await fetch (
` ${ API_URL } /transactionAdd?lnaddress= ${ lnaddress } &email= ${ email } &voucher_id= ${ voucherId } ` ,
{
headers ,
method: 'POST'
}
)
const json = await response . json ()
return CheckoutSchema . parse ( json )
}
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