DeepSeek Usage Widget

What it is: a tiny desktop widget that watches your DeepSeek API spend so you don't have to keep checking the platform page. Live balance, budget burn, session usage, estimated tokens — all in one dark little window.

Built by Moddy — https://www.moddys.net · Licensed MIT.

What it does

• Live balance straight from the DeepSeek API (GET /user/balance) — on launch, on demand, and every 30 seconds in the background.
• A budget-burn meter — tell it what you bought (say $15) and it shows how much of that is gone, colour-coded green → cyan → orange → red with a pulsing red zone when you're deep into it. Alerts at a threshold you set.
• Session tracking that survives restarts — close the widget mid-chat and it remembers; reopen it and your session picks up exactly where it left off. It only resets when a session really ends: Hermes shuts down, its last session closes, or you hit the New Session button.
• Token estimates that make sense — two of them: what you've burned this session and all-time, both worked out from DeepSeek's own published per-model pricing blended with how you actually use it (output vs cache-hit mix). The blended $/M rate is shown live on the dashboard.
• Dashboard calibration — DeepSeek doesn't expose a usage-tracking API, so if you want the all-time token figure to line up exactly with your platform page, paste in the token count from your dashboard and your total top-ups. The widget locks your real rate and tracks from there.
• The little things — scroll-wheel transparency over the dashboard, right-click paste on every field, a window that resizes properly, and a toolbar Back button so you never get lost.

Quick start

1. Download DeepSeekUsageWidgetStandalone.zip from the Releases page and extract it.
2. Run DeepSeekUsageWidget.exe — no install wizard, no admin rights, nothing else to download.
3. On first launch you'll land on the setup screen (a welcome popup shows you the way): enter your DeepSeek platform email and API key.
4. Set Amount Bought to what you paid — in USD, or your own currency — and hit Save & Fetch Live Balance.

That's it. The widget pulls your balance, pins your session, and starts counting.

First run on Windows: SmartScreen may grumble about an unsigned exe. Click More info → Run anyway. It's fully open source — build it yourself if you'd rather not trust a binary (instructions below).

System & compatibility

Operating systems:

• Windows 10 / 11 — the ready-made .exe
• macOS / Linux — run from source (python widget.py); window transparency needs a compositor on Linux and just quietly doesn't apply if there isn't one
• Requires Python 3.11+ to build from source; the exe needs nothing

API requirements:

• A DeepSeek platform account with an API key (platform.deepseek.com)
• The widget talks to exactly one API host: api.deepseek.com — the models endpoint and /user/balance. Nothing else.

Optional (session auto-reset only): if you run the Hermes Agent web dashboard, the widget can watch it (/api/status) so your session resets when Hermes shuts down or its last session closes. Leave the field blank if you don't use Hermes — everything else works the same.

How the numbers work

Amount Bought   = what you entered (Initial Spend)
Live Balance    = GET /user/balance (every 30 s)

Meter %         = (Amount Bought − Live Balance) ÷ Amount Bought   ← total used
Amount Used     = Session Start − Live Balance                     ← this session
Est. Tokens     = Amount Used ÷ effective rate × 1M                ← this session
Est. Overall    = (Amount Bought − Live) ÷ effective rate × 1M     ← all-time

Bought $15, balance $10 → the bar reads 33 % and you've got two token estimates derived from the same dollars. When the balance is the only thing the API will tell you, that's the honest way to get from dollars to tokens.

Code build checks

Every build in this repo went through the same gauntlet before release:

• Live API verification — balance fetched through the widget's own code against a real key before packaging (not mocked).
• Launch stability — the compiled exe is started and watched through its first two auto-refresh cycles; it must stay alive with no crash log.
• Session lifecycle tests — restore-on-restart, reset-on-session-end, calibration lock, and the refresh pipeline, all asserted programmatically.
• Crash diagnostics — a frozen windowed build never dies silently: any uncaught exception writes a crash.log next to the app instead of vanishing. If something misbehaves, that file is the first thing to grab.

Privacy & safety

• Your key never leaves your machine. It's stored in deepseek_settings.json next to the exe and sent only to DeepSeek's own API as a Bearer header over HTTPS.
• No telemetry. No analytics. No third-party calls. The only network hosts are api.deepseek.com and, optionally, your own Hermes dashboard.
• The settings file is plain JSON on purpose — you can read exactly what's stored. Keep it private; the repo's .gitignore refuses to track it.
• Auditable: roughly 900 lines of readable Python under MIT. Don't trust the binary? Read it, build it, done.

Building from source

Requires Python 3.11+ and tkinter (ships with the standard Windows installer).

pip install customtkinter requests pyinstaller
pyinstaller --onefile --windowed --name DeepSeekUsageWidget \
    --icon icon.ico widget.py

The .exe lands in dist/.

Thanks & credits

Thanks for checking out this release. If you use it, I hope it saves you some head-scratching over your balance. Cheers Moddy !