Introduction¶

When doing agent development, the DeepSeek account balance is an unavoidable issue: running out of balance causes calls to fail directly. The common practice is to leave the current working environment to check the platform backend, or manually call the API yourself. dsh-balance turns this into a DSH plugin: it registers a tool callable by the agent, while simultaneously displaying the balance permanently in the session input area of the Web UI, so queries no longer interrupt the workflow.

Below, I introduce the positioning, features, installation, configuration, and precautions of this plugin.

What is it¶

Maintained by qiuyongjin, the current version is 0.2.0 and uses the MIT license. It calls DeepSeek’s /user/balance API to query account balance, covering both the tool and interface sides: in a headless environment, it serves as a tool for the agent to call; in a Web environment, it displays the balance permanently in the session input area.

Implementation-wise, it uses TypeScript dual-sided development (node half + client half), with zero dependencies at runtime—@deepseek-ai/* dependencies are inlined during build, and the only peerDependencies is react ^18.2.0.

Core Features¶

dsh_balance Tool¶

On the node side, a tool named dsh_balance is registered to call DeepSeek’s GET /user/balance, returning the account availability status and balance details for each currency—under each currency, there are three items: total balance, bonus balance, and top-up balance. It is available in both headless and web combinations.

Web UI Balance Entry¶

In the Web environment, the plugin fills the official conversation.input.right slot: a button stays in the session input area, directly displaying the current total balance; clicking it expands a detail card containing availability status, currency details, and update time, with manual refresh supported.

Balance Endpoint¶

On the node side, an optional webServer backend exposes a JSON endpoint (waiting for readiness via ctx.inject) for the browser to fetch:

GET /plugins/dsh-balance/balance

The browser performs only a same-origin fetch; this endpoint is not mounted in the headless combination.

Credential Parsing¶

The API key is parsed by the DSH credential service, defaulting to referencing DEEPSEEK_API_KEY, which can be written directly on the Models settings page in Web; if the credential service is absent, it falls back to the startup environment variables. It is parsed in real-time with every call, so changing the key does not require a restart, and the retrieval method is consistent with the official dsh-llm-deepseek.

A notable design point: the API key exists only on the node side; the browser does not handle credentials.

Cancellation Semantics¶

When the tool executes, it merges timeout with caller cancellation (AbortSignal.any), conforming to dsh-tools’ cooperative cancellation contract.

Installation & Enable¶

First, install the plugin:

dsh plugin --profile web add ./dsh-balance

Changes to the bundle layer stack require a restart to take effect:

dsh --profile web

When the following line appears in the startup logs, mounting is successful:

[dsh-balance] plugin loaded（API key 引用：DEEPSEEK_API_KEY，基地址：https://api.deepseek.com）

After restarting, the 🔋 balance entry will appear on the right side of the tool row in the session input area (before the send button).

Configuration¶

The default configuration works out of the box. If you need to override it, override it by id in the profile’s cordis.patch.yml. Note that the patch completely replaces the config, so you need to restate all keys when overriding:

- id: dsh-balance
  config:
    apiKeyEnv: DEEPSEEK_API_KEY
    baseURL: https://api.deepseek.com
    timeoutMs: 10000

The meanings of the three keys:

Typical Usage¶

After installing and restarting, there are two ways to use it:

1. View the interface: The balance button directly displays the current total balance; click to expand the detail card, and manually refresh when you need the latest data.
2. Ask the agent: Ask the agent in the session “Query DeepSeek balance”, and the agent will call the dsh_balance tool to return the result.

Verify that the plugin is working correctly:

1. Run pnpm run typecheck at the type level;
2. Ask “Query my DeepSeek balance” in the session and confirm that the account availability status and balance details are returned.

Development & Build¶

If secondary development is needed, the common scripts are as follows:

pnpm install
pnpm run build       # tsc produces lib/types + tsdown produces lib/index.js / lib/client.js
pnpm run typecheck   # strict type checking, single tsconfig covering node + client sides
pnpm run watch       # tsdown incremental rebuild of client half

lib/ is the build artifact; do not edit it manually. You need to rebuild after modifying the source code.

Applicable Scenarios & Notes¶

Suitable for developers who use DeepSeek long-term and want to keep track of their account balance anytime, especially those already organizing workflows using the DSH plugin mechanism. A few notes:

1. The plugin runs with the permissions of the current dsh process; it is recommended to check the source code and license yourself before installing (this project is MIT).
2. Changing the API key does not require a restart (credentials are parsed in real-time on every call), but installing or uninstalling requires a restart of dsh --profile web to take effect.
3. In the headless combination, there is no webServer, so the balance endpoint and Web UI entry are unavailable; you can only query via the tool.

Conclusion¶

The problem dsh-balance solves is small but specific: making balance queries a constant piece of information so they no longer interrupt the workflow. It can be used on both the tool and interface sides, credentials are kept on the node side, and you only need to install it once.

• GitHub: https://github.com/qiuyongjin/dsh-balance
• Community Directory: https://www.skillhub.cn/plugins/qiuyongjin/dsh-balance

The Community Directory is an independent site with no official affiliation to DeepSeek or High-Fin.