MeteorNOX/DeepSeek-Balance-Whale-Widget: DeepSeek Harness (DSH) — A Playful Whale Girl That Keeps an Eye on Your DeepSeek Account Balance

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.

Introduction

What Is the DeepSeek-Balance-Whale-Widget?

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.

Why Monitor Your DeepSeek Balance?

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:

Interrupted workflows: Requests fail mid-task when credits run dry.
Unexpected downtime: Production services that depend on DeepSeek will go dark.
Budget overruns: Without tracking, it's easy to lose sight of cumulative spending.

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.

Overview of the Widget's Features and Playful Design

The widget isn't just a number readout. It's a small interactive companion with several thoughtful features:

Real-time balance display: Polls the DeepSeek API for your current balance.
QQ弹弹 animation: The whale girl has a soft, bouncy physics effect that makes it feel alive.
Drag-and-drop with snap-to-edge: Move it anywhere; it snaps to the nearest edge.
Left-edge flip: When snapped to the left side, it flips horizontally to face inward.
Number rolling animation: Balance changes transition smoothly rather than blinking to a new value.
Automatic enabling: The widget activates when DSH starts — no manual toggling required.

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.

Understanding DeepSeek Harness (DSH)

What Is DSH?

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.

How DSH Integrates with DeepSeek Services

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.

The Role of Widgets in DSH

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.

Getting Started with the Widget

Prerequisites: DSH and DeepSeek API Key

Before installing the widget, you need:

DeepSeek Harness (DSH) installed and running. The widget is designed for DSH specifically, not for standalone use.
A DeepSeek API key with an active account balance. You can create one at platform.deepseek.com.
Git (if you're cloning the repository) or the ability to download files directly from GitHub.

Installation Steps: Clone, Configure, Integrate

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:

Copy the widget folder into DSH's widgets/ directory, or
Use DSH's built-in widget manager to load the folder.

Check your DSH documentation for the exact method. The README in the repository should also have specific instructions.

Verifying the Widget Is Active

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.

Exploring the Widget's Features

Real-Time Balance Display

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.

QQ弹弹 Animation Effect

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.

Drag-and-Drop and Snap-to-Edge

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.

Left-Edge Flip Animation

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.

Number Rolling Animation

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.

Automatic Enabling with DSH

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.

Customization and Technical Insights

Modifying Appearance with CSS

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.

Adjusting Update Frequency and API Polling

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.

Underlying Technologies: HTML, CSS, JavaScript, Libraries

The widget is a standard web app:

HTML for structure
CSS for styling and animations (including the QQ bounce)
JavaScript for API calls, drag-and-drop, and state management
interact.js (or similar) for the drag-and-drop and snap-to-edge behavior
CountUp.js (or custom code) for the rolling number animation

Because it's all standard web tech, it runs in any modern browser or Electron-based shell like DSH.

Extending Functionality for Advanced Users

If you're comfortable with JavaScript, you can extend the widget:

Add alerts when balance drops below a threshold
Log historical balance data to a file
Display token usage alongside the balance
Add multiple account support with a dropdown

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.

Practical Use Cases and Examples

Monitoring Balance During Development

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.

Tracking Spending Across Projects

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.

Customizing for Different Themes

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.

Shared Team Environments

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.

Educational Demonstrations

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.

Common Misconceptions

Third-Party vs. Official DeepSeek Product

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.

Widget Does Not Top Up Balance

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.

Internet Connection Requirement

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.

Not a Standalone Application

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.

More Than Just Aesthetics

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.

Troubleshooting and FAQ

Widget Not Loading

If the whale girl doesn't appear after installation:

Check the DSH console for JavaScript errors (Ctrl+Shift+I).
Verify the config file — is your API key correct and properly formatted?
Confirm the widget directory is in the right location for DSH's widget loader.
Check DSH version — the widget may require a minimum version.

Balance Not Updating

If the widget loads but the balance stays stale:

Check your internet connection.
Verify the API key is valid — test it by making a manual API call.
Check the poll interval — maybe you set it too high.
Look for rate limiting — if you're making too many API calls, DeepSeek may throttle you.

Drag-and-Drop Issues

If the widget doesn't move or doesn't snap correctly:

Check for CSS conflicts — other DSH styles may interfere.
Update interact.js — make sure you're using a compatible version.
Report a bug on the GitHub repository with your DSH version and browser/OS details.

Compatibility with Mobile Devices

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.

Frequently Asked Questions

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.

Conclusion

Recap of Benefits

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:

Always-visible balance in the corner of your DSH interface
Smooth animations (QQ bounce, number rolling) that make updates pleasant
Drag-and-drop flexibility with smart edge snapping
Automatic activation with DSH — no extra steps
Open-source extensibility for customization and learning

Encouragement to Try the Widget

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.

Community and Contribution

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!

In This Article