Spenzo : The Omni-Chain Financial Superpower

Spenzo is an advanced, Omni-Chain Financial Superpower. It doesn't just track your fiat expenses: it operates as a consolidated NLP layer to manage your wealth. Monitor live Web3 portfolios, simulate advanced DEX routing quotes, and extract invoice metadata entirely through programmatic chat integrations natively inside WhatsApp and Claude Desktop.

Website: spenzo.xyz

---

Features

• WhatsApp Native: Text your expenses naturally ("Spent ₹150 on chai"). Spenzo auto-categorizes and logs them instantly.
• Receipt Vision: Snap a photo of a bill or receipt on WhatsApp. Spenzo extracts the merchant, total, and date automatically using GPT-4o.
• Smart Bill Splitting: "Dinner was 3000 but we split it 3 ways." Spenzo handles the math and logs your exact share.
• Live Crypto Prices: Built-in real-time CoinGecko integration. Ask "What's the price of SOL?" to log crypto purchases accurately.
• Claude Desktop Integration: Use Spenzo as a native MCP (Model Context Protocol) tool inside Claude for hands-free financial management.
• Instant Summaries: Ask "How much did I spend on food this week?" and Spenzo computes category breakdowns on the fly — right inside Claude or WhatsApp.
• Cross-Platform Sync: Securely link your WhatsApp number to your desktop session via OTP so all your financial data is unified.

---

Architecture

Spenzo uses a modern, serverless-friendly microservice architecture:

flowchart TD
    %% ── Client Layer ──
    WA["📱 WhatsApp User"] <-->|"Text · Receipts · Images"| TW["Twilio WhatsApp API"]
    CD["🖥️ Claude Desktop"] <-->|"FastMCP Protocol<br/>(stdio / SSE)"| MCP

    %% ── WhatsApp Pipeline ──
    TW -->|"POST /webhook"| BOT["bot.py<br/>FastAPI Webhook Server"]
    BOT -->|"Reply Message"| TW
    BOT <-->|"Chat Completions<br/>+ Tool Use"| LLM(("GPT-4o-mini<br/>+ Vision"))
    BOT <-->|"stdio subprocess<br/>(MCP Client → Server)"| MCP["main.py<br/>FastMCP Server · 16 Tools"]

    %% ── Database ──
    MCP <-->|"CRUD · IOUs · OTP Auth"| DB[("Supabase<br/>PostgreSQL")]

    %% ── External APIs ──
    MCP -->|"Live Prices"| CB["Coinbase · CoinGecko"]
    MCP -->|"Wallet · Gas · Staking"| W3["Alchemy · Helius · Blockscout"]
    MCP -->|"Swap Routing"| JUP["Jupiter v6 DEX"]
    MCP -->|"Payment Links"| UPI["UPI Intent + QR Generator"]
    MCP -.->|"OTP Delivery"| TW

    %% ── Styles ──
    classDef client fill:#a7dd5d,stroke:#000,stroke-width:2px,color:#000
    classDef infra fill:#1c1c1c,stroke:#fff,stroke-width:1px,color:#fff
    classDef ai fill:#6c47ff,stroke:#fff,stroke-width:2px,color:#fff
    classDef db fill:#3ECF8E,stroke:#000,stroke-width:2px,color:#000
    classDef api fill:#2d2d2d,stroke:#555,stroke-width:1px,color:#ccc

    class WA,CD client
    class TW,BOT,MCP infra
    class LLM ai
    class DB db
    class CB,W3,JUP,UPI api

---

QuickStart Guide

1. Try the WhatsApp Bot

1. Message +1 (415) 523-8886 on WhatsApp.
2. Send the exact phrase join conversation-heading to enter the secure Twilio sandbox.
3. Say "Hi" to see what Spenzo can do!
4. Ask "How much did I spend this week?" for an instant summary.

Note: The backend sleeps on Render's free tier. Your very first message might take ~45 seconds while the server wakes up. Consecutive messages are instant.

2. Connect to Claude Desktop (3 Options)

Since Spenzo is an MCP Server, it must attach to a client like Claude Desktop. Choose the right method for you:

1. Download the App for Mac/Windows (No Coding Required)

You can run Spenzo as a single, zero-dependency executable. No source code or environment setup required.

1. Download the compiled binary for your platform from the latest GitHub Release:
   • 👉 Download for Mac
   • 👉 Download for Windows
2. Edit your claude_desktop_config.json:

   "mcpServers": {
     "spenzo": {
       "command": "/Users/YOUR_NAME/Desktop/spenzo-mac",
       "env": { "SUPABASE_URL": "...", "SUPABASE_KEY": "..." }
     }
   }
   

2. Cloud API (Zero Local Compute)

Spenzo's main.py detects cloud environments automatically and starts a Server-Sent Events (SSE) listener.

1. Run Spenzo on Render/AWS.
2. Download the tiny sse_relay.py connection script to your Desktop.
3. Edit your claude_desktop_config.json:

   "mcpServers": {
     "spenzo-cloud": {
       "command": "python",
       "args": ["/Users/YOUR_NAME/Desktop/sse_relay.py", "https://YOUR-RENDER-URL.onrender.com/sse"]
     }
   }
   

3. From Source (For Developers)

Prerequisites: Python 3.11+ and the uv package manager.

1. Clone & Install:

   git clone https://github.com/Arav-Arun/Spenzo.git
   cd Spenzo
   uv sync
   

2. Environment Variables: Create a .env file in the root directory:

   SUPABASE_URL="https://your-project.supabase.co"
   SUPABASE_KEY="your-service-role-key"
   OPENAI_API_KEY="sk-..."
   TWILIO_ACCOUNT_SID="ACxxx..."
   TWILIO_AUTH_TOKEN="your-auth-token"
   TWILIO_WHATSAPP_NUMBER="whatsapp:+14155238886"
   ALCHEMY_API_KEY="your-alchemy-key"
   HELIUS_API_KEY="your-helius-key"
   

3. Link to Claude Desktop: Open your Claude Desktop config file and add:

   {
     "mcpServers": {
       "spenzo": {
         "command": "uv",
         "args": ["run", "fastmcp", "run", "/ABSOLUTE/PATH/TO/Spenzo/server/main.py"]
       }
     }
   }
   

   Restart Claude, and you can now ask Claude to manage your expenses!

---

Available MCP Tools

Developers can utilize the following database tools via server/main.py:

Tool	Description
add_expense	Log a new expense (date, amount, category, subcategory, note).
list_expenses	Fetch chronological expense entries within a date range.
summarize	Generate category-based spending totals and breakdowns.
search_expenses	Keyword search across all categories, subcategories, or notes.
edit_expense / delete_expense	Modify or remove specific transaction rows securely.
get_crypto_price	Fetch live USD/INR prices for seamless crypto logging.
register_phone / verify_phone	Issue and verify Twilio OTPs to securely bridge platforms.

---

The Web3 Edge (Advanced MCP Tools)

Spenzo seamlessly acts as a Bloomberg Terminal for personal crypto wallets, pulling live data from Alchemy (Ethereum) and Helius (Solana) RPCs.

Whenever you provide a public Web3 wallet (0x... or base58), Spenzo exposes 4 powerful analytical tools:

Web3 Tool	Capabilities
analyze_web3_wallet	Scans an ETH/SOL wallet to pull real-time token balances and fiat Net Worth.
simulate_dex_swap	Hits DEX aggregators (Jupiter/Uniswap) to quote trades and slippage.
analyze_gas_burn	Sweeps strictly on-chain transactions via Helius/Etherscan to compute real gas fees.
check_staking_yield	Scans for LST balances (stETH, JitoSOL) and native validator staking rewards.

---

Spenzo securely transitions from a read-only intelligence layer to an active Execution tool. By dynamically constructing deep-link payloads, Spenzo handles complex routing and computation in the background, then hands you a 1-click confirmation prompt without ever requesting access to your private keys or banking credentials.

Execution Tool	Action & Routing Mechanism
simulate_dex_swap	Hits Jupiter v6 Quote API to format exact 1-Click Transaction Execution links.
generate_upi_payment_link	Constructs upi://pay intent payloads and dynamic QR codes for 1-click fiat drops.
log_debt / list_debts	Serves as an isolated IOU ledger, natively returning auto-generated UPI collection links.