README.md

---
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:

```powershell
npm.cmd install
```

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

```env
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:

```powershell
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:

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

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

```text
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`