API credits have a knack for running out at the worst possible moments. You're mid-request, deep into a debugging session, and suddenly the response stops with a 402 Payment Required or an authentication error. The context window was fine. The prompt was perfect. But the balance hit zero, and now you're scrambling to top up while your flow is shattered.
The DeepSeek-Balance-Whale-Widget from MeteorNOX exists to eliminate that exact scenario. It's a small, playful widget that lives in the bottom-right corner of the DeepSeek Harness (DSH) interface, displaying your account balance in real-time. The widget features a whale girl — a cute anthropomorphic whale character — that bounces, flips, and rolls numbers as your balance changes. But beneath the charming exterior lies a genuinely useful monitoring tool.
This article breaks down everything you need to know: what the widget is, why it matters, how to install it, what makes it tick, and how to get the most out of it.
The DeepSeek-Balance-Whale-Widget is an open-source project hosted on GitHub under the username MeteorNOX. It's a lightweight, web-based widget designed specifically for DeepSeek Harness (DSH), a tool that provides a unified interface for working with DeepSeek's AI services.
The widget's core job is simple: display your DeepSeek account balance so you always know how much credit you have left. It accomplishes this with a visual flair that's rare in developer tools — the balance is shown on a small whale girl character that sits in the corner of your screen. When your balance updates, the number rolls with a smooth animation. The character itself is "QQ弹弹" (QQ-bouncy), meaning it has a soft, jiggly physics-like feel when you interact with it.
This isn't a serious enterprise dashboard. It's a companion. And that's precisely why it works.
DeepSeek's API operates on a prepaid credit system. You load funds into your account, and every API call deducts from that balance based on token usage. As of 2025, the pricing for the deepseek-chat model is $0.14 per million input tokens and $0.28 per million output tokens. That's inexpensive, but costs accumulate quickly when you're running batch jobs, iterating on prompts, or operating a production service.
Without real-time visibility into your balance, you risk:
The widget solves this by putting the balance directly in your peripheral vision. No need to open a browser tab, log into the DeepSeek platform, and check manually. It's always there.
The widget isn't just a number readout. It's a small interactive companion with several thoughtful features:
Key Takeaway: This is a monitoring tool disguised as a cute desktop pet. The playful design lowers the friction of checking your balance — you'll glance at it constantly without thinking, which is exactly what good monitoring should feel like.
DeepSeek Harness (DSH) is a desktop or web-based interface that wraps DeepSeek's API into a more accessible workspace. While the raw API is powerful, DSH provides structure — project management, prompt history, model selection, and configuration — so you can work with DeepSeek models without juggling raw HTTP requests or terminal commands.
Think of DSH as the cockpit for your DeepSeek usage. You manage API keys, run queries, track conversations, and organize your work all in one place. It's the kind of tool that becomes indispensable once you start using DeepSeek regularly.
DSH connects to DeepSeek's platform using your API key. This key grants access to models like deepseek-chat and deepseek-reasoner, and every request you make through DSH is billed to your account.
The integration means DSH knows your account state. It can query your balance, check usage, and surface errors. This is the hook that the Balance-Whale-Widget leverages.
DSH supports a plugin/widget architecture, allowing third-party developers to extend its functionality. Widgets can add UI elements, background tasks, or data visualizations. The Balance-Whale-Widget is one such extension — it hooks into DSH's lifecycle, reads your balance via the API, and renders a persistent overlay.
This architecture is why the widget can "automatically enable" when DSH starts. It's not a separate app you need to launch; it's part of the DSH environment.
Before installing the widget, you need:
The installation process is straightforward:
Step 1: Clone the repository
git clone https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget.git
cd DeepSeek-Balance-Whale-Widget
Step 2: Configure your API key
The widget needs your DeepSeek API key to fetch your balance. Locate the configuration file (typically config.js or .env in the project root) and add your key:
// config.js
const config = {
apiKey: "your-deepseek-api-key-here",
pollInterval: 60000 // update every 60 seconds
};
Step 3: Integrate with DSH
Depending on your DSH version, you'll either:
widgets/ directory, orCheck your DSH documentation for the exact method. The README in the repository should also have specific instructions.
Once installed, restart DSH (or reload the interface). The whale girl should appear in the bottom-right corner. Hover over her — the balance should display. If you see nothing, check the DSH console for errors (usually accessible via Ctrl+Shift+I or the menu).
Key Takeaway: The entire setup takes under five minutes. The hardest part is finding where to put your API key.
The widget queries the DeepSeek API at a set interval (default is typically 60 seconds) to fetch your current balance. This is the same endpoint used by the DeepSeek platform dashboard, so the numbers match what you'd see in your browser.
The "QQ弹弹" effect gives the whale girl a squishy, jelly-like quality. When you click, drag, or even just hover, the character deforms slightly and springs back. This is achieved through CSS transforms and JavaScript physics calculations — the kind of effect you'd see in modern game UI or animated mascots.
You can grab the whale girl and move her anywhere on the screen. When you release, she snaps to the nearest edge or corner. This ensures she never floats awkwardly in the middle of your workspace, blocking content.
If you snap the widget to the left edge, the whale girl flips horizontally. This is a thoughtful detail — it ensures she's always "facing" inward toward your workspace rather than staring at the edge of the screen. The flip is animated, not instant.
When your balance updates, the number doesn't just change. It rolls — each digit counts up or down to the new value. This is implemented using a counting animation library (like CountUp.js) or custom JavaScript that interpolates between old and new values over a short duration.
No manual activation needed. When DSH launches, the widget loads automatically. When DSH closes, the widget goes away. It's fully integrated into the DSH lifecycle.
Key Takeaway: The widget's features are polished, not bolted on. The flip animation, the rolling numbers, and the bouncy physics all serve the same goal: making balance monitoring feel natural and even enjoyable.
The widget is built with web technologies, which means you can restyle it with CSS. The whale girl's colors, size, shadow, and glow effects are all adjustable. For example, to match a dark theme:
.whale-widget {
background-color: #1a1a2e;
border: 1px solid #e94560;
box-shadow: 0 0 15px rgba(233, 69, 96, 0.5);
}
You can also change the animation speed, the bounce intensity, or even hide the whale entirely and show only the balance number.
The pollInterval config value controls how often the widget fetches your balance. The default is 60 seconds. You can lower it to 10 seconds for near-real-time tracking, but be aware that each poll counts against DeepSeek's API rate limits. For most users, 60 seconds is plenty.
The widget is a standard web app:
Because it's all standard web tech, it runs in any modern browser or Electron-based shell like DSH.
If you're comfortable with JavaScript, you can extend the widget:
The project is open-source, so the code is yours to modify.
Key Takeaway: The widget is simple on the surface but built on standard, extensible web technologies. If you can write a little CSS and JavaScript, you can make it truly yours.
A developer building a chatbot with DeepSeek's API needs to run dozens of test prompts. Without a visible balance, they might burn through credits without realizing it. The widget sits in the corner, continuously showing the declining balance, so the developer knows when to pause and top up.
A researcher uses DSH for multiple projects — one for data analysis, one for text generation, one for experimentation. By watching the balance widget, they can correlate balance drops with specific activities and adjust their usage patterns accordingly.
A hobbyist prefers a dark UI with neon accents. They edit the widget's CSS to turn the whale girl a deep blue with a cyan glow, matching their setup. The widget now feels like a native part of their environment.
A small team shares a single DeepSeek account in a collaborative DSH instance. The widget's drag-and-drop feature lets each member position it where they prefer. The visible balance keeps everyone aware of the collective budget.
An instructor teaching API integration uses the widget to show students how real-time monitoring works. The rolling number animation serves as a concrete example of front-end animation techniques, and the drag-and-drop demonstrates event handling in JavaScript.
Key Takeaway: The widget's value scales with how much you rely on DeepSeek. For heavy users, it's a practical necessity. For casual users, it's a charming addition that prevents unpleasant surprises.
The widget is not an official DeepSeek product. It's a community-created tool hosted on GitHub. DeepSeek doesn't endorse or support it, though it uses the official API. If you encounter issues, your first stop should be the GitHub repository, not DeepSeek support.
The widget only displays your balance. It cannot add funds. If your balance hits zero, you need to visit the DeepSeek platform and add credit manually. The widget will show 0 until you do.
The widget needs an active internet connection to fetch balance data from DeepSeek's API. If you're offline, the last known balance will still display, but it won't update.
The widget depends on DSH. You can't run it as a standalone browser extension or desktop app (at least not without significant modification). It's designed to live inside DSH.
While the whale girl is cute, the widget serves a real purpose. The visual design is a means to an end — making balance monitoring so effortless that you never forget to check. Underestimating it as "just a toy" misses the point.
Key Takeaway: Know what the widget is and isn't. It's a community tool that displays balance data. It doesn't manage funds, work without DSH, or offer official support.
If the whale girl doesn't appear after installation:
Ctrl+Shift+I).If the widget loads but the balance stays stale:
If the widget doesn't move or doesn't snap correctly:
The widget is designed for desktop DSH environments. It may work in mobile browsers, but drag-and-drop and edge-snapping are desktop-centric features. Touch support is not guaranteed.
What is the DeepSeek-Balance-Whale-Widget? It's an open-source widget for DeepSeek Harness that displays your DeepSeek account balance in real-time, presented as a small animated whale girl character.
How do I install the widget?
Clone the GitHub repository, add your DeepSeek API key to the config file, and load the widget folder into DSH via its widget manager or the widgets/ directory.
Does the widget require any API keys? Yes. You need a valid DeepSeek API key to fetch balance data. The widget won't work without it.
Can I customize the widget's appearance? Absolutely. The widget is built with HTML/CSS/JS. You can edit the CSS to change colors, sizes, animations, and more.
Is the widget compatible with all DeepSeek models?
Yes. The widget monitors your account balance, which is model-agnostic. Whether you're using deepseek-chat, deepseek-reasoner, or any other model, the balance is the same.
What happens if my balance is low? The widget just displays the number. It won't alert you, but you'll see it drop. You can extend the widget to add threshold alerts if you want.
Does the widget work on mobile devices? It's primarily designed for desktop DSH. Mobile support is limited and not guaranteed.
Is the widget free to use? Yes. It's open-source and free. You only pay for your DeepSeek API usage.
How often does the widget update the balance? By default, every 60 seconds. You can change this in the config file.
Can I contribute to the project? Yes. The repository is on GitHub. You can submit issues, fork the repo, and create pull requests with improvements.
The DeepSeek-Balance-Whale-Widget is a small tool that solves a real problem: keeping your DeepSeek API balance visible without requiring manual checks. It does this with a playful design that makes monitoring feel less like a chore and more like a companion.
The key benefits:
If you use DeepSeek through DSH, this widget is worth the five-minute setup. It's free, it's open-source, and it adds a layer of awareness that prevents the most annoying failure mode in API development: running out of credits at the worst moment.
The project lives on GitHub under MeteorNOX. If you find bugs, have feature ideas, or want to improve the whale girl's wardrobe, get involved. Open an issue, submit a pull request, or fork the project and make your own version.
Ready to keep an eye on your DeepSeek balance with a cute companion? Visit the GitHub repository, follow the installation guide, and let the little whale girl brighten your DSH interface today!