Medusa Pricing API

The Medusa Pricing API provides access to historical Bitcoin price data across multiple fiat currencies. This is essential for calculating the fiat value of Bitcoin transactions at the time they occurred.

Import

import medusa from '@/api/medusa'

Configuration

The Medusa API uses the following base URL and credentials:

const BASE_URL = 'https://api.medusa.bz'
const API_URL = `${BASE_URL}/v1`

Authentication is handled automatically with Basic Auth credentials embedded in the API client.

Functions

getBitcoinPricesAt

Retrieve Bitcoin prices in all supported fiat currencies at a specific timestamp.

const prices = await medusa.getBitcoinPricesAt(timestamp)

timestamp

number

required

Unix timestamp in milliseconds

prices

FiatSnapshot

Object containing Bitcoin prices in multiple fiat currencies

Show supported currencies

USD

number

Price in US Dollars

EUR

number

Price in Euros

GBP

number

Price in British Pounds

JPY

number

Price in Japanese Yen

AUD

number

Price in Australian Dollars

CAD

number

Price in Canadian Dollars

CHF

number

Price in Swiss Francs

CNY

number

Price in Chinese Yuan

Usage
Response Example
With Payment

import medusa from '@/api/medusa'

// Get Bitcoin prices from January 1, 2024
const timestamp = new Date('2024-01-01').getTime()
const prices = await medusa.getBitcoinPricesAt(timestamp)

console.log(`BTC price on Jan 1, 2024:`)
console.log(`  USD: $${prices.USD}`)
console.log(`  EUR: €${prices.EUR}`)
console.log(`  GBP: £${prices.GBP}`)

{
  "USD": 44156.78,
  "EUR": 39842.31,
  "GBP": 34521.45,
  "JPY": 6234567.89,
  "AUD": 65432.10,
  "CAD": 58765.43,
  "CHF": 37654.32,
  "CNY": 312345.67
}

// Get historical price for a payment
const payment = {
  timestamp: new Date('2024-01-15').getTime(),
  sats: 10000
}

const prices = await medusa.getBitcoinPricesAt(payment.timestamp)
const SATOSHIS_IN_BITCOIN = 100_000_000

const btcAmount = payment.sats / SATOSHIS_IN_BITCOIN
const usdValue = btcAmount * prices.USD

console.log(`10,000 sats = $${usdValue.toFixed(2)}`)

getPricesAt

Calculate the fiat value of a specific satoshi amount at a historical timestamp.

const fiatValues = await medusa.getPricesAt(sats, timestamp)

sats

number

required

Amount in satoshis to convert

timestamp

number

required

Unix timestamp in milliseconds

fiatValues

FiatSnapshot

Object containing the satoshi amount converted to multiple fiat currencies at the historical rate

Usage
Response Example
Transaction History

import medusa from '@/api/medusa'

// Convert 50,000 sats to fiat at a specific date
const sats = 50000
const timestamp = new Date('2024-01-01').getTime()
const fiatValues = await medusa.getPricesAt(sats, timestamp)

console.log(`50,000 sats on Jan 1, 2024:`)
console.log(`  USD: $${fiatValues.USD}`)
console.log(`  EUR: €${fiatValues.EUR}`)
console.log(`  GBP: £${fiatValues.GBP}`)

{
  "USD": 22.08,
  "EUR": 19.92,
  "GBP": 17.26,
  "JPY": 3117.28,
  "AUD": 32.72,
  "CAD": 29.38,
  "CHF": 18.83,
  "CNY": 156.17
}

// Calculate fiat values for transaction history
const transactions = [
  { id: '1', sats: 10000, timestamp: 1704067200000 },
  { id: '2', sats: 25000, timestamp: 1704153600000 },
  { id: '3', sats: 50000, timestamp: 1704240000000 }
]

const enrichedTransactions = await Promise.all(
  transactions.map(async (tx) => {
    const fiatValues = await medusa.getPricesAt(tx.sats, tx.timestamp)
    return {
      ...tx,
      fiatValues
    }
  })
)

enrichedTransactions.forEach((tx) => {
  console.log(`Transaction ${tx.id}:`)
  console.log(`  ${tx.sats} sats = $${tx.fiatValues.USD}`)
})

Use Cases

Payment History with Fiat Values

The Medusa API is used throughout Medusa Wallet to display historical fiat values for Lightning payments:

import lnbits from '@/api/lnbits'
import medusa from '@/api/medusa'
import { SATOSHIS_IN_BITCOIN } from '@/constants/btc'

// Fetch payments
const payments = await lnbits.getPayments(inkey)

// Each payment already includes fiatSnapshot from Medusa API
payments.forEach(payment => {
  console.log(`Payment: ${payment.sats} sats`)
  console.log(`Value at time: $${payment.fiatSnapshot.USD}`)
})

Price Snapshot Caching

The LNbits API automatically batches and caches Medusa price requests to optimize performance:

import { getHistoricalPricesMap } from '@/utils/medusa'

// Group payments by rounded timestamps
const historicalPricesMap = getHistoricalPricesMap(
  payments.map((payment) => ({
    id: payment.payment_hash,
    timestamp: new Date(payment.time).getTime()
  }))
)

// Fetch prices once per unique timestamp
for (const [timestamp, ids] of Object.entries(historicalPricesMap)) {
  const fiatSnapshot = await medusa.getBitcoinPricesAt(Number(timestamp))
  // Use fiatSnapshot for all payments in this timestamp bucket
}

Display Historical Values

Show users how much their Lightning transactions were worth at the time:

import medusa from '@/api/medusa'
import { SATOSHIS_IN_BITCOIN } from '@/constants/btc'

function formatHistoricalValue(sats: number, timestamp: number) {
  const fiatValues = await medusa.getPricesAt(sats, timestamp)
  const date = new Date(timestamp).toLocaleDateString()

  return `${sats} sats (${date}): $${fiatValues.USD.toFixed(2)}`
}

const payment = {
  sats: 21000,
  timestamp: new Date('2024-01-15').getTime()
}

console.log(await formatHistoricalValue(payment.sats, payment.timestamp))
// Output: 21000 sats (1/15/2024): $9.25

Data Accuracy

Historical prices are sourced from reliable cryptocurrency exchanges
Prices are available for dates going back to Bitcoin’s inception
Timestamps are automatically rounded to optimize caching
All prices are returned as floating-point numbers with full precision

Error Handling

The Medusa API uses Zod schema validation for all responses:

import { TimestampPriceSchema } from '@/schemas/medusa'

try {
  const prices = await medusa.getBitcoinPricesAt(timestamp)
} catch (error) {
  // Invalid timestamp or API error
  console.error('Failed to fetch prices:', error)
}

The LNbits API automatically integrates Medusa prices for payment history
See /api/lnbits for payment-related functions that use Medusa data
Historical price caching is managed by the fiat store

Developer Guide

API Reference

Components

Import

Configuration

Functions

getBitcoinPricesAt

getPricesAt

Use Cases

Payment History with Fiat Values

Price Snapshot Caching

Display Historical Values

Data Accuracy

Error Handling

Build docs developers (and LLMs) love

Developer Guide

API Reference

Components

​Import

​Configuration

​Functions

​getBitcoinPricesAt

​getPricesAt

​Use Cases

​Payment History with Fiat Values

​Price Snapshot Caching

​Display Historical Values

​Data Accuracy

​Error Handling

​Related

Build docs developers (and LLMs) love

Import

Configuration

Functions

getBitcoinPricesAt

getPricesAt

Use Cases

Payment History with Fiat Values

Price Snapshot Caching

Display Historical Values

Data Accuracy

Error Handling

Related