DeepSeek Balance Whale Widget: a DSH plugin that watches your API balance

The gap it fills: DeepSeek spend is invisible until you go looking

DeepSeek's API billing lives on the platform website. You see a balance when you log in, and nothing while you work. The usual failure is not a surprise invoice, it is a mid-session 402 because the account ran dry during a long agent loop. This widget puts a bubble with the balance in the corner of the DSH web interface and refreshes it every 60 seconds, with a manual refresh on click. It also answers a narrower question the platform does not answer in place: how much did this particular turn just cost me.

The audience is narrow on purpose. This is a DSH plugin, packaged as a DSH bundle, mounted through cordis.patch.yml. If you do not run DeepSeek Harness, there is no host to attach it to and the repository offers no standalone page or CLI. The README's own framing is a resident widget for the DSH web UI, and the install steps all go through dsh plugin --profile web.

How the widget is wired: a bundle patch, three JSON routes, and a whale image

package.json declares a dsh.bundle.patch pointing at ./cordis.patch.yml, and main points at lib/index.js. The README's directory listing shows the host-side plugin body in lib/index.js, the cut-out whale in assets/DSniang1.png, and a fallback full image assets/DSniang02.png kept for the old manual install path. The bubble itself is drawn in code rather than baked into the image.

The visible surface is HTTP. The README's verification section names four routes served by the plugin: /dsh-whale/image.png returns image/png, /dsh-whale/balance.json returns JSON containing ok, totalBalance, currency and todayUsage, /dsh-whale/size.json answers GET with the configuration and accepts PUT to write it, and /dsh-whale/last-turn.json returns the most recent turn as seq, turn, amount and tokens. That is a small design decision worth noting: the widget's state is inspectable with curl, which makes it debuggable without opening browser devtools.

Balance comes from api.deepseek.com/user/balance using DEEPSEEK_API_KEY. Today's usage has two paths. The default, called 小鲸鱼记账 in the README, needs no token at all: the widget observes the balance, and whenever it drops it adds the difference to a local ledger at $DSH_HOME/.dshw-usage.json, rolling over at midnight and keeping 30 days. The optional 实时·令牌 mode calls the platform usage endpoint with DEEPSEEK_PLATFORM_TOKEN and converts hourly token buckets into money using a PRICING constant at the top of lib/index.js. Per-turn cost is a third path that listens to local DSH session events and settles on turn/end, so it needs neither credential beyond the API key.

Two details in the README are worth calling out because they show where the author expected trouble. When the observed currency changes, the ledger resets its baseline instead of recording a difference, to avoid polluting the ledger on multi-currency accounts. And on transient network errors the widget keeps the last known balance rather than showing an error. Both are reasonable, and both mean the number on screen can be stale rather than wrong.

Installing the whale widget and confirming it responds

The README gives three install routes. The recommended one adds the plugin straight from GitHub, with no local clone. Run it in PowerShell:

dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget

Behind the scenes dsh plugin forwards to pnpm and, on success, adds dsh-whale-widget to dsh.profile.bundles. After it finishes, restart dsh web and press F5 in the browser. The README notes the plugin then appears on the DSH plugin management page, so later updates can be done there instead of by command. If your network needs a proxy, the README sets http_proxy, https_proxy and all_proxy environment variables before the same command.

For a local checkout, run this from the repository root, the directory holding package.json:

dsh plugin --profile web add link:.

The README is explicit that link:. refers to the current directory because the repository root is the plugin package, and warns against link:.\dsh-whale-widget, which installs as an ordinary dependency and leaves you with no widget after restart. If you move the source directory later, re-run the same command with the new path.

Then confirm the plugin is mounted and the routes answer:

dsh --profile web --dump-config | Select-String -Pattern "whale"

curl http://127.0.0.1:3080/dsh-whale/balance.json
curl http://127.0.0.1:3080/dsh-whale/last-turn.json

You should see dsh-whale-widget in the bundles list, and balance.json should return 200 with a JSON body containing totalBalance. If the balance reports 未配置 DEEPSEEK_API_KEY, the API key is missing from DSH credentials, which the README says to configure either in the credential management UI or in .dsh/.credentials.yaml. With only that key set, the default ledger mode works and today's usage starts accumulating after the first observation, which the README says happens within 60 seconds.

To remove it:

dsh plugin --profile web remove dsh-whale-widget

The README also documents cleanup for people upgrading from the old manual install, which involved copying whale-balance.mjs into the web profile and editing cordis.patch.yml by hand. That path removes whale-balance.mjs, whale-balance.cjs and the two PNG files from $env:USERPROFILE\.dsh\profiles\web, then deletes the old insert block from cordis.patch.yml, replacing the file with [] if that block was its only content.

The ledger mode has a hole, and the token that closes it is a session credential

The default usage mode cannot see spending that happens while DSH is closed. It works by differencing observed balances, so if you run scripts or another client against the same API key overnight, that spend appears as one large jump at the next observation, or is attributed to the wrong day if the rollover happened in between. The README states this plainly: 若 DSH 关闭期间有消耗会漏记. Anyone who uses the same DeepSeek key outside DSH should treat the today number as a lower bound.

The token mode is more accurate but asks for something different in kind. DEEPSEEK_PLATFORM_TOKEN is not an sk- API key, it is the Authorization header value from a logged-in platform.deepseek.com browser session, obtained by opening devtools, finding the usage/by_api_key/amount request and copying the header. It expires when the session does, so after re-login you may need to fetch it again. Putting a browser session token into a credentials file is a real decision, and the widget's own convenience does not change that. The README's mitigation is that the token is optional and the widget falls back to the ledger mode without it.

The pricing table is another maintenance surface. The usage endpoint returns token buckets, not money, so the widget converts using a PRICING constant at the top of lib/index.js, which the README says to edit yourself when DeepSeek changes prices. Peak-hour pricing is encoded there too, with weekday peaks 9:00-12:00 and 14:00-18:00 and weekends on off-peak rates from 2026-08-23. A stale table produces a plausible wrong number, which is worse than an obvious error.

Finally, per-turn cost only settles when a turn completes. A cancelled or interrupted turn does not produce a turn/end event, so no bubble appears. The README lists this among the common issues.

Alternatives: a platform dashboard, a budget alert, or your own cron job

The simplest alternative is the DeepSeek platform dashboard itself. It is authoritative, it shows real billing rather than a differenced estimate, and it costs nothing to install. The difference is placement: it lives in a browser tab you have to open, and it does not know about DSH turns, so it cannot tell you what the turn you just ran cost.

On the other side, a small script against api.deepseek.com/user/balance plus a cron entry gives you the same number and can push it anywhere, including a chat channel or a Prometheus endpoint. That approach survives DSH being closed, which the ledger mode does not, and it does not care which editor or agent you use. What it does not give you is the per-turn attribution, because that comes from DSH session events, not from the balance API.

A third option is a hard spend limit on the DeepSeek account side. That is a control, not a display. The widget tells you where you are; it does not stop anything. If your actual problem is an agent loop burning tokens unattended, a limit or a cheaper model matters more than a nicer readout.

Licence, upgrade path and what maintenance actually costs

The project is MIT licensed, declared in both package.json and the LICENSE file at the repository root. MIT permits commercial use, modification and redistribution provided the copyright notice and licence text are kept. That is the whole of it; nothing in the repository suggests a dual licence or a separate terms file, and this is not legal advice.

Upgrades are cheap if you installed from GitHub: the README says the plugin shows up on the DSH plugin management page and can be updated there. The version in package.json is 0.3.0 while the most recent tagged release listed is v0.2.10, published 2026-08-24, the same day as the last push to main. There is also a v1.0.0+win tag labelled DS Desktop Whale, which does not match the 0.x line and is not explained in the README; treat it as a separate artifact until you find out what it contains.

The real maintenance cost is not the code, it is the two external contracts: the PRICING table in lib/index.js and the platform usage endpoint's response shape. The balance endpoint is stable and simple. The usage endpoint is an internal web API, not a documented public one, so a change there breaks the token mode without warning. The ledger mode is insulated from that but inherits the closed-window gap described above. If you adopt the widget, the thing to watch is not the repository's commit activity but whether the number in the bubble still matches the platform dashboard.

Editorial conclusion

Adopt it if you already run dsh web and want a passive balance readout without opening the DeepSeek platform in a browser tab. Skip it if you do not use DSH, if you need server-side accounting, or if you are unwilling to put a platform session token in a credentials file, because the token mode is the only one that survives time when the UI is closed. Verify first that dsh --profile web --dump-config lists dsh-whale-widget, that curl http://127.0.0.1:3080/dsh-whale/balance.json returns 200 with a totalBalance field, and that DEEPSEEK_API_KEY is present, since the widget shows 未配置 DEEPSEEK_API_KEY without it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. MeteorNOX/DeepSeek-Balance-Whale-Widget on GitHub
4. README
5. Releases