Kimi balance monitor (low-balance alerts)

What it is

Moonshot's Kimi API is prepaid — when the account balance hits zero, every Kimi session stops instantly with an "insufficient balance, please recharge" error. Moonshot also supports auto-recharge (a linked-card top-up), which can silently bill your card whenever the balance runs low. The Kimi balance monitor covers both surprises: Omniscio checks your Moonshot balance in the background and (a) warns you — with a one-click Recharge button — before it runs dry, and (b) flags a balance that jumped UP since the last check (a recharge that most likely billed your card), so a silent auto-recharge doesn't go unnoticed.

It is opt-in and OFF by default. Turn it on at Settings → Notifications → Kimi balance monitor (kimiBalanceMonitorEnabled). It only does anything once you've also set a Kimi API key (Settings → Accounts → Kimi).

Where to find it

You meet it in two places: an inbox card when the balance drops below your threshold, and the switch that turns the whole check on at Settings → Notifications → Kimi balance monitor. It only does anything once you have also saved a Kimi API key under Settings → Accounts → Kimi.

How it behaves

What you see

When your balance drops below your threshold:

1. One inbox card — "Kimi API balance low", showing the current balance and your threshold, with a one-click Recharge button that opens platform.moonshot.ai.
2. One desktop / phone notification — fired when the card is first created.

The card is deduped (kimi-low-balance): you get one card while you're low, not a new one every few hours. It clears when you dismiss it (and re-fires later if you go low again after recharging).

When your balance jumps UP between checks (a recharge — most likely a silent auto-recharge that billed your card):

1. A separate "Kimi balance auto-recharged" card — showing the before → after balance and the jump, deduped by kimi-recharge-detected (distinct from the low-balance card so the two never coalesce), with a one-click Manage billing button to platform.moonshot.ai so you can turn OFF auto-recharge if you didn't expect it. This is the signal the low-balance alert can NEVER give — auto-recharge keeps the balance ABOVE the low mark, so it never crosses the low threshold.

Settings

• Kimi balance monitor (kimiBalanceMonitorEnabled, default off) — the master toggle for the feature.
• Alert threshold (kimiBalanceThresholdUSD, default $5, range $0–$10,000) — you get the alert once your available balance falls under this. Setting it to $0 disables the check without turning the feature off.

Cost

None on Omniscio's side. Reading the balance is a free metadata call. The only money involved is the recharge you choose to make on Moonshot's platform.

For agents

How it works

• A registered background service ticks about every 4 hours (first run ~2 min after launch). Each tick, only if the feature is ON and a Kimi key is set, it GETs your balance from Moonshot's GET /v1/users/me/balance (a free metadata call — no AI tokens, no account usage) and compares available_balance to your threshold.
• Below threshold → it raises the deduped low-balance card + notification. At or above → nothing.
• Each tick also persists the balance to kimi-balance-state.json and compares it to the PREVIOUS tick's; a meaningful upward jump (> ~$1, above rounding noise) raises the separate recharge-detected card. The baseline survives the 4-hour gap AND an app restart; the first-ever poll only sets the baseline (no false alert).
• A failed balance fetch (offline, invalid key, rate-limited) is treated as "unknown" and simply skips that tick — it never raises a false low-balance alert.

Under the hood

• Service: src/main/services/kimi-balance/kimi-balance-monitor.ts — a registered periodic tick (started in startup/registry.ts, stopped in app/shutdown.ts); bulletproof (never throws out of a tick), inert under AMC_INSTANCE_ID, kill switch AMC_DISABLE_KIMI_BALANCE_MONITOR=1.
• Pure decision logic (unit-tested, no I/O): kimi-balance-core.ts (shouldPollBalance, shouldAlertLowBalance).
• Balance client: moonshot-balance-client.ts (returns null on any failure — never alerts off a transient error).
• Alert: kimi-balance-alert.ts (dedup key kimi-low-balance); the one-click Recharge action is declared in alert-primary-actions.ts.
• Settings: kimiBalanceMonitorEnabled / kimiBalanceThresholdUSD in the notifications slice (notifications-settings.ts).

Related

• kimi-provider.md — the Kimi provider itself (the out-of-balance error it surfaces mid-session is what this monitor warns you about ahead of time).
• new-model-watcher.md — the sibling background provider watcher this mirrors (scheduled poll → deduped inbox alert).