GPIOX/dsh-api-balance

A floating badge for the DeepSeek Harness (DSH) Web GUI. Shows your LLM API account balance, drags anywhere, resizes, and switches text color to match whatever sits beneath it.

中文文档

Screenshots

The screenshots show the badge itself only. No real UI or conversation content.

Features

• Floats in a frame-wide overlay above every column. Click-through, so it never blocks the app underneath.
• One badge per configured provider. Drag each one anywhere and resize it from 70% to 250% with its bottom-right handle.
• Frosted-glass look: translucent neutral tint, backdrop blur, a thin border. Reads fine on light and dark skins.
• Text color follows the brightness of the content beneath each badge, light text over dark areas and dark text over light ones. Sampled every 1.5 seconds.
• Balance providers (DeepSeek, Moonshot, OpenAI, custom endpoint) show the currency balance. OpenCode Go shows its subscription quota in three windows: rolling 5h, weekly, and monthly, each with used and remaining percentages and a reset countdown.
• Click a badge to refresh all of them. Data refreshes itself every minute by default, configurable down to 30 seconds.
• API keys stay in the Harness credential store (~/.dsh/.credentials.yaml) and never reach the browser.
• The settings page manages the provider list (enable/disable, order), per-provider keys, balance and quota details, badge visibility, and position reset.

Installation

One command installs the plugin into your DSH web profile and registers it automatically (dsh plugin reconciles dsh.profile.bundles for you). The tarball form is plain HTTPS. You don't need a GitHub account, an SSH key, or git:

dsh plugin --profile web add https://github.com/GPIOX/dsh-api-balance/archive/refs/heads/main.tar.gz

Alternative git-based form (resolves through your local git configuration): dsh plugin --profile web add github:GPIOX/dsh-api-balance.

Then restart DSH (stop the dsh process and run it again, e.g. dsh web), refresh the page, and open Settings › API Balance to save your key. The badge shows up right away.

Uninstall / rollback:

dsh plugin --profile web remove dsh-api-balance-badge

The in-app Market (Settings › Plugins/Market) can install it too once it is listed in the awesome-dsh-plugin registry. For local development: dsh plugin --profile web add link:/path/to/dsh-api-balance-badge.

Zero-install quick start (dynamic plugin)

If you would rather not touch your profile, paste the plugin into any DSH Web GUI session as a dynamic plugin. No build step and no restart:

1. Call the cordis_define tool (kind: "new", any 3-6 letter prefix) and paste plugins/api-balance/host.js / plugins/api-balance/client.js as code.host / code.client
2. Activate the returned Package with cordis_run and click Approve on the run card
3. Open Settings › API Balance, pick a provider, paste your key, and save. The badge shows your balance immediately

Dynamic plugins live in the process, not on disk. After a DSH restart, define and activate it again (both source files are in this repo).

Supported providers

Provider	Balance endpoint	Auth	Notes
DeepSeek	GET https://api.deepseek.com/user/balance	API Key (sk-...)	total / granted / topped-up (CNY)
Moonshot (Kimi)	GET https://api.moonshot.cn/v1/users/me/balance	API Key (sk-...)	available / voucher / cash (CNY)
OpenAI	GET https://api.openai.com/dashboard/billing/credit_grants	Browser session token (sess-...)	OpenAI offers no API-key balance endpoint; session tokens expire
OpenCode Go	GET https://opencode.ai/zen/go/v1/usage	API key (usually OPENCODE_GO_API_KEY, written by the DSH Models page)	subscription quota: rolling 5h / weekly / monthly, each with used and remaining percentage plus reset time
Custom	any GET endpoint (Bearer auth)	your own	JSON field paths like data.available_balance or balance_infos[0].total_balance, such as relay stations

Security

• The browser only sees whether a key is configured. The plaintext key is never sent back to the page.
• Keys are stored by the Harness credential service (~/.dsh/.credentials.yaml), the same place DSH keeps its other secrets.
• Requests use native fetch (packaged install) or curl with the key via environment variable (dynamic plugin). Either way the key never lands in process listings or the browser.

Repository layout

.
├── assets/                  # README screenshots (badge renders, no real UI content)
├── lib/index.js             # Host half: /dsh-api-balance-badge/* HTTP routes + credential handling
├── client/client.js         # Client half: floating badge + settings page (factory bundle)
├── cordis.patch.yml         # Bundle patch inserting this plugin into a profile
├── package.json             # DSH plugin package manifest (dsh.bundle / dsh.client)
├── plugins/api-balance/     # Same halves as dynamic-plugin sources (zero-install path)
│   ├── host.js
│   ├── client.js
│   └── README.md
├── LICENSE                  # MIT
├── README.md                # this file (English)
└── README.zh-CN.md          # 中文文档

License

MIT © 2026 GPIOX