TokenLedger: A Token Usage Accounting DSH plugin for DeepSeek Harness

TokenLedger is a token usage accounting plugin (DSH plugin) for DeepSeek Harness, maintained by zh667 under the MIT license, designed specifically for the dsh web GUI. It solves the problem of accurately attributing token consumption per request to the relay site that actually served it, with zero configuration and no credentials required. The plugin automatically discovers relay sites from the host's provider configuration, normalizes origins by baseURL, merges multiple keys from the same site into one row, and uses the domain as the site name. Core capabilities include relay attribution, balance queries (supporting DeepSeek official, New API, Sub2API, Moonshot, Zhipu, OpenRouter, etc.), three-window usage analysis (today/month/cumulative), drill-down by site/model, cache hit rate, one-year activity heatmap, cost estimation (rate tables, tiered pricing, peak/off-peak), CSV/JSON export, and diagnostics. The plugin only exposes loopback read-only endpoints and never reads prompts, tool arguments, or response content, ensuring privacy and security.

What core features does the TokenLedger DSH plugin support?

TokenLedger provides relay attribution, balance, usage analysis, cost estimation, export, and diagnostics. Relay attribution groups by normalized origin from the provider's baseURL, merging multiple keys from the same site into one row. Balance queries support DeepSeek official, New API family (including One API, VoAPI), Sub2API, Moonshot/Kimi, Zhipu GLM/Z.ai, and OpenRouter (requires Management Key); all except OpenRouter need only a regular API key. Usage analysis offers today/month/cumulative windows, drill-down by site/model, cache hit rate, and a one-year activity heatmap. Cost estimation supports rate tables with effective dates, tiered pricing, and peak/off-peak periods; unpriced models show a dash. Export supports CSV/JSON, and diagnostics include index health and unattributed row counts.

How to install TokenLedger?

Requires DeepSeek Harness web profile (@deepseek-ai/dsh >= 0.1.0-rc.6). Installation command:

dsh plugin --profile web add github:zh667/tokenledger

Restart the running dsh web, hard-refresh the browser, and the "Usage Ledger" entry appears at the bottom of the sidebar. Upgrade or uninstall:

dsh plugin --profile web update dsh-tokenledger
dsh plugin --profile web remove dsh-tokenledger

It works immediately after installation—no configuration or credentials needed.

What are the command-line usages of TokenLedger?

Anything the panel can answer, the command line can answer too—both read the same queries. Common commands:

/tokenledger                      # all time
/tokenledger 7                    # last 7 days
/tokenledger 30 api.example.com   # a specific relay, last 30 days
/tokenledger site                 # list discovered relays
/tokenledger site add <route> <address>
/tokenledger site rm <route>
/tokenledger export csv 30        # export
/tokenledger diagnostics          # index health
/tokenledger reindex              # drop index and rebuild

Which account types and upstream interfaces does TokenLedger support?

Supports DeepSeek official (/user/balance), New API family (/api/usage/token/ + /api/status), Sub2API (/v1/usage), Moonshot/Kimi (/v1/users/me/balance), Zhipu GLM/Z.ai (/api/paas/v4/balance), and OpenRouter (/api/v1/credits, requires Management Key). The relay's software is auto-detected via route fingerprint; vendor domains need no detection. New API quotas are per-key, so two keys on the same site are two separate quotas.

Does TokenLedger require configuration?

Usually no configuration is needed; relays are read from the host's provider settings. To override, configure relays, rates, and fingerprint in settings.yaml; changes hot-reload without restart.

How does TokenLedger ensure correctness and data accounting?

It handles three error-prone folding scenarios: requests that fail after reporting usage (from assistant/chunk usage), the same (turn, step) reported twice (replacement not accumulation), and orphan usage chunks without identity (fallback to the last request/header). Accounting: inputTokens, cacheReadTokens, and cacheWriteTokens are mutually exclusive; reasoningTokens is a subset of outputTokens. Days are split by the host process's local time, and attribution is fixed at fold time—history is never rewritten.

How does TokenLedger handle privacy and security?

The plugin never reads content—only counts and identifiers. Both endpoints accept only loopback GET and are guarded on the peer socket address. It never reads prompts, tool arguments, or response content, and never sends API keys or upstream raw responses to the browser.

See more DSH plugins at dsh-plugin.org