[0%]

26 March 2026

Spenzo

#Python#FastAPI#OpenAI#Twilio#Firebase#React#Vite#PostgreSQL#MCP (Model Context Protocol)#Vercel
Spenzo - Image 1
Source CodeLive Demo

Overview

Spenzo is a full-stack, AI-native personal finance system that goes far beyond conventional expense trackers. At its core, it is a unified natural language layer sitting across your entire financial life — from everyday chai purchases to live Ethereum wallet analytics — all accessible without leaving your preferred chat interface. Users interact with Spenzo natively through WhatsApp and Claude Desktop: just type or say what you spent, and Spenzo intelligently categorizes, logs, and stores the data. More powerfully, it bridges the gap between Web2 and Web3 finance by connecting directly to real blockchain RPCs (Alchemy for Ethereum, Helius for Solana) to give you live wallet balances, gas burn analysis, staking yield reports, and even 1-click DEX swap execution — all through a single conversational interface. The project is fully open-source, production-deployed on Render and Vercel, and includes a real-time React analytics dashboard at spenzo.xyz backed by a Supabase PostgreSQL database.

Architecture

Key Features

  • Natural Language Expense Logging — Text expenses conversationally ("Spent ₹150 on chai") and Spenzo auto-classifies the category, date, and amount, then upserts the record to the database.
  • Receipt Vision (OCR) — Send a photo of any bill or receipt on WhatsApp; GPT-4o Vision extracts the merchant, total, and date automatically and logs it for you.
  • Smart Bill Splitting — Handles "we split dinner 3 ways" logic, calculates your exact share, and logs it correctly.
  • Deep Search & Analytics — Query past expenses by keyword, date range, or category ("Did I buy coffee last month?") with natural language.
  • Ledger Management — Edit or delete past entries conversationally, e.g., "That Uber was ₹500, not ₹450."
  • Real-Time Spending Dashboard — A mobile-optimized React dashboard with spending charts, category pie charts, and full transaction history synced via Supabase real-time listeners.
  • Live Multi-Currency Crypto Ticker — Fetch live USD/INR prices via CoinGecko inside chat for accurate crypto expense logging.
  • IOU Auto-Ledger (Splitwise Killer) — Log who owes you money conversationally. Spenzo maintains an isolated "Receivables" table in the database.
  • 1-Click UPI Payment Generator — Automatically constructs upi://pay deep-link payloads and QR codes for instant debt collection without ever exposing banking credentials.
  • Live Crypto Net Worth — Connect an ETH or Solana public wallet address; Spenzo pulls real-time token balances from Alchemy/Helius RPCs and calculates fiat net worth.
  • DEX Swap Simulator & Executor — Hits the Jupiter v6 Quote API for live routing/slippage data, then generates a non-custodial 1-click swap link — all without ever touching your private key.
  • Gas Burn Analyzer — Sweeps on-chain transaction history to compute the total ETH/SOL spent on network gas fees.
  • Staking Yield Crawler — Scans for Liquid Staking Tokens (stETH, JitoSOL) and native validator accounts to report current APY and yield positions.
  • Cross-Platform Sync via OTP — Link your WhatsApp session to your Claude Desktop session securely using a Twilio-issued one-time password, unifying all financial data across devices.
  • Claude Desktop MCP Integration — Spenzo is a fully compliant Model Context Protocol (MCP) server, meaning it plugs natively into Claude Desktop as a financial tool palette with 11 registered tools. No secondary apps or UIs needed.
  • Distributable Binary — Packaged as a zero-dependency, single-file executable (spenzo-mac, spenzo-win.exe) for non-technical users, no Python environment needed.

Why I built this

I've always been frustrated that personal finance apps fall into one of two camps: either they're beautifully designed but dumb (no intelligence, just manual entry), or they're powerful but locked behind paywalls, complex setups, or inaccessible UIs. The moment I started experimenting with Anthropic's Model Context Protocol (MCP) — which lets you attach any server as a "tool" to Claude's reasoning engine — I realized I could build something genuinely different: a finance layer where the UI is literally just talking. No app to open, no form to fill. Just chat. I chose WhatsApp because that's where people actually are. Asking someone to download yet another finance app creates friction. Texting "spent 200 on lunch" to a number you've already saved? That's zero friction. The Web3 edge came from a personal pain point: crypto portfolio data is scattered across wallets, chains, and dashboards. I wanted to unify it alongside my fiat spending so I could genuinely see my complete financial picture — total net worth across crypto and fiat — in a single query. Building Spenzo taught me how to architect a real microservice system from scratch: designing asynchronous webhook flows, building a secure OTP authentication bridge between platforms, deploying containerized servers on cloud infrastructure, and creating a production-grade MCP server that other developers can extend.

Tech stack used

Python
Python
OpenAI
Firebase
Firebase
React
React
Vite
Vite
PostgreSQL
PostgreSQL
MCP (Model Context Protocol)
Vercel
Vercel

Python 3.11 + FastAPI

Core backend runtime. Both main.py (MCP server) and bot.py (WhatsApp webhook) are built as FastAPI applications for async request handling.

FastMCP

Framework used to define and expose MCP-compliant tools (add_expense, analyze_web3_wallet, etc.) that Claude Desktop can discover and call natively.

OpenAI GPT-4o / GPT-4o-mini

Powers natural language understanding in the WhatsApp bot. The OpenAI SDK is used in function-calling mode to route user intent to the correct database tool. GPT-4o Vision handles receipt image parsing.

Twilio

Provides the WhatsApp sandbox webhook. Inbound messages (text and media) hit a Twilio webhook, which forwards them to bot.py. Twilio is also used to dispatch OTP SMS/WhatsApp messages for cross-platform authentication.

Supabase (PostgreSQL)

Primary database layer. Stores expenses, IOU records, and user phone links in a managed PostgreSQL instance. The React dashboard subscribes to Supabase real-time listeners for live updates without polling.

React.js + Vite

Frontend analytics dashboard deployed on Vercel. Uses Supabase's JavaScript client to fetch and display charts, transaction logs, and spending KPIs.

Alchemy API

Ethereum RPC provider used to fetch ERC-20 token balances and on-chain transaction history for gas burn analysis.

Helius API

Solana RPC provider used to query SPL token accounts, native SOL balances, and LST (Liquid Staking Token) positions on-chain.

Jupiter v6 API

Solana DEX aggregator API used to fetch live token swap quotes, routing paths, and slippage estimates — and construct non-custodial 1-click swap execution links.

CoinGecko API

Used for fetching live USD and INR spot prices for cryptocurrencies, enabling accurate crypto expense logging.

Pyinstaller

Packages the entire Python MCP server (with all dependencies) into a single standalone binary (spenzo-mac, spenzo-win.exe) for distribution to non-technical end users.

Docker

Provides a Dockerfile for containerized deployment to cloud platforms like Render, ensuring reproducible production environments.

Render

Cloud hosting for the FastAPI backend (both the MCP SSE relay and the WhatsApp webhook bot).

Vercel

Hosts the React marketing website and analytics dashboard on a global CDN with zero-config deployment from GitHub.

uv

Modern Python package manager used for fast, reproducible dependency resolution and production environment management.

Design & Developed by Arav Arun© 2026. All rights reserved.