README.md

metadata

title: ROI Bet Tracking Bot
emoji: 📈
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
short_description: Discord bet tracker with per-user ROI stats.

ROI Bet Tracking Discord Bot

A Discord bot for manually tracking bets and ROI per user. Each Discord user gets their own independent bet history, sport-tagged analytics, exports, and summary charts.

Features

• /bet logs one bet privately using sportsbook and sport dropdowns
• /bulkadd logs multiple bets privately for one sportsbook and one sport
• /editbet updates an open bet privately
• /deletebet soft deletes a bet privately without wiping audit history
• /resolve grades a bet as win, loss, or void
• /resolveall grades multiple bet IDs to the same result
• /bankroll manages starting bankroll and unit settings
• /roi posts a public trend-first ROI view with filters and chart
• /bets posts a public filtered ledger with pagination
• /summary posts a public record-first summary with chart
• /books shows ROI and win rate by sportsbook
• /sports shows ROI and win rate by sport
• /export exports a filtered CSV of a user’s bets privately
• /commands posts a public command reference embed
• /welcome posts a public welcome embed and tags everyone for admins only
• CockroachDB / Postgres-compatible persistence via DATABASE_URL
• Docker-ready for Hugging Face Spaces

Setup

1. Install dependencies:

npm.cmd install

2. Copy .env.example to .env and add your bot config:

DISCORD_TOKEN=your_token_here
GUILD_ID=optional_guild_id
DATABASE_URL=postgresql://username:password@host:26257/database?sslmode=require
ADMIN_ROLE_NAME=Admin

3. Start the bot:

npm.cmd start

Notes

• Node.js 24+ is required.
• The bot stores data in your remote CockroachDB database.
• /welcome is restricted to members with the Discord role name set in ADMIN_ROLE_NAME.
• If GUILD_ID is set, slash commands register to that guild for faster updates. Otherwise they register globally.
• Set DATABASE_URL, DISCORD_TOKEN, and ADMIN_ROLE_NAME as Hugging Face Space secrets.
• The Docker Space exposes a tiny health endpoint on port 7860 while the Discord bot runs in the same container.

Hugging Face Deployment

1. Create a new Hugging Face Space using the Docker SDK.
2. Push this repository to that Space.
3. Add these Space secrets:
   • DISCORD_TOKEN
   • DATABASE_URL
   • ADMIN_ROLE_NAME
   • GUILD_ID (optional)
4. Let the Space build and start.

The app will create and backfill its tables automatically on startup if they do not exist yet.

Bet Input Tips

The /bet command requires sportsbook and sport dropdowns first, then the modal asks for:

prop: Luka Doncic over 29.5 points
odds: -115
stake: $25

The /bulkadd modal accepts one bet per line in this format:

Bryan Rocchio 1+ HR | +1450 | $5
3 leg parlay | +1452 | $5

Oracle Cloud Always Free Deployment

This bot is a good fit for an Oracle Cloud Always Free Ubuntu VM because it:

• runs on Node.js 24+
• uses your remote CockroachDB/Postgres-compatible database
• does not require local persistent bet storage

Recommended deployment shape:

• Oracle Compute VM with Ubuntu LTS
• native Node runtime
• systemd for auto-restart and boot persistence
• SSH exposed publicly on port 22 only

Deployment assets included in this repo:

• docs/oracle-always-free.md
• deploy/oracle/roibot.service
• deploy/oracle/roibot.env.example

Market Scanner

Market scanning is admin-controlled and built into the same long-running bot process.

• /scanstatus shows scanner health and last-run information
• /scanrun runs the Circa disagreement scanner manually
• /scanreport posts the morning discrepancy and width reports on demand
• /circatest previews Circa OCR parsing

Environment variables for scanner features:

• ODDS_API_KEY
• ODDS_API_BASE_URL
• ODDS_API_SPORT_KEY
• ODDS_API_REGIONS
• ODDS_API_MARKETS
• CIRCA_DROPBOX_URL (public shared folder link)
• SCAN_REPORT_CHANNEL_ID
• SCAN_ALERT_CHANNEL_ID
• SCAN_MORNING_TIME
• SCAN_TIMEZONE
• SCAN_MIN_BOOKS
• SCAN_DISAGREEMENT_THRESHOLD
• SCAN_ALERT_COOLDOWN_MINUTES
• SCAN_FREQUENCY_MINUTES