unorouter-balance/README.md

UnoRouter Balance — Hermes Desktop Plugin

Statusbar chip for Hermes Agent Desktop showing how much UnoRouter credit you have left, plus a popover with the full breakdown.

What it shows

Statusbar readout — left/total (pct%) of your spendable budget:

7.02/10 (70%)

Click opens a popover:

• UnoRouter heading with a refresh button
• Available — total spendable, with a progress bar
• Subscription credit, plan name, time to weekly reset
• Wallet balance, lifetime spend, request count

Hover shows a one-line tip; details live in the popover only.

Install

1. Create an access token (not an sk- API key) at unorouter.com → Settings → Security → API access.
2. Copy this folder to $HERMES_HOME/desktop-plugins/unorouter-balance/.
   • Windows: %LOCALAPPDATA%\hermes\desktop-plugins\unorouter-balance\
   • Linux/macOS: ~/.hermes/desktop-plugins/unorouter-balance/
   • The folder name must match the plugin id.
3. Either paste the token into DEFAULT_TOKEN at the top of plugin.js, or run ⌘K → UnoRouter: set access token (persisted per plugin).
4. ⌘K → Reload desktop plugins.

The app watches the folder, so later saves hot-reload in place.

Two credit pools

This trips people up. UnoRouter keeps two separate pools:

Pool	Source	Expiry
Subscription credit	weekly delivery on a plan	resets weekly, does not carry over
Wallet	one-time top-ups	never expires

/api/user/self → quota is the wallet only. It reads 0 on an active subscription, so a naive plugin reports "$0.00" to a paying subscriber. This plugin adds the subscription remainder (/api/subscription/self) and shows the sum, because billing_preference is subscription_first and the subscription carries allow_wallet_overflow: true.

API

Both endpoints take the access token as Authorization: Bearer <token>. Quota units: 500000 == $1.

GET /api/user/self          # wallet quota, lifetime spend, request count
GET /api/subscription/self  # subscription credit, next reset, plan title

/api/subscription/self is not in the public docs. It answers 200. Dead ends: /api/subscription, /api/billing, /api/plan → 404; /api/user/subscription, /api/user/plan → 403.

Most failures answer HTTP 200 with success: false — check that field, not the status code. Real 401/403 means a bad or revoked token.

Refresh

Polls every 5 minutes via React Query (REFRESH_MS). Background polling is off by default, so an unfocused window doesn't tick. Manual refresh: the button in the popover, or ⌘K → UnoRouter: refresh balance.

Palette commands

• UnoRouter: refresh balance
• UnoRouter: set access token
• UnoRouter: open billing page

Note on the token

DEFAULT_TOKEN in this repo is empty on purpose — don't commit a live token.