BTC Real-World Converter

GitHub Repo | Live Demo | Updated: July 27, 2025

A comprehensive web application that converts Bitcoin (BTC) and Satoshis (sats) to real-world goods and services using live market prices. Features bidirectional conversion, historical price charts, and multiple data sources for accurate pricing.

Technologies: Python, FastAPI, JavaScript (Vanilla), HTML5, CSS3, CanvasJS

APIs: CoinGecko, Federal Reserve (FRED), Alpha Vantage, Bureau of Labor Statistics (BLS)

Deployment: Vercel

License: Apache License 2.0

Role: Creator & Full-Stack Developer

Project Overview:

The BTC Real-World Converter transforms abstract Bitcoin values into tangible, understandable quantities by showing how much Bitcoin can buy in terms of everyday items. The application provides real-time conversions across multiple categories including food, energy, commodities, housing, and entertainment.

Core Features:

  • Real-Time Conversion: Live BTC to goods conversion using current market prices
  • Bidirectional Conversion: Convert BTC → Items or Items → BTC with seamless switching
  • Unit Flexibility: Toggle between BTC and Satoshis (sats) for precision
  • Historical Charts: Interactive price charts for CPI items with custom date ranges
  • Multiple Categories: 15+ items across Food, Energy, Commodities, Housing, Transportation, and Entertainment
  • Mobile-Responsive: Optimized for both desktop and mobile experiences
  • Real-Time Data: Multiple API integrations for accurate, up-to-date pricing

Technical Architecture:

Backend (FastAPI):

  • Async API Design: Non-blocking concurrent requests for optimal performance
  • Multiple Data Sources: CoinGecko (Bitcoin), FRED (economic data), Alpha Vantage (commodities), BLS (labor statistics)
  • Smart Caching: 5-minute BTC price cache to reduce API calls and improve response times
  • Error Handling: Graceful fallbacks with hardcoded prices when APIs fail
  • Decimal Precision: Proper decimal handling for financial calculations
  • Pydantic Validation: Type-safe request/response models

Frontend (Vanilla JavaScript):

  • Debounced Inputs: 300ms delay to reduce unnecessary API calls
  • Interactive Charts: CanvasJS integration for historical data visualization
  • Toast Notifications: User-friendly error and success messaging
  • Dynamic UI: Real-time updates without page refreshes
  • Responsive Design: Mobile-first CSS with desktop enhancements
  • Loading States: Visual feedback during API requests

Data Integration:

Live Price Sources:

  • Bitcoin Price: CoinGecko API (no authentication required)
  • Oil Prices: Alpha Vantage API (WTI Crude Oil spot prices)
  • Precious Metals: Alpha Vantage currency exchange rates (USD/XAU for Gold, USD/XAG for Silver)
  • Natural Gas: Alpha Vantage API (Henry Hub spot prices)
  • Economic Indicators: Federal Reserve Economic Data (FRED) for CPI items
  • Labor Statistics: Bureau of Labor Statistics (BLS) for gasoline prices

Historical Support:

Items with historical chart capabilities: - Bread, Milk, Coffee, Eggs (FRED CPI data) - Gasoline (BLS historical data) - Median Home Price (FRED housing data) - New Car Price (FRED transportation data)

Available Conversion Items:

Food Category: - Bread (loaf), Milk (gallon), Coffee (pound), Eggs (dozen), Big Mac (burger)

Energy Category: - Oil (barrel), Natural Gas (MMBtu), Gasoline (gallon)

Commodities Category: - Gold (ounce), Silver (ounce)

Housing Category: - Median Home (house)

Transportation Category: - New Car (car), Uber Ride (ride)

Entertainment Category: - Netflix (month), Spotify (month), Movie Ticket (ticket)

API Endpoints:

  • GET /api/convert: Bidirectional conversion between BTC and items
  • GET /api/items: Available items grouped by category
  • GET /api/historical: Historical price data for chart generation

Performance Optimizations:

  • Lean Architecture: No heavy frameworks, optimized for speed
  • Concurrent Requests: Async/await for parallel API calls
  • Smart Fallbacks: Hardcoded prices when external APIs fail
  • Efficient Caching: Reduces redundant API calls
  • Debounced User Input: Prevents excessive API requests
  • Responsive Design: Optimized for all device sizes

Deployment & DevOps:

  • Vercel Deployment: Serverless deployment with automatic scaling
  • Environment Management: Secure API key handling
  • Zero-Downtime Deployment: Git-based deployment pipeline
  • Error Monitoring: Comprehensive error handling and logging

User Experience:

Conversion Interface: - Clean, intuitive design with clear input/output sections - Real-time conversion as users type - Unit toggle (BTC/sats) with automatic value conversion - Bidirectional swap button for easy conversion direction changes

Historical Analysis: - Interactive charts with custom date range selection - Automatic chart updates when date ranges change - Visual price trends for supported CPI items - Educational context about Bitcoin's purchasing power over time

Educational Value:

The application serves as an educational tool demonstrating: - Bitcoin's real-world purchasing power - Historical price trends and inflation context - Economic data visualization - Cryptocurrency adoption and utility

Technical Highlights:

  • API-First Design: Clean separation between backend data processing and frontend presentation
  • Financial Precision: Proper decimal handling for accurate monetary calculations
  • Scalable Architecture: Designed for easy addition of new items and data sources
  • Error Resilience: Graceful degradation when external services are unavailable
  • Modern Web Standards: Progressive enhancement and accessibility considerations

This project demonstrates practical application of financial APIs, real-time data processing, and user-centered design in the cryptocurrency space.