balance-bot

The friendly money buddy that spots allowance drops, snack splurges, and everything in between—then gives your family a cheerful heads-up.

Say hello to balance-bot

Balance-bot keeps a watch on your SimpleFIN accounts and sends timely notes through Apprise. Parents and kids stay in the loop—no spreadsheets, no stress, just quick reminders when something changes.

Why families love it

• Everyone hears the news. Drop in Discord, Matrix, email, or any Apprise-ready place and we’ll send updates right where your family hangs out.
• You stay in charge. Pick which accounts matter to each person, then relax while balance-bot keeps watch.

Peek at the alerts

Here’s an example message you might see:

🏦 Balance update for Jamie
📉 -$15.00
💰 $79.22

Gather Your Ingredients

• A SimpleFIN setup token or an existing access link. Copy the whole thing so we can trade it for a long-lived key.
• Somewhere for Apprise to deliver the news—Discord channel, Matrix room, email, you name it.
• (Optional) A healthchecks.io ping URL if you want balance-bot to report every run.
• Docker or Node.js 20+ if you prefer running it directly.

Quick Start

version: '3.8'

services:
  balance-bot:
    image: ghcr.io/hursey013/balance-bot:latest
    container_name: balance-bot
    restart: unless-stopped
    ports:
      - '4000:4000' # opens the setup site
    environment:
      TZ: 'America/New_York' # adjust to match your timezone
      # Apprise endpoint used to deliver notifications
      APPRISE_API_URL: 'http://apprise:8000/notify'
      # Cache SimpleFIN balances in milliseconds (0 disables caching)
      SIMPLEFIN_CACHE_TTL_MS: '300000'
      # Cron expression (UTC) controlling how often balances are checked
      BALANCE_BOT_CRON: '0 * * * *'
      # Optional healthchecks.io (or compatible) ping URL (remove if unused)
      HEALTHCHECKS_PING_URL: ''
      # Directory for persisted config, cache, and state files
    volumes:
      - ./data:/app/data
    depends_on:
      - apprise

  apprise:
    image: lscr.io/linuxserver/apprise-api:latest
    container_name: apprise
    restart: unless-stopped
    environment:
      PUID: '1026' # adjust to match your user
      PGID: '100'
      TZ: 'America/New_York'
    volumes:
      - ./apprise-config:/config
      - ./apprise-attachments:/attachments
    ports:
      - '8000:8000'

Once the containers settle, visit http://localhost:4000 (replace localhost with your NAS IP if needed). That’s your command center.

Track runs with healthchecks.io

If you use healthchecks.io or a compatible service, paste your project's ping URL in step three of the setup UI. Balance-bot will trigger /start, /fail, and a JSON success payload after each polling cycle so you can keep an eye on uptime. Prefer to set it ahead of time? Provide the HEALTHCHECKS_PING_URL environment variable and the UI will pick it up automatically.

License

balance-bot is released under the MIT License.