---
title: Kimi balance monitor (low-balance alerts)
---

# 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](../../src/main/services/kimi-balance/kimi-balance-monitor.ts) —
  a registered periodic tick (started in [startup/registry.ts](../../src/main/startup/registry.ts),
  stopped in [app/shutdown.ts](../../src/main/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](../../src/main/services/kimi-balance/kimi-balance-core.ts)
  (`shouldPollBalance`, `shouldAlertLowBalance`).
- Balance client: [moonshot-balance-client.ts](../../src/main/services/kimi-balance/moonshot-balance-client.ts)
  (returns `null` on any failure — never alerts off a transient error).
- Alert: [kimi-balance-alert.ts](../../src/main/services/kimi-balance/kimi-balance-alert.ts)
  (dedup key `kimi-low-balance`); the one-click **Recharge** action is declared in
  [alert-primary-actions.ts](../../src/shared/alert-primary-actions.ts).
- Settings: `kimiBalanceMonitorEnabled` / `kimiBalanceThresholdUSD` in the notifications
  slice ([notifications-settings.ts](../../src/shared/types/settings/notifications-settings.ts)).

## Related

- [kimi-provider.md](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](new-model-watcher.md) — the sibling background provider watcher this
  mirrors (scheduled poll → deduped inbox alert).