llm-connect/contracts/functional/account-balance.md

Provider Account Balance

llm_connect.balance reports prepaid / key remaining for a selected inference backend. Balance is never assumed to be OpenRouter unless that backend is selected (explicitly or as the current default provider).

Selection rules

from llm_connect import get_account_balance, resolve_balance_provider

resolve_balance_provider(None)           # → LLMConfig().provider (today openrouter)
resolve_balance_provider("openrouter")   # one-shot; does not mutate defaults
get_account_balance()                    # default backend
get_account_balance("openrouter")        # explicit backend for this call only

• Explicit provider / CLI --provider is invocation-only.
• It must not rewrite config files, env, LLMConfig class defaults, or OpenRouter model defaults.
• Unspecified → current default provider via resolve_balance_provider(None).

Contract

• AccountBalance carries optional wallet fields (credits_*) and optional key-limit fields (limit, limit_remaining, limit_reset, usage).
• EUR display fields use the same FX resolution as cost estimates.
• BalanceClientRegistry maps provider id → client factory.
• Unsupported providers raise LLMBalanceUnsupportedError listing supported backends (do not fall back to OpenRouter).

OpenRouter (v1)

• GET /api/v1/credits → account prepaid: remaining = total_credits − total_usage
• GET /api/v1/auth/key → key limit remaining / reset policy
• Both are fetched best-effort; one may fail while the other succeeds.

CLI

llm-connect balance
llm-connect balance --provider openrouter
llm-connect balance --json