Introduction¶

When developing with the DeepSeek API, there are three questions you often need to pause to verify: how much money remains in the account, whether it is currently the half-price period, and how much was deducted from the last call. Since balances must be queried via a separate API endpoint and peak-valley pricing causes costs to fluctuate with the time period, relying purely on switching pages and mental arithmetic is not realistic.

The DSH Web interface has a whale widget in the bottom right corner for viewing balances (data sourced from the same origin as the official API). However, if you want to keep dual-currency balances, peak-valley status, and every deduction in your line of sight while coding, deepseek-balance-banner turns these into a banner at the top of the page. Below, we introduce its features, installation, and daily usage.

What is This¶

deepseek-balance-banner is a community plugin for the DeepSeek Harness (DSH) Web interface, authored by iskshadow195563, and is released under the MIT License. It is a standard DSH bundle package. After installation, it displays two balance capsules—USD and CNY—at the top right of the page, to the left of the theme toggle (day/night) button. It highlights negative balances and automatically refreshes every 60 seconds.

The plugin is independently developed by the community and has no affiliation with the DeepSeek official entity.

Core Features¶

Dual-Currency Balances and Negative Value Highlighting¶

The plugin calls the official GET /user/balance endpoint, parses all returned balance_infos, and renders a capsule for both USD and CNY. When the balance of any currency drops below 0, it is highlighted in a warning color, making the debt instantly visible.

Deduction and Recharge Animations¶

When a deduction is detected, a red gamified floating text (e.g., -¥0.03) appears next to the balance capsule, floating up, enlarging, and fading out. When a recharge or credit is detected, a green positive floating text (e.g., +¥0.05) appears. Hovering over the banner displays the total deduction and recharge amounts for the current page session.

Peak and Valley Period Recognition¶

The badge displays in real-time whether the current period is peak (standard price) or valley (half price), along with the current Beijing time. Saturday and Sunday automatically display the valley price all day. The time period rules are based on the official DeepSeek pricing rules effective August 23, 2026.

Refresh Mechanism¶

It automatically refreshes every 60 seconds; clicking any capsule immediately triggers a manual refresh. The host side also employs a 25-second TTL cache to avoid hitting the official API too frequently.

Demo Mode and Theme Adaptation¶

The styles use DSH theme variables (--dsw-*) and are coordinated for both dark and light skins. Adding ?dsb-demo=1 to the page URL triggers a looping play of deduction/charge animations, useful for development or previewing.

Installation and Enablement¶

Prerequisites¶

dsh >= 0.1.0-rc.6, recommended 0.1.1-rc.2+;
DEEPSEEK_API_KEY has been configured in DSH credentials (used to request GET https://api.deepseek.com/user/balance);
The Web Profile directory $DSH_HOME/profiles/web/ exists (default for Windows is %USERPROFILE%\.dsh\profiles\web\).

Installation with a Single Command¶

# Install from npm
dsh plugin --profile web add deepseek-balance-banner

# Or install directly from GitHub (no npm account required)
dsh plugin --profile web add github:iskshadow195563/DeepSeek_Harness_Balance_Banner#v1.0.0

--profile is a required parameter, and web is the default Web interface profile. If you are using a different profile name, please replace it. After installation, the plugin joins the bundle layer of that profile. Restart dsh web and refresh the page (F5) to make it take effect.

Manual Installation¶

If you prefer not to use package management, you can place deepseek-balance-banner.mjs into the Web profile directory:

# macOS / Linux
cp deepseek-balance-banner.mjs "${DSH_HOME:-$HOME/.dsh}/profiles/web/"

# Windows PowerShell
Copy-Item deepseek-balance-banner.mjs "$env:USERPROFILE\.dsh\profiles\web\"

Then edit the cordis.patch.yml in the same directory and append an insert entry:

- insert:
    - id: deepseek-balance-banner
      name: ./deepseek-balance-banner.mjs?v=1

?v=1 is used to bypass browser ESM caching; increment the number when upgrading the plugin. After saving, it usually takes effect immediately. If there is no response within 5 seconds, restart dsh web and refresh the page (F5).

Note: Do not install the same plugin both as a package and as a file. To uninstall the package version, use:

dsh plugin --profile web remove deepseek-balance-banner

To uninstall the file version, delete the .mjs file and remove the corresponding two lines from the insert in cordis.patch.yml, then refresh the page.

Daily Usage and Troubleshooting¶

View Balance: The capsule at the top right displays both ¥ CNY and $ USD simultaneously, with negative values highlighted in a warning color.
Manual Refresh: Click any capsule, or wait for the automatic 60-second refresh.
Data Source: Official GET /user/balance, same origin as the whale widget in the bottom right of DSH.
Demo Mode: Add ?dsb-demo=1 to the page URL.

Two common situations: If the capsule always displays — or is loading, first check if DEEPSEEK_API_KEY is configured in DSH credentials. If only one currency is displayed, it is usually because your account only returns one currency type.

How It Works and Security Design¶

The data flow is as follows:

Browser Page ──(same-origin fetch)──> Local dsh web(/dsb-balance.json)
                                    │ ctx.credentials parses DEEPSEEK_API_KEY (not exposed to page)
                                    ▼
                     https://api.deepseek.com/user/balance  (balance_infos: USD + CNY)

The host plugin exposes the balance endpoint on the local dsh web, and the page script polls it every 60 seconds. The host side merges requests using a 25-second TTL cache. The entire process is read-only, with no write operations. The plugin itself does not contain the key; DEEPSEEK_API_KEY is parsed by the DSH credential service within the host process. The page communicates only with the local dsh web (same origin), without cross-domain requests or exposing the key.

Suitable Scenarios and Precautions¶

The plugin is suitable for users who keep the DSH Web interface open for a long time and wish to be aware of their balance, peak-valley pricing, and individual deductions at all times. Here are a few suggestions before installation:

The plugin runs with the permissions of the current dsh process. Read the source code repository before installation to ensure the code behavior meets your expectations.
Confirm that the license (this project is MIT) aligns with your usage.
If you maintain the plugin version yourself, remember to increment the ?v= number in the install patch with each release to avoid browser caching of old scripts.

Summary¶

deepseek-balance-banner condenses balance inquiries, peak-valley pricing alerts, and deduction feedback into a single banner at the top of the page, serving as a typical small yet complete capability supplement under the DSH “everything is a plugin” philosophy. The project homepage and community directory are as follows:

GitHub: https://github.com/iskshadow195563/DeepSeek_Harness_Balance_Banner
Community Plugin Directory: https://www.skillhub.cn/plugins/iskshadow195563/DeepSeek_Harness_Balance_Banner (An independent community site with no official affiliation to DeepSeek or Hanhua)

deepseek-balance-banner: Top dual-currency balance banner for the DSH Web interface