Zen API: expose credit balance in GET /zen/go/v1/usage (or /zen/v1/balance) #44189

Summary

The Zen API does not expose the workspace's credit wallet balance. GET /zen/go/v1/usage returns only Go-subscription usage windows (rolling/weekly/monthly), while the credit balance — shown on the console billing page and backed by BillingTable.balance — is only retrievable from the web console through a SolidStart server function (billing.get → Billing.get()), which requires an authenticated browser session. API-key callers have no way to read it.

Today the only key-authenticated balance signal is the error thrown at $0:

Insufficient balance. Manage your billing here: https://opencode.ai/workspace/<id>/billing

i.e. binary, no number, and only after the money is gone.

Request

Add the credit balance to the existing usage endpoint:

GET /zen/go/v1/usage (same Authorization: Bearer key auth)

{
  "usage": {
    "rolling": { "status": "ok", "percent": 12, "resetsAt": "..." },
    "weekly":  { "status": "ok", "percent": 34, "resetsAt": "..." },
    "monthly": { "status": "ok", "percent": 56, "resetsAt": "..." }
  },
  "balance": {
    "usd": 4.10,
    "currency": "USD",
    "asOf": "2026-08-22T17:00:00Z"
  }
}

A dedicated GET /zen/v1/balance returning the same balance object would also work. Returning it as part of the current usage endpoint keeps one polling endpoint for everything a monitor needs.

Use cases

• Programmatic monitoring (status-bar widgets, dashboards, budget alerts) without scraping the console in a logged-in browser.
• Early warnings before requests start failing with Insufficient balance — e.g. notify at $5 remaining.
• Workspaces that enable "Use balance" as a Go fallback: knowing the remaining balance tells you how much headroom the fallback actually has.

Notes

• Keys are workspace-scoped and the balance is the same workspace's balance, so this adds no new exposure surface.
• The console already shows this exact value to the same user at opencode.ai/workspace/<id>/billing (formatBalance = balance / 1e8, see packages/console/app/src/routes/workspace/common.tsx).

Relevant sources:

• packages/console/app/src/routes/zen/go/v1/usage.ts
• packages/console/app/src/routes/zen/util/handler.ts (balance check + CreditsError)
• packages/console/core/src/billing.ts (BillingTable.balance)